OpenAI Agents SDK
A utilidade de um SDK de agentes aparece quando você precisa combinar instruções, ferramentas, continuidade e rastreamento em um fluxo consistente. Ele organiza a execução, mas não conhece a regra financeira do seu negócio nem decide quem pode cancelar um pedido. Nesta semana, o caso será um atendimento que consulta dados e transfere a conversa a um especialista em devoluções quando o assunto exige outro conjunto de instruções. A saída deve ser estruturada e verificável.
As fontes oficiais do OpenAI Agents SDK descrevem agentes, ferramentas, handoffs, guardrails, resultados e tracing. O exemplo local desta aula representa essas fronteiras sem importar o pacote, portanto não é um teste do SDK nem uma receita de API com versão implícita. A implementação integrada do laboratório exige fixar a versão instalada, conferir os métodos correspondentes na documentação e separar os resultados locais dos obtidos com o provedor.
JavaScriptOpenAIAgentesSegurançaAo terminar esta aula
- SDK organiza o loop; a aplicação conserva regras de negócio e autorização.
- Handoff e especialista como ferramenta mudam quem controla a conversa.
- Resultado estruturado e tracing ajudam inspeção, mas não garantem verdade.
Antes de continuar: Laboratório: Agent state/persistence/approval
Agente é configuração; runtime é execução
AgentesUm agente reúne instruções, modelo e ferramentas disponíveis. Essas instruções descrevem o papel e os limites; as ferramentas representam operações que a aplicação implementa. O runtime recebe entrada, consulta o modelo e interpreta o resultado, continuando diante de ferramentas ou handoffs até produzir uma saída ou interrupção. A diferença é prática: alterar instruções não muda a autorização de uma API financeira. O executor da ferramenta precisa validar os argumentos e usar a identidade estabelecida pela aplicação. Uma descrição de ferramenta pode ajudar a escolha, mas não é um mecanismo de controle de acesso.
No atendimento, consultar pedido é leitura, preparar devolução é proposta e confirmar devolução é efeito. Separe essas operações em contratos diferentes. Valide que o identificador pertence ao cliente antes da consulta e que a devolução atende à política antes da alteração. Campos estruturados ajudam a detectar ausência de informação: um resultado pode exigir status, pedido e evidências. Eles não garantem verdade semântica. O modelo pode preencher um identificador de aparência válida com um pedido inexistente; a aplicação ainda precisa comparar a saída com os dados autorizados.
Handoff transfere a responsabilidade conversacional
FundamentosUm handoff muda o agente ativo para um especialista. É adequado quando a devolução precisa conduzir as próximas perguntas e respostas. Usar um especialista como ferramenta é diferente: o controlador principal solicita uma contribuição e continua responsável pela síntese. A escolha depende de quem deve dirigir o fluxo depois da consulta. Para nosso caso, o especialista de devoluções recebe a intenção e o identificador do pedido; ele não precisa receber todo o histórico pessoal do cliente. Filtrar o contexto reduz exposição e também evita instruções irrelevantes.
Orquestração pode ser conduzida pelo modelo ou por regras da aplicação. Se a palavra-chave ou uma classificação validada já determina a área responsável, um roteamento explícito pode ser suficiente. Se a escolha depende de interpretação contextual, o modelo pode propor o destino, e a aplicação deve aceitar apenas destinos conhecidos. Não permita que o texto do usuário escolha um nome arbitrário de agente ou uma ferramenta de maior privilégio. Um handoff altera o papel de conversação, mas não cria automaticamente permissão para o especialista acessar dados de outro cliente.
Guardrails precisam acompanhar a fronteira de efeito
SegurançaA documentação oficial distingue guardrails de entrada, saída e ferramentas e explica que sua cobertura depende da posição no fluxo. Um controle apenas na entrada inicial não substitui a verificação de uma ferramenta sensível executada depois de um handoff. Posicione a validação perto do efeito: tipo e faixa de argumentos, identidade, propriedade do pedido e aprovação quando aplicável. Se o guardrail for baseado em modelo, sua decisão continua sujeita a erros; regras determinísticas devem cobrir os limites que conseguem ser expressos de forma exata.
O simulador rejeita qualquer pedido fora da lista autorizada, escolhe um especialista conhecido e valida a forma do resultado. O trace guarda três marcos: entrada aceita, transferência e saída validada. Isso permite reconstruir a decisão operacional sem armazenar raciocínio privado. Em produção, traces podem conter argumentos e resultados sensíveis; defina política de coleta, mascaramento, acesso e retenção. Um trace é evidência de execução, não prova de que a saída é correta. Para provar correção, compare o conteúdo com o pedido e com a política de devolução.
function atender(entrada) {
const trace=[];
if (entrada.pedido !== 'P7') throw new Error('pedido nao autorizado');
trace.push({evento:'entrada_validada',pedido:entrada.pedido});
const destino=entrada.assunto==='devolucao' ? 'devolucoes' : 'suporte';
trace.push({evento:'handoff_local',destino});
const resultado={status:'encaminhado',pedido:entrada.pedido,destino};
if (!resultado.pedido || resultado.status!=='encaminhado') throw new Error('saida invalida');
trace.push({evento:'saida_validada'});
return {resultado,trace};
}
console.log(atender({pedido:'P7',assunto:'devolucao'}));
try { atender({pedido:'P99',assunto:'devolucao'}); } catch(e) { console.log(e.message); }Continuidade e avaliação do resultado
AvaliaçãoSessões e mecanismos de continuação preservam contexto entre turnos, enquanto um resultado de execução expõe superfícies úteis para continuar ou inspecionar o trabalho. Escolha uma estratégia coerente com a versão e com o controle de armazenamento desejado. Não misture histórico reconstruído, sessão persistida e estado remoto sem compreender quem é a fonte de verdade. Se você reenviar todo o histórico juntamente com um estado que já o contém, pode duplicar contexto ou aumentar custo. O estado de conversa também não substitui o ledger de efeitos discutido na semana anterior.
Avalie o fluxo com pedido permitido, pedido proibido, solicitação ambígua e saída malformada do especialista. Registre destino selecionado, ferramentas usadas, resultado final e posição em que o bloqueio ocorreu. Uma implementação que acerta a resposta, mas consulta um pedido proibido, deve falhar. Compare também handoff com especialista como ferramenta para perceber a mudança de controle. O SDK oferece os mecanismos; a arquitetura precisa explicar por que cada um foi escolhido e que regra crítica permanece aplicada pela aplicação, fora de instruções naturais.
Exercício aplicado
Um atendimento deve consultar P7, transferir pedidos de devolução ao especialista e retornar um objeto estruturado. Pedidos fora do conjunto autorizado não podem ser consultados, mesmo depois da transferência.
- Execute o simulador e capture os eventos de P7 e P99.
- Defina e valide o schema do resultado.
- Fixe a versão do SDK e implemente ferramenta, handoff e continuação conforme a documentação oficial.
- Capture um trace da execução integrada e descreva a posição dos guardrails.
Abrir resolução comentada
A resolução aceita apenas P7, identifica devolução e registra a transferência para um destino conhecido. O especialista local devolve status e pedido, e a validação final exige o status permitido. Para representar uma falha de saída, substitua o resultado por um objeto sem pedido; acrescente ao validador a exigência desse campo e observe o bloqueio. Essa revisão evita que uma estrutura parcialmente correta seja apresentada como resultado completo.
Ao integrar o SDK, mantenha o mesmo catálogo de casos e associe cada transição ao trace oficial da versão fixada. O laboratório não inventa uma versão do pacote nem afirma ter executado chamadas de modelo. A evidência integrada deverá conter versão, configuração do agente, ferramenta consultada, handoff observado e validação da saída.
function atender(entrada) {
const trace=[];
if (entrada.pedido !== 'P7') throw new Error('pedido nao autorizado');
trace.push({evento:'entrada_validada',pedido:entrada.pedido});
const destino=entrada.assunto==='devolucao' ? 'devolucoes' : 'suporte';
trace.push({evento:'handoff_local',destino});
const resultado={status:'encaminhado',pedido:entrada.pedido,destino};
if (!resultado.pedido || resultado.status!=='encaminhado') throw new Error('saida invalida');
trace.push({evento:'saida_validada'});
return {resultado,trace};
}
console.log(atender({pedido:'P7',assunto:'devolucao'}));
try { atender({pedido:'P99',assunto:'devolucao'}); } catch(e) { console.log(e.message); }Como conferir seu resultado
- O simulador rejeita P99 antes de encaminhar.
- A execução integrada demonstra tool call e handoff.
- A saída possui forma e conteúdo compatíveis com o pedido autorizado.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Separar configuração Agent e runner.
- Entender tool/handoff/estado de sessão.
Suporte passa pedido autorizado L4 ao especialista. Outro pedido L5 aparece após handoff. Onde proteger e que trace esperar?
Conferir raciocínio e critérios de domínio
Handoff muda agente ativo; especialista como tool retornaria ao controlador.
Executor deve negar L5 independentemente do agente; guardrails não substituem autorização.
Trace de tool/handoff e resultado estruturado mostram caminho; modelo dublê não avalia seleção real.
Evidências para autoavaliação ou revisão por pares
- Transferência: Handoff muda agente ativo; especialista como tool retornaria ao controlador.
- Defesa: Executor deve negar L5 independentemente do agente; guardrails não substituem autorização.
- Evidência: Trace de tool/handoff e resultado estruturado mostram caminho; modelo dublê não avalia seleção real.
Um erro frequente
Guardrail inicial protege toda chamada posterior.
Autorização deve existir também no executor de cada chamada.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Handoff concede nova autorização?
Não. Ele transfere o controle conversacional.
Permissões continuam derivadas da aplicação e dos executores.
2. Tracing substitui avaliação?
Não. Mostra eventos que precisam ser comparados com critérios de correção.
Uma sequência bem registrada ainda pode conter uma decisão errada.
3. Saída estruturada garante fatos verdadeiros?
Não. O schema verifica forma; evidências verificam conteúdo.
Um campo válido pode conter um identificador inventado.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Agent definitions
OpenAI • consulta: 2026-10-06
OpenAIAgentesDefinição de agente, instruções, tools e saída estruturada.
Limites: APIs e nomes diferem entre Python e TypeScript; usar versão fixada no laboratório.
- Orchestration and handoffs
OpenAI • consulta: 2026-10-06
OpenAIAgentesHandoffs transferem responsabilidade; agents-as-tools mantêm o gestor responsável; especialistas e custos de divisão.
Limites: Não demonstra superioridade universal de múltiplos agentes; medir qualidade, custo e latência.
- Guardrails and human review
OpenAI • consulta: 2026-10-06
OpenAISegurançaGuardrails de entrada, saída e ferramentas; interrupções de aprovação e retomada.
Limites: Guardrails de entrada só no primeiro agente e de saída no agente final; validação não substitui autorização.
- Results and state
OpenAI • consulta: 2026-10-06
OpenAIResultados, estado retomável e continuidade de conversas.
Limites: Serializar estado de execução e persistir sessões são escolhas diferentes; armazenamento é responsabilidade da aplicação.
- Integrations and observability
OpenAI • consulta: 2026-10-06
OpenAIAvaliaçãoTracing de runs, chamadas, handoffs, guardrails e integração MCP.
Limites: Considerar dados sensíveis nos traces e controles de retenção; tracing não prova correção.
- Running agents
OpenAI • consulta: 2026-10-06
OpenAIAgentesLoop do SDK, tool calls, critérios de término, streaming e continuação.
Limites: Controle de duração e ferramentas exige configuração; SDK não fornece automaticamente infraestrutura durável.