Visão geral

A API Agents está disponível em versão beta. Permite aos programadores criar aplicações com um agente Codex gerido pela OpenAI, capaz de trabalhar em várias etapas e de continuar na mesma sessão.

A sua aplicação fornece a tarefa, as ferramentas e a configuração. A OpenAI gere a sessão do agente e a coordenação entre o seu modelo e as ferramentas.

O que pode fazer um agente?

Consoante as ferramentas e o ambiente de execução, um agente pode executar código, editar ficheiros, usar ligações MCP e criar ficheiros para a sua aplicação. Pode enviar instruções adicionais ou continuar com outra tarefa na mesma sessão.

Consulte a visão geral da API Agents para conhecer as funcionalidades suportadas e ver exemplos.

Como posso 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 as sessões e api.responses.write para os pedidos 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 consultar o progresso e os resultados. Guarde o ID da sessão se quiser continuar o trabalho.

Mantenha a sua chave de API fora da sandbox do agente. Os pedidos requerem o cabeçalho OpenAI-Beta: agents=v1. Os SDKs da OpenAI adicionam este cabeçalho automaticamente.

O meu agente precisa de uma sandbox?

Escolha o ambiente adequado à tarefa:

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

• Sandbox alojada pela OpenAI: O agente precisa de executar scripts ou trabalhar com ficheiros, e pretende que a OpenAI gira a sandbox.

• Sandbox com alojamento próprio: Precisa da sua própria infraestrutura, software ou rede privada. A sua aplicação gere o ciclo de vida do ambiente.

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

Onde posso consultar uma sessão?

Abra os Registos no painel da plataforma, selecione Agentes e pesquise o ID da sessão. Pode examinar os turnos, as chamadas de ferramentas e a atividade dos subagentes.

O guia de observabilidade também explica como consultar o consumo de tokens registado.

O que devo fazer se o fluxo de eventos perder a ligação?

Obtenha a sessão existente e os respetivos itens guardados antes de tentar novamente. Isto permite verificar o que aconteceu antes de enviar mais trabalho.

Um turno concluído não significa que todas as ferramentas tenham sido executadas com êxito. Verifique o resultado apresentado. Uma sessão inativa, por si só, não confirma que a tarefa tenha sido concluída com êxito.

Como é faturada a utilização?

Os pedidos ao modelo são faturados às tarifas da API do modelo selecionado. Às ferramentas da OpenAI e às sandboxes alojadas pela OpenAI aplicam-se as respetivas tarifas de ferramentas e contentores.

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

Como são tratados os dados e ficheiros das sessões?

A API Agents conserva o estado da sessão para que o trabalho possa continuar ao longo de vários turnos. Pode eliminar sessões e artefactos publicados quando já não forem necessários. Guarde os ficheiros de que precisa antes de eliminar uma sessão.

Atualmente, a API Agents só suporta a residência de dados nos Estados Unidos. Não suporta a retenção zero de dados, mesmo quando utiliza uma sandbox alojada na sua própria infraestrutura. Consulte a documentação da API Agents para obter detalhes sobre os controlos de dados.