API de Agentes

A API de Agentes dá à sua aplicação acesso ao harness do Codex por meio de uma API gerenciada pela OpenAI.

A OpenAI gerencia sessões, orquestração, compactação de contexto e recuperação, enquanto sua aplicação fornece ferramentas e escolhe o ambiente de execução.

Os agentes podem operar em um sandbox onde podem executar código, editar arquivos, conectar-se a servidores MCP e produzir artefatos.

Preços

O uso do modelo é cobrado de acordo com as tarifas da API do modelo selecionado. As ferramentas da OpenAI seguem suas tarifas padrão, e os sandboxes hospedados pela OpenAI seguem as tarifas padrão de contêineres.

Experimente um exemplo

Experimente estes exemplos completos:

Crie e execute um script de árvore de diretórios em um sandbox hospedado pela OpenAI.
Compare notas de versão com subagentes e reúna as conclusões em uma única resposta.

Explore aplicações completas:

Agente de resposta a incidentes: investigue alertas e solicite aprovação para ações de recuperação.
Bot do Slack: investigue solicitações usando ferramentas de trabalho conectadas.
Analista de dados: responda a perguntas sobre o armazém de dados com consultas SQL somente leitura.
Use o investigador de issues do GitHub para reproduzir bugs relatados e compartilhar os resultados no GitHub.
Use o revisor de documentos para revisar documentos com habilidades de políticas e agentes especialistas.

Conceitos fundamentais

A API de Agentes se baseia em quatro conceitos principais:

Agente: O modelo, as instruções, as ferramentas e os servidores MCP disponíveis para o agente.
Ambiente: Um sandbox ou computador opcional onde o agente acessa arquivos, carrega habilidades e executa comandos.
Sessão: Uma instância persistente de um agente que executa tarefas e responde às entradas.
Eventos e itens: As entradas enviadas a um agente e a saída produzida durante uma sessão.

Uma sessão do início ao fim

Comece com um sandbox hospedado pela OpenAI no início rápido:

Crie uma sessão. Configure o agente; a OpenAI provisiona o ambiente dele.
Atribua uma tarefa. A entrada do usuário inicia um turno de trabalho assim que o ambiente está pronto.
Acompanhe o progresso. Receba a saída por streaming ou use webhooks para saber quando o agente termina ou precisa de informações.
Continue ou oriente. Envie outra tarefa para a mesma sessão ou oriente o agente durante o turno atual.

Com uma sessão hospedada pela OpenAI, sua aplicação envia entradas e recebe eventos, enquanto a OpenAI executa o agente e provisiona e gerencia o sandbox dele. Consulte as opções de ambiente para saber mais sobre a configuração e as limitações.

Sua aplicação inicia sessões e recebe eventos e saídas da API de Agentes. A OpenAI executa o harness gerenciado do Codex e provisiona e gerencia o sandbox dele.

O que o harness gerenciado oferece

O harness gerenciado do Codex permite:

Executar comandos e código em um sandbox.
Aplicar habilidades e instruções relevantes.
Conectar-se a dados externos por meio de ferramentas ou MCP.
Orientar o agente enquanto ele trabalha.
Resumir o trabalho anterior para gerenciar a janela de contexto.
Dividir o trabalho em subtarefas e delegá-las a subagentes.
Retomar uma sessão de onde parou.

Consulte os pré-requisitos do início rápido para saber mais sobre as permissões da chave de API e a configuração do SDK. Configure essas capacidades ao criar uma sessão:

Configure as capacidades do harness gerenciado

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
41import OpenAI from "openai";

const client = new OpenAI();

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    instructions:
      "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
    tools: [
      { type: "programmatic_tool_calling" },
      {
        type: "mcp",
        server_label: "openai_docs",
        transport: {
          type: "http",
          server_url: "https://developers.openai.com/mcp",
        },
      },
      { type: "web_search" },
    ],
    multi_agent: { enabled: true, max_concurrent_subagents: 4 },
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/capabilities/skills"],
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
        },
      ],
    },
  ],
});
console.log(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
35
36
37
38
39
40from openai import OpenAI

client = OpenAI()

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
        "tools": [
            {"type": "programmatic_tool_calling"},
            {
                "type": "mcp",
                "server_label": "openai_docs",
                "transport": {
                    "type": "http",
                    "server_url": "https://developers.openai.com/mcp",
                },
            },
            {"type": "web_search"},
        ],
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/capabilities/skills"],
    },
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
                }
            ],
        }
    ],
)
print(session.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"
	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra"),
	Instructions: openai.String("Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful."),
	Tools: []openai.AgentToolParamUnion{openai.AgentToolParamUnion{OfParamProgrammaticToolCalling: &openai.AgentToolParamProgrammaticToolCalling{}},
		openai.AgentToolParamUnion{OfParamMcp: &openai.AgentToolParamMcp{ServerLabel: "openai_docs",
			Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: "https://developers.openai.com/mcp"}}}},
		openai.AgentToolParamUnion{OfParamWebSearch: &openai.AgentToolParamWebSearch{}}},
	MultiAgent: openai.MultiAgentConfigParam{Enabled: true,
		MaxConcurrentSubagents: openai.Int(4)}},
	Environment: openai.EnvironmentParamUnion{OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace",
		CapabilityDirectories: []string{"/workspace/capabilities/skills"}}},
	Input: openai.BetaAgentSessionNewParamsInputUnion{OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{openai.AgentSessionInputMessageParam{Content: []openai.InputContentParamUnion{openai.InputContentParamUnion{OfParamInputText: &openai.InputContentParamInputText{Text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."}}}}}}})
if err != nil {
	panic(err)
}
fmt.Println(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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentToolParam;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.McpTransportParam;
import com.openai.models.beta.agents.MultiAgentConfigParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var session =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(
                    SessionCreateParams.Agent.builder()
                        .model("gpt-6-astra")
                        .instructions(
                            "Use the OpenAI documentation MCP and web search to answer"
                                + " technical questions accurately. Delegate independent"
                                + " research tasks to subagents when useful.")
                        .addTool(AgentToolParam.ProgrammaticToolCalling.builder().build())
                        .addTool(
                            AgentToolParam.Mcp.builder()
                                .serverLabel("openai_docs")
                                .transport(
                                    McpTransportParam.Http.builder()
                                        .serverUrl("https://developers.openai.com/mcp")
                                        .build())
                                .build())
                        .addTool(AgentToolParam.WebSearch.builder().build())
                        .multiAgent(
                            MultiAgentConfigParam.builder()
                                .enabled(true)
                                .maxConcurrentSubagents(4L)
                                .build())
                        .build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .capabilityDirectories(List.of("/workspace/capabilities/skills"))
                        .build())
                .input(
                    "Research how to connect an MCP server to an OpenAI agent, check for recent"
                        + " updates, and summarize the recommended setup.")
                .build());
System.out.println(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
35
36
37
38
39
40
41
42
43require "openai"

client = OpenAI::Client.new

session = client.beta.agents.sessions.create(
  agent: {
    model: "gpt-6-astra",
    instructions: "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
    tools: [
      { type: "programmatic_tool_calling" },
      {
        type: "mcp",
        server_label: "openai_docs",
        transport: {
          type: "http",
          server_url: "https://developers.openai.com/mcp"
        }
      },
      { type: "web_search" }
    ],
    multi_agent: {
      enabled: true,
      max_concurrent_subagents: 4
    }
  },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/capabilities/skills"]
  },
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
        }
      ]
    }
  ]
)
puts 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
35
36
37
38
39
40
41
42
43
44
45
46curl -sS -X POST "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": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
      "tools": [
        {
          "type": "programmatic_tool_calling"
        },
        {
          "type": "mcp",
          "server_label": "openai_docs",
          "transport": {
            "type": "http",
            "server_url": "https://developers.openai.com/mcp"
          }
        },
        {
          "type": "web_search"
        }
      ],
      "multi_agent": {
        "enabled": true,
        "max_concurrent_subagents": 4
      }
    },
    "environment": {
      "type": "self_hosted",
      "workspace_directory": "/workspace",
      "capability_directories": ["/workspace/capabilities/skills"]
    },
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."
          }
        ]
      }
    ]
  }'

Para comparar ambientes de execução, consulte a visão geral de Agentes.

A API de Agentes mantém o estado da sessão para que você possa continuar o trabalho entre turnos sem reconstruir o contexto da conversa. Você pode excluir sessões e artefatos publicados quando não precisar mais deles. Atualmente, a API de Agentes oferece suporte à residência de dados apenas nos Estados Unidos e não oferece suporte à zero retenção de dados (ZDR). Escolher um sandbox em hospedagem própria não torna a API de Agentes elegível para ZDR. Consulte Controles de dados na plataforma OpenAI para obter detalhes sobre residência e retenção de dados.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Recursos

APIs legadas

Escolha um modelo

Texto e código

Criação de prompts

Raciocínio

Imagens e vídeo

Tempo real e áudio

Modelos especializados

SDK de Agentes

ChatKit

Pesquisa e recuperação

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolva com voz

Conexões

Processamento de áudio

Entre em produção

Desempenho e qualidade

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Plan

Build

Test and publish

Conversion specs

Guias

Recursos

Primeiros passos

Guias

File Upload

API

Measurement

Advertiser API

Referência da API

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Amplie os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Amplie e automatize

Ambientes

Desenvolva com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

ChatGPT Work

Identidade e autenticação

Acesso, política e modelos do workspace

Controles de plug-ins e conectores

Uso, governança e conformidade

Implantação e provedores de modelos

Comunidade

Blog

Comunidade

Blog