Pelos últimos anos, "um agente usa uma ferramenta" significou um mecanismo específico: o modelo emite um blob estruturado — usualmente JSON — nomeando uma função e seus argumentos, um runtime o analisa, chama a função, e alimenta o resultado de volta no contexto do modelo. Este padrão tool-calling alimentou a primeira geração de frameworks de agente e funciona. Mas ele tem uma ineficiência quieta que se torna óbvia uma vez que você a procura: cada ação é uma round-trip separada através do modelo. Quer chamar três ferramentas e combinar seus resultados? Isso é pelo menos três chamadas do modelo, cada uma relendo o contexto acumulado, porque o modelo pode apenas emitir uma chamada de ferramenta JSON por vez e deve aguardar para ver cada resultado antes de decidir o próximo. Uma escola crescente de pensamento em 2026 argumenta que há um jeito melhor, e está escondido em vista plena: deixe o agente escrever código.
Este é o paradigma de agente code-first, e está remodelando como os frameworks de agente mais eficientes funcionam. Em vez de emitir JSON, o agente escreve um snippet de Python — que pode chamar múltiplas ferramentas, loopear, usar variáveis e combinar resultados — e o runtime o executa. Este guia explica por que aquele shift importa, como muda desempenho e custo do agente, e como os frameworks líderes o implementam, através de smolagents (a abordagem code-first em sua forma mais pura) e Pydantic AI (agentes type-safe do time Pydantic). Também cobre o flip side essencial: executar código gerado por modelo seguramente.
O problema com chamadas de ferramenta JSON
Para ver por que code-first importa, olhe perto do que tool calling JSON custa. Considere uma tarefa que requer buscar dados de uma API, filtrá-los e computar um resumo. Com tool calls, o modelo emite uma chamada ao fetch tool, aguarda o resultado, emite uma chamada ao filter tool, aguarda, então emite uma chamada ao compute tool, aguarda, e finalmente compõe uma resposta. Isso são quatro invocações de modelo, e cada uma re-processa todo o contexto crescente — a tarefa original, mais cada resultado intermediário acumulado até aqui. O custo de token e latência escalem com o número de passos, e tarefas complexas têm muitos passos.
Há um problema mais sutil também: tool calling JSON restringe como o agente pode compor ações. Cada passo é uma chamada de função única com argumentos literais. O modelo não consegue facilmente expressar "chame essa ferramenta para cada item naquela lista," ou "se o resultado está vazio, tente uma query diferente," ou "combine esses dois resultados com um cálculo," sem quebrar cada um daqueles em round-trips separadas e raciocinar sobre estado intermediário através de chamadas de modelo. A expressiveness da programação ordinária — loops, conditionals, variáveis, composição — é exatamente o que está faltando, e aqueles são os construtos que tornam lógica multi-step natural. Tool calling pede ao modelo para ser um program counter emitindo uma instrução por vez, quando o que a tarefa precisa é um programa.
O insight code-first
A abordagem code-first resolve ambos os problemas de uma vez. Em vez de emitir uma chamada de ferramenta JSON única, o agente escreve um bloco de código Python que pode chamar várias ferramentas, usar control flow, segurar valores intermediários em variáveis e retornar um resultado. O runtime executa aquele código, e as ferramentas que o agente consegue chamar são simplesmente funções Python disponíveis em seu ambiente de execução. O fetch da API, o filter e o compute do exemplo anterior se tornam um bloco de código com três chamadas de função e um pouco de lógica entre elas — executado em um passo único, de uma invocação de modelo única.
O ganho de eficiência é real e mensurável. Porque um bloco de código consegue fazer o que previamente levou várias round-trips de tool-call, agentes code-first fazem significativamente menos chamadas LLM — reduções relatadas ao redor de 30% — que corta tanto custo quando latência. E porque o agente expressa ações em uma linguagem de programação real, manipula tarefas composicionais (iterando sobre resultados, branchendo em condições, combinando computações) muito mais naturalmente que uma sequência de chamadas JSON isoladas conseguiria. Há também um argumento de training-data: modelos têm visto quantidades enormes de código e são genuinamente bons em escrevê-lo, possivelmente melhor que em produzir JSON perfectly-formatted de tool-call para schemas novos. Pedir a um modelo para expressar sua intenção como código joga para uma força.
smolagents: o paradigma em sua forma mais pura
smolagents, do Hugging Face, é a expressão mais clara da ideia code-first. É uma biblioteca deliberadamente minimalista construída ao redor do CodeAgent: um agente cujas ações são código Python. Dê a ele um conjunto de ferramentas (funções Python ordinárias) e um modelo, mande a ele uma tarefa, e funciona escrevendo e executando código que chama aquelas ferramentas, loopeia, e computa até que tenha uma resposta. A biblioteca permanece pequena e hackeável propositalmente — sua filosofia é que o loop de agente deveria ser simples o suficiente para ler e modificar, com a inteligência vindo do modelo e da abordagem code-execution ao invés de um framework pesado.
O que torna smolagents compelling além da eficiência é como naturalmente manipula tarefas reais. Porque o agente escreve código, uma tarefa de pesquisa consegue buscar, analisar resultados, filtrá-los e computar sobre eles em um passo coerente único; uma tarefa de dados consegue carregar, transformar e analisar sem uma round-trip JSON por operação. É agnóstico ao modelo — funcionando com modelos Hugging Face, modelos locais ou qualquer provider através de LiteLLM — então você não está locked a um backend único, e suporta a execução em sandbox que code-first fundamentalmente requer (mais nisso abaixo). Para times que querem a eficiência code-first em um pacote pequeno, compreensível, smolagents é a implementação de referência, e a cheatsheet smolagents cobre seus agentes, ferramentas e sandboxing.
O tradeoff da minimalidade do smolagents é que ele fornece menos scaffolding que um framework heavyweight — menos abstrações built-in para orquestração complexa de multi-agente, estado durável ou control flow elaborado. Para loops de código de agente único isso é uma feature, não uma limitação; para sistemas com estado sprawling você poderia alcançar por algo mais pesado. Mas como a expressão mais pura, mais minimalista do code-first agentes, é difícil de bater.
Pydantic AI: type safety encontra agentes
Pydantic AI, do time atrás de Pydantic (a validation library que fundamenta FastAPI e muito do ecossistema Python AI), aborda agentes de um ângulo diferente: type safety e developer experience. Sua aposta é que a mesma rigor que Pydantic trouxe para validação de dados — declarando a forma dos seus dados com Python type hints e obtendo validação automática — deveria aplicar aos agentes. Cada entrada de agente, saída e tool call é typed, o framework valida que outputs de modelo combinam a estrutura esperada, e pode automaticamente pedir ao modelo para corrigir-se quando a saída não está em conformidade. O resultado é uma experiência de desenvolvedor estilo FastAPI para construir agentes: familiar, type-checked e production-oriented.
Type safety importa para agentes mais do que poderia parecer. Uma dor recorrente de aplicações LLM é que output de modelo é texto não estruturado, e transformá-lo confiavelmente nos dados estruturados que seu programa precisa — os campos certos, os tipos certos, valores válidos — é fiddly e error-prone. Pydantic AI torna saída estruturada uma garantia de primeira classe: você declara o tipo de saída, e o framework a reforça, retrying com o modelo se necessário. Isso transforma "analise o texto do modelo e esperança que está válido" em "receba um objeto validado, typed," que é exatamente o que código de produção quer. Seu redesenho V2 em 2026 empurrou mais adiante com um modelo harness-first que agrupa ferramentas, instruções e settings em capacidades compostas. A cheatsheet Pydantic AI cobre seus agentes typed e ferramentas.
Pydantic AI e smolagents não são realmente competidores tanto quanto expressões de prioridades diferentes. smolagents otimiza pela eficiência e expressiveness de código-como-ação; Pydantic AI otimiza por type safety, validated structured output e production ergonomics. Um time que valoriza menos chamadas LLM e lógica multi-step natural inclina smolagents; um time que valoriza type-checked, validated, código de agente estilo FastAPI inclina Pydantic AI. Ambos representam o movimento 2026 para longe dos frameworks de primeira geração, JSON-only para algo mais programmer-native.
O problema de segurança: executar código gerado por modelo
Agentes code-first têm um problema óbvio e sério: eles executam código escrito por um language model, e código gerado por modelo é untrusted por definição. Um agente que consegue escrever e rodar Python arbitrário consegue, se compromido por uma prompt injection ou simplesmente por estar errado, deletar arquivos, exfiltrar dados, fazer chamadas de rede ou consumir recursos sem limite. Esse não é um concern hipotético — é o risco operacional central de todo o paradigma, e levá-lo a sério é não-negociável para qualquer deployment de produção.
A resposta é sandboxing: execute o código gerado em um ambiente isolado com capacidades restritas. Os frameworks suportam isso diretamente — smolagents consegue executar código em sandboxes remotos como E2B, ou em containers Docker ou Modal, em vez de no processo host, e você consegue restringir quais módulos o código gerado é até permitido importar. O princípio é least privilege: o sandbox deveria ter apenas o acesso que a tarefa genuinamente requer — nenhum acesso de filesystem que não precisa, nenhum egress de rede além do que é necessário, nenhuma habilidade de afetar o host. Rodar código de agente gerado diretamente em seu processo de aplicação, com permissões de sua aplicação, é o erro que transforma um agente útil em uma vulnerabilidade de remote code execution vestindo uma interface amigável.
A guidance prática é straightforward mas deve ser seguida. Em desenvolvimento, execução local é conveniente e aceitável para tarefas confiáveis, não sensíveis. Em qualquer coisa aproximando produção, ou qualquer tarefa tocando input untrusted ou sistemas sensíveis, rode o código em um sandbox com acesso least-privilege, restrinja imports e trate a saída de código do agente do jeito que você trataria qualquer input untrusted — porque isso é o que é. A eficiência e poder de agentes code-first são reais, mas vêm com uma responsabilidade que tool calling JSON (que é mais restringido por design) não impôs tão nitidamente. Aceite aquela responsabilidade e sandbox apropriadamente, e o paradigma é tanto poderoso quando seguro.
Quando chamadas de ferramenta JSON ainda são a escolha certa
Agentes code-first são mais eficientes e expressivos, mas seria um erro conclua que JSON tool calling é obsoleto. Há situações reais onde o modelo constrangido, one-call-at-a-time é o melhor encaixe, e entendê-los mantém a escolha honesta. O mais claro é quando ações devem ser tightly controlled e auditadas. Uma chamada de ferramenta JSON é um evento discreto, inspecionável, facilmente-validado: o agente quer chamar essa função com esses argumentos, e você consegue aprovar, log ou rejeitar isso antes de qualquer coisa rodar. Aquela auditabilidade é valiosa em domains de high-stakes — ações financeiras, mudanças de infraestrutura, qualquer coisa com side effects irreversíveis — onde você quer um humano ou um policy check entre a intenção do agente e sua execução. Código que executa como um bloco é mais duro de gate naquela granularidade.
O segundo caso é simplicidade. Muitos agentes genuinamente apenas precisam chamar uma ferramenta por vez em um loop straightforward — responda uma pergunta chamando uma ferramenta de busca, look algo, execute uma ação. Para aqueles, a expressiveness de código-como-ação é capacidade não-usada, e o maquinário extra de um sandbox de código é overhead sem payoff. Um agente simples de tool-calling é mais fácil de raciocinar e deployar quando a tarefa não precisa de composição multi-step. O terceiro caso é postura de segurança: porque JSON tool calling apenas deixa o agente invocar funções pré-definidas com argumentos estruturados, é inerentemente mais restringido que executar código arbitrário, e para alguns threat models aquele blast radius menor é vale o custo de eficiência até quando uma tarefa conseguiria beneficiar de código.
A visualização madura é que essas são duas ferramentas para trabalhos diferentes, não um vencedor e um perdedor. Alcance por code-first quando tarefas envolvem composição genuína multi-step, iteração ou computação sobre resultados intermediários, e você consegue sandbox apropriadamente. Alcance por JSON tool calling quando ações precisam de controle fino-granulado e auditoria, quando a tarefa é simples o suficiente que código-como-ação é overkill, ou quando a restrição mais appertada de funções-pré-definidas-somente encaixa seus requisitos de segurança. Vários frameworks, incluindo smolagents, suportam ambos um CodeAgent e um agente de tool-calling exatamente para essa razão — o paradigma é uma escolha que você faz por use case, não uma doutrina que você adota wholesale.
A linha de fundo
O movimento de chamadas de ferramenta JSON para agentes code-first é um dos shifts significativos em como agentes são construídos em 2026, e é acionado por uma observação simples: deixar um agente escrever código, em vez de emitir uma chamada de ferramenta por vez, é mais eficiente e mais expressivo. Menos chamadas LLM, lógica multi-step natural e modelos jogando para sua força de code-writing são o payoff, visível nas reduções de chamada de aproximadamente 30% que frameworks code-first relatam. smolagents expressa o paradigma em sua forma mais pura, mais minimalista; Pydantic AI traz type safety e validated structured output para construção de agente. Ambos apontam para longe da primeira geração de frameworks JSON-only para algo mais programmer-native. A uma regra você não consegue pular: código gerado por modelo é untrusted, então o sandbox com least privilege. Faça isso, e agentes code-first são o jeito mais rápido, mais capaz para construir.
Referências e Recursos
Frameworks
Fundo e análise
- The best open source frameworks for building AI agents in 2026 — Firecrawl
- Python AI Agent Library Comparison 2026 — Pydantic AI vs Instructor vs Smolagents
- Best Python AI Agent Frameworks in 2026 — Uvik
Related 1337skills cheatsheets