Agentes de IA com smolagents: quando usar ações em Python

Use smolagents para criar agentes de IA em Python quando for preciso combinar ferramentas e cálculos de forma dinâmica e houver um ambiente controlado para executar esse código. A Hugging Face oferece 2 classes de agente, CodeAgent e ToolCallingAgent: a escolha depende de como o modelo deve expressar a próxima ação, em Python ou por uma chamada estruturada de ferramenta. A proposta enxuta ajuda a resolver problemas com escopo definido, mas a responsabilidade por fluxos de trabalho persistentes, permissões e isolamento continua sendo sua.

Verificado com base na documentação oficial disponível da Hugging Face, LangChain e OpenAI em 31 de outubro de 2026. As recomendações a seguir comparam a composição de ações, o controle do fluxo de trabalho e os limites de execução. São avaliações de arquitetura, não benchmarks de desempenho.

Como o smolagents cria agentes de IA com Python

smolagents é a biblioteca Python de código aberto da Hugging Face para criar agentes de inteligência artificial cujas ações podem ser código executável. Um agente funciona em um ciclo guiado pelo modelo: escolhe uma ação, observa o resultado e decide o próximo passo. CodeAgent expressa essa ação em Python; ToolCallingAgent usa chamadas estruturadas de ferramentas. Ambos recebem um modelo e um conjunto de ferramentas. Referência de agentes da Hugging Face.

Pense no CodeAgent como um pesquisador que pode escrever um pequeno script entre uma observação e outra. Ele pode consultar registros por meio de uma ferramenta autorizada, transformar os dados recebidos e calcular uma resposta. Você define as capacidades e as restrições; o modelo escreve parte da lógica que conecta essas peças.

Isso é diferente de um assistente que entrega um arquivo de código para você revisar. Aqui, o código gerado é o meio pelo qual o agente executa a próxima ação.

Para comparar as opções, vale identificar qual parte da aplicação precisa de flexibilidade:

As duas últimas linhas descrevem o foco apresentado na documentação do LangGraph e do OpenAI Agents SDK, não capacidades exclusivas. A decisão depende de onde você quer que o framework forneça estrutura.

CodeAgent do smolagents: deixe o modelo combinar ações

CodeAgent faz sentido quando é mais fácil expressar as etapas intermediárias em Python do que em um menu fixo de chamadas. A Hugging Face destaca loops, condicionais e combinações de ferramentas entre seus pontos fortes, junto da necessidade de lidar com erros de sintaxe, exceções e comportamentos inesperados. Visão geral guiada.

Imagine, por exemplo, um desenvolvedor investigando inconsistências em registros de estoque. Uma ferramenta de consulta somente para leitura retorna os registros candidatos. O agente talvez precise padronizar nomes, agrupar entradas semelhantes e somar os valores de um campo antes de decidir quais registros exigem outra consulta. Python é uma linguagem adequada para essas operações intermediárias.

O resultado da execução passa a embasar a próxima decisão do modelo. Um cálculo que falhou é uma observação à qual o agente pode reagir, não uma garantia de que conseguirá corrigir o próprio erro.

ToolCallingAgent: mantenha as ações em um conjunto definido

ToolCallingAgent é o melhor ponto de partida quando suas operações já têm contratos claros. Ele emite chamadas JSON estruturadas com nomes de ferramentas e argumentos, em vez de gerar ações em Python. Comparação da Hugging Face.

Um assistente de suporte que consulta um pedido e busca uma política de atendimento pode não precisar de mais nada. Deixe as transformações previsíveis a cargo do código convencional da aplicação. Adicionar Python gerado a um fluxo que já cabe em funções bem definidas introduz mais uma possibilidade de falha sem um ganho evidente.

Chamadas estruturadas também precisam de autorização. Uma solicitação de cancelamento de pedido pode estar no formato correto e ainda assim ser inadequada para aquele cliente. O esquema informa ao programa o que foi solicitado; a aplicação decide se a ação é permitida.

Ferramentas e modelos são escolhas independentes

Restrinja o conjunto de ferramentas e escolha o modelo separadamente. Essa separação é um dos atrativos práticos do smolagents: você pode mudar a forma como o agente raciocina sem redefinir cada capacidade de negócio.

Ferramentas são funções com contratos que o agente consegue usar

Uma ferramenta do smolagents encapsula uma função com nome, descrição, metadados de entrada e tipo de saída. O decorador @tool atende a funções simples com anotações de tipo e uma docstring útil. Para ferramentas mais elaboradas, crie uma subclasse de Tool e coloque a lógica de execução em forward. Guia de ferramentas.

