Pour accéder à l’index complet de la documentation, consultez llms.txt. Pour obtenir la version Markdown d’une page de documentation, ajoutez
.md à la fin de l’URL de la page.
Prise en compte du temps et saisie asynchrone pour les agents personnels
Comment créer des agents qui tiennent compte des contraintes de temps et poursuivent leur travail en attendant une réponse de l’utilisateur
Auteur: Kevin Whinnery
Si vous créez un agent personnel semblable à un dot, vous souhaiterez souvent qu’il remette ses résultats à l’utilisateur dans un délai précis.
Imaginons que j’aie rendez-vous avec un client potentiel dans 15 minutes. Je demande à mon agent de se renseigner sur l’entreprise et de préparer une note de synthèse en me laissant trois minutes pour la lire avant la réunion. C’est à peu près le temps dont je dispose habituellement pour préparer mes réunions au cours d’une journée de travail 😬.
L’agent remarque que je n’ai pas précisé si la réunion porte sur une évaluation technique ou sur les tarifs. Or, les détails à examiner et les informations à inclure dans la note dépendent de cette distinction.
L’agent décide de me demander quel est l’objet de la réunion. Comment peut-il mettre à profit le temps qui reste, tenir compte de ma réponse si elle arrive et me remettre une note utile même si je ne réponds jamais ?
Prise en compte du temps et saisie asynchrone
Grâce à la prise en compte du temps, une fonctionnalité récemment ajoutée à l’API Agents, le modèle reçoit régulièrement un rappel de l’heure qu’il est et peut adapter son travail à l’échéance. Les outils de type fonction asynchrones permettent à l’agent de poursuivre son travail pendant que l’application attend une réponse de l’utilisateur final.
La réunion commence dans 15 minutes. L’agent dispose donc de 12 minutes pour préparer ma note. À l’approche de l’échéance, il peut donner la priorité à la vérification des informations les plus solides et à la rédaction de la note avant d’explorer une nouvelle piste. Si vous lui accordez un délai plus long, le modèle sait qu’il peut approfondir ses recherches et en mener d’autres.
Une demande comme « J’ai une réunion dans 15 minutes. Prépare-moi une note de synthèse et laisse-moi trois minutes pour la lire » fixe l’échéance. La prise en compte du temps permet au modèle de suivre l’heure pendant qu’il attend les résultats de recherche ou la réponse de l’utilisateur.
4:00de l’après-midi
Note à remettre à 16 h 12
DébutRemise de la noteRéunion
Agent
Recherches sur l’entreprise
Question pour vous
Sujet de la réunion non précisé
Notes
Pied Piper
Note de préparation à la réunion
Présentation de l’entreprise
Annonces récentes
Pour illustrer ce fonctionnement, nous allons configurer un agent qui aide les utilisateurs à préparer leurs réunions. Dans l’illustration, à 16 h UTC, je demande une note pour 16 h 12 en vue d’une réunion à 16 h 15. Nous verrons comment configurer l’agent, lui indiquer régulièrement l’heure, réagir à ses appels d’outils et traiter son résultat final.
Pour aider l’utilisateur à préparer une réunion, notre agent doit se renseigner sur l’entreprise, demander les précisions qui lui manquent sur la réunion et suivre le temps dont il dispose pour rédiger une note. Il lui faut donc un outil de recherche web, un outil asynchrone pour interroger l’utilisateur et la fonctionnalité de prise en compte du temps.
Définissez experimental.time_awareness sur true pour que le modèle reçoive régulièrement un rappel de l’heure.
Activez l’outil intégré web_search en mode live pour que l’agent puisse rechercher des informations à jour sur le web.
Définissez un outil de type fonction nommé request_user_input_async. Définissez async sur true pour que l’agent puisse poursuivre son travail pendant que votre application recueille la réponse.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38const requests = new AbortController();const agent = await client.beta.agents.create( { name: "Personal assistant", model: "gpt-6.2-astra", instructions: "You are a personal assistant. Deliver useful, well-sourced answers within the user's time constraints. " + "Ask for clarification when it would materially improve the result, and keep making progress while a reply is pending. " + "State important uncertainties.", experimental: { time_awareness: true }, tools: [ { type: "web_search", mode: "live" }, { type: "function", name: "request_user_input_async", description: "Ask the user for context. The result contains their reply or reports that the question expired.", async: true, parameters: { type: "object", properties: { question: { type: "string" }, choices: { type: "array", items: { type: "string" }, description: "Optional suggested replies to display with the question.", }, }, required: ["question"], additionalProperties: false, }, }, ], }, { signal: requests.signal });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30asyncdefcreate_agent(client: AsyncOpenAI):returnawait client.beta.agents.create(name="Personal assistant",model="gpt-6.2-astra",experimental={"time_awareness": True},instructions=("You are a personal assistant. Deliver useful, well-sourced answers ""within the user's time constraints. Ask for clarification when it ""would materially improve the result, and keep making progress while ""a reply is pending. State important uncertainties." ),tools=[ {"type": "web_search", "mode": "live"}, {"type": "function","name": "request_user_input_async","description": "Ask for missing context while continuing independent work.","async": True,"parameters": {"type": "object","properties": {"question": {"type": "string"},"choices": {"type": "array", "items": {"type": "string"}}, },"required": ["question"],"additionalProperties": False, }, }, ], )
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26func createAgent(ctx context.Context, client *openai.Client) (*openai.Agent, error) { return client.Beta.Agents.New(ctx, openai.BetaAgentNewParams{ Name: openai.String("Personal assistant"), Model: "gpt-6.2-astra", Instructions: openai.String("You are a personal assistant. Deliver useful, well-sourced answers within the user's time constraints. " + "Ask for clarification when it would materially improve the result, and keep making progress while a reply is pending. " + "State important uncertainties."), Experimental: openai.BetaAgentNewParamsExperimental{TimeAwareness: openai.Bool(true)}, Tools: []openai.PersistedAgentToolParamUnion{ {OfParamWebSearch: &openai.PersistedAgentToolParamWebSearch{Mode: "live"}}, {OfParamFunction: &openai.PersistedAgentToolParamFunction{ Name: "request_user_input_async", Description: "Ask for missing context while continuing independent work.", Async: openai.Bool(true), Parameters: map[string]any{ "type": "object", "properties": map[string]any{ "question": map[string]any{"type": "string"}, "choices": map[string]any{"type": "array", "items": map[string]any{"type": "string"}}, }, "required": []string{"question"}, "additionalProperties": false, }, }}, }, })}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50var agent = client .beta() .agents() .create( AgentCreateParams.builder() .name("Personal assistant") .model("gpt-6.2-astra") .instructions( "You are a personal assistant. Deliver useful, well-sourced answers" + " within the user's time constraints. Ask for clarification when it" + " would materially improve the result, and keep making progress" + " while a reply is pending. State important uncertainties.") .experimental( AgentCreateParams.Experimental.builder().timeAwareness(true).build()) .addTool( PersistedAgentToolParam.WebSearch.builder() .mode(PersistedAgentToolParam.WebSearch.Mode.LIVE) .build()) .addTool( PersistedAgentToolParam.Function.builder() .name("request_user_input_async") .description( "Ask the user for context. The result contains their reply or" + " reports that the question expired.") .async(true) .parameters( PersistedAgentToolParam.Function.Parameters.builder() .putAdditionalProperty("type", JsonValue.from("object")) .putAdditionalProperty( "properties", JsonValue.from( Map.of( "question", Map.of("type", "string"), "choices", Map.of( "type", "array", "items", Map.of("type", "string"), "description", "Optional suggested replies to" + " display with the question.")))) .putAdditionalProperty( "required", JsonValue.from(List.of("question"))) .putAdditionalProperty( "additionalProperties", JsonValue.from(false)) .build()) .build()) .build());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35def create_agent(client) client.beta.agents.create( name: "Personal assistant", model: "gpt-6.2-astra", experimental: { time_awareness: true }, instructions: "You are a personal assistant. Deliver useful, well-sourced answers " \ "within the user's time constraints. Ask for clarification when it would " \ "materially improve the result, and keep making progress while a reply is " \ "pending. State important uncertainties.", tools: [ { type: "web_search", mode: "live" }, { type: "function", name: "request_user_input_async", description: "Ask for missing context while continuing independent work.", async: true, parameters: { type: "object", properties: { question: { type: "string" }, choices: { type: "array", items: { type: "string" } } }, required: ["question"], additionalProperties: false } } ] )end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33agent=$(curl --fail-with-body --silent --show-error --max-time 30 \ https://api.openai.com/v1/agents \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: agents=v1" \ -H "Content-Type: application/json" \ --data-binary @- <<'JSON'{ "name": "Personal assistant", "model": "gpt-6.2-astra", "instructions": "You are a personal assistant. Deliver useful, well-sourced answers within the user's time constraints. Ask for clarification when it would materially improve the result, and keep making progress while a reply is pending. State important uncertainties.", "experimental": {"time_awareness": true}, "tools": [ {"type": "web_search", "mode": "live"}, { "type": "function", "name": "request_user_input_async", "description": "Ask the user for context. The result contains their reply or reports that the question expired.", "async": true, "parameters": { "type": "object", "properties": { "question": {"type": "string"}, "choices": {"type": "array", "items": {"type": "string"}} }, "required": ["question"], "additionalProperties": false } } ]}JSON)agent_id=$(jq -er '.id' <<<"$agent")
Lancez une tâche avec une échéance
Nous pouvons maintenant demander à l’agent de préparer une réunion avec un client. La demande précise le nom de l’entreprise, l’heure de la réunion et l’heure de remise de la note. L’agent choisit les recherches à mener et décide s’il doit demander des précisions.
Votre application doit convertir les indications de temps telles que « dans 15 minutes » et « trois minutes pour la lire » en horodatages absolus afin que le modèle et l’application utilisent les mêmes repères temporels. Ce code indique à l’agent que la réunion commence dans 15 minutes et lui demande de remettre la note dans 12 minutes.
Démarrage de la session de préparation de la réunion
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17const startedAt = Date.now();const meetingAt = new Date(startedAt + 15 * 60_000);const briefingBy = new Date(startedAt + 12 * 60_000);const replyCutoff = new Date(startedAt + 10 * 60_000);const stream = await client.beta.agents.sessions.create( { agent_id: agent.id, environment: { type: "none" }, stream: true, input: `I am meeting with Pied Piper (example.com) about our customer-support software at ${meetingAt.toISOString()}. ` + "Get me up to speed on their business, recent product announcements, and questions I should ask. " + `Send me a concise briefing by ${briefingBy.toISOString()} so I have time to read it before the meeting.`, }, { signal: requests.signal });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15now = datetime.now(UTC)meeting = (now + timedelta(minutes=15)).isoformat(timespec="seconds")delivery = (now + timedelta(minutes=12)).isoformat(timespec="seconds")stream =await client.beta.agents.sessions.create(agent_id=agent.id,environment={"type": "none"},input=(f"I am meeting with Pied Piper (example.com) about our customer-support software at "f"{meeting}. Get me up to speed on their business, recent product "f"announcements, and questions I should ask. Send me a concise briefing by "f"{delivery} so I have time to read it before the meeting." ),stream=True,timeout=12*60,)
1
2
3
4
5
6
7
8
9events := client.Beta.Agents.Sessions.NewStreaming(streamCtx, openai.BetaAgentSessionNewParams{ AgentID: openai.String(agent.ID), Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}}, Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String(fmt.Sprintf( "I am meeting with Pied Piper (example.com) about our customer-support software at %s. "+ "Get me up to speed on their business, recent product announcements, and questions I should ask. "+ "Send me a concise briefing by %s so I have time to read it before the meeting.", meetingAt.UTC().Format(time.RFC3339), briefingBy.UTC().Format(time.RFC3339)))},})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25try (var events = client .beta() .agents() .sessions() .createStreaming( SessionCreateParams.builder() .agentId(agent.id()) .environmentNone() .input( "I am meeting with Pied Piper (example.com) about our customer-support software at " + meetingAt + ". Get me up to speed on their business, recent product" + " announcements, and questions I should ask. Send me a concise" + " briefing by " + briefingBy + " so I have time to read it before the meeting.") .build(), RequestOptions.builder() .timeout( Duration.ofMillis( Math.max( 1, Duration.between(Instant.now(), briefingBy).toMillis() + 1000))) .build())) {
1
2
3
4
5
6
7
8
9
10
11now = Time.now.utcmeeting = (now + 15 * 60).iso8601delivery = (now + 12 * 60).iso8601stream = sessions.create_streaming( agent_id: agent_id, environment: { type: "none" }, input: "I am meeting with Pied Piper (example.com) about our customer-support software " \ "at #{meeting}. Get me up to speed on their business, recent product " \ "announcements, and questions I should ask. Send me a concise briefing " \ "by #{delivery} so I have time to read it before the meeting.")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17started=$(date +%s)meeting_at=$(jq -nr --argjson start "$started" '$start + 900 | strftime("%Y-%m-%dT%H:%M:%SZ")')briefing_by=$(jq -nr --argjson start "$started" '$start + 720 | strftime("%Y-%m-%dT%H:%M:%SZ")')request=$(jq -n --arg agent "$agent_id" --arg meeting "$meeting_at" --arg delivery "$briefing_by" '{ agent_id: $agent, environment: {type: "none"}, stream: true, input: ("I am meeting with Pied Piper (example.com) about our customer-support software at " + $meeting + ". Get me up to speed on their business, recent product announcements, and questions I should ask. Send me a concise briefing by " + $delivery + " so I have time to read it before the meeting.")}')curl --fail-with-body --silent --show-error --no-buffer \ https://api.openai.com/v1/agents/sessions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: agents=v1" \ -H "Content-Type: application/json" \ --data-binary "$request" >"$work/events" &stream_pid=$!
Affichez une question en attente de réponse
Lorsque l’agent demande quel est l’objet de la réunion, l’application doit afficher la question pendant que les recherches sur l’entreprise se poursuivent. En recueillant la réponse dans une tâche distincte, l’application peut continuer à recevoir les mises à jour de l’agent.
C’est à votre application de recueillir la réponse de l’utilisateur lorsque le modèle demande des précisions au moyen d’un appel d’outil.
Surveillez le flux d’événements de la session pour repérer les événements agent.session.turn.item.done contenant un appel à la fonction request_user_input_async. Lisez la question et les éventuelles réponses proposées dans item.arguments. La liste required_actions de la session décrit les actions bloquantes. Si vous attendez qu’une entrée y apparaisse, vous risquez de manquer une question asynchrone.
Enregistrez l’identifiant de la session ainsi que les valeurs turn_id et call_id de l’appel pour associer la réponse à la question. Suivez les questions en attente afin de n’afficher et de ne traiter chacune qu’une seule fois. Annulez leurs gestionnaires de saisie à la fin de l’exécution de l’agent.
La question arrive sous la forme d’un événement d’appel de fonction :
{ "type": "agent.session.turn.item.done", "item": { "type": "function_call", "name": "request_user_input_async", "arguments": { "question": "Is this meeting mainly a technical evaluation or a commercial discussion?", "choices": ["Technical evaluation", "Commercial discussion"] }, "turn_id": "turn_789abcd", "call_id": "call_012ef34" }}
Renvoyez le résultat de l’outil
La réponse de l’utilisateur permet à l’agent de cibler la note en fonction de l’objectif de la réunion. Même sans réponse, l’agent doit avoir le temps de terminer la rédaction. L’application ferme donc les questions restées sans réponse à 16 h 10, deux minutes avant la remise de la note.
Renvoyez un résultat d’outil par appel en attente tant que l’agent est en cours d’exécution :
À la réception d’une réponse, définissez status sur answered et placez le texte saisi ou l’option choisie dans answer.
À l’heure limite de réponse, si l’appel portant le même call_id est toujours en attente et que l’utilisateur n’a pas répondu, renvoyez {"status":"no_answer"}.
Envoyez le résultat avec la méthode du SDK qui crée un événement de session. Utilisez les identifiants enregistrés pour associer le résultat à la question. Continuez à lire le flux pendant l’envoi du résultat. Si l’agent termine plus tôt, fermez la question en attente dans l’interface.
Renvoi de la réponse ou signalement de l’expiration du délai
Remettez une note concise dès qu’elle est prête, en laissant à l’utilisateur au moins trois minutes pour la lire avant la réunion. Si l’échéance arrive avant, renvoyez la dernière note achevée ou indiquez qu’aucun résultat vérifié n’est disponible.
Si le flux se ferme prématurément, listez les tours de la session pour vérifier l’état enregistré. Consultez la section sur la reprise du flux pour vous reconnecter et récupérer le travail enregistré.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16def final_text(item) return unless item.type.to_s == "message" && item.role.to_s == "assistant" && item.status.to_s == "completed" && item.phase.to_s == "final_answer" text = item.content.select { |part| part.type.to_s == "output_text" }.map(&:text).join("\n") text unless text.empty?enddef retrieve_answer(sessions, session_id, turn_id) page = sessions.turns.items.list(turn_id, session_id: session_id, order: "desc") page.auto_paging_each do |item| text = final_text(item) return text if text && !text.empty? end nilend
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18retrieve_answer() { local turn_id=$1 page after="" text local -a page_args=() while :; do page=$(curl --fail-with-body --silent --show-error --max-time 30 --get \ "https://api.openai.com/v1/agents/sessions/$session_id/turns/$turn_id/items" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: agents=v1" \ --data-urlencode order=desc ${page_args[@]+"${page_args[@]}"}) text=$(jq -r '[.data[] | select(.type == "message" and .role == "assistant" and .status == "completed" and .phase == "final_answer") | [.content[] | select(.type == "output_text") | .text] | join("\n")][0] // empty' <<<"$page") if [ -n "$text" ]; then printf '%s\n' "$text"; return; fi if [ "$(jq -r '.has_more' <<<"$page")" != true ]; then return 1; fi after=$(jq -er '.last_id' <<<"$page") page_args=(--data-urlencode "after=$after") done}
Code complet de l’exemple
Pour chaque langage, l’exemple ci-dessous regroupe dans un seul fichier toutes les étapes de préparation d’une réunion, de la configuration du client à la libération des ressources, en passant par le traitement des réponses asynchrones et la minuterie de remise de la note. Chaque script lit la variable d’environnement OPENAI_API_KEY et accepte les réponses saisies dans le terminal.
Exemple complet de préparation d’une réunion
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276import OpenAI from "openai";import type { AgentFunctionCallItem } from "openai/resources/beta/agents/agents";import { createInterface } from "node:readline";const client = new OpenAI({ timeout: 30_000, maxRetries: 0 });const startedAt = Date.now();const meetingAt = new Date(startedAt + 15 * 60_000);const briefingBy = new Date(startedAt + 12 * 60_000);const replyCutoff = new Date(startedAt + 10 * 60_000);const requests = new AbortController();const terminal = createInterface({ input: process.stdin });const bufferedReplies: string[] = [];const waitingReplies = new Map<string, (answer?: string) => void>();const seenCalls = new Set<string>();const replyTasks = new Set<Promise<void>>();let agentId: string | undefined;let sessionId: string | undefined;let turnActive = false;let delivered = false;let deadlineReached = false;let finalAnswer = "";let replyError: unknown;terminal.on("line", (line) => { const waiting = waitingReplies.values().next().value; if (waiting) { waiting( Date.now() < replyCutoff.getTime() ? line.trim() || undefined : undefined ); } else bufferedReplies.push(line.trim());});function closeQuestions() { for (const finish of waitingReplies.values()) finish(); terminal.close(); process.stdin.pause();}function deliver(text: string) { if (delivered) return; delivered = true; console.log(text);}function readReply(call: AgentFunctionCallItem): Promise<string | undefined> { return new Promise((resolve) => { const key = `${call.turn_id}:${call.call_id}`; let timer: ReturnType<typeof setTimeout> | undefined; const finish = (answer?: string) => { clearTimeout(timer); waitingReplies.delete(key); resolve(answer); }; waitingReplies.set(key, finish); timer = setTimeout(finish, Math.max(0, replyCutoff.getTime() - Date.now())); if (Date.now() >= replyCutoff.getTime()) finish(); else if (bufferedReplies.length) finish(bufferedReplies.shift() || undefined); });}async function returnResult( sessionId: string, call: AgentFunctionCallItem, answer: string | undefined) { const result = answer ? { status: "answered", answer } : { status: "no_answer" }; await client.beta.agents.sessions.events.create( sessionId, { events: [ { type: "agent.session.input.tool_result", turn_id: call.turn_id, call_id: call.call_id, success: true, output: JSON.stringify(result), }, ], }, { signal: requests.signal } );}async function collectReply(sessionId: string, call: AgentFunctionCallItem) { const arguments_ = call.arguments; if ( typeof arguments_ !== "object" || arguments_ === null || !("question" in arguments_) || typeof arguments_.question !== "string" ) { throw new Error("The question tool did not provide a question"); } console.error(arguments_.question); if ("choices" in arguments_ && Array.isArray(arguments_.choices)) { console.error(arguments_.choices.join(" / ")); } const answer = await readReply(call); if (turnActive && !requests.signal.aborted) { await returnResult(sessionId, call, answer); }}async function retrieveAnswer(sessionId: string, turnId: string) { for await (const item of client.beta.agents.sessions.turns.items.list( turnId, { session_id: sessionId, order: "desc" }, { signal: requests.signal } )) { if ( item.type === "message" && item.role === "assistant" && item.status === "completed" && item.phase === "final_answer" ) { return item.content .filter((part) => part.type === "output_text") .map((part) => part.text) .join("\n"); } } throw new Error("The completed turn has no final answer");}const deliveryTimer = setTimeout( () => { deadlineReached = true; deliver( finalAnswer || "No results were verified by the briefing deadline." ); turnActive = false; closeQuestions(); requests.abort(); }, Math.max(0, briefingBy.getTime() - Date.now()));try { const agent = await client.beta.agents.create( { name: "Personal assistant", model: "gpt-6.2-astra", instructions: "You are a personal assistant. Deliver useful, well-sourced answers within the user's time constraints. " + "Ask for clarification when it would materially improve the result, and keep making progress while a reply is pending. " + "State important uncertainties.", experimental: { time_awareness: true }, tools: [ { type: "web_search", mode: "live" }, { type: "function", name: "request_user_input_async", description: "Ask the user for context. The result contains their reply or reports that the question expired.", async: true, parameters: { type: "object", properties: { question: { type: "string" }, choices: { type: "array", items: { type: "string" }, description: "Optional suggested replies to display with the question.", }, }, required: ["question"], additionalProperties: false, }, }, ], }, { signal: requests.signal } ); agentId = agent.id; const stream = await client.beta.agents.sessions.create( { agent_id: agent.id, environment: { type: "none" }, stream: true, input: `I am meeting with Pied Piper (example.com) about our customer-support software at ${meetingAt.toISOString()}. ` + "Get me up to speed on their business, recent product announcements, and questions I should ask. " + `Send me a concise briefing by ${briefingBy.toISOString()} so I have time to read it before the meeting.`, }, { signal: requests.signal } ); turnActive = true; for await (const event of stream) { if (event.type === "agent.session.created") { sessionId = event.session.id; } if (event.type === "agent.session.turn.item.done") { const call = event.item; if ( call.type === "function_call" && call.name === "request_user_input_async" ) { const key = `${call.turn_id}:${call.call_id}`; if (!seenCalls.has(key)) { seenCalls.add(key); // Start collecting the reply without blocking the event stream. const task = collectReply(event.session_id, call).catch( (error: unknown) => { replyError = error; requests.abort(); } ); replyTasks.add(task); } } } if ( event.type === "agent.session.turn.item.done" && event.item.type === "message" && event.item.role === "assistant" && event.item.phase === "final_answer" && event.item.status === "completed" ) { finalAnswer = event.item.content.map((part) => part.text).join("\n"); } if (event.type === "agent.session.turn.completed") { turnActive = false; closeQuestions(); finalAnswer = await retrieveAnswer(event.session_id, event.turn.id); deliver(finalAnswer); break; } if ( event.type === "agent.session.turn.failed" || event.type === "agent.session.turn.cancelled" || event.type === "agent.session.failed" || event.type === "agent.session.environment.failed" || event.type === "error" ) { throw new Error(`Agent lifecycle failure: ${event.type}`); } } if (replyError) throw replyError; if (!delivered && !deadlineReached) { throw new Error("The stream closed before the turn completed"); }} catch (error) { if (!deadlineReached) throw replyError || error;} finally { clearTimeout(deliveryTimer); const mustCancel = turnActive || deadlineReached; turnActive = false; closeQuestions(); requests.abort(); await Promise.allSettled(replyTasks); try { if (sessionId) { try { if (mustCancel) { await client.beta.agents.sessions.events.create(sessionId, { events: [{ type: "agent.session.input.cancel" }], }); } } finally { // Cancellation can briefly leave the session busy. await client.beta.agents.sessions.delete(sessionId, { maxRetries: 5, timeout: 10_000, }); } } } finally { if (agentId) await client.beta.agents.delete(agentId); }}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239import asyncioimport jsonimport osimport sysfrom contextlib import AsyncExitStack, suppressfrom datetime importUTC, datetime, timedeltafrom threading import Threadfrom openai import AsyncOpenAI, ConflictErrorfrom openai.types.beta import AgentFunctionCallItem, AgentOutputItem, AgentSessionItemclient = AsyncOpenAI(max_retries=0)asyncdefcreate_agent(client: AsyncOpenAI):returnawait client.beta.agents.create(name="Personal assistant",model="gpt-6.2-astra",experimental={"time_awareness": True},instructions=("You are a personal assistant. Deliver useful, well-sourced answers ""within the user's time constraints. Ask for clarification when it ""would materially improve the result, and keep making progress while ""a reply is pending. State important uncertainties." ),tools=[ {"type": "web_search", "mode": "live"}, {"type": "function","name": "request_user_input_async","description": "Ask for missing context while continuing independent work.","async": True,"parameters": {"type": "object","properties": {"question": {"type": "string"},"choices": {"type": "array", "items": {"type": "string"}}, },"required": ["question"],"additionalProperties": False, }, }, ], )defconsole_replies() -> asyncio.Queue[str]: loop = asyncio.get_running_loop() replies: asyncio.Queue[str] = asyncio.Queue()defread_lines():with os.fdopen( os.dup(sys.stdin.fileno()), encoding=sys.stdin.encoding ) as terminal:for line in terminal:try: loop.call_soon_threadsafe(replies.put_nowait, line.strip())exceptRuntimeError:return# The session and its event loop have closed.# A pending terminal read must not keep the program open after delivery. Thread(target=read_lines, daemon=True).start()return repliesasyncdefrespond(client, session_id, call, replies, prompt_lock, cutoff): loop = asyncio.get_running_loop()try:asyncwith asyncio.timeout_at(cutoff), prompt_lock:if loop.time() >= cutoff:raiseTimeoutErrorprint(call.arguments["question"], file=sys.stderr, flush=True)for choice in call.arguments.get("choices", []):print(f" {choice}", file=sys.stderr, flush=True) reply =await replies.get() answer = reply if loop.time() < cutoff else""exceptTimeoutError: answer ="" result = ( {"status": "answered", "answer": answer} if answer else {"status": "no_answer"} )await client.beta.agents.sessions.events.create( session_id,events=[ {"type": "agent.session.input.tool_result","turn_id": call.turn_id,"call_id": call.call_id,"success": True,"output": json.dumps(result), } ], )deffinal_text(item: AgentSessionItem | AgentOutputItem) -> str:if ( item.type =="message"and item.role =="assistant"and item.status =="completed"and item.phase =="final_answer" ):return"\n".join( part.text for part in item.content if part.type =="output_text" )return""asyncdefretrieve_answer(client: AsyncOpenAI, session_id: str, turn_id: str) -> str:asyncfor item in client.beta.agents.sessions.turns.items.list( turn_id, session_id=session_id, order="desc" ):if text := final_text(item):return textreturn""asyncdefmain():asyncwith client, AsyncExitStack() as cleanup: agent =await create_agent(client) cleanup.push_async_callback(client.beta.agents.delete, agent.id) sessions = client.beta.agents.sessions session_id =None active =False saved_answer ="" questions = {} prompt_lock = asyncio.Lock() replies = console_replies() loop = asyncio.get_running_loop() started = loop.time() reply_cutoff = started +10*60try:asyncwith asyncio.timeout_at(started +12*60): now = datetime.now(UTC) meeting = (now + timedelta(minutes=15)).isoformat(timespec="seconds") delivery = (now + timedelta(minutes=12)).isoformat(timespec="seconds") stream =await client.beta.agents.sessions.create(agent_id=agent.id,environment={"type": "none"},input=(f"I am meeting with Pied Piper (example.com) about our customer-support software at "f"{meeting}. Get me up to speed on their business, recent product "f"announcements, and questions I should ask. Send me a concise briefing by "f"{delivery} so I have time to read it before the meeting." ),stream=True,timeout=12*60, )asyncwith stream:asyncfor event in stream:if event.type =="agent.session.created": session_id = event.session.id# A cancelled turn can take a moment to release its session. cleanup_sessions = client.with_options(max_retries=4, timeout=10 ).beta.agents.sessions cleanup.push_async_callback( cleanup_sessions.delete, session_id ) active =Trueelif event.type =="agent.session.turn.item.done": item = event.itemif (isinstance(item, AgentFunctionCallItem)and item.name =="request_user_input_async"and item.call_id notin questions ): questions[item.call_id] = asyncio.create_task( respond( client, event.session_id, item, replies, prompt_lock, reply_cutoff, ) ) saved_answer = final_text(item) or saved_answerelif event.type =="agent.session.turn.completed": active =Falsefor question in questions.values(): question.cancel()# Allow the creation stream to finish releasing its connection.with suppress(TimeoutError):asyncwith asyncio.timeout(1):asyncfor _ in stream:continue answer =await retrieve_answer( client, event.session_id, event.turn.id )print( answeror saved_answeror"No verified findings were available.",flush=True, )returnelif event.type in ("agent.session.failed","agent.session.environment.failed","agent.session.turn.failed","agent.session.turn.cancelled","error", ): active =FalseraiseRuntimeError(f"Meeting briefing stopped: {event.type}" )for question in questions.values():if question.done(): error = question.exception()# A finished turn can reject a reply still in flight.if error isnotNoneandnotisinstance( error, ConflictError ):raise errorraiseRuntimeError("The event stream closed before the turn completed.")exceptTimeoutError:print( saved_answer or"No verified findings were available by the deadline.",flush=True, )finally:for question in questions.values(): question.cancel()await asyncio.gather(*questions.values(), return_exceptions=True)if active and session_id:await sessions.events.create( session_id, events=[{"type": "agent.session.input.cancel"}] )if__name__=="__main__": asyncio.run(main())
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282package mainimport ( "bufio" "context" "encoding/json" "errors" "fmt" "os" "strings" "time" "github.com/openai/openai-go/v3" "github.com/openai/openai-go/v3/option")func createAgent(ctx context.Context, client *openai.Client) (*openai.Agent, error) { return client.Beta.Agents.New(ctx, openai.BetaAgentNewParams{ Name: openai.String("Personal assistant"), Model: "gpt-6.2-astra", Instructions: openai.String("You are a personal assistant. Deliver useful, well-sourced answers within the user's time constraints. " + "Ask for clarification when it would materially improve the result, and keep making progress while a reply is pending. " + "State important uncertainties."), Experimental: openai.BetaAgentNewParamsExperimental{TimeAwareness: openai.Bool(true)}, Tools: []openai.PersistedAgentToolParamUnion{ {OfParamWebSearch: &openai.PersistedAgentToolParamWebSearch{Mode: "live"}}, {OfParamFunction: &openai.PersistedAgentToolParamFunction{ Name: "request_user_input_async", Description: "Ask for missing context while continuing independent work.", Async: openai.Bool(true), Parameters: map[string]any{ "type": "object", "properties": map[string]any{ "question": map[string]any{"type": "string"}, "choices": map[string]any{"type": "array", "items": map[string]any{"type": "string"}}, }, "required": []string{"question"}, "additionalProperties": false, }, }}, }, })}func returnResult(ctx context.Context, client *openai.Client, sessionID string, call openai.AgentFunctionCallItem, answer string) error { result := map[string]string{"status": "no_answer"} if answer != "" { result = map[string]string{"status": "answered", "answer": answer} } output, err := json.Marshal(result) if err != nil { return err } return client.Beta.Agents.Sessions.Events.New(ctx, sessionID, openai.BetaAgentSessionEventNewParams{ Events: []openai.AgentSessionInputParamUnion{{ OfParamAgentSessionInputToolResult: &openai.AgentSessionInputParamAgentSessionInputToolResult{ TurnID: call.TurnID, CallID: call.CallID, Success: true, Output: openai.AgentFunctionCallOutputParamUnion{OfString: openai.String(string(output))}, }, }}, })}func retrieveAnswer(ctx context.Context, client *openai.Client, sessionID, turnID string) (string, error) { items := client.Beta.Agents.Sessions.Turns.Items.ListAutoPaging(ctx, sessionID, turnID, openai.BetaAgentSessionTurnItemListParams{Order: "desc"}) for items.Next() { item := items.Current() if item.Type == "message" && item.Role == "assistant" && item.Status == "completed" && item.Phase == "final_answer" { var parts []string for _, part := range item.AsMessage().Content { if part.Type == "output_text" { parts = append(parts, part.Text) } } return strings.Join(parts, "\n"), nil } } return "", items.Err()}func consoleReplies(ctx context.Context) <-chan string { lines := make(chan string) go func() { defer close(lines) scanner := bufio.NewScanner(os.Stdin) for scanner.Scan() { select { case lines <- strings.TrimSpace(scanner.Text()): case <-ctx.Done(): return } } }() return lines}type question struct { call openai.AgentFunctionCallItem shown bool}func (q *question) show() error { args, _ := q.call.Arguments.(map[string]any) text, _ := args["question"].(string) if text == "" { return errors.New("the clarification tool did not supply a question") } fmt.Fprintln(os.Stderr, text) choices, _ := args["choices"].([]any) for _, choice := range choices { fmt.Fprintln(os.Stderr, " ", choice) } q.shown = true return nil}func run() (err error) { started := time.Now() replyCutoff := started.Add(10 * time.Minute) briefingBy := started.Add(12 * time.Minute) meetingAt := started.Add(15 * time.Minute) ctx, cancel := context.WithDeadline(context.Background(), briefingBy) defer cancel() client := openai.NewClient(option.WithMaxRetries(0)) var agentID, sessionID, finalText string var active, delivered bool defer func() { if !delivered && errors.Is(ctx.Err(), context.DeadlineExceeded) { if finalText == "" { finalText = "No verified findings were available by the deadline." } fmt.Println(finalText) err = nil } cleanup, finish := context.WithTimeout(context.Background(), time.Minute) defer finish() if sessionID != "" { if active { err = errors.Join(err, client.Beta.Agents.Sessions.Events.New(cleanup, sessionID, openai.BetaAgentSessionEventNewParams{ Events: []openai.AgentSessionInputParamUnion{{OfParamAgentSessionInputCancel: &openai.AgentSessionInputParamAgentSessionInputCancel{}}}, })) } // A cancelled turn can take a moment to release its session. _, deleteErr := client.Beta.Agents.Sessions.Delete(cleanup, sessionID, option.WithMaxRetries(4)) err = errors.Join(err, deleteErr) } if agentID != "" { _, deleteErr := client.Beta.Agents.Delete(cleanup, agentID) err = errors.Join(err, deleteErr) } }() agent, err := createAgent(ctx, &client) if err != nil { return err } agentID = agent.ID streamCtx, stopStream := context.WithCancel(ctx) events := client.Beta.Agents.Sessions.NewStreaming(streamCtx, openai.BetaAgentSessionNewParams{ AgentID: openai.String(agent.ID), Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}}, Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String(fmt.Sprintf( "I am meeting with Pied Piper (example.com) about our customer-support software at %s. "+ "Get me up to speed on their business, recent product announcements, and questions I should ask. "+ "Send me a concise briefing by %s so I have time to read it before the meeting.", meetingAt.UTC().Format(time.RFC3339), briefingBy.UTC().Format(time.RFC3339)))}, }) incoming := make(chan openai.AgentSessionEventUnion) readerDone := make(chan struct{}) go func() { defer close(readerDone) defer close(incoming) defer events.Close() for events.Next() { select { case incoming <- events.Current(): case <-streamCtx.Done(): return } } }() defer func() { stopStream() <-readerDone }() lines := consoleReplies(ctx) cutoffTimer := time.NewTimer(time.Until(replyCutoff)) defer cutoffTimer.Stop() seen := map[string]bool{} var pending []question for { var reply <-chan string if len(pending) != 0 { if !time.Now().Before(replyCutoff) || lines == nil { if err := returnResult(ctx, &client, sessionID, pending[0].call, ""); err != nil { return err } pending = pending[1:] continue } if !pending[0].shown { if err := pending[0].show(); err != nil { return err } } reply = lines } select { case <-ctx.Done(): return ctx.Err() case <-cutoffTimer.C: continue case answer, open := <-reply: if !open { lines = nil } if !time.Now().Before(replyCutoff) { answer = "" } if err := returnResult(ctx, &client, sessionID, pending[0].call, answer); err != nil { return err } pending = pending[1:] case event, open := <-incoming: if !open { if err := events.Err(); err != nil { return err } return errors.New("the session stream closed before the turn finished") } switch event.Type { case "agent.session.created": sessionID, active = event.Session.ID, true case "agent.session.turn.item.done": item := event.AsAgentSessionTurnItemDone().Item if item.Type == "function_call" && item.Name == "request_user_input_async" { call := item.AsFunctionCall() key := call.TurnID + "/" + call.CallID if !seen[key] { seen[key] = true pending = append(pending, question{call: call}) } } if item.Type == "message" && item.Status == "completed" && item.Phase == "final_answer" { var parts []string for _, part := range item.AsMessage().Content { parts = append(parts, part.Text) } finalText = strings.Join(parts, "\n") } case "agent.session.turn.completed": active = false answer, err := retrieveAnswer(ctx, &client, sessionID, event.Turn.ID) if err != nil { return err } if answer == "" { answer = finalText } if answer == "" { return errors.New("the completed turn has no final briefing") } fmt.Println(answer) delivered = true return nil case "agent.session.turn.failed", "agent.session.turn.cancelled", "agent.session.failed", "agent.session.environment.failed", "error": return fmt.Errorf("meeting briefing stopped: %s", event.Type) } } }}func main() { if err := run(); err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) }}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345import com.fasterxml.jackson.databind.json.JsonMapper;import com.openai.client.OpenAIClient;import com.openai.client.okhttp.OpenAIOkHttpClient;import com.openai.core.JsonValue;import com.openai.core.RequestOptions;import com.openai.core.http.StreamResponse;import com.openai.models.beta.agents.AgentCreateParams;import com.openai.models.beta.agents.AgentFunctionCallItem;import com.openai.models.beta.agents.AgentSessionEvent;import com.openai.models.beta.agents.AgentSessionInputParam;import com.openai.models.beta.agents.PersistedAgentToolParam;import com.openai.models.beta.agents.sessions.SessionCreateParams;import com.openai.models.beta.agents.sessions.events.EventCreateParams;import com.openai.models.beta.agents.sessions.turns.items.ItemListParams;import java.io.BufferedReader;import java.io.InputStreamReader;import java.time.Duration;import java.time.Instant;import java.util.HashSet;import java.util.List;import java.util.Map;import java.util.Set;import java.util.concurrent.BlockingQueue;import java.util.concurrent.Executors;import java.util.concurrent.LinkedBlockingQueue;import java.util.concurrent.TimeUnit;import java.util.concurrent.atomic.AtomicBoolean;import java.util.concurrent.atomic.AtomicReference;import java.util.stream.Collectors;public final class MeetingPreparation { public record Question(String question, List<String> choices) {} private final OpenAIClient client = OpenAIOkHttpClient.builder().fromEnv().timeout(Duration.ofSeconds(30)).maxRetries(0).build(); private final Instant startedAt = Instant.now(); private final Instant meetingAt = startedAt.plus(Duration.ofMinutes(15)); private final Instant briefingBy = startedAt.plus(Duration.ofMinutes(12)); private final Instant replyCutoff = startedAt.plus(Duration.ofMinutes(10)); private final BlockingQueue<String> replies = new LinkedBlockingQueue<>(); private final Set<String> seenCalls = new HashSet<>(); private final AtomicBoolean active = new AtomicBoolean(); private final AtomicBoolean expired = new AtomicBoolean(); private final AtomicBoolean delivered = new AtomicBoolean(); private final AtomicReference<StreamResponse<AgentSessionEvent>> streamRef = new AtomicReference<>(); private final AtomicReference<RuntimeException> replyError = new AtomicReference<>(); private final java.util.concurrent.ExecutorService replyWorker = Executors.newSingleThreadExecutor(); private final java.util.concurrent.ScheduledExecutorService timers = Executors.newSingleThreadScheduledExecutor(); private String agentId; private String sessionId; private volatile String finalAnswer = ""; public static void main(String[] args) throws Exception { new MeetingPreparation().run(); } private void run() throws Exception { startInputReader(); var deliveryTimer = timers.schedule( () -> { expired.set(true); deliver( finalAnswer.isBlank() ? "No results were verified by the briefing deadline." : finalAnswer); active.set(false); closeStream(); }, Math.max(0, Duration.between(Instant.now(), briefingBy).toMillis()), TimeUnit.MILLISECONDS); try { var agent = client .beta() .agents() .create( AgentCreateParams.builder() .name("Personal assistant") .model("gpt-6.2-astra") .instructions( "You are a personal assistant. Deliver useful, well-sourced answers" + " within the user's time constraints. Ask for clarification when it" + " would materially improve the result, and keep making progress" + " while a reply is pending. State important uncertainties.") .experimental( AgentCreateParams.Experimental.builder().timeAwareness(true).build()) .addTool( PersistedAgentToolParam.WebSearch.builder() .mode(PersistedAgentToolParam.WebSearch.Mode.LIVE) .build()) .addTool( PersistedAgentToolParam.Function.builder() .name("request_user_input_async") .description( "Ask the user for context. The result contains their reply or" + " reports that the question expired.") .async(true) .parameters( PersistedAgentToolParam.Function.Parameters.builder() .putAdditionalProperty("type", JsonValue.from("object")) .putAdditionalProperty( "properties", JsonValue.from( Map.of( "question", Map.of("type", "string"), "choices", Map.of( "type", "array", "items", Map.of("type", "string"), "description", "Optional suggested replies to" + " display with the question.")))) .putAdditionalProperty( "required", JsonValue.from(List.of("question"))) .putAdditionalProperty( "additionalProperties", JsonValue.from(false)) .build()) .build()) .build()); agentId = agent.id(); if (expired.get()) return; try (var events = client .beta() .agents() .sessions() .createStreaming( SessionCreateParams.builder() .agentId(agent.id()) .environmentNone() .input( "I am meeting with Pied Piper (example.com) about our customer-support software at " + meetingAt + ". Get me up to speed on their business, recent product" + " announcements, and questions I should ask. Send me a concise" + " briefing by " + briefingBy + " so I have time to read it before the meeting.") .build(), RequestOptions.builder() .timeout( Duration.ofMillis( Math.max( 1, Duration.between(Instant.now(), briefingBy).toMillis() + 1000))) .build())) { streamRef.set(events); if (expired.get()) return; active.set(true); var iterator = events.stream().iterator(); while (!expired.get() && iterator.hasNext()) { var event = iterator.next(); event.created().ifPresent(created -> sessionId = created.session().id()); if (event.turnItemDone().isPresent()) { var item = event.turnItemDone().get().item(); if (item.functionCall().isPresent()) { var call = item.functionCall().get(); String key = call.turnId() + ":" + call.callId(); if (call.name().equals("request_user_input_async") && seenCalls.add(key)) { // Collect the reply on another thread while consuming session events. replyWorker.submit( () -> collectReply(event.turnItemDone().get().sessionId(), call)); } } } event .turnItemDone() .flatMap(done -> done.item().message()) .filter(message -> message.status().toString().equals("completed")) .filter( message -> message .phase() .map(phase -> phase.toString().equals("final_answer")) .orElse(false)) .ifPresent( message -> finalAnswer = message.content().stream() .map(part -> part.text()) .collect(Collectors.joining("\n"))); if (event.turnCompleted().isPresent()) { active.set(false); replyWorker.shutdownNow(); var completed = event.turnCompleted().get(); finalAnswer = retrieveAnswer(completed.sessionId(), completed.turn().id()); deliver(finalAnswer); break; } if (event.turnFailed().isPresent() || event.turnCancelled().isPresent() || event.failed().isPresent() || event.environmentFailed().isPresent() || event.error().isPresent()) { throw new IllegalStateException("Agent lifecycle failure: " + event); } } } if (replyError.get() != null) throw replyError.get(); if (!delivered.get()) throw new IllegalStateException("Stream closed before the turn completed"); } catch (RuntimeException error) { if (!expired.get()) throw error; } finally { deliveryTimer.cancel(false); boolean mustCancel = active.getAndSet(false) || expired.get(); replyWorker.shutdownNow(); timers.shutdownNow(); closeStream(); try { if (sessionId != null) { try { if (mustCancel) { client .beta() .agents() .sessions() .events() .create( EventCreateParams.builder() .sessionId(sessionId) .addEventAgentSessionInputCancel() .build()); } } finally { // Cancellation settles asynchronously; retry a temporary deletion conflict. client .withOptions(options -> options.maxRetries(5).timeout(Duration.ofSeconds(10))) .beta() .agents() .sessions() .delete(sessionId); } } } finally { if (agentId != null) client.beta().agents().delete(agentId); } } } private void collectReply(String sessionId, AgentFunctionCallItem call) { try { var question = call._arguments().convert(Question.class); System.err.println(question.question()); if (question.choices() != null) System.err.println(String.join(" / ", question.choices())); long remaining = Math.max(0, Duration.between(Instant.now(), replyCutoff).toMillis()); String answer = remaining == 0 ? null : replies.poll(remaining, TimeUnit.MILLISECONDS); if (Instant.now().isAfter(replyCutoff)) answer = null; if (active.get() && !expired.get()) returnResult(sessionId, call, answer); } catch (InterruptedException ignored) { Thread.currentThread().interrupt(); } catch (Exception error) { if (active.get() && !expired.get()) { replyError.set(new IllegalStateException("Could not return the reply", error)); closeStream(); } } } private void returnResult(String sessionId, AgentFunctionCallItem call, String answer) throws Exception { var result = answer == null || answer.isBlank() ? Map.of("status", "no_answer") : Map.of("status", "answered", "answer", answer); client .beta() .agents() .sessions() .events() .create( EventCreateParams.builder() .sessionId(sessionId) .addEvent( AgentSessionInputParam.AgentSessionInputToolResult.builder() .turnId(call.turnId()) .callId(call.callId()) .success(true) .output(new JsonMapper().writeValueAsString(result)) .build()) .build()); } private String retrieveAnswer(String sessionId, String turnId) { var items = client .beta() .agents() .sessions() .turns() .items() .list( ItemListParams.builder() .sessionId(sessionId) .turnId(turnId) .order(ItemListParams.Order.DESC) .build()); for (var item : items.autoPager()) { if (item.message().isEmpty()) continue; var message = item.message().get(); if (message.role().toString().equals("assistant") && message.status().toString().equals("completed") && message.phase().map(phase -> phase.toString().equals("final_answer")).orElse(false)) { return message.content().stream() .flatMap(part -> part.outputText().stream()) .map(part -> part.text()) .collect(Collectors.joining("\n")); } } throw new IllegalStateException("The completed turn has no final answer"); } private void deliver(String text) { if (delivered.compareAndSet(false, true)) System.out.println(text); } private void closeStream() { var stream = streamRef.getAndSet(null); if (stream != null) stream.close(); } private void startInputReader() { var input = new Thread( () -> { try { var reader = new BufferedReader(new InputStreamReader(System.in)); String line; while ((line = reader.readLine()) != null) replies.add(line.trim()); } catch (java.io.IOException error) { System.err.println("Input closed: " + error.getMessage()); } }); input.setDaemon(true); input.start(); }}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199require "openai"require "json"require "time"require "timeout"def create_agent(client) client.beta.agents.create( name: "Personal assistant", model: "gpt-6.2-astra", experimental: { time_awareness: true }, instructions: "You are a personal assistant. Deliver useful, well-sourced answers " \ "within the user's time constraints. Ask for clarification when it would " \ "materially improve the result, and keep making progress while a reply is " \ "pending. State important uncertainties.", tools: [ { type: "web_search", mode: "live" }, { type: "function", name: "request_user_input_async", description: "Ask for missing context while continuing independent work.", async: true, parameters: { type: "object", properties: { question: { type: "string" }, choices: { type: "array", items: { type: "string" } } }, required: ["question"], additionalProperties: false } } ] )enddef monotonic_time Process.clock_gettime(Process::CLOCK_MONOTONIC)enddef console_reply(arguments, input_lock, cutoff) remaining = cutoff - monotonic_time return if remaining <= 0 Timeout.timeout(remaining) do input_lock.synchronize do return if monotonic_time >= cutoff question = arguments.transform_keys(&:to_s) warn question.fetch("question") Array(question["choices"]).each { |choice| warn " #{choice}" } line = $stdin.gets sleep([cutoff - monotonic_time, 0].max) if line.nil? line&.strip if monotonic_time < cutoff end endrescue Timeout::Error nilenddef return_result(sessions, session_id, call, answer) result = if answer.nil? || answer.empty? { status: "no_answer" } else { status: "answered", answer: answer } end sessions.events.create( session_id, events: [ { type: "agent.session.input.tool_result", turn_id: call.turn_id, call_id: call.call_id, success: true, output: JSON.generate(result) } ] )enddef final_text(item) return unless item.type.to_s == "message" && item.role.to_s == "assistant" && item.status.to_s == "completed" && item.phase.to_s == "final_answer" text = item.content.select { |part| part.type.to_s == "output_text" }.map(&:text).join("\n") text unless text.empty?enddef retrieve_answer(sessions, session_id, turn_id) page = sessions.turns.items.list(turn_id, session_id: session_id, order: "desc") page.auto_paging_each do |item| text = final_text(item) return text if text && !text.empty? end nilenddef prepare_briefing(client, agent_id) sessions = client.beta.agents.sessions state = { session_id: nil, stream: nil, status: nil, answer: nil } questions = {} input_lock = Mutex.new cutoff = monotonic_time + 10 * 60 begin Timeout.timeout(12 * 60) do now = Time.now.utc meeting = (now + 15 * 60).iso8601 delivery = (now + 12 * 60).iso8601 stream = sessions.create_streaming( agent_id: agent_id, environment: { type: "none" }, input: "I am meeting with Pied Piper (example.com) about our customer-support software " \ "at #{meeting}. Get me up to speed on their business, recent product " \ "announcements, and questions I should ask. Send me a concise briefing " \ "by #{delivery} so I have time to read it before the meeting." ) state[:stream] = stream stream.each do |event| questions.each_value { |thread| thread.value unless thread.alive? } case event when OpenAI::Models::Beta::AgentSessionCreatedEvent state[:session_id] = event.session.id state[:status] = :active when OpenAI::Models::Beta::AgentSessionTurnItemDoneEvent item = event.item if item.is_a?(OpenAI::Models::Beta::AgentFunctionCallItem) && item.name == "request_user_input_async" && !questions.key?(item.call_id) questions[item.call_id] = Thread.new(item, event.session_id) do |call, id| answer = console_reply(call.arguments, input_lock, cutoff) return_result(sessions, id, call, answer) rescue OpenAI::Errors::ConflictError # The turn can finish while the reply is in flight. nil end end state[:answer] = final_text(item) || state[:answer] when OpenAI::Models::Beta::AgentSessionTurnCompletedEvent state[:status] = :completed questions.each_value(&:kill) state[:answer] = retrieve_answer(sessions, event.session_id, event.turn.id) || state[:answer] break when OpenAI::Models::Beta::AgentSessionTurnFailedEvent, OpenAI::Models::Beta::AgentSessionTurnCancelledEvent, OpenAI::Models::Beta::AgentSessionFailedEvent, OpenAI::Models::Beta::AgentSessionEnvironmentFailedEvent state[:status] = :failed raise "Meeting briefing stopped: #{event.type}" when OpenAI::Models::Beta::AgentSessionErrorEvent raise "Meeting briefing stopped: #{event.type}" end end raise "The event stream closed before the turn completed." unless state[:status] == :completed end puts(state[:answer] || "No verified findings were available.") rescue Timeout::Error puts(state[:answer] || "No verified findings were available by the deadline.") ensure $stdout.flush questions.each_value(&:kill) begin state[:stream]&.close session_id = state[:session_id] sessions.events.create(session_id, events: [{ type: "agent.session.input.cancel" }]) if state[:status] == :active && session_id ensure if state[:session_id] # Cancellation settles asynchronously; retry a temporary deletion conflict. sessions.delete( state[:session_id], request_options: { max_retries: 5, timeout: 10 } ) end end endendclient = OpenAI::Client.new(max_retries: 0, timeout: 12 * 60)agent = create_agent(client)begin prepare_briefing(client, agent.id)ensure client.beta.agents.delete(agent.id)end
Prise en compte du temps dans une boucle de l’API Responses
Si vous avez vous-même écrit la boucle d’appels à l’API Responses de votre agent personnel, votre application doit tenir le modèle informé du temps qui lui reste pour préparer la note. Calculez l’échéance une seule fois, puis ajoutez un rappel de l’heure avant chaque requête au modèle, y compris celles qui transmettent des résultats d’outils.
Les étapes ci-dessous mettent en œuvre la même tâche de préparation de réunion. Chaque requête à l’API Responses indique au modèle l’heure qu’il est. Une minuterie reste active dans l’application tout au long de la boucle pour assurer la remise de la note même si une requête ou un outil prend trop de temps.
1. Fixez l’heure de la réunion et l’échéance de la note
Indiquez à l’agent sur quelle entreprise il doit se renseigner et à quelle heure il doit remettre la note. Conservez les mêmes instructions générales et le même outil de questionnement asynchrone pour que le modèle décide s’il a besoin de précisions.
La réunion commence dans 15 minutes, la note est attendue dans 12 minutes et l’application ferme les questions restées sans réponse 10 minutes après le début de la tâche. Gardez ces échéances fixes tout au long de la tâche.
Configuration de la tâche de préparation de réunion avec l’API Responses
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59import OpenAI from "openai";import { createInterface } from "node:readline";const requests = new AbortController();const instructions = "You are a personal assistant. Deliver useful, well-sourced answers within the user's time constraints. " + "Ask for clarification when it would materially improve the result, and keep making progress while a reply is pending. " + "State important uncertainties.";const tools: OpenAI.Responses.Tool[] = [ { type: "web_search" }, { type: "function", name: "request_user_input_async", description: "Ask the user for context. The result contains their reply or reports that the question expired.", async: true, strict: false, parameters: { type: "object", properties: { question: { type: "string" }, choices: { type: "array", items: { type: "string" }, description: "Optional suggested replies to display with the question.", }, }, required: ["question"], additionalProperties: false, }, },];const startedAt = Date.now();const monotonicStart = performance.now();const meetingAt = new Date(startedAt + 15 * 60_000);const briefingBy = new Date(startedAt + 12 * 60_000);const deliveryLimit = monotonicStart + 12 * 60_000;const replyLimit = monotonicStart + 10 * 60_000;const initialInput: OpenAI.Responses.ResponseInput = [ { role: "user", content: `I am meeting with Pied Piper (example.com) about our customer-support software at ${meetingAt.toISOString()}. ` + "Get me up to speed on their business, recent product announcements, and questions I should ask. " + `Send me a concise briefing by ${briefingBy.toISOString()} so I have time to read it before the meeting.`, },];const responseIds = new Set<string>();let latestResponseId: string | undefined;let finalAnswer = "";let delivered = false;let deadlineReached = false;let closed = false;let replyError: unknown;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72import asyncioimport jsonimport osimport sysfrom contextlib import suppressfrom dataclasses import dataclass, fieldfrom datetime importUTC, datetime, timedeltafrom threading import Threadfrom openai import APITimeoutError, AsyncOpenAI, OpenAIErrorfrom openai.types.responses import ( Response, ResponseFunctionToolCall, ResponseInputItemParam, ToolParam,)instructions = ("You are a personal assistant. Deliver useful, well-sourced answers ""within the user's time constraints. Ask for clarification when it ""would materially improve the result, and keep making progress while ""a reply is pending. State important uncertainties.")tools: list[ToolParam] = [ {"type": "web_search"}, {"type": "function","name": "request_user_input_async","description": "Ask for missing context while continuing independent work.","async": True,"strict": False,"parameters": {"type": "object","properties": {"question": {"type": "string"},"choices": {"type": "array", "items": {"type": "string"}}, },"required": ["question"],"additionalProperties": False, }, },]@dataclassclassState: response_ids: list[str] = field(default_factory=list) questions: dict[str, asyncio.Task[ResponseInputItemParam]] = field(default_factory=dict ) seen_calls: set[str] = field(default_factory=set) latest_response_id: str|None=None saved_answer: str=""defconfigure_task(): now = datetime.now(UTC) started = asyncio.get_running_loop().time() meeting = (now + timedelta(minutes=15)).isoformat(timespec="seconds") delivery = (now + timedelta(minutes=12)).isoformat(timespec="seconds") reply_cutoff = started +10*60 delivery_cutoff = started +12*60 input_items = [ {"role": "user","content": (f"I am meeting with Pied Piper (example.com) about our customer-support software at "f"{meeting}. Get me up to speed on their business, recent product "f"announcements, and questions I should ask. Send me a concise briefing by "f"{delivery} so I have time to read it before the meeting." ), } ]return input_items, reply_cutoff, delivery_cutoff
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50package mainimport ( "bufio" "context" "encoding/json" "errors" "fmt" "os" "strings" "sync" "time" "github.com/openai/openai-go/v3" "github.com/openai/openai-go/v3/option" "github.com/openai/openai-go/v3/packages/ssestream" "github.com/openai/openai-go/v3/responses")const instructions = "You are a personal assistant. Deliver useful, well-sourced answers " + "within the user's time constraints. Ask for clarification when it would " + "materially improve the result, and keep making progress while a reply is " + "pending. State important uncertainties."func meetingTools() []responses.ToolUnionParam { question := responses.ToolParamOfFunction("request_user_input_async", map[string]any{ "type": "object", "properties": map[string]any{ "question": map[string]string{"type": "string"}, "choices": map[string]any{"type": "array", "items": map[string]string{"type": "string"}}, }, "required": []string{"question"}, "additionalProperties": false, }, false) question.OfFunction.Async = openai.Bool(true) question.OfFunction.Description = openai.String("Ask for missing context while continuing independent work.") return []responses.ToolUnionParam{responses.ToolParamOfWebSearch("web_search"), question}}func deadlines(now time.Time) (meeting, delivery, replyCutoff time.Time) { return now.Add(15 * time.Minute), now.Add(12 * time.Minute), now.Add(10 * time.Minute)}func userRequest(meeting, delivery time.Time) responses.ResponseInputParam { text := fmt.Sprintf("I am meeting with Pied Piper (example.com) about our customer-support software at %s. "+ "Get me up to speed on their business, recent product announcements, and questions I should ask. "+ "Send me a concise briefing by %s so I have time to read it before the meeting.", meeting.UTC().Format(time.RFC3339), delivery.UTC().Format(time.RFC3339)) return responses.ResponseInputParam{responses.ResponseInputItemParamOfMessage(text, "user")}}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97import com.fasterxml.jackson.databind.json.JsonMapper;import com.openai.client.OpenAIClient;import com.openai.client.okhttp.OpenAIOkHttpClient;import com.openai.core.JsonValue;import com.openai.core.RequestOptions;import com.openai.core.http.AsyncStreamResponse;import com.openai.models.responses.EasyInputMessage;import com.openai.models.responses.FunctionTool;import com.openai.models.responses.ResponseCreateParams;import com.openai.models.responses.ResponseFunctionToolCall;import com.openai.models.responses.ResponseInputItem;import com.openai.models.responses.ResponseStreamEvent;import com.openai.models.responses.Tool;import com.openai.models.responses.WebSearchTool;import java.io.BufferedReader;import java.io.InputStreamReader;import java.time.Duration;import java.time.Instant;import java.util.ArrayList;import java.util.List;import java.util.Map;import java.util.Optional;import java.util.Set;import java.util.concurrent.BlockingQueue;import java.util.concurrent.CompletableFuture;import java.util.concurrent.ConcurrentHashMap;import java.util.concurrent.ExecutorService;import java.util.concurrent.Executors;import java.util.concurrent.LinkedBlockingQueue;import java.util.concurrent.ScheduledExecutorService;import java.util.concurrent.TimeUnit;import java.util.concurrent.atomic.AtomicBoolean;import java.util.concurrent.atomic.AtomicReference;import java.util.stream.Collectors;private final String instructions = "You are a personal assistant. Deliver useful, well-sourced answers within the user's time" + " constraints. Ask for clarification when it would materially improve the result, and" + " keep making progress while a reply is pending. State important uncertainties.";private final List<Tool> tools = List.of( Tool.ofWebSearch(WebSearchTool.builder().type(WebSearchTool.Type.WEB_SEARCH).build()), Tool.ofFunction( FunctionTool.builder() .name("request_user_input_async") .description( "Ask the user for context. The result contains their reply or reports that the question expired.") .async(true) .strict(false) .parameters( FunctionTool.Parameters.builder() .putAdditionalProperty("type", JsonValue.from("object")) .putAdditionalProperty( "properties", JsonValue.from( Map.of( "question", Map.of("type", "string"), "choices", Map.of( "type", "array", "items", Map.of("type", "string"), "description", "Optional suggested replies to display with the question.")))) .putAdditionalProperty("required", JsonValue.from(List.of("question"))) .putAdditionalProperty("additionalProperties", JsonValue.from(false)) .build()) .build()));private final Instant startedAt = Instant.now();private final long monotonicStart = System.nanoTime();private final Instant meetingAt = startedAt.plus(Duration.ofMinutes(15));private final Instant briefingBy = startedAt.plus(Duration.ofMinutes(12));private final long deliveryLimit = monotonicStart + Duration.ofMinutes(12).toNanos();private final long replyLimit = monotonicStart + Duration.ofMinutes(10).toNanos();private final List<ResponseInputItem> initialInput = List.of( ResponseInputItem.ofEasyInputMessage( EasyInputMessage.builder() .role(EasyInputMessage.Role.USER) .content( "I am meeting with Pied Piper (example.com) about our customer-support software at " + meetingAt + ". Get me up to speed on their business, recent product announcements," + " and questions I should ask. Send me a concise briefing by " + briefingBy + " so I have time to read it before the meeting.") .build()));private final Set<String> responseIds = ConcurrentHashMap.newKeySet();private final AtomicReference<AsyncStreamResponse<ResponseStreamEvent>> streamRef = new AtomicReference<>();private final AtomicBoolean expired = new AtomicBoolean();private final AtomicBoolean delivered = new AtomicBoolean();private final AtomicBoolean closed = new AtomicBoolean();private final AtomicReference<RuntimeException> replyError = new AtomicReference<>();private volatile String latestResponseId;private volatile String finalAnswer = "";
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49require "json"require "openai"require "time"require "timeout"INSTRUCTIONS = "You are a personal assistant. Deliver useful, well-sourced answers " \ "within the user's time constraints. Ask for clarification when it would " \ "materially improve the result, and keep making progress while a reply is " \ "pending. State important uncertainties."TOOLS = [ { type: "web_search" }, { type: "function", name: "request_user_input_async", description: "Ask for missing context while continuing independent work.", async: true, strict: false, parameters: { type: "object", properties: { question: { type: "string" }, choices: { type: "array", items: { type: "string" } } }, required: ["question"], additionalProperties: false } }].freezedef deadlines(now) { meeting: now + 15 * 60, delivery: now + 12 * 60, reply: now + 10 * 60 }enddef user_request(meeting, delivery) { role: "user", content: "I am meeting with Pied Piper (example.com) about our customer-support software at " \ "#{meeting.utc.iso8601}. Get me up to speed on their business, recent product " \ "announcements, and questions I should ask. Send me a concise briefing by " \ "#{delivery.utc.iso8601} so I have time to read it before the meeting." }end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50work=$(mktemp -d)stream_pid=""timer_pid=""reader_pid=""owned='[]'latest_response_id=""pending='{}'seen='{}'ready='[]'exec 4<&0started=$(date +%s)reply_cutoff=$((SECONDS + 10 * 60))delivery_cutoff=$((SECONDS + 12 * 60))meeting=$(jq -nr --argjson start "$started" '$start + 900 | strftime("%Y-%m-%dT%H:%M:%SZ")')delivery=$(jq -nr --argjson start "$started" '$start + 720 | strftime("%Y-%m-%dT%H:%M:%SZ")')input=$(jq -nc --arg meeting "$meeting" --arg delivery "$delivery" '[{ role: "user", content: ("I am meeting with Pied Piper (example.com) about our customer-support software at " + $meeting + ". Get me up to speed on their business, recent product announcements, " + "and questions I should ask. Send me a concise briefing by " + $delivery + " so I have time to read it before the meeting.")}]')configuration=$(cat <<'JSON'{ "model": "gpt-6.2-astra", "instructions": "You are a personal assistant. Deliver useful, well-sourced answers within the user's time constraints. Ask for clarification when it would materially improve the result, and keep making progress while a reply is pending. State important uncertainties.", "tools": [ {"type": "web_search"}, { "type": "function", "name": "request_user_input_async", "description": "Ask for missing context while continuing independent work.", "async": true, "strict": false, "parameters": { "type": "object", "properties": { "question": {"type": "string"}, "choices": {"type": "array", "items": {"type": "string"}} }, "required": ["question"], "additionalProperties": false } } ], "store": true, "stream": true}JSON)
2. Ajoutez l’heure avant chaque requête au modèle
Le modèle a besoin de connaître l’heure au moment de choisir sa prochaine action. Utilisez la même fonction pour envoyer la requête initiale et toutes les requêtes suivantes. Vous n’aurez ainsi qu’un seul endroit où actualiser l’heure.
Juste avant d’appeler l’API Responses, ajoutez l’heure UTC actuelle dans un message de développeur, après la saisie de l’utilisateur ou les résultats d’outils. Envoyez les instructions et les outils à chaque requête. L’échéance initiale reste dans l’historique de la conversation.
Actualisation de l’heure et création d’une réponse
Lorsque l’agent demande quel est l’objet de la réunion, affichez la question et recueillez la réponse de l’utilisateur indépendamment de la génération de la réponse du modèle. Le gestionnaire de saisie renvoie la réponse de l’utilisateur dès qu’elle arrive, ou no_answer à l’heure limite. Il utilise le call_id d’origine pour associer le résultat à la bonne question.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44# Buffer terminal replies independently of the event stream.next_reply=1( number=1 while IFS= read -r line || [ -n "$line" ]; do printf '%s\n' "$line" >"$work/incoming" mv "$work/incoming" "$work/reply-$number" number=$((number + 1)) done) <&4 &reader_pid=$!register_question() { local call=$1 call_id call_id=$(jq -r '.call_id' <<<"$call") if jq -e --arg id "$call_id" 'has($id)' <<<"$seen" >/dev/null; then return; fi seen=$(jq -c --arg id "$call_id" '.[$id] = true' <<<"$seen") pending=$(jq -c --arg id "$call_id" --argjson call "$call" '.[$id] = $call' <<<"$pending") if [ "$SECONDS" -lt "$reply_cutoff" ]; then jq -r '.arguments | fromjson | .question, (.choices[]? // empty)' <<<"$call" >&2 fi}collect_replies() { local call_id answer result while :; do call_id=$(jq -r 'keys_unsorted[0] // empty' <<<"$pending") if [ -z "$call_id" ]; then break; fi answer="" if [ "$SECONDS" -lt "$reply_cutoff" ]; then if [ ! -f "$work/reply-$next_reply" ]; then break; fi IFS= read -r answer <"$work/reply-$next_reply" next_reply=$((next_reply + 1)) fi if [ "$SECONDS" -ge "$reply_cutoff" ]; then answer=""; fi result=$(jq -nc --arg answer "$answer" ' if $answer == "" then {status: "no_answer"} else {status: "answered", answer: $answer} end') ready=$(jq -c --arg id "$call_id" --arg result "$result" '. + [{ type: "function_call_output", call_id: $id, output: $result }]' <<<"$ready") pending=$(jq -c --arg id "$call_id" 'del(.[$id])' <<<"$pending") done}
4. Traitez les questions et les réponses terminées
Démarrez le gestionnaire de saisie dès que la question complète arrive dans le flux de réponse. Continuez à lire les événements pendant que l’utilisateur réfléchit à sa réponse afin que le modèle puisse poursuivre ses recherches sur le web.
Lorsque le modèle termine une réponse, enregistrez son identifiant pour la requête suivante et conservez toute note achevée pour pouvoir la remettre à l’utilisateur. Le gestionnaire d’événements enregistre également les identifiants des réponses pour permettre leur suppression ultérieure.
Lecture des questions du flux et des réponses terminées
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35def final_text(item) return unless item.is_a?(OpenAI::Models::Responses::ResponseOutputMessage) return unless item.role.to_s == "assistant" && item.status.to_s == "completed" return unless item.phase.nil? || item.phase.to_s == "final_answer" text = item.content.filter_map { |part| part.text if part.is_a?(OpenAI::Models::Responses::ResponseOutputText) }.join("\n") text unless text.empty?enddef consume(stream, state, jobs, seen, input_lock, cutoff) stream.each do |event| case event when OpenAI::Models::Responses::ResponseCreatedEvent state[:ids][event.response.id] = true when OpenAI::Models::Responses::ResponseOutputItemDoneEvent item = event.item if item.is_a?(OpenAI::Models::Responses::ResponseFunctionToolCall) && item.name == "request_user_input_async" && !seen.key?(item.call_id) seen[item.call_id] = true jobs[item.call_id] = start_question(item, input_lock, cutoff) end when OpenAI::Models::Responses::ResponseCompletedEvent state[:ids][event.response.id] = true state[:latest_id] = event.response.id answer = event.response.output.filter_map { |item| final_text(item) }.join("\n") state[:saved_answer] = answer unless answer.empty? return answer when OpenAI::Models::Responses::ResponseFailedEvent, OpenAI::Models::Responses::ResponseIncompleteEvent, OpenAI::Models::Responses::ResponseErrorEvent raise "Response stopped: #{event.type}" end end raise "The stream closed before response.completed."end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58read_response() { local chunk buffer="" line event event_type id current_answer="" while :; do chunk="" if IFS= read -r -t 1 -u 3 chunk; then line="$buffer$chunk" buffer="" if [[ "$line" == 'data: '* && "$line" != 'data: [DONE]' ]]; then event=${line#data: } event_type=$(jq -r '.type' <<<"$event") if [ "$event_type" = response.created ]; then id=$(jq -er '.response.id' <<<"$event") owned=$(jq -c --arg id "$id" 'if index($id) then . else . + [$id] end' <<<"$owned") elif [ "$event_type" = response.output_item.done ] && \ jq -e '.item.type == "function_call" and .item.name == "request_user_input_async"' \ <<<"$event" >/dev/null; then register_question "$(jq -c '.item' <<<"$event")" elif [ "$event_type" = response.completed ]; then latest_response_id=$(jq -er '.response.id' <<<"$event") current_answer=$(jq -r '[.response.output[] | select(.type == "message" and .status == "completed" and (.phase == "final_answer" or .phase == null)) | .content[] | select(.type == "output_text") | .text] | join("\n")' <<<"$event") if [ -n "$current_answer" ]; then printf '%s\n' "$current_answer" >"$work/candidate.txt" mv "$work/candidate.txt" "$work/final.txt" fi collect_replies if wait "$stream_pid"; then : else status=$? if [ "$status" -eq 28 ]; then deliver; exit 0; fi return "$status" fi stream_pid="" exec 3<&- return elif [[ "$event_type" == response.failed || "$event_type" == response.incomplete || "$event_type" == error ]]; then printf 'Meeting briefing stopped: %s\n' "$event_type" >&2 return 1 fi fi else buffer="$buffer$chunk" if ! kill -0 "$stream_pid" 2>/dev/null; then if wait "$stream_pid"; then : else status=$? if [ "$status" -eq 28 ]; then deliver; exit 0; fi fi printf '%s\n' 'The response stream closed before completion.' >&2 return 1 fi fi collect_replies done}
5. Poursuivez la boucle avec les résultats disponibles
La version suivante de la note doit tenir compte de toute réponse de l’utilisateur reçue pendant les recherches. Après chaque réponse du modèle, recueillez les résultats d’outils disponibles et envoyez-les avec la fonction d’envoi des requêtes, qui ajoute un nouveau rappel de l’heure. Utilisez l’identifiant de la dernière réponse terminée comme valeur de previous_response_id, même lorsqu’un résultat correspond à une question posée dans une réponse antérieure.
Envoyez les requêtes l’une après l’autre pour que chacune s’appuie sur le dernier état de la conversation. Si la note est terminée et qu’aucun résultat d’outil n’est disponible, remettez-la à l’utilisateur et fermez les questions en attente. Sinon, poursuivez le travail en tenant compte de l’heure actualisée, sans attendre de réponse de l’utilisateur.
Poursuite des recherches et prise en compte des réponses
Python
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15async function runLoop() { let nextInput = initialInput; while (!delivered) { const answer = await consumeEvents(await request(nextInput)); if (replyError) throw replyError; nextInput = readyResults.splice(0); if (nextInput.length > 0) continue; if (answer) { closeQuestions(); deliver(answer); } // With no final answer or ready result, the next request continues work. // It receives a fresh clock message without waiting for pending replies. }}
1
2
3
4
5
6
7
8
9
10
11
12
13while [ "$SECONDS" -lt "$delivery_cutoff" ]; do start_response read_response collect_replies if [ "$(jq length <<<"$ready")" -gt 0 ]; then input="$ready" ready='[]' continue fi if [ -n "$current_answer" ]; then deliver; exit 0; fi input='[{"role":"developer","content":"Continue working on the briefing while replies are pending."}]'donedeliver
6. Respectez l’échéance même si une requête est en cours
Une minuterie dans l’application fait respecter l’heure de remise de la note pour que l’utilisateur dispose du temps prévu pour la lire. Appliquez cette minuterie à toute la boucle, y compris aux requêtes à l’API et à la lecture du flux.
À l’échéance, arrêtez la requête en cours et remettez la note enregistrée, ou indiquez qu’aucun résultat vérifié n’est disponible. Après la remise de la note, fermez les gestionnaires de saisie encore en attente et supprimez les réponses stockées.
Remise de la note à temps et libération des ressources de la tâche
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49private final ScheduledExecutorService timers = Executors.newSingleThreadScheduledExecutor();private void deliver(String text) { if (delivered.compareAndSet(false, true)) System.out.println(text);}private void closeStream() { var stream = streamRef.getAndSet(null); if (stream != null) stream.close();}private void run() { startInputReader(); var deliveryTimer = timers.schedule( () -> { expired.set(true); deliver( finalAnswer.isBlank() ? "No results were verified by the briefing deadline." : finalAnswer); closeQuestions(); closeStream(); }, Math.max(0, deliveryLimit - System.nanoTime()), TimeUnit.NANOSECONDS); try { runLoop(); } catch (RuntimeException error) { if (!expired.get()) throw error; } finally { deliveryTimer.cancel(false); closeQuestions(); closeStream(); timers.shutdownNow(); RuntimeException cleanupFailure = null; for (String id : responseIds) { try { client.responses().delete(id); } catch (RuntimeException error) { if (cleanupFailure == null) cleanupFailure = new IllegalStateException("Could not delete every stored response"); cleanupFailure.addSuppressed(error); } } client.close(); if (cleanupFailure != null) throw cleanupFailure; }}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23times = deadlines(Time.now.utc)state = { ids: {}, latest_id: nil, saved_answer: nil}jobs = {}begin answer = Timeout.timeout(times[:delivery] - Time.now) do prepare(client, state, jobs, times) end puts answerrescue Timeout::Error puts(state[:saved_answer] || "No verified findings were available by the deadline.")ensure $stdout.flush jobs.each_value(&:kill) state[:ids].each_key do |id| client.responses.delete(id) rescue OpenAI::Errors::APIError => error warn "Could not delete response #{id}: #{error.message}" endend
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37cleanup() { local exit_status=$? trap - EXIT TERM for pid in "$stream_pid" "$timer_pid" "$reader_pid"; do if [ -n "$pid" ]; then kill "$pid" 2>/dev/null || true wait "$pid" 2>/dev/null || true fi done while IFS= read -r response_id; do curl --fail-with-body --silent --show-error --max-time 10 -X DELETE \ "https://api.openai.com/v1/responses/$response_id" \ -H "Authorization: Bearer $OPENAI_API_KEY" >/dev/null || exit_status=1 done < <(jq -r 'reverse[]' <<<"$owned") rm -rf "$work" exit "$exit_status"}deliver() { if mkdir "$work/delivered" 2>/dev/null; then if [ -s "$work/final.txt" ]; then cat "$work/final.txt" else printf '%s\n' 'No verified findings were available by the deadline.' fi fi}trap cleanup EXITtrap 'exit 0' TERM( sleep "$((delivery_cutoff - SECONDS))" & sleep_pid=$! trap 'kill "$sleep_pid" 2>/dev/null || true; wait "$sleep_pid" 2>/dev/null || true; exit 0' TERM wait "$sleep_pid" deliver kill -TERM "$$") &timer_pid=$!
Conclusion
Les agents personnels doivent parfois terminer leur travail dans un délai précis. Dans l’idéal, ils demandent des précisions pour améliorer le résultat. Même sans ces précisions, ils doivent pouvoir accomplir un travail utile.
Nous avons fixé une échéance à l’agent et activé la prise en compte du temps pour l’aider à décider s’il doit approfondir ses recherches, vérifier une information ou terminer la rédaction. Les outils de type fonction asynchrones lui ont permis de poursuivre ses recherches pendant que l’utilisateur réfléchissait à sa réponse. Même si la question reste sans réponse, l’agent dispose d’assez de contexte pour rédiger une note utile à la préparation de la réunion.
ChatGPT et d’autres harnais d’agents utilisent cette approche pour poursuivre le travail tout en demandant des précisions à l’utilisateur. Nous espérons que la prise en compte du temps dans l’API Agents vous aidera à mettre en œuvre cette approche dans vos propres applications. Montrez-nous ce que vous créez !