A configuração de um agente define como ele se comporta. Você pode fornecê-la ao criar uma sessão ou salvá-la para reutilização. A sessão mantém a conversa e o trabalho, enquanto o agente salvo mantém as configurações reutilizáveis.
Comece pelo modelo e pelas instruções e, em seguida, adicione as ferramentas e os controles necessários para sua tarefa:
- Modelo: Qual modelo realiza o trabalho.
- Instruções: O que o agente deve fazer e como deve se comportar.
- Ferramentas: Quais ações o agente pode realizar, como pesquisar na Web ou chamar suas funções.
- Raciocínio e saída: Quanto raciocínio o modelo usa e qual é o formato e o nível de detalhe de suas respostas.
Passe essas configurações em agent ao criar uma sessão. Este exemplo fornece um modelo, instruções e a primeira mensagem do usuário:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25import OpenAI from "openai";
const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions: "Answer the user clearly and concisely.",
},
environment: {
type: "none",
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "What can you help with?",
},
],
},
],
});
console.log(session);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Answer the user clearly and concisely.",
},
environment={"type": "none"},
input=[
{
"role": "user",
"content": [{"type": "input_text", "text": "What can you help with?"}],
}
],
)
print(session.to_json())
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
32import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("Answer the user clearly and concisely."),
},
Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
{
Content: []openai.InputContentParamUnion{
{
OfParamInputText: &openai.InputContentParamInputText{Text: "What can you help with?"},
},
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(result)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.instructions("Answer the user clearly and concisely.")
.build())
.environmentNone()
.input("What can you help with?")
.build());
System.out.println(result);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22require "openai"
client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
agent: {
model: "gpt-6-astra",
instructions: "Answer the user clearly and concisely."
},
environment: { type: "none" },
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "What can you help with?"
}
]
}
]
)
puts result
Consulte a referência da API de Agentes para conhecer os campos de configuração e os valores aceitos. Consulte Funções e Conexões MCP para configurar ferramentas, e Múltiplos agentes para saber sobre delegação.
Salve um agente para reutilizar sua configuração em várias sessões. Crie-o uma vez e passe seu ID como agent_id ao iniciar cada sessão:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import OpenAI from "openai";
const client = new OpenAI();
const agent = await client.beta.agents.create({
model: "gpt-6-astra",
instructions: "Answer technical questions accurately.",
reasoning: {
summary: "auto",
},
});
const session = await client.beta.agents.sessions.create({
agent_id: agent.id,
environment: { type: "none" },
input: "Explain how an agent connects to an MCP server.",
});
console.log(session);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from openai import OpenAI
client = OpenAI()
agent = client.beta.agents.create(
model="gpt-6-astra",
instructions="Answer technical questions accurately.",
reasoning={"summary": "auto"},
timeout=360,
)
session = client.beta.agents.sessions.create(
agent_id=agent.id,
environment={"type": "none"},
input="Explain how an agent connects to an MCP server.",
)
print(session.to_json())
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
28import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
agent, err := client.Beta.Agents.New(ctx,
openai.BetaAgentNewParams{
Model: "gpt-6-astra",
Instructions: openai.String("Answer technical questions accurately."),
Reasoning: openai.AgentReasoningParam{Summary: "auto"},
})
if err != nil {
panic(err)
}
result, err := client.Beta.Agents.Sessions.New(ctx,
openai.BetaAgentSessionNewParams{
AgentID: openai.String(agent.ID),
Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Explain how an agent connects to an MCP server.")},
})
if err != nil {
panic(err)
}
fmt.Println(result)
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
32import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentCreateParams;
import com.openai.models.beta.agents.AgentReasoningParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var agent =
client
.beta()
.agents()
.create(
AgentCreateParams.builder()
.model("gpt-6-astra")
.instructions("Answer technical questions accurately.")
.reasoning(
AgentReasoningParam.builder()
.summary(AgentReasoningParam.Summary.of("auto"))
.build())
.build());
var result =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agentId(agent.id())
.environmentNone()
.input("Explain how an agent connects to an MCP server.")
.build());
System.out.println(result);
1
2
3
4
5
6
7
8
9
10
11
12
13
14require "openai"
client = OpenAI::Client.new
agent = client.beta.agents.create(
model: "gpt-6-astra",
instructions: "Answer technical questions accurately.",
reasoning: { summary: "auto" }
)
result = client.beta.agents.sessions.create(
agent_id: agent.id,
environment: { type: "none" },
input: "Explain how an agent connects to an MCP server."
)
puts result
Cada sessão tem sua própria conversa e seu próprio trabalho. Consulte a referência da API de Agentes para listar, recuperar, atualizar ou excluir agentes salvos. As credenciais ficam em cofres, separadas da configuração salva.
As atualizações de um agente salvo se aplicam apenas a novas sessões. Cada sessão copia a configuração salva no momento da criação e mantém essas configurações nos turnos seguintes. Para alterar uma sessão existente, atualize suas configurações.
Ao atualizar um agente salvo:
- Os campos omitidos mantêm os valores salvos. Alterar apenas
model preserva reasoning, service_tier e text.
- Os objetos fornecidos substituem o campo inteiro. Fornecer
reasoning apenas com effort também limpa o valor salvo de summary.
null redefine os campos que aceitam esse valor. Por exemplo, reasoning: null restaura o esforço padrão do modelo.
Na mesma requisição, altere ou redefina todas as configurações que o novo modelo não suporta.
Inclua tanto agent_id quanto agent ao criar uma sessão para personalizar a configuração de um agente salvo. No momento da criação, a sessão copia do agente salvo as configurações omitidas, incluindo o modelo.
Substitua o valor ilustrativo agent_123 pelo ID do agente salvo antes de executar este exemplo:
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// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();
const agentId = "agent_123";
const session = await client.beta.agents.sessions.create({
agent_id: agentId,
agent: {
instructions: "Answer this question in one concise paragraph.",
},
environment: {
type: "none",
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Explain how an agent connects to an MCP server.",
},
],
},
],
});
console.log(session);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23# Replace the illustrative IDs and URLs below with your own resource values.
from openai import OpenAI
client = OpenAI()
agent_id = "agent_123"
session = client.beta.agents.sessions.create(
agent_id=agent_id,
agent={"instructions": "Answer this question in one concise paragraph."},
environment={"type": "none"},
input=[
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Explain how an agent connects to an MCP server.",
}
],
}
],
)
print(session.to_json())
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// Replace the illustrative IDs and URLs below with your own resource values.
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
openai.BetaAgentSessionNewParams{
AgentID: openai.String("agent_123"),
Agent: openai.BetaAgentSessionNewParamsAgent{Instructions: openai.String("Answer this question in one concise paragraph.")},
Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
{
Content: []openai.InputContentParamUnion{
{
OfParamInputText: &openai.InputContentParamInputText{Text: "Explain how an agent connects to an MCP server."},
},
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(result)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22// Replace the illustrative IDs and URLs below with your own resource values.
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agentId("agent_123")
.agent(
SessionCreateParams.Agent.builder()
.instructions("Answer this question in one concise paragraph.")
.build())
.environmentNone()
.input("Explain how an agent connects to an MCP server.")
.build());
System.out.println(result);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21# Replace the illustrative IDs and URLs below with your own resource values.
require "openai"
client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
agent_id: "agent_123",
agent: { instructions: "Answer this question in one concise paragraph." },
environment: { type: "none" },
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Explain how an agent connects to an MCP server."
}
]
}
]
)
puts result
As substituições se aplicam apenas àquela sessão. Elas não alteram o agente salvo nem outras sessões. Os objetos e arrays fornecidos substituem o campo inteiro, em vez de serem mesclados com o valor salvo. Por exemplo, fornecer tools substitui a lista de ferramentas salva.
Consulte a referência de criação de sessões para conhecer os campos da requisição.
Envie POST /v1/agents/sessions/{session_id} com um objeto agent para alterar model, reasoning.effort ou service_tier em uma sessão. Essas configurações estão disponíveis nos contratos das versões beta e GA da API. Você pode atualizar metadata na mesma requisição.
As alterações se aplicam a novos turnos iniciados por mensagens enviadas após a conclusão da atualização. Mensagens já em trânsito podem usar as configurações anteriores. Um turno ativo mantém suas configurações, inclusive quando você envia uma mensagem de direcionamento. A sessão mantém seu histórico de conversa. O modelo selecionado deve suportar as configurações resultantes; caso contrário, a atualização falha.
- Os objetos
agent e reasoning mesclam os campos fornecidos às configurações atuais. Os campos omitidos permanecem inalterados, incluindo o resumo de raciocínio. Alterar apenas model preserva o esforço de raciocínio e o nível de serviço da sessão.
reasoning.effort: null redefine o esforço para o padrão do modelo selecionado.service_tier: null restaura a seleção automática do nível de serviço.- Um modelo deve permanecer definido, portanto você não pode fornecer
model: null. Os objetos agent e reasoning também rejeitam null.
metadata substitui o mapa inteiro. Omita esse campo para preservar os metadados ou passe null ou {} para limpá-los.
Por exemplo, esta requisição altera o esforço de raciocínio e permite que a API selecione o nível de serviço automaticamente:
123456{
"agent": {
"reasoning": { "effort": "low" },
"service_tier": null
}
}
Atualizar uma sessão não altera o agente salvo nem outras sessões. Atualizações posteriores do agente salvo não alteram a sessão.
Você não pode atualizar reasoning.summary, text, tools, instructions ou multi_agent por meio deste endpoint. Crie uma nova sessão para alterar essas configurações.
Defina environment junto com agent ao criar uma sessão. Essa configuração determina onde o agente executa comandos e trabalha com arquivos.
Escolha none, openai_hosted ou self_hosted. A página Arquitetura explica quando usar cada opção e quem gerencia o ambiente.
Para um ambiente hospedado pela OpenAI, configure os pacotes, os arquivos iniciais e o acesso à rede necessários para a tarefa. Você pode reutilizar um template de ambiente em várias sessões. Para um ambiente em infraestrutura própria, prepare seus recursos computacionais e conecte um executor.
Consulte a referência de criação de sessões para conhecer os campos do ambiente e Plug-ins para saber sobre habilidades, plug-ins e templates. Consulte Artefatos da sessão para saber sobre os arquivos que você deseja manter após a execução.