Para um assistente de estoque, prefira uma capacidade como “consultar registros no catálogo autorizado” a um acesso irrestrito ao banco de dados. Implemente na própria ferramenta as verificações de acesso por cliente, as restrições de consulta e os limites de resposta. Um prompt convincente não substitui essas verificações.

As ferramentas também podem vir do Model Context Protocol, ou MCP, uma interface padrão para disponibilizar ferramentas a aplicações baseadas em modelos, além de adaptadores para ferramentas do LangChain e Hugging Face Spaces. Reutilizar uma ferramenta não garante que sua implementação seja confiável. A Hugging Face exige explicitamente trust_remote_code=True ao carregar ferramentas do Hub, pois elas executam código personalizado. Documentação de integração e carregamento de ferramentas.

Essa decisão exige revisão de código. Inspecione a implementação da ferramenta e suas dependências antes de disponibilizá-la a um agente.

O backend do modelo não define o sandbox

A referência atual de modelos documenta várias opções:

• InferenceClientModel se conecta por meio dos Inference Providers da Hugging Face.
• LiteLLMModel usa a camada de integração com provedores do LiteLLM.
• TransformersModel executa um modelo Transformers localmente.
• OpenAIModel se conecta a um servidor de modelos compatível com a OpenAI.

A visão geral guiada também aborda o Ollama para inferência local. São opções de backend, não promessas de que todos os modelos terão a mesma capacidade de gerar código ou escolher ferramentas.

Separe duas perguntas: onde o modelo roda e onde roda o Python gerado por ele? Um modelo hospedado pode acionar um executor Docker. Um modelo local também pode gerar ações inseguras. Trazer a inferência para sua máquina não estabelece um limite de isolamento para a execução.

Pensando na reprodutibilidade, configure o modelo explicitamente ao avançar além da demonstração. A Hugging Face alerta que o modelo padrão de InferenceClientModel pode mudar. Configuração do modelo.

Um exemplo simples baseado na documentação

Use a tarefa de aritmética da documentação para entender o caminho da execução antes de adicionar ferramentas. O exemplo introdutório da Hugging Face pede a soma dos números de 1 a 10 com um conjunto vazio de ferramentas. A versão abaixo mantém essa tarefa e acrescenta o padrão de gerenciador de contexto para Docker apresentado no guia de sandbox. Exemplo original, configuração da execução com Docker.

1. 1

   Prepare o ambiente

   O guia de instalação exige Python 3.10 ou mais recente e recomenda um ambiente virtual. Para este exemplo, o Docker também precisa estar instalado e em execução. Guia de instalação.

   python -m venv .venv
   source .venv/bin/activate
   pip install 'smolagents[docker]'

   Defina HF_TOKEN no ambiente com um token da Hugging Face que tenha permissão para chamar os Inference Providers. InferenceClientModel consegue ler essa variável automaticamente. Não coloque o token no script. Funcionamento da autenticação.

2. 2

   Execute a tarefa da documentação no Docker

   Salve o código abaixo em sum_agent.py:

   from smolagents import CodeAgent, InferenceClientModel
   
   model = InferenceClientModel()
   
   with CodeAgent(
       tools=[],
       model=model,
       executor_type="docker",
   ) as agent:
       result = agent.run("Calculate the sum of numbers from 1 to 10")
       print(result)

   Em seguida, execute:

   python sum_agent.py

   O gerenciador de contexto cuida da limpeza do sandbox ao sair do bloco. Este exemplo é uma adaptação da documentação, não o resultado de um teste executado para este artigo.

3. 3

   Confira o resultado e o limite de execução

   A resposta matemática esperada é 55, calculada como 10 × 11 ÷ 2. O modelo escolhe o código Python que gera; por isso, não espere uma sequência exata de execução nem uma resposta com as mesmas palavras em todas as vezes.

   tools=[] indica que nenhuma ferramenta personalizada foi fornecida. Isso não significa que CodeAgent perdeu a capacidade de executar Python. É a configuração do executor que leva esse código gerado para dentro do Docker.

Para esse cálculo fixo, o mais sensato é usar Python convencional na aplicação. O exemplo serve para mostrar o funcionamento do agente. Adicione um agente quando escolher as etapas intermediárias fizer parte do problema, e não apenas porque o cálculo pode ser descrito em inglês.

