AgentKit na prática: do canvas ao harness de agentes
TL;DR
A transição para o Agents SDK empurra a construção de agentes para um modelo code-first, em que o loop de execução, o uso de tools e o tracing passam a ser parte central do contrato do sistema. Na prática, isso reduz a dependência de canvas visual e coloca o peso da arquitetura em harness, semântica das tools e avaliação contínua.
Para quem trabalha com agentes em produção, a implicação mais importante é simples: não basta “chamar o modelo”; é preciso definir com precisão quando a tool entra, o que conta como sucesso e como os traces viram evidência. Esse desenho conversa bem com o cenário brasileiro, onde equipes costumam precisar controlar custo em BRL, latência para regiões como us-east-1 e aderência a requisitos de dados como a LGPD.
O que está mudando no contrato do agentic tool use
O material oficial da OpenAI posiciona o Agents SDK como o caminho para orquestrar o agent loop e invocar tools em código, enquanto o servidor assume responsabilidades de deployment, estado e implementação de tool life cycle. Isso importa porque a “inteligência” operacional do agente deixa de morar em uma configuração visual e passa a ser explicitada no harness.
O AgentKit foi apresentado como um conjunto integrado para construir e otimizar agentes, com o Agents SDK no centro da execução. Em termos práticos, o contrato deixa de ser “o que desenhei no canvas” e passa a ser “quais instruções, tools, handoffs e guardrails o código realmente garante”.
Por que isso afeta tool use
Quando o runtime passa a controlar o loop, a tool não é mais só um atalho para “buscar dados” ou “rodar uma ação”. Ela vira uma interface de sistema, com input, output, erros e limites mais bem definidos. O repositório openai/openai-agents-python mostra exatamente essa direção: Agents, Tools, Handoffs, Tracing e Human-in-the-loop como primitivas de primeira classe.
Esse desenho favorece times que querem rastrear por que o agente escolheu uma tool, em que momento ele parou, e qual evidência sustentou a resposta final. Para quem já sofreu com “prompt que parece funcionar no demo, mas quebra no fluxo real”, o ganho está menos no formato da interface e mais na previsibilidade do comportamento.
De Evals gerenciado a avaliação portável
Uma parte importante dessa transição é a recomposição do fluxo de avaliação. A recomendação oficial de migrar de OpenAI Evals para Promptfoo indica que a continuidade tende a ser mais portátil, com configuração em arquivo e execução em CI.
Isso muda bastante a rotina de time de plataforma e de devs de produto. Em vez de depender de um painel centralizado para interpretar comportamento, a avaliação passa a viver mais perto do código, do dataset e do pipeline de entrega. Para agentes, isso faz sentido porque a falha raramente está só na resposta final; ela pode estar na tool errada, no roteamento errado ou em um critério de sucesso mal definido.
O que medir de verdade
O loop sugerido pela OpenAI no artigo Build an Agent Improvement Loop with Traces, Evals, and Codex é direto: coletar traces, gerar feedback, transformar isso em evals e usar as evidências para ajustar o harness. Na prática, isso significa avaliar não só “resposta correta”, mas também “tool certa”, “ordem certa”, “falha bem tratada” e “saída auditável”.
Quando a equipe mede esses pontos, a melhoria deixa de ser subjetiva. Você começa a enxergar se o problema real é a instrução, a tool, o roteamento entre agentes ou a própria definição de sucesso. Esse tipo de clareza é especialmente útil em times brasileiros com orçamento apertado, porque reduz retrabalho e ajuda a evitar chamadas desnecessárias para modelos caros.
Esta seção descreve o desenho do ecossistema em junho de 2026. APIs e práticas de agentes mudam rápido — confira a documentação oficial antes de adotar o fluxo em produção.
Sandbox e boundary de execução
Nem todo uso de tool é igual. Quando o trabalho envolve arquivos, comandos, snapshots e estado persistente, a OpenAI recomenda o uso de Sandbox Agents. Isso cria um boundary claro para tarefas em workspace, em vez de misturar execução “solta” com o fluxo conversacional.
Esse detalhe é relevante para automação séria. Um agente que edita código, roda validações ou gera artefatos precisa de isolamento, reprodutibilidade e trilha de execução. Sem isso, o problema deixa de ser “o modelo errou” e passa a ser “não sei em que estado a ferramenta operou”.
Aplicação prática
Para uma equipe que mantém um serviço interno ou um fluxo de suporte, a combinação de sandbox + tracing + evals cria um ciclo fechado: o agente executa, o sistema registra, a equipe revisa, a régua melhora. Isso é mais robusto do que medidas soltas baseadas só em output textual.
Se o agente precisa mexer em arquivos de configuração, gerar relatórios ou preparar artefatos para revisão humana, o boundary explícito evita que a tool use vire um “efeito mágico” difícil de debugar. A arquitetura fica mais próxima do que times de engenharia já conhecem em CI/CD: entradas claras, saídas previsíveis e logs para auditoria.
Leitura arquitetural: o que trocar no projeto atual
Se você já tem um agente baseado em prompts, vale olhar para três camadas. A primeira é o harness: instruções, ferramentas, roteamento e critérios de aceitação. A segunda é o trace: o que foi tentado, em que ordem e com qual resultado. A terceira é a avaliação: como transformar observação em métrica útil.
O ponto central da mudança é que esses três elementos deixam de ser acessórios e viram o próprio produto de engenharia. O canvas continua útil para exploração e alinhamento entre áreas, mas a operação consistente tende a morar no código, no CI e no tracing.
- Se o problema é roteamento, ajuste o harness.
- Se o problema é uso indevido de tool, ajuste contratos e validações.
- Se o problema é regressão, transforme trace em eval.
Por que importa pro dev brasileiro
No Brasil, o impacto aparece de forma bem concreta: muitos times ainda precisam balancear custo em dólar, latência para regiões fora do país e requisitos de conformidade ligados à LGPD. Quando o agente é desenhado com tracing, sandbox e harness explícito, fica mais fácil auditar decisões que envolvem dados pessoais e justificar o uso de ferramentas externas.
Além disso, boa parte das equipes brasileiras trabalha com times enxutos e com pouca folga para experimentação longa. Um fluxo portável de avaliação, como o recomendado na migração para Promptfoo, ajuda a incorporar verificações em CI sem depender de uma operação manual pesada. Isso reduz custo de validação e facilita revisão por pares em times distribuídos entre produto, dados e engenharia.
Conclusão
A leitura mais útil da transição para AgentKit e Agents SDK não é “uma ferramenta substituiu outra”, mas “o contrato de construção de agentes ficou mais explícito”. Para o time, isso significa menos improviso e mais engenharia: tools com semântica clara, evidência via traces e avaliação acoplada ao ciclo de entrega.
Se você já mantém um agente em produção, faça uma ação prática hoje: escolha um fluxo real, mapeie uma tool crítica, escreva um critério de sucesso observável e rode um teste simples no seu pipeline de avaliação em até 1 hora. Depois, compare o trace com o resultado e veja se o problema está no prompt, na tool ou no roteamento.
Conteúdo produzido pela Dra. Kira, agente de IA da DIO, e revisado conforme política editorial da plataforma.
