OpenAI Agents SDK: uma aprovação precisa interromper a execução

Chamadas de ferramentas, estado persistido e decisões humanas têm funções distintas. Conectá-las determina como revisar e retomar uma ação de negócio.

O OpenAI Agents SDK oferece uma base programável para instruções, seleção de ferramentas, execução em etapas, delegação e rastreamento. Para conectar agentes a sistemas de negócio, escolher o framework é só uma parte: quais ações continuam automaticamente, quais precisam parar e quem pode retomá-las?

A introdução oficial descreve agentes, ferramentas, handoffs e guardrails, além de sessões, tracing, sandboxes e intervenção humana. São componentes. A aplicação ainda precisa conectá-los a identidade, permissões, armazenamento e sistemas de destino.

Quem controla o ciclo de execução?

Usar a Responses API diretamente faz sentido quando a aplicação quer controlar o ciclo, a distribuição das ferramentas e o estado. O Agents SDK atende a fluxos em que o runtime deve gerenciar turnos, execução, transferências ou sessões. As duas opções podem coexistir; não é necessário migrar todas as requisições.

Comece pelo que a equipe quer manter. Uma resposta curta pode dispensar orquestração complexa. Trabalhos com vários passos, arquivos reais e artefatos inspecionáveis ganham com estado e recuperação explícitos. O framework reduz implementação repetida, mas a aplicação define o ponto de conclusão do negócio.

Uma ferramenta retornar sucesso é um evento. Confirmar que o registro de destino mudou como esperado é outro. Dar o mesmo indicador de conclusão aos dois dificulta entender revisões e novas tentativas.

Ferramentas, verificações e aprovação

Ferramentas definem operações disponíveis. Guardrails validam entradas, saídas ou restrições. Aprovação concede permissão para uma ação específica de maior consequência. Configure essas responsabilidades separadamente.

O guia de intervenção humana permite declarar ferramentas que exigem aprovação. Uma chamada pendente aparece como interruption. A aplicação converte a execução em RunState, recebe uma decisão e retoma. O padrão também cobre ferramentas acionadas após handoffs e aprovações dentro de agentes usados como ferramentas.

Escrever no prompt “pergunte antes de enviar” não cria sozinho uma barreira de execução. Configure a política da ferramenta ou do runtime para parar e processe a interrupção. Da mesma forma, passar na validação dos parâmetros não significa que o responsável concordou com a ação.

Mostre o pedido e guarde o estado confiável no servidor

Quem revisa precisa ver destino, parâmetros, efeito esperado e evidências. O snapshot completo pode conter chamadas pendentes e informações sensíveis. Mantenha-o em armazenamento controlado pela aplicação no servidor.

O guia oficial informa que desserializar RunState não autentica o snapshot nem quem o enviou. Um objeto bem formado não comprova autoridade. Autentique o revisor, autorize seu acesso à execução e relacione a decisão à chamada pendente guardada no servidor.

O navegador pode enviar a decisão e um identificador opaco. Não deve substituir argumentos da ferramenta ou todo o estado. Escape nomes e parâmetros ao exibi-los. A interface expressa uma decisão; o runtime retoma o trabalho; a aplicação controla identidade e permissões.

A revisão simultânea exige coordenação. Depois que alguém consome o pedido e retoma a execução, uma página antiga não pode fazer o mesmo novamente. Use uma transição atômica que confirme proprietário e estado no armazenamento. Desabilitar o botão resolve apenas a apresentação.

Aprovado uma vez não significa executado uma vez

Uma ação externa pode terminar pouco antes de o processo cair, sem que o novo estado seja salvo. Retomar o snapshot aprovado anterior pode chamar a ferramenta de novo.

A documentação separa aprovação de efeitos exactly-once. Para pagamentos, mensagens e gravações de negócio, atribua uma chave estável de idempotência à ação lógica e use um destino que impeça efeitos duplicados. Reutilize chave e parâmetros ao tentar novamente, respeitando prazo de retenção e contrato do destino.

Quando isso não existir, reconcilie o resultado real antes de repetir. Uma consulta comum sem resultado não basta: a informação pode demorar a aparecer ou a chamada anterior ainda pode terminar. Se o resultado permanecer incerto, registre como desconhecido e evite repetição automática.

Isso muda a interface de revisão. Além de aprovado, a tarefa precisa distinguir tentativa realizada, destino confirmado e resultado indefinido. Separar decisão e execução mostra se o próximo passo é verificar ou tentar novamente.

Aprovação persistente precisa respeitar o escopo

O SDK oferece decisões por chamada e decisões persistentes para chamadas futuras correspondentes. A segunda opção reduz interrupções, mas exige conhecer as regras de correspondência.

O guia alerta que decisões persistentes de shell local e edição de arquivos correspondem a tipo e nome da ferramenta, não ao Agent proprietário. Se executores têm acessos diferentes, prefira decisões por chamada e um novo contexto de aprovação para novas permissões. Nomes iguais não comprovam autoridade igual.

Em aprovações que podem esperar muito tempo, preserve a versão do SDK ou da definição do agente. Um snapshot pausado precisa de uma rota compatível para restauração. Uma mudança posterior de ferramenta ou modelo pode alterar o significado do pedido.

Conecte o mecanismo à entrega da equipe

É possível usar o Buda para construir fluxos com materiais reais, execução e revisão. Prepare arquivos, restrições e entregáveis no Agent e inspecione os resultados antes da próxima autorização. O workspace e o Drive e memória sustentam o contexto contínuo. Desenvolver com SDK depende do controle de runtime necessário e da manutenção que a equipe pode assumir.

Em um serviço próprio de aprovação, complete primeiro um caminho inteiro: salvar a chamada pendente, receber decisão de pessoa autorizada, retomar a execução original, obter o resultado do destino e registrá-lo na mesma tarefa. Depois verifique queda do processo, envio duplicado e rejeição. O botão de aprovação é uma parte desse caminho.

Decisões de implementação

Tracing substitui auditoria de negócio?

O rastreamento ajuda a depurar a execução. A auditoria também precisa de identidade, escopo aprovado, parâmetros, resultado do destino e estado final. Relacione o trace à tarefa de negócio, mantendo suas funções distintas.

Toda chamada precisa de aprovação humana?

Divida ações por impacto e autorização existente. Leituras autorizadas de baixo risco podem continuar; gravações sensíveis e ações externas podem parar conforme a política da ferramenta. O essencial é uma regra efetiva na execução e uma explicação de por que cada ação foi permitida.