Una sesión conserva la configuración del agente, la conversación y el trabajo guardado a lo largo del tiempo. Usa la misma sesión para enviar mensajes de seguimiento y continuar el trabajo.
Un turno es un ciclo de trabajo dentro de una sesión. Si envías un mensaje a una sesión inactiva, se inicia un nuevo turno. Si lo envías durante un turno activo, el mensaje guía al agente durante ese turno.
Los turnos se ejecutan de forma asíncrona. Tu aplicación puede seguir el progreso mediante una transmisión de eventos o recibir notificaciones de los cambios de estado de la sesión mediante webhooks.
Usa automatizaciones programadas para iniciar el trabajo en un momento futuro o a intervalos regulares. Una automatización puede crear una sesión nueva en cada ejecución o continuar una conversación existente.
Crea una sesión con la configuración del agente y una entrada inicial en input. Establece stream en true para recibir los eventos del primer turno en la misma solicitud.
Una vez que configures tu clave de API y el SDK, ejecuta este ejemplo para crear y ejecutar un script. OpenAI administra el entorno en el que se ejecuta.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import OpenAI from "openai";
const client = new OpenAI();
const events = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions: "Write clean code, run it, and report the actual output.",
},
environment: { type: "openai_hosted" },
input:
"Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
stream: true,
});
events.withResultCollection();
try {
for await (const event of events) {
console.log(JSON.stringify(event));
}
const result = await events.finalResult();
console.log(result.output_text);
console.log("Session:", result.session_id);
} finally {
events.controller.abort();
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai import OpenAI
with OpenAI() as client:
with client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Write clean code, run it, and report the actual output.",
},
environment={"type": "openai_hosted"},
input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
stream=True,
).with_result_collection() as stream:
for event in stream:
print(event.to_json(indent=None), flush=True)
result = stream.get_final_result()
print(result.output_text)
session_id = result.session_id
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
35import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
events := client.Beta.Agents.Sessions.NewStreaming(ctx, openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("Write clean code, run it, and report the actual output."),
},
Environment: openai.EnvironmentParamUnion{OfParamOpenAIHosted: &openai.EnvironmentParamOpenAIHosted{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfString: openai.String("Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output."),
},
})
defer events.Close()
openai.BetaAgentSessionWithResultCollection(events)
if events.Err() != nil {
panic(events.Err())
}
for events.Next() {
event := events.Current()
fmt.Println(event.RawJSON())
}
result, err := openai.BetaAgentSessionFinalResult(events)
if err != nil {
panic(err)
}
fmt.Println(result.OutputText())
sessionID := result.SessionID()
fmt.Println("Session:", sessionID)
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
39import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.ObjectMappers;
import com.openai.core.http.StreamResponse;
import com.openai.models.beta.agents.AgentSessionEvent;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import com.openai.services.beta.agents.AgentTurnResults;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var json = ObjectMappers.jsonMapper();
try (StreamResponse<AgentSessionEvent> events =
client
.beta()
.agents()
.sessions()
.createStreaming(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.instructions("Write clean code, run it, and report the actual output.")
.build())
.environment(EnvironmentParam.OpenAIHosted.builder().build())
.input(
"Create tree.py, a Python script that prints a readable tree of the files"
+ " in the current directory. Run it and show me the output.")
.build())) {
AgentTurnResults.withResultCollection(events);
var iterator = events.stream().iterator();
while (iterator.hasNext()) {
var event = iterator.next();
System.out.println(json.writeValueAsString(event));
}
var result = AgentTurnResults.getFinalResult(events);
System.out.println(result.outputText());
String sessionId = result.sessionId();
System.out.println(sessionId);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"
require "json"
client = OpenAI::Client.new
events = client.beta.agents.sessions.create_streaming(
agent: {
model: "gpt-6-astra",
instructions: "Write clean code, run it, and report the actual output."
},
environment: { type: "openai_hosted" },
input: "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output."
)
begin
events.with_result_collection
events.each do |event|
puts JSON.generate(event.to_h)
end
result = events.get_final_result
puts result.output_text
session_id = result.session_id
puts "Session: #{session_id}"
ensure
events.close
end
1
2
3
4
5
6
7
8
9
10
11
12
13curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": {
"model": "gpt-6-astra",
"instructions": "Write clean code, run it, and report the actual output."
},
"environment": { "type": "openai_hosted" },
"input": "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
"stream": true
}'
Guarda el session_id junto con el estado de la conversación en tu aplicación. Úsalo para enviar mensajes de seguimiento y recuperar el trabajo guardado de esa conversación.
Para activar la revisión automática de acciones, establece review en "auto_review" al crear una sesión que cumpla los requisitos en un proyecto que tenga habilitada la revisión automática. Puedes cambiar este ajuste cuando la tarea principal esté inactiva y ya no haya envíos de datos de entrada en curso. Consulta Revisión automática para conocer los modos de revisión, los requisitos previos del entorno y cómo funcionan las aprobaciones.
Consulta Configuración de agentes para conocer los ajustes reutilizables de los agentes y Arquitectura para conocer las opciones de entorno. Las sesiones con environment.type: "none" requieren una entrada inicial. La referencia de creación de sesiones enumera los campos de la solicitud.
Si la sesión usa archivos adjuntos de la API de archivos, la verificación de los archivos puede devolver el código HTTP 429 con
files_api_rate_limit_exceeded. Consulta Límites de solicitudes de la API de archivos
para saber cómo recuperarte del error.
El entorno de ejecución del agente acepta solicitudes de hasta 4 MiB (4 194 304 bytes). Mantén el tamaño combinado de input y del esquema de salida (agent.text.format.schema) por debajo de ese límite. Deja espacio para los metadatos que agrega la API de agentes. Los archivos que subes al entorno están sujetos a límites de archivos independientes.
Los eventos muestran la salida del agente y los cambios que se producen mientras trabaja. Comprueba si el turno se completó, falló o se canceló. El hecho de que la sesión esté inactiva no basta para saber si el turno se completó correctamente.
Busca agent.session.turn.completed, agent.session.turn.failed o agent.session.turn.cancelled. Revisa también la salida del agente. Que el turno se haya completado no garantiza que todas las herramientas se hayan ejecutado correctamente.
Si la sesión necesita el resultado de una función o una conexión con el entorno, recupera la sesión y revisa required_actions. Tu código debe gestionar la llamada a la función o conectar el entorno para que el trabajo pueda continuar.
Consulta Eventos y elementos para conocer los tipos de eventos y los datos que contiene cada uno.
Envía otro agent.session.input.message a la misma sesión. Si el agente está trabajando, el mensaje lo guía durante el turno activo. Si la sesión está inactiva, el mensaje inicia un nuevo turno en la conversación existente.
El mismo límite de tamaño de la entrada se aplica a los mensajes de seguimiento.
Los cambios en un agente guardado solo se aplican a las sesiones nuevas. Para cambiar el modelo, el esfuerzo de razonamiento o el nivel de servicio en los turnos posteriores de esta sesión, actualiza la configuración de la sesión.
Usa el ID de sesión de la conversación para enviar la entrada. Suscríbete a su flujo de eventos antes de enviar el mensaje para que tu aplicación reciba los primeros eventos del turno.
Crea una clave de idempotencia para cada envío lógico de un mensaje. Guárdala junto con el mensaje antes de enviar la entrada. Usa la clave guardada al enviar el mensaje.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// Reuse the same submission key when retrying this message.
async function sendMessage(client, sessionId, text, submissionKey) {
await client.beta.agents.sessions.events.create(sessionId, {
"Idempotency-Key": submissionKey,
events: [
{
type: "agent.session.input.message",
input: [
{
role: "user",
content: [
{
type: "input_text",
text,
},
],
},
],
},
],
});
}
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
31from uuid import uuid4
# Reuse the same submission key when retrying this message.
def send_message(
client: OpenAI, session_id: str, text: str, submission_key: str
) -> None:
client.beta.agents.sessions.events.create(
session_id,
idempotency_key=submission_key,
events=[
{
"type": "agent.session.input.message",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": text,
}
],
}
],
}
],
)
submission_key = str(uuid4())
# Save this key with the message before submitting it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23// Reuse the same submission key when retrying this message.
func sendMessage(ctx context.Context, client *openai.Client, sessionID, text, submissionKey string) error {
return client.Beta.Agents.Sessions.Events.New(ctx,
sessionID,
openai.BetaAgentSessionEventNewParams{
IdempotencyKey: openai.String(submissionKey),
Events: []openai.AgentSessionInputParamUnion{
{
OfParamAgentSessionInputMessage: &openai.AgentSessionInputParamAgentSessionInputMessage{
Input: []openai.AgentSessionInputMessageParam{
{
Content: []openai.InputContentParamUnion{
{
OfParamInputText: &openai.InputContentParamInputText{Text: text},
},
},
},
},
},
},
},
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Reuse the same submission key when retrying this message.
public static void sendMessage(
OpenAIClient client, String sessionId, String text, String submissionKey) {
client
.beta()
.agents()
.sessions()
.events()
.create(
EventCreateParams.builder()
.sessionId(sessionId)
.idempotencyKey(submissionKey)
.addEvent(
AgentSessionInputParam.AgentSessionInputMessage.builder()
.addInput(
AgentSessionInputMessageParam.builder()
.addInputTextContent(text)
.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# Reuse the same submission key when retrying this message.
def send_message(client, session_id, text, submission_key)
client.beta.agents.sessions.events.create(
session_id,
idempotency_key: submission_key,
events: [
{
type: "agent.session.input.message",
input: [
{
role: "user",
content: [
{
type: "input_text",
text: text
}
]
}
]
}
]
)
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24curl \
"https://api.openai.com/v1/agents/sessions/$session_id/events" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Idempotency-Key: $submission_key" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"type": "agent.session.input.message",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "List the files in the current directory."
}
]
}
]
}
]
}'
Envía la clave en el encabezado Idempotency-Key y reutilízala en los reintentos automáticos. Si tu aplicación vuelve a intentarlo porque se agotó el tiempo de espera o se perdió la respuesta, usa la misma clave, el mismo ID de sesión y el mismo mensaje. Genera una clave diferente para cada envío independiente, incluso si el texto del mensaje es idéntico.
Para ver un ejemplo que combina el envío de un mensaje con la recepción de eventos en tiempo real, consulta Eventos y elementos.
Los eventos muestran el progreso en tiempo real. Los elementos son los mensajes y las llamadas a herramientas que se guardaron, incluidas las respuestas completas. Recupéralos para mostrar el trabajo anterior o revisar los resultados cuando termine un turno.
1
2
3
4
5
6
7// Pass your saved session ID to this helper.
async function listItems(client, sessionId) {
return client.beta.agents.sessions.items.list(sessionId, {
order: "asc",
limit: 100,
});
}
1
2
3# Pass your saved session ID to this helper.
def list_items(client: OpenAI, session_id: str):
return client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)
1
2
3
4
5
6
7
8
9// Pass your saved session ID to this helper.
func listItems(ctx context.Context, client *openai.Client, sessionID string) (*pagination.CursorPage[openai.AgentSessionItemUnion], error) {
return client.Beta.Agents.Sessions.Items.List(ctx,
sessionID,
openai.BetaAgentSessionItemListParams{
Order: "asc",
Limit: openai.Int(100),
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14// Pass your saved session ID to this helper.
public static ItemListPage listItems(OpenAIClient client, String sessionId) {
return client
.beta()
.agents()
.sessions()
.items()
.list(
ItemListParams.builder()
.sessionId(sessionId)
.order(ItemListParams.Order.of("asc"))
.limit(100L)
.build());
}
1
2
3
4
5
6
7
8# Pass your saved session ID to this helper.
def list_items(client, session_id)
client.beta.agents.sessions.items.list(
session_id,
order: "asc",
limit: 100
)
end
1
2
3
4curl \
"https://api.openai.com/v1/agents/sessions/$session_id/items?order=asc&limit=100" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY"
Consulta Gestión de sesiones para revisar el estado de la sesión y los resultados de los turnos. Para recuperar archivos, sigue las instrucciones de Archivos y artefactos.
Los flujos de eventos no vuelven a transmitir los eventos que tu aplicación no recibió. Si se interrumpe la conexión, recupera el trabajo consultando la sesión y sus elementos guardados. Consulta Recuperar un flujo de eventos tras una desconexión para saber cómo volver a conectarte.
Cancela el turno actual cuando quieras que el agente se detenga. La sesión y el trabajo anterior siguen disponibles.
1
2
3
4
5
6// Pass your saved session ID to this helper.
async function cancelTurn(client, sessionId) {
await client.beta.agents.sessions.events.create(sessionId, {
events: [{ type: "agent.session.input.cancel" }],
});
}
1
2
3
4
5# Pass your saved session ID to this helper.
def cancel_turn(client: OpenAI, session_id: str) -> None:
client.beta.agents.sessions.events.create(
session_id, events=[{"type": "agent.session.input.cancel"}]
)
1
2
3
4
5
6
7
8
9
10// Pass your saved session ID to this helper.
func cancelTurn(ctx context.Context, client *openai.Client, sessionID string) error {
return client.Beta.Agents.Sessions.Events.New(ctx,
sessionID,
openai.BetaAgentSessionEventNewParams{
Events: []openai.AgentSessionInputParamUnion{
{OfParamAgentSessionInputCancel: &openai.AgentSessionInputParamAgentSessionInputCancel{}},
},
})
}
1
2
3
4
5
6
7
8
9
10
11
12
13// Pass your saved session ID to this helper.
public static void cancelTurn(OpenAIClient client, String sessionId) {
client
.beta()
.agents()
.sessions()
.events()
.create(
EventCreateParams.builder()
.sessionId(sessionId)
.addEventAgentSessionInputCancel()
.build());
}
1
2
3
4
5
6
7# Pass your saved session ID to this helper.
def cancel_turn(client, session_id)
client.beta.agents.sessions.events.create(
session_id,
events: [{ type: "agent.session.input.cancel" }]
)
end
1
2
3
4
5curl "https://api.openai.com/v1/agents/sessions/$session_id/events" \
-H "OpenAI-Beta: agents=v1" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events":[{"type":"agent.session.input.cancel"}]}'
