Para ver el índice completo de la documentación, consulta llms.txt. Para ver la versión en Markdown de una página de la documentación, agrega
.md al final de la URL de esa página.
Seguimiento del tiempo y respuestas asíncronas del usuario en agentes personales
Cómo crear agentes que tengan en cuenta los plazos y sigan trabajando mientras esperan una respuesta del usuario
Autor: Kevin Whinnery
Si estás creando un agente personal similar a un dot, a menudo querrás que le entregue los resultados al usuario dentro de un plazo determinado.
Supongamos que en 15 minutos tengo una reunión con un posible cliente. Le pido a mi agente que investigue a la empresa y prepare un informe breve que me deje tres minutos para leerlo antes de la reunión. Más o menos con ese margen suelo prepararme para las reuniones durante la jornada laboral 😬.
El agente se da cuenta de que no le dije si la reunión es para hacer una evaluación técnica o para hablar de precios. De eso depende qué detalles conviene investigar y qué información incluir en el informe.
El agente decide preguntarme cuál es el objetivo de la reunión. ¿Cómo puede aprovechar el tiempo que queda mientras espera, incorporar mi respuesta si llega y entregar un informe útil incluso si nunca respondo?
Seguimiento del tiempo y respuestas asíncronas del usuario
El seguimiento del tiempo, una función que se incorporó hace poco a la API de agentes, le recuerda periódicamente al modelo qué hora es para que pueda ajustar su trabajo al plazo de entrega. Las herramientas de función asíncronas permiten que el agente siga trabajando mientras la aplicación espera la respuesta del usuario final.
Si faltan 15 minutos para la reunión, el agente tiene 12 minutos para preparar mi informe. A medida que se acerca la hora de entrega, puede dar prioridad a verificar los hallazgos mejor sustentados y redactar el informe antes de iniciar otra línea de investigación. Si le das un plazo más amplio, el modelo sabrá que tiene tiempo para investigar más a fondo.
Una solicitud como “Tengo una reunión en 15 minutos. Entrégame un informe cuando falten tres minutos para que pueda revisarlo” fija el plazo de entrega. El seguimiento del tiempo mantiene al modelo al tanto de la hora mientras espera los resultados de las búsquedas o la respuesta del usuario.
4:00p. m.
Entrega del informe a las 4:12
InicioEntrega del informeReunión
Agente
Investigando sobre la empresa
Pregunta para ti
Tema de la reunión sin definir
Notas
Pied Piper
Informe para la reunión
Antecedentes de la empresa
Anuncios recientes
Para ver cómo funciona, vamos a configurar un agente que ayude a los usuarios a prepararse para sus reuniones. En la ilustración, a las 16:00 UTC le pido un informe para las 16:12, antes de una reunión que empieza a las 16:15. Veremos cómo configurar el agente, mantenerlo al tanto de la hora, responder a sus llamadas a herramientas y procesar el resultado final.
Para ayudar al usuario a prepararse para una reunión, el agente necesita investigar a la empresa, preguntar por los detalles de la reunión que aún desconoce y llevar la cuenta del tiempo que le queda para preparar el informe. Para eso necesita acceso a la búsqueda web, una herramienta asíncrona para hacerle preguntas al usuario y la función de seguimiento del tiempo.
Define una herramienta de función llamada request_user_input_async. Establece async en true para que el agente pueda seguir trabajando mientras tu aplicación recoge la respuesta.
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")
Iniciar una tarea con un plazo de entrega
Ahora podemos pedirle al agente que nos ayude a preparar una reunión con un cliente. La solicitud indica de qué empresa se trata, a qué hora empieza la reunión y cuándo hay que entregar el informe. El agente decide qué investigar y si necesita pedir una aclaración.
Tu aplicación tendrá que convertir expresiones de tiempo como “dentro de 15 minutos” y “cuando queden tres minutos para revisarlo” en marcas de tiempo absolutas para que el modelo y la aplicación utilicen las mismas referencias temporales. Este código le indica al agente que la reunión empieza dentro de 15 minutos y le pide que entregue el informe dentro de 12 minutos.
Iniciar la sesión de preparación de la reunión
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=$!
Mostrar una pregunta pendiente
Cuando el agente pregunta por el objetivo de la reunión, la aplicación debe mostrar la pregunta mientras el agente sigue investigando a la empresa. Recoger la respuesta en una tarea independiente permite que la aplicación siga recibiendo las actualizaciones del agente.
Cuando el modelo pide una aclaración mediante una llamada a una herramienta, el código de tu aplicación se encarga de recoger la respuesta del usuario.
Revisa el flujo de eventos de la sesión para detectar eventos agent.session.turn.item.done que contengan una llamada a la función request_user_input_async. Lee la pregunta y las opciones de respuesta que se sugieran en item.arguments. La lista required_actions de la sesión describe las acciones que bloquean la ejecución. Si esperas a que aparezca una entrada en esa lista, podrías pasar por alto una pregunta asíncrona.
Guarda el ID de la sesión y los identificadores turn_id y call_id de la llamada para asociar la respuesta con la pregunta. Lleva un registro de las preguntas pendientes para mostrar y procesar cada una una sola vez. Cuando termine la ejecución del agente, cancela los manejadores que esperan esas respuestas:
La pregunta llega en un evento de llamada a función:
{ "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" }}
Devolver el resultado de la herramienta
La respuesta del usuario ayuda al agente a orientar el informe según el objetivo de la reunión. Incluso si el usuario nunca responde, el agente necesita tiempo para terminar de redactar el informe. Por eso, la aplicación cierra las preguntas sin respuesta a las 16:10, dos minutos antes de la entrega.
Cuando el usuario responda, establece status en answered y coloca en answer el texto que escribió o la opción que seleccionó.
Cuando venza el plazo para responder, si la llamada con el mismo call_id sigue pendiente y el usuario no ha respondido, devuelve {"status":"no_answer"}.
Envía el resultado mediante el método del SDK para eventos de sesión y usa los identificadores guardados para asociarlo con la pregunta. Sigue leyendo el flujo de eventos mientras envías el resultado. Si el agente termina antes, cierra la pregunta pendiente en la interfaz.
Devolver la respuesta o indicar que venció el plazo
Entrega un informe breve en cuanto esté listo y deja al usuario al menos tres minutos para leerlo antes de la reunión. Si el plazo vence antes, devuelve el último informe completo o indica que todavía no hay hallazgos verificados.
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}
Código completo del ejemplo
A continuación encontrarás, para cada lenguaje, un ejemplo con todo el proceso de preparación de la reunión en un solo archivo. Incluye la configuración del cliente, las respuestas asíncronas, el temporizador de entrega y la liberación de recursos. Cada script lee OPENAI_API_KEY del entorno y acepta respuestas desde la terminal.
Ejemplo completo de preparación de una reunión
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
Seguimiento del tiempo en un bucle de la API de respuestas
Si tu agente personal usa un bucle de la API de respuestas que programaste tú, la aplicación debe mantener al modelo al tanto del tiempo que le queda para preparar el informe. Calcula la hora de entrega una sola vez. Luego, antes de cada solicitud al modelo, agrega un recordatorio con la hora actual, incluso en las solicitudes que envían resultados de herramientas.
Los siguientes pasos implementan la misma tarea de preparación de reuniones. Cada solicitud a la API de respuestas incluye un recordatorio con la hora actual para el modelo. Un temporizador de la aplicación permanece activo durante todo el bucle para asegurar la entrega aunque una solicitud o una herramienta tarde demasiado.
1. Fijar la hora de la reunión y el plazo de entrega del informe
Indícale al agente qué empresa debe investigar y a qué hora debe entregar el informe. Conserva las mismas instrucciones generales y la herramienta asíncrona para hacer preguntas para que el modelo decida si necesita una aclaración.
La reunión empieza dentro de 15 minutos, el informe debe entregarse dentro de 12 y la aplicación cierra las preguntas sin respuesta 10 minutos después del inicio de la tarea. Mantén esos plazos fijos durante toda la tarea.
Configurar la tarea de preparación de la reunión con la API de respuestas
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. Agregar la hora actual antes de cada solicitud al modelo
El modelo necesita saber qué hora es cada vez que decide cómo proceder. Usa la misma función auxiliar para la solicitud inicial y para todas las solicitudes posteriores. Así, la hora se actualiza en un solo lugar del código.
Justo antes de llamar a la API de respuestas, agrega la hora UTC actual como mensaje de desarrollador, después del mensaje del usuario o de los resultados de las herramientas. Envía las instrucciones y las herramientas en cada solicitud. El plazo original permanece en el historial de la conversación.
3. Recoger la respuesta del usuario mientras continúa la investigación
Cuando el agente pregunte por el objetivo de la reunión, muestra la pregunta y recoge lo que responda el usuario en una tarea independiente de la generación de respuestas. Esa tarea devuelve la respuesta del usuario en cuanto llega, o no_answer si se acaba el tiempo. Usa el call_id original para asociar el resultado con la pregunta correspondiente.
Recoger de forma asíncrona el resultado de una solicitud de aclaración
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. Procesar las preguntas y las respuestas completas
Inicia la tarea que recoge la respuesta del usuario en cuanto llegue la pregunta completa por el flujo de la respuesta. Sigue leyendo los eventos mientras el usuario piensa qué responder para que el modelo pueda continuar su investigación en la web.
Cuando el modelo termine de generar una respuesta, guarda su ID para la siguiente solicitud y conserva cualquier informe completo para entregarlo. El manejador de eventos también registra los ID de las respuestas para liberar recursos al final.
Leer las preguntas del flujo de eventos y las respuestas completas
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. Continuar el bucle con los resultados disponibles
Si el usuario responde durante la investigación, la siguiente versión del informe debe tener en cuenta su respuesta. Cada vez que el modelo termine de generar una respuesta, reúne los resultados de herramientas que estén listos y envíalos mediante la función auxiliar, que agrega un nuevo recordatorio de la hora. Usa el ID de la última respuesta completa del modelo como valor de previous_response_id, incluso si el resultado corresponde a una pregunta de una respuesta anterior.
Envía las solicitudes en secuencia para que cada una parta del estado más reciente de la conversación. Si el informe está completo y no hay ningún resultado listo, entrégalo y cierra las preguntas pendientes. En caso contrario, continúa el trabajo con la hora actualizada, sin esperar a que el usuario responda.
Continuar la investigación e incorporar las respuestas del usuario
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. Cumplir el plazo de entrega aunque haya una solicitud en curso
Un temporizador de la aplicación impone el plazo de entrega del informe para que el usuario tenga tiempo de revisarlo. Aplica el temporizador a todo el bucle, incluidas las solicitudes a la API y la lectura del flujo de eventos.
Al vencer el plazo, detén la solicitud activa y entrega el informe guardado o indica que todavía no hay hallazgos verificados. Cierra los manejadores que siguen esperando respuestas del usuario y elimina las respuestas almacenadas después de la entrega.
Entregar a tiempo y liberar los recursos de la tarea
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=$!
Conclusión
A veces, los agentes personales deben terminar una tarea dentro de un plazo determinado. Lo ideal es que pidan aclaraciones para mejorar el resultado, pero incluso si no las reciben, tienen que poder hacer un trabajo útil.
Le dimos al agente un plazo y habilitamos el seguimiento del tiempo para ayudarlo a decidir si convenía investigar más, verificar un hallazgo o terminar de redactar el informe. Gracias a las herramientas de función asíncronas, pudo seguir investigando mientras el usuario pensaba qué responder. Incluso si la pregunta queda sin respuesta, el agente cuenta con suficiente contexto para redactar un informe útil para la reunión.
ChatGPT y otros arneses de ejecución de agentes usan este patrón para seguir trabajando mientras le piden una aclaración al usuario. Esperamos que el seguimiento del tiempo en la API de agentes te ayude a implementar este patrón por tu cuenta. ¡Cuéntanos qué creas!