Agentes que executam código precisam de sandbox

Trate o Python gerado como código não confiável e defina um sandbox explícito antes de expô-lo a entradas não confiáveis. O executor local padrão é um interpretador com restrições, não uma garantia de isolamento da máquina hospedeira. A Hugging Face aponta erros do modelo, injeção de prompt e solicitações maliciosas como riscos. Execução segura de código.

O interpretador local avalia a árvore sintática abstrata do Python, a estrutura do programa após a análise sintática, operação por operação. Ele restringe imports e submódulos e limita a quantidade de operações. Esses controles reduzem a exposição, mas o guia específico de segurança alerta que a execução local ainda traz riscos. Autorizar um pacote adicional amplia o que o programa gerado pode acessar.

Quais opções de sandbox a Hugging Face oferece?

A API atual de executores oferece suporte a Blaxel, E2B, Modal e Docker, além do executor local. Os nomes de configuração abaixo correspondem à referência do CodeAgent e à referência de executores.

A escolha do provedor e das credenciais é separada dessas configurações. A documentação de instalação lista as dependências opcionais; instalar um extra, por si só, não configura a implantação.

Em um experimento interno, o Docker pode oferecer um limite concreto de isolamento da execução que você consegue inspecionar. Para um serviço que recebe solicitações não confiáveis, escolha o ambiente de acordo com o isolamento, o ciclo de vida e os controles operacionais necessários. O comparativo de sandboxes de código para agentes de IA aprofunda essa decisão de infraestrutura.

Isolar trechos de código não é isolar o agente inteiro

Defina o que ficará dentro do ambiente isolado antes de adicionar mais agentes. A Hugging Face diferencia a execução de trechos de código gerado em um sandbox da execução de todo o sistema de agentes nesse ambiente. O guia de segurança alerta que a abordagem restrita aos trechos de código não oferece suporte a agentes gerenciados, ou seja, agentes que outro agente chama como auxiliares. Levar o sistema inteiro para dentro do sandbox exige mais configuração e pode exigir o fornecimento de credenciais. Abordagens de sandbox.

Isso tem uma consequência para a arquitetura. Se um futuro agente especialista precisar chamar um modelo de dentro do ambiente de execução, o arranjo original de “enviar código e receber resultado” talvez deixe de ser suficiente. Reveja onde ficam as credenciais e as dependências das ferramentas quando mudar a estrutura da implantação.

Para um serviço voltado ao cliente, defina os arquivos permitidos, os destinos de rede e as operações disponíveis antes de iniciar o agente. Dê a cada execução apenas o acesso necessário à tarefa. Trate o estouro do tempo limite, o cancelamento e a limpeza como caminhos normais de execução, inclusive quando o modelo não concluir o trabalho.

Quando o minimalismo compensa — e quando não compensa

Escolha o framework de acordo com o problema de controle mais difícil da aplicação. Uma inicialização curta é útil, mas o código que você precisa escrever ao redor dela importa mais.

smolagents ou LangGraph: ações dinâmicas ou controle persistente?

LangGraph é o ponto de partida mais adequado quando o processo precisa persistir, pausar e retomar a execução por estados de negócio explícitos. É um ambiente de execução de orquestração de baixo nível para fluxos de trabalho com estado, com persistência e suporte à intervenção humana. Ele pode combinar etapas determinísticas com etapas guiadas pelo modelo e não exige LangChain. Visão geral do LangGraph.

Pense em um fluxo de compras que reúne evidências, aguarda um gestor e retoma a execução após a aprovação. O problema central é preservar o processo e garantir que a transição seja permitida. Comece pelo LangGraph se esses requisitos definirem o produto.

O trabalho que continua com você é o desenho do fluxo: estados, transições, persistência e o que significa tentar uma etapa novamente. Esse esforço se justifica no processo de compras. Para um assistente de pesquisa com escopo definido, que lê dados, calcula uma resposta e encerra a execução, essa estrutura pode ser desnecessária.

Escolha smolagents quando a principal incerteza for quais operações Python resolvem esta tarefa. Escolha LangGraph quando for como este processo avança com segurança por estados persistentes. Essa é uma recomendação de arquitetura, não uma afirmação de que cada framework só consegue realizar um tipo de trabalho.

OpenAI Agents SDK: transferências, verificações e rastreamento

OpenAI Agents SDK é uma escolha inicial mais adequada quando a aplicação gira em torno da coordenação entre especialistas e de verificações operacionais. Seus handoffs transferem o controle da conversa para outro agente; o padrão de agentes como ferramentas permite que um agente gerente mantenha a responsabilidade pela resposta. Documentação de orquestração.

Em um assistente de atendimento ao cliente, um especialista em faturamento que assume a conversa pode ser uma abstração mais clara do que um agente que resolve problemas gerais com Python. O rastreamento integrado registra chamadas de modelos, chamadas de ferramentas, handoffs e guardrails. Os guardrails fazem verificações automatizadas, enquanto os mecanismos de revisão humana pausam ações sensíveis para uma decisão. Rastreamento, guardrails e revisão.

A política da aplicação continua sendo sua responsabilidade: decidir o que exige aprovação, implementar a ferramenta corretamente e lidar com trabalho interrompido. Essas primitivas não escrevem a política por você. O SDK também documenta padrões de agentes em sandbox, portanto a execução de código não é uma exclusividade do smolagents.

Prefira smolagents quando o recurso necessário for a composição de ações em Python e um ciclo simples bastar. Escolha o Agents SDK quando suas primitivas de coordenação e revisão se encaixarem na aplicação que você está construindo. Ser “leve”, por si só, não resolve essa comparação.

Para ampliar a seleção, consulte o comparativo de frameworks de agentes de IA. Se você procura uma aplicação de agente para instalar, em vez de uma biblioteca sobre a qual desenvolver, comece pelo guia de agentes de IA de código aberto.

Onde há exagero nas promessas dos agentes que executam código

Um framework pequeno não torna previsível uma tarefa imprevisível. A expressividade do Python é útil, mas não garante que o modelo selecionou os registros certos, interpretou uma unidade corretamente ou respeitou uma regra de negócio.

Não transforme a capacidade de combinar operações em uma promessa universal de velocidade. Agrupar operações pode mudar a estrutura de uma execução; o resultado ainda depende do modelo, da tarefa, do comportamento das ferramentas e do ambiente de execução. Meça o desempenho na sua própria tarefa antes de usá-lo como critério de escolha.

Também existe um limite concreto que vale entender: o valor padrão de max_steps é 20 na API atual de agentes. Ele limita as etapas do agente, não os recursos consumidos por uma ação Python individual. A API também oferece callbacks, agentes gerenciados e verificações da resposta final; portanto, minimalismo não deve ser confundido com ausência de controles. Referência de agentes.

Na prática, configure separadamente os limites de tempo de execução e de recursos. Um teto de etapas não substitui uma política de sandbox, e um sandbox não substitui um resultado correto.

O que desenvolver na próxima semana

Comece com uma tarefa de escopo definido, somente para leitura, cuja resposta possa ser verificada de forma independente. Um desenvolvedor Python que esteja avaliando o smolagents pode usar uma exportação de estoque com dados sensíveis removidos e uma ferramenta de consulta com escopo restrito, comparando depois as divergências apontadas pelo agente com exemplos conhecidos.

Registre se ele selecionou os registros corretos, usou as ferramentas adequadamente, se recuperou das falhas esperadas e encerrou a execução dentro dos limites definidos. Mantenha uma solução determinística como referência. Se a tarefa sempre segue o mesmo caminho, implemente esse caminho com código convencional; a própria orientação da Hugging Face favorece funções determinísticas sempre que possível. Como construir bons agentes.

Avance com CodeAgent quando a composição dinâmica em Python justificar a complexidade adicional. Use ToolCallingAgent quando um conjunto definido de ferramentas for suficiente. Adie a migração se o fluxo atual já atender aos requisitos. Reavalie o framework quando aprovações persistentes ou transferências entre especialistas se tornarem centrais.

Instalação e compatibilidade

Como instalar smolagents com pip?

Instale a biblioteca principal com pip install smolagents. Adicione os extras necessários para suas ferramentas, seus modelos ou seu ambiente de execução. O exemplo deste artigo usa smolagents[docker].

Devo usar HfApiModel no smolagents?

Em código novo, siga a interface InferenceClientModel da documentação atual. Confira exemplos antigos na referência atualizada de modelos antes de copiar os imports.

Como usar smolagents com Docker?

Instale e inicie o Docker, instale o extra para Docker e selecione executor_type="docker". Configure o limite de isolamento da execução de acordo com sua carga de trabalho; essa opção, sozinha, não constitui uma política de segurança completa.

Receba dicas práticas de desenvolvimento com IA na newsletter.