Uma sessão preserva a configuração do agente, a conversa e o trabalho salvo ao longo do tempo. Use a mesma sessão para enviar novas mensagens e dar continuidade ao trabalho.
Um turno é um ciclo de trabalho dentro de uma sessão. Uma mensagem enviada a uma sessão ociosa inicia um novo turno. Quando há um turno em andamento, a mensagem orienta o agente nesse mesmo turno.
Os turnos são executados de forma assíncrona. Seu aplicativo pode acompanhar o progresso por meio de um fluxo de eventos ou receber notificações de mudanças no estado da sessão por meio de webhooks.
Use automações agendadas para iniciar o trabalho em um horário futuro ou em intervalos regulares. Uma automação pode criar uma sessão a cada execução ou continuar uma conversa existente.
Crie uma sessão com a configuração do agente e os dados iniciais em input. Defina stream como true para receber os eventos do primeiro turno na mesma requisição.
Depois de configurar a chave de API e o SDK, execute este exemplo para criar e executar um script. A OpenAI gerencia o ambiente de execução do script.
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
}'
Armazene o session_id junto com o estado da conversa no aplicativo. Use esse identificador para enviar novas mensagens e recuperar o trabalho salvo nessa conversa.
Para ativar a revisão automática de ações, defina review como "auto_review" ao criar uma sessão elegível em um projeto em que a revisão automática já esteja ativada. Você pode alterar essa configuração quando a tarefa principal estiver ociosa e não houver mais envios de dados de entrada pendentes. Consulte Revisão automática para conhecer os modos de revisão, os pré-requisitos do ambiente e como funcionam as aprovações.
Consulte Configuração de agentes para conhecer as configurações reutilizáveis dos agentes e Arquitetura para conhecer as opções de ambiente. Sessões com environment.type: "none" exigem dados de entrada iniciais. A referência de criação de sessões lista os campos da requisição.
Se a sessão usar anexos da API de arquivos, a verificação dos arquivos poderá retornar o código HTTP 429 com o erro
files_api_rate_limit_exceeded. Consulte Limites de taxa da API de arquivos
para saber como retomar o trabalho.
O ambiente de execução do agente aceita requisições de até 4 MiB (4.194.304 bytes). Mantenha a soma dos tamanhos de input e do schema de saída (agent.text.format.schema) abaixo desse limite. Reserve espaço para os metadados que a API de agentes adiciona. Os arquivos enviados ao ambiente estão sujeitos a limites próprios.
Os eventos informam o que o agente produz e o que muda durante o trabalho. Verifique se o turno foi concluído, falhou ou foi cancelado. O fato de a sessão estar ociosa, por si só, não indica que o turno foi bem-sucedido.
Procure os eventos agent.session.turn.completed, agent.session.turn.failed ou agent.session.turn.cancelled. Examine também a saída do agente. A conclusão do turno não garante que todas as ferramentas tenham sido executadas com sucesso.
Se a sessão precisar do resultado de uma função ou de uma conexão com o ambiente, consulte a sessão e examine required_actions. Para que o trabalho continue, seu código precisa tratar a chamada de função ou conectar o ambiente.
Consulte Eventos e itens para conhecer os tipos de evento e os dados que cada um contém.
Envie outra mensagem agent.session.input.message à mesma sessão. Se o agente estiver trabalhando, a mensagem orientará o agente no turno em andamento. Se a sessão estiver ociosa, a mensagem iniciará um novo turno na conversa existente.
O mesmo limite de tamanho da entrada se aplica às mensagens seguintes.
As atualizações de um agente salvo se aplicam apenas a novas sessões. Para alterar o modelo, o esforço de raciocínio ou o nível de serviço nos próximos turnos desta sessão, atualize as configurações da sessão.
Use o ID da sessão associada à conversa para enviar os dados de entrada. Inscreva-se no fluxo de eventos da sessão antes de enviar a mensagem para que seu aplicativo receba os primeiros eventos do turno.
Crie uma chave de idempotência para cada operação de envio de mensagem. Antes de enviar os dados de entrada, salve a chave junto com a mensagem. Use a chave salva ao enviar a mensagem.
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."
}
]
}
]
}
]
}'
Envie a chave no cabeçalho Idempotency-Key e reutilize-a nas tentativas automáticas de reenvio. Se o aplicativo tentar novamente após o tempo limite expirar ou a resposta se perder, use a mesma chave, o mesmo ID de sessão e a mesma mensagem. Gere uma chave diferente para cada operação de envio distinta, mesmo que o texto da mensagem seja idêntico.
Para ver um exemplo que combina o envio de uma mensagem com o recebimento de eventos em tempo real, consulte Eventos e itens.
Os eventos mostram o progresso em tempo real. Os itens são registros salvos das mensagens e chamadas de ferramentas, incluindo as respostas concluídas. Recupere os itens para exibir o trabalho anterior ou examinar os resultados após o término de um 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"
Consulte Gerenciamento de sessões para verificar o estado da sessão e os resultados dos turnos. Para recuperar arquivos, siga as instruções em Arquivos e artefatos.
O fluxo não retransmite eventos perdidos. Se a conexão cair, recupere a sessão e os itens salvos para recuperar o trabalho já realizado. Consulte Recuperar um fluxo após a desconexão para saber como restabelecer a conexão.
Cancele o turno atual quando quiser que o agente pare. A sessão e o trabalho realizado anteriormente continuam disponíveis.
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"}]}'
