OpenAI Agents SDK
Construa um fluxo de atendimento que encaminha devoluções ao especialista e preserva um resultado estruturado. Comece pelo simulador local para tornar as fronteiras visíveis. Depois, implemente a mesma sequência no OpenAI Agents SDK com a versão que você efetivamente instalar e registrar. A fase integrada requer credencial local e acesso autorizado ao provedor; o código fornecido não realiza essa chamada.
A entrega deve distinguir duas evidências: a verificação local do contrato e a execução do SDK com tool call, handoff e trace. Não marque a segunda como concluída a partir da primeira. As falhas a investigar são pedido não autorizado, transferência indevida e saída incompleta. O objetivo é localizar cada defesa na aplicação e mostrar quais mecanismos foram fornecidos pelo framework.
BashOpenAIAgentesSegurançaAo terminar esta aula
- Validação local e integração de SDK são evidências distintas.
- A autorização deve funcionar também depois do handoff.
- A versão instalada determina quais APIs você pode reproduzir.
Antes de continuar: Leitura: OpenAI Agents SDK
Implemente a fronteira local primeiro
FundamentosSalve o exemplo em atendimento.cjs e execute. O caso P7 deve produzir o trace e o resultado de devolução. O caso P99 deve falhar antes da transferência. Acrescente ao trace um evento de tentativa recusada sem registrar conteúdo pessoal do pedido. Isso permite ver que a rejeição ocorreu no controle de acesso e não na interpretação do especialista. Troque temporariamente a validação de autorização por uma instrução textual: o simulador revela que a função continua acessível. Restaure o bloqueio no executor.
↗ Integrations and observability↗ Orchestration and handoffs
Defina um schema do resultado com status, pedido, próximos passos e evidências. Escreva os valores permitidos de status e o comportamento quando faltar informação. Um status aguardando_dados deve conter a pergunta necessária, enquanto um status encaminhado deve indicar o destino aprovado. Não use uma resposta livre para todas as situações, pois a interface precisará distinguir conclusão de pendência. Valide primeiro a estrutura e depois a consistência com o estado autorizado; as duas verificações detectam classes diferentes de falha.
Integre com documentação correspondente à versão
FundamentosInstale o SDK escolhido no projeto do laboratório e conserve o lockfile. Registre a versão exata, a versão de Node.js e o modelo configurado. Consulte as páginas oficiais de definição, execução e orquestração para essa instalação, criando o agente inicial, a ferramenta de leitura e o especialista de devoluções. Não copie nomes de métodos de tutoriais antigos sem comparar com a referência atual. O requisito funcional é observar uma chamada de ferramenta e uma transferência real, não encaixar o código em uma sintaxe presumida.
A ferramenta de leitura usa dados locais autorizados para que o teste integrado não altere sistemas de produção. Deixe a credencial em variável de ambiente, e mantenha a lógica de propriedade do pedido no executor. Execute uma solicitação clara de devolução e uma solicitação comum de consulta. A primeira deve transferir o controle; a segunda pode permanecer no agente inicial. Se o modelo selecionar o destino errado, capture o caso e revise instruções ou roteamento sem remover os controles determinísticos que protegem os dados.
Inspecione guardrails e continuidade
SegurançaCrie um caso em que o especialista tenta operar sobre P99. O controle deve bloquear mesmo que a entrada inicial tenha sido aceita para P7. Essa prova identifica se você confiou demais em uma validação aplicada apenas no início. Acrescente aprovação somente a uma operação com efeito, como confirmar devolução, deixando claro que a proposta precisa ser vista antes da execução. No teste local, represente essa operação por registro fictício; na integração, conserve a fronteira para que o agente não consiga confirmar por simples texto.
Faça um segundo turno perguntando sobre a mesma solicitação. Escolha uma única estratégia de continuação e verifique quais campos reaparecem. Compare o estado enviado com a documentação da versão instalada. Não presuma que o trace será usado como memória: rastreamento serve para inspeção, enquanto sessão serve para continuidade. Uma sessão com histórico completo também pode conter dados demais; revise retenção e minimização. Ao reiniciar o processo, registre o que foi preservado e o que foi perdido na configuração realmente utilizada.
Apresente o trace junto do resultado
FundamentosExporte ou capture um trace autorizado contendo entrada, chamada, handoff e saída. Remova credenciais e dados pessoais das evidências compartilhadas. Relacione os eventos do trace oficial aos marcos do simulador, indicando onde a validação ocorreu. Se a integração não tiver sido executada, seu relatório deve dizer exatamente isso e apresentar somente o teste local. Para aceitar a entrega semanal completa, é necessário demonstrar o comportamento do SDK, e não somente um diagrama do fluxo esperado.
↗ Integrations and observability↗ Orchestration and handoffs
Resolução integrada, ambiente e evidência
FundamentosSalve a resolução como openai.mjs. Esta implementação usa Agent, tool, run, MemorySession e o tracing reais de @openai/agents0.19.0. Um modelo dublê produz a sequência tool, handoff e saída para tornar o teste reproduzível sem chave; o SDK efetivamente executa a ferramenta, transfere para devolucoes, valida o schema e conserva seis itens de histórico. O processor local substitui o exportador de traces e recebe spans de function e handoff, sem enviar dados. O teste final propõe P99 e exige rejeição pelo executor. Foram executados esses caminhos localmente; qualidade de um modelo OpenAI e exportação ao painel do provedor não foram medidas. Para testar o modelo real, remova a propriedade model dos dois agentes e configure o modelo disponível e a credencial local conforme a documentação; conserve os testes e o processor enquanto revisar dados sensíveis.
↗ Running agents↗ Orchestration and handoffs↗ Integrations and observability
npm init -y
npm install --save-exact @openai/agents@0.19.0 zod@4.6.5
node openai.mjsExercí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
Salve a resolução como openai.mjs. Esta implementação usa Agent, tool, run, MemorySession e o tracing reais de @openai/agents0.19.0. Um modelo dublê produz a sequência tool, handoff e saída para tornar o teste reproduzível sem chave; o SDK efetivamente executa a ferramenta, transfere para devolucoes, valida o schema e conserva seis itens de histórico. O processor local substitui o exportador de traces e recebe spans de function e handoff, sem enviar dados. O teste final propõe P99 e exige rejeição pelo executor. Foram executados esses caminhos localmente; qualidade de um modelo OpenAI e exportação ao painel do provedor não foram medidas. Para testar o modelo real, remova a propriedade model dos dois agentes e configure o modelo disponível e a credencial local conforme a documentação; conserve os testes e o processor enquanto revisar dados sensíveis.
O caso nominal transfere para devolucoes e retorna um objeto com pedido P7. O pedido P99 é recusado na entrada, e o mesmo controle deve existir no executor da ferramenta para impedir chamadas posteriores indevidas. A validação de saída deve rejeitar ausência de campos, valores desconhecidos e resultados incompatíveis com as observações.
A implementação integrada preserva essas regras enquanto usa o runner, as ferramentas e os handoffs do SDK instalado. O trace precisa confirmar a sequência real. Registre falhas de seleção e custo observado sem tratá-los como benchmarks gerais: uma execução isolada caracteriza somente aquele caso e configuração.
import { Agent,tool,run,Usage,MemorySession,setTraceProcessors,withTrace } from '@openai/agents';
import { z } from 'zod';
import assert from 'node:assert/strict';
// Testa o runtime verdadeiro com um modelo dublê. Nenhuma chamada ao provedor.
const spans=[];
// Processor local substitui o exportador: tracing real do SDK, sem enviar dados.
setTraceProcessors([{onTraceStart(){},onTraceEnd(){},onSpanStart(){},onSpanEnd(span){spans.push(span.spanData.type);},async forceFlush(){},async shutdown(){}}]);
const eventos=[];
const consultar=tool({name:'consultar_pedido',description:'Leitura autorizada de pedido.',parameters:z.object({pedido:z.string()}),errorFunction:null,execute:async({pedido})=>{
if(pedido!=='P7')throw new Error('pedido nao autorizado');
eventos.push({evento:'tool',pedido});return {pedido,item:'I2'};
}});
let turno=0,pedidoTeste='P7';
const model={
async getResponse(request){
turno++;let output;
if(turno===1)output=[{type:'function_call',callId:'c1',name:'consultar_pedido',arguments:JSON.stringify({pedido:pedidoTeste})}];
else if(turno===2){const destino=request.handoffs[0].toolName;eventos.push({evento:'handoff_proposto',destino});output=[{type:'function_call',callId:'c2',name:destino,arguments:'{}'}];}
else output=[{type:'message',role:'assistant',status:'completed',content:[{type:'output_text',text:'{"status":"encaminhado","pedido":"P7"}'}]}];
return {usage:new Usage(),output};
},async *getStreamedResponse(){throw new Error('stream fora do teste');}
};
const schema=z.object({status:z.literal('encaminhado'),pedido:z.literal('P7')});
const especialista=new Agent({name:'devolucoes',instructions:'Analise a devolucao.',model,outputType:schema});
const agente=new Agent({name:'suporte',instructions:'Consulte antes de transferir.',model,outputType:schema,tools:[consultar],handoffs:[especialista]});
const session=new MemorySession();
const resultado=await withTrace('curso-atendimento',()=>run(agente,'Devolucao do pedido P7',{session,maxTurns:6}));
assert.equal(resultado.finalOutput.pedido,'P7');
assert.equal(resultado.lastAgent.name,'devolucoes');
console.log('saida',resultado.finalOutput,'itens',resultado.newItems.map(i=>i.type));
console.log('eventos',eventos,'historico', (await session.getItems()).length);
console.log('spans locais',spans);assert(spans.includes('function'));assert(spans.includes('handoff'));
turno=0;pedidoTeste='P99';
await assert.rejects(()=>run(agente,'Pedido proibido',{maxTurns:6}),/pedido nao autorizado/);
console.log('pedido proibido recusado pelo executor');
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.
Dublê no SDK consulta L4 autorizado, transfere suporte→devoluções e devolve {status: 'encaminhado', pedido: 'L4'}. Segunda execução propõe L5 proibido. Resolva schema, agente final e trace.
Conferir raciocínio e critérios de domínio
A primeira execução termina no agente devoluções com objeto compatível com schema e histórico de tool/handoff/saída.
L5 é negado pelo executor antes de devolver dados, mesmo que a seleção do modelo dublê o proponha.
O processor local deve receber spans function/handoff; isso demonstra runtime, não qualidade de seleção de um modelo externo nem exportação ao painel.
Evidências para autoavaliação ou revisão por pares
- Agente final e schema: A primeira execução termina no agente devoluções com objeto compatível com schema e histórico de tool/handoff/saída.
- Autorização da tool: L5 é negado pelo executor antes de devolver dados, mesmo que a seleção do modelo dublê o proponha.
- Trace e limites: O processor local deve receber spans function/handoff; isso demonstra runtime, não qualidade de seleção de um modelo externo nem exportação ao painel.
Um erro frequente
Array de eventos equivale a tracing integrado.
Tracing integrado exige spans reais do runtime, não só logs inventados.
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.