Configuração de agentes

A configuração de um agente define como ele se comporta. Você pode fornecê-la ao criar uma sessão ou salvá-la para reutilizar depois. A sessão mantém a conversa e o trabalho realizado, enquanto o agente salvo armazena as configurações reutilizáveis.

Defina o comportamento do agente

Comece pelo modelo e pelas instruções. Em seguida, adicione as ferramentas e os controles necessários para a tarefa:

Modelo: qual modelo executa a tarefa.
Instruções: o que o agente deve fazer e como deve se comportar.
Ferramentas: quais ações o agente pode executar, como pesquisar na Web ou chamar suas funções.
Raciocínio e saída: quanto esforço de raciocínio o modelo emprega, em que formato responde e com que nível de detalhe.

Passe essas configurações em agent ao criar uma sessão. Este exemplo especifica o modelo, as instruções e a primeira mensagem do usuário:

Configurar um agente para uma sessão

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
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 seus valores. Para obter instruções de configuração, consulte Funções, Uso do computador, Conexões MCP ou Delegação entre agentes.

Tamanho da configuração

Mantenha o tamanho total das instruções e da configuração das ferramentas abaixo de 4 MiB (4.194.304 bytes), deixando uma pequena margem para os metadados da API de agentes. Se a sessão não iniciar porque a configuração é grande demais, reduza o tamanho das instruções e da configuração das ferramentas e crie uma nova sessão.

Os arquivos enviados ao ambiente estão sujeitos a limites de arquivos específicos.

Reutilize um agente em várias sessões

Salve um agente para reutilizar sua configuração em várias sessões. Crie o agente uma vez e passe o ID dele em agent_id ao iniciar cada sessão:

Reutilizar um agente

Python

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 mantém sua própria conversa e o trabalho realizado nela. 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.

Atualize um agente salvo

As atualizações de um agente salvo se aplicam apenas a novas sessões. Ao ser criada, cada sessão copia a configuração salva e a mantém 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.
Cada objeto fornecido substitui todo o valor do campo correspondente. Se você fornecer reasoning apenas com effort, o valor salvo em summary também será apagado.
null redefine os campos que aceitam esse valor. Por exemplo, reasoning: null restaura o esforço de raciocínio padrão do modelo.

Na mesma requisição, altere ou redefina todas as configurações incompatíveis com o novo modelo.

Sobrescreva configurações para uma única sessão

Inclua agent_id e 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, inclusive o modelo.

Substitua o valor de exemplo agent_123 pelo ID do agente salvo antes de executar o código:

Sobrescrever a configuração do agente para uma sessão

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// 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

Essas alterações valem apenas para essa sessão. Elas não modificam o agente salvo nem outras sessões. Os objetos e arrays fornecidos substituem todo o valor do campo, sem mesclá-lo 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.

Atualize as configurações de uma sessão existente

Envie POST /v1/agents/sessions/{session_id} com um objeto agent para alterar tools, model, reasoning.effort ou service_tier em uma única sessão. Essas configurações estão disponíveis nos contratos da API em beta e em disponibilidade geral (GA). Você também pode atualizar metadata na mesma requisição.

As alterações no modelo, no esforço de raciocínio e no nível de serviço se aplicam aos novos turnos iniciados por mensagens enviadas após a conclusão da atualização. Mensagens que já estão em processamento podem usar as configurações anteriores. Um turno em andamento mantém as configurações anteriores de modelo, esforço de raciocínio e nível de serviço, mesmo que você envie uma mensagem para orientar o agente. A sessão preserva o histórico da conversa. O modelo selecionado precisa ser compatível com a configuração resultante. Caso contrário, a atualização falha.

Os objetos agent e reasoning mesclam os campos fornecidos com as configurações atuais. Os campos omitidos mantêm seus valores, inclusive o resumo do raciocínio. Alterar apenas model preserva o esforço de raciocínio e o nível de serviço da sessão.
tools substitui toda a lista de ferramentas. As alterações nas funções e nos servidores MCP entram em vigor na próxima chamada ao modelo. As alterações nas ferramentas integradas entram em vigor, no máximo, no próximo turno. Omita tools para manter as ferramentas atuais ou passe null ou [] para esvaziar a lista.
reasoning.effort: null restaura o esforço de raciocínio padrão do modelo selecionado.
service_tier: null restaura a seleção automática do nível de serviço.
A sessão precisa ter um modelo definido, portanto você não pode fornecer model: null. Os objetos agent e reasoning também não aceitam null.
metadata substitui todo o mapa de metadados. Omita o campo para preservar os metadados ou passe null ou {} para apagá-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 também não alteram essa sessão.

Você não pode atualizar reasoning.summary, text, instructions ou multi_agent por esse endpoint. Para alterar essas configurações, crie uma nova sessão. Consulte a referência de atualização de sessões para conhecer os campos da requisição.

Revisão automática de ações

Defina o campo review da sessão como "auto_review" para que a API revise automaticamente as solicitações de aprovação compatíveis com esse modo. Inclua o campo no mesmo nível de agent ou agent_id, fora da configuração do agente. Se você omitir review ao criar a sessão, o valor padrão será "none".

A revisão automática também altera as permissões de execução. Verifique os pré-requisitos do ambiente antes de ativá-la.

Você pode atualizar review quando a tarefa principal estiver ociosa e não houver mais envios de dados de entrada pendentes. As operações seguintes de execução e recuperação usam a nova configuração. Se você solicitar a mudança de modo antes de atender a essas duas condições, a API retornará 409 Conflict sem aplicar nenhuma alteração. Use um projeto com a revisão automática ativada e uma sessão compatível com esse modo. Consulte Revisão automática para saber como configurar o modo e lidar com solicitações de aprovação.

Configurações do ambiente

Defina environment junto com agent ao criar uma sessão. O ambiente determina onde o agente executa comandos e trabalha com arquivos.

Escolha none, openai_hosted ou self_hosted. A seção Arquitetura explica quando usar cada opção e quem gerencia o ambiente.

Para um ambiente hospedado pela OpenAI, escolha o tamanho do contêiner e configure os pacotes, os arquivos iniciais e o acesso à rede necessários para a tarefa. Você pode reutilizar um modelo de ambiente em várias sessões. Para um ambiente hospedado na sua própria infraestrutura, prepare os recursos computacionais e conecte um executor.

Consulte a referência de criação de sessões para conhecer os campos do ambiente e a seção Plug-ins para saber mais sobre habilidades, plug-ins e modelos. Para saber como manter arquivos após a execução, consulte Artefatos da sessão.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração