Visão geral

A API de agentes está disponível em versão beta. Ela permite que desenvolvedores criem aplicações com um agente Codex gerenciado pela OpenAI, capaz de trabalhar em várias etapas e dar continuidade ao trabalho na mesma sessão.

Sua aplicação fornece a tarefa, as ferramentas e a configuração. A OpenAI gerencia a sessão do agente e a coordenação entre o modelo e as ferramentas dele.

O que um agente pode fazer?

Dependendo das ferramentas e do ambiente de execução, um agente pode executar código, editar arquivos, usar conexões MCP e gerar arquivos para sua aplicação. Você pode enviar instruções adicionais ou continuar com outra tarefa na mesma sessão.

Consulte a visão geral da API de agentes para ver os recursos disponíveis e exemplos.

Como começar?

1. Crie uma chave de API para a aplicação no seu projeto na plataforma OpenAI. Conceda as permissões api.agents.read e api.agents.write para sessões, além de api.responses.write para solicitações ao modelo.

2. Siga o guia de início rápido para configurar um agente, criar uma sessão e enviar uma tarefa.

3. Acompanhe os eventos da sessão para conferir o progresso e os resultados. Salve o ID da sessão se quiser continuar o trabalho.

Mantenha sua chave de API fora do sandbox do agente. As solicitações exigem o cabeçalho OpenAI-Beta: agents=v1. Os SDKs da OpenAI adicionam esse cabeçalho automaticamente.

Meu agente precisa de um sandbox?

Escolha o ambiente adequado para a tarefa:

• Sem ambiente: O agente responde a perguntas ou usa ferramentas externas sem precisar de comandos de shell integrados ou de arquivos do espaço de trabalho.

• Sandbox hospedado pela OpenAI: O agente precisa executar scripts ou trabalhar com arquivos, e você quer que a OpenAI gerencie o sandbox dele.

• Sandbox hospedado em infraestrutura própria: Você precisa usar sua própria infraestrutura, seus softwares ou sua rede privada. Sua aplicação gerencia o ciclo de vida do ambiente.

Consulte a arquitetura da API de agentes para obter detalhes de configuração.

Onde posso analisar uma sessão?

Abra os Logs no painel da plataforma, selecione Agentes e busque o ID da sessão. Você pode inspecionar turnos, chamadas de ferramentas e atividades de subagentes.

O guia de observabilidade também explica como consultar o uso de tokens registrado.

E se o fluxo de eventos for desconectado?

Recupere a sessão existente e seus itens salvos antes de tentar novamente. Isso ajuda a verificar o que aconteceu antes de enviar mais tarefas.

Um turno concluído não significa que todas as ferramentas foram executadas com sucesso. Analise o resultado informado. Uma sessão ociosa, por si só, não comprova que a tarefa foi concluída com sucesso.

Como o uso é cobrado?

As solicitações ao modelo são cobradas pelas tarifas de API do modelo selecionado. As ferramentas da OpenAI e os sandboxes hospedados pela OpenAI são cobrados pelas respectivas tarifas de ferramentas e contêineres.

Consulte os preços da API para ver as tarifas atuais.

Como os dados e arquivos da sessão são tratados?

A API de agentes mantém o estado da sessão para que o trabalho possa continuar entre turnos. Você pode excluir sessões e artefatos publicados quando não forem mais necessários. Salve os arquivos de que precisar antes de excluir uma sessão.

Atualmente, a API de agentes oferece suporte à residência de dados apenas nos Estados Unidos. Ela não oferece suporte à zero retenção de dados, mesmo quando você usa um sandbox hospedado em infraestrutura própria. Consulte a documentação da API de agentes para obter detalhes sobre os controles de dados.