Como criar um agente de IA em Python (do loop manual ao framework)

Salve salve, Pythonista!

Você já reparou que o ChatGPT sabe te explicar qualquer coisa, mas não consegue fazer nada por você? Ele não checa a cotação do dólar de hoje, não consulta o seu banco de dados, não roda um cálculo de verdade. Ele só prevê texto. Quando a tarefa exige agir no mundo - buscar um dado, chamar uma API, decidir o próximo passo - o modelo sozinho não dá conta.

É aí que entram os agentes de IA: o tema mais quente de 2026 e a evolução natural de quem já brinca com LLMs. Um agente pega aquele mesmo modelo de linguagem e o coloca para decidir e usar ferramentas em um loop, até concluir a tarefa.

Neste artigo você vai entender o que é um agente de verdade (sem hype) e construir um, em Python, de duas formas: primeiro na mão, com um loop cru, para enxergar o mecanismo por dentro; depois com um framework (LangGraph), para ver quanto trabalho ele te poupa.

Vá Direto ao Assunto…

• O que é um agente de IA?
• Agente, chatbot ou chain: qual a diferença?
• Como um agente funciona por baixo dos panos
• Preparando o ambiente
• Construindo um agente do zero (sem framework)
• O mesmo agente com um framework (LangGraph)
• Dando ferramentas melhores ao seu agente
• Quando NÃO usar um agente (e usar um prompt simples)
• Perguntas frequentes (FAQ)
• Conclusão

O que é um agente de IA?

Um agente de IA é um LLM acoplado a um conjunto de ferramentas e a um loop de raciocínio: em vez de só responder, o modelo decide sozinho quais ações executar, observa o resultado de cada uma e repete o ciclo até concluir a tarefa. A diferença para um chatbot comum é essa autonomia - o agente escolhe o que fazer, não apenas o que dizer.

Pense na fórmula:

Agente = LLM (o cérebro) + ferramentas (as mãos) + um loop (a iniciativa).

O LLM continua sendo um previsor de texto. A mágica está em dar a ele ações que pode chamar (uma busca, um cálculo, uma consulta a banco) e um laço de repetição que deixa o modelo encadear essas ações. Se você já viu o Claude Code ou o modo ultracode resolvendo uma tarefa de programação sozinho, viu um agente em ação - ele lê arquivos, roda comandos, observa a saída e segue.

Agente, chatbot ou chain: qual a diferença?

Esse é o ponto que mais confunde quem está começando. Nem todo uso de LLM é um agente. Vale separar:

Uma chain (corrente) é um fluxo que você desenhou: passo 1, depois 2, depois 3, sempre na mesma ordem. É exatamente o que vimos no artigo sobre o que é e como funciona o LangChain. Já um agente recebe um objetivo e descobre o caminho sozinho, em tempo de execução. Quando o problema tem passos previsíveis, uma chain basta (e é mais barata). Quando o caminho depende do que for surgindo, você precisa de um agente.

Como um agente funciona por baixo dos panos

Todo agente, por mais sofisticado que pareça, gira em torno do mesmo ciclo. Ele recebe a tarefa e repete estes passos:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

1. pergunta do usuário
        |
        v
2. o LLM pensa e decide:  responder agora  OU  usar uma ferramenta
        |
        v   (escolheu uma ferramenta)
3. o código executa a ferramenta (busca, cálculo, API...)
        |
        v
4. o resultado da ferramenta volta para o LLM como nova informação
        |
        +--> repete os passos 2 a 4 até o LLM decidir que já pode responder
        |
        v
5. resposta final

Esse padrão - pensar, agir, observar, repetir - é conhecido como ciclo ReAct (de Reasoning + Acting). É a espinha dorsal de praticamente todo agente, do mais simples ao mais complexo. As peças que o compõem:

O elo que liga o LLM às ferramentas tem nome: tool calling (ou function calling). Em vez de devolver texto, o modelo devolve um pedido estruturado - “execute a ferramenta cotacao com o argumento USD” - e o seu código se encarrega de rodar a função e devolver o resultado. É isso que vamos implementar agora.

Preparando o ambiente

Para o agente “na mão” precisamos só da biblioteca openai, a mesma que usamos no artigo de RAG na prática e no de integração do ChatGPT com Python:

Se ainda não trabalha com ambientes isolados, vale ler este artigo sobre virtualenv antes - mantém cada projeto com suas próprias dependências.

1

pip install openai

Configure sua chave da OpenAI como variável de ambiente:

1

export OPENAI_API_KEY="sua-chave-aqui"

Prefere não pagar API? Dá para rodar tudo com modelos locais via Ollama, contanto que o modelo suporte tool calling. A lógica do agente é exatamente a mesma.

Construindo um agente do zero (sem framework)

Vamos montar um agente que responde a perguntas como “Tenho 250 dólares, quanto é isso em reais hoje?”. Repare que essa pergunta sozinha derruba um LLM puro: ele não sabe a cotação de hoje e é péssimo em conta. Nosso agente vai resolver em dois passos: buscar a cotação e depois calcular.

Passo 1: as ferramentas

Uma ferramenta é só uma função Python comum. Vamos criar duas:

1
2
3
4
5
6
7
8
9
10
11
12

COTACOES = {"USD": 5.40, "EUR": 5.85}

def cotacao(moeda: str) -> str:
    """Retorna a cotação de uma moeda estrangeira em reais (BRL)."""
    valor = COTACOES.get(moeda.upper())
    if valor is None:
        return f"Moeda '{moeda}' não encontrada."
    return f"1 {moeda.upper()} = {valor} BRL"

def calcular(expressao: str) -> str:
    """Avalia uma expressão aritmética e devolve o resultado."""
    return str(eval(expressao))

Cuidado com o eval. Usamos aqui por simplicidade, mas eval em texto vindo de um LLM é uma porta aberta para código malicioso. Em produção, troque por um avaliador seguro (a biblioteca simpleeval, por exemplo). Tratar ferramentas como código não confiável é o tipo de cuidado que separa um protótipo de um sistema sério.

Agora descrevemos essas funções para o modelo no formato que a OpenAI espera. É esse “cardápio” que o LLM lê para decidir o que chamar:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

FERRAMENTAS = [
    {
        "type": "function",
        "function": {
            "name": "cotacao",
            "description": "Retorna a cotação atual de uma moeda estrangeira em reais.",
            "parameters": {
                "type": "object",
                "properties": {
                    "moeda": {"type": "string", "description": "Código, ex: USD, EUR"},
                },
                "required": ["moeda"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "calcular",
            "description": "Avalia uma expressão aritmética, ex: 250 * 5.40",
            "parameters": {
                "type": "object",
                "properties": {
                    "expressao": {"type": "string", "description": "Expressão a calcular"},
                },
                "required": ["expressao"],
            },
        },
    },
]

# Mapa nome -> função, para o loop saber qual chamar.
DISPONIVEIS = {"cotacao": cotacao, "calcular": calcular}

Passo 2: o loop de raciocínio

Aqui mora o coração do agente. O loop chama o modelo; se ele pedir uma ferramenta, executamos e devolvemos o resultado; se ele responder direto, terminamos. O max_iteracoes é a nossa condição de parada - sem ela, um agente pode girar para sempre (e queimar créditos):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import json
from openai import OpenAI

cliente = OpenAI()  # lê a chave de OPENAI_API_KEY automaticamente

def agente(pergunta: str, max_iteracoes: int = 5) -> str:
    mensagens = [
        {"role": "system", "content": "Você é um assistente que usa ferramentas quando precisa."},
        {"role": "user", "content": pergunta},
    ]

    for _ in range(max_iteracoes):
        resposta = cliente.chat.completions.create(
            model="gpt-4o-mini",
            messages=mensagens,
            tools=FERRAMENTAS,
        )
        msg = resposta.choices[0].message
        mensagens.append(msg)  # guarda a decisão do modelo no histórico (memória)

        # Sem pedido de ferramenta -> o agente concluiu.
        if not msg.tool_calls:
            return msg.content

        # Executa cada ferramenta pedida e devolve o resultado ao modelo.
        for chamada in msg.tool_calls:
            funcao = DISPONIVEIS[chamada.function.name]
            argumentos = json.loads(chamada.function.arguments)
            resultado = funcao(**argumentos)
            print(f"  -> {chamada.function.name}({argumentos})")
            mensagens.append({
                "role": "tool",
                "tool_call_id": chamada.id,
                "content": resultado,
            })

    return "Limite de iterações atingido sem resposta final."

Repare na lista mensagens: ela é a memória do agente. Cada decisão do modelo e cada resultado de ferramenta são anexados ali, e o histórico inteiro volta ao modelo na iteração seguinte. É assim que ele “lembra” que já buscou a cotação na hora de calcular.

Rodando o agente

1
2

if __name__ == "__main__":
    print(agente("Tenho 250 dólares. Quanto é isso em reais hoje?"))

A saída é parecida com esta (as linhas com -> são o nosso rastro mostrando o loop em ação):

1
2
3
4

  -> cotacao({'moeda': 'USD'})
  -> calcular({'expressao': '250 * 5.40'})
Com 250 dólares você tem cerca de R$ 1.350,00 hoje, considerando a cotação de
1 USD = 5,40 BRL.

Veja o que aconteceu: o modelo percebeu que precisava da cotação, chamou a ferramenta cotacao, recebeu 5.40, concluiu que ainda faltava a conta, chamou calcular com 250 * 5.40 e só então respondeu. Foram duas voltas no loop, duas ferramentas, uma decisão de parada - tudo orquestrado pelo próprio modelo. Isso é um agente.

Construir essa base sólida em Python - de funções e estruturas de dados a integrações com IA como esta - é o que separa quem só copia código de quem entende o que está fazendo. É exatamente isso que ensinamos, do zero ao avançado, na Jornada Python:

Domine Python: A Linguagem da Inteligência Artificial, do Desenvolvimento Web e das Carreiras do Futuro.

A mais completa formação para você se tornar um especialista em Python, pronto para construir desde aplicações web robustas com Django até projetos de Inteligência Artificial e Ciência de Dados .

Quero conhecer!

Nota 4,9 de 5 na Hotmart O curso de Python mais bem avaliado da Hotmart!

O mesmo agente com um framework (LangGraph)

O loop acima é ótimo para entender o mecanismo, mas em um projeto real você não vai querer reescrever (e manter) todo aquele encanamento: histórico, parsing de argumentos, paralelismo, streaming, persistência. É para isso que servem os frameworks de agentes.

O LangGraph - o irmão do LangChain feito justamente para orquestrar agentes - resume tudo o que escrevemos a poucas linhas. Instale as dependências:

1

pip install langgraph langchain-openai

E o agente inteiro vira isto:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

@tool
def cotacao(moeda: str) -> str:
    """Retorna a cotação de uma moeda estrangeira em reais (BRL)."""
    return f"1 {moeda.upper()} = {COTACOES.get(moeda.upper(), '?')} BRL"

@tool
def calcular(expressao: str) -> str:
    """Avalia uma expressão aritmética."""
    return str(eval(expressao))

modelo = ChatOpenAI(model="gpt-4o-mini", temperature=0)
agente = create_react_agent(modelo, tools=[cotacao, calcular])

resposta = agente.invoke(
    {"messages": [("user", "Tenho 250 dólares. Quanto é isso em reais hoje?")]}
)
print(resposta["messages"][-1].content)

O create_react_agent constrói, internamente, o mesmo loop ReAct que fizemos na mão - só que com memória, controle de iterações, tratamento de erros e streaming já resolvidos. O decorador @tool substitui aquele “cardápio” JSON gigante: o LangGraph lê a assinatura e a docstring da função para montar a descrição sozinho.

Loop manual ou framework: qual escolher?

Os dois caminhos levam ao mesmo agente. A escolha é de contexto:

E a “diferença entre LangChain e LangGraph”? O LangChain te dá os blocos (modelos, prompts, integrações, chains de fluxo fixo). O LangGraph orquestra esses blocos como um grafo com estado e ciclos - exatamente o que um loop de agente precisa. Para chains lineares, LangChain; para agentes que decidem em loop, LangGraph.

Dando ferramentas melhores ao seu agente

Um agente só é tão útil quanto as ferramentas que você dá a ele. A partir do esqueleto acima, dá para evoluir em várias direções:

• Saída estruturada e validada: em vez de devolver texto solto, faça as ferramentas retornarem dados validados com Pydantic. Isso reduz erros de parsing e deixa o agente muito mais confiável.
• Conhecimento próprio (RAG): transforme uma busca no seu RAG em uma ferramenta. Aí o agente decide quando consultar os seus documentos, em vez de fazer isso sempre.
• Ferramentas padronizadas (MCP): o Model Context Protocol (MCP) é um padrão para expor ferramentas a agentes de forma reaproveitável - você escreve a ferramenta uma vez e qualquer agente compatível a usa.

Quando NÃO usar um agente (e usar um prompt simples)

Agente é poderoso, mas tem custo: cada volta no loop é uma chamada de API a mais (mais lento, mais caro) e mais imprevisível. Não vale a pena quando:

• A tarefa tem passos fixos. Se você já sabe a sequência exata, uma chain ou até uma chamada única ao LLM resolve - sem o overhead de deixar o modelo “decidir”.
• Não há ferramentas envolvidas. Resumir, traduzir ou classificar um texto não precisa de agente nenhum. É só um prompt.
• Você precisa de previsibilidade total. Quanto mais autonomia o agente tem, mais difícil é garantir que ele faça sempre a mesma coisa. Para fluxos críticos e auditáveis, código tradicional ganha.
• Latência e custo importam muito. Um agente que dá cinco voltas no loop custa (e demora) cinco vezes uma chamada simples.

A regra de ouro: comece com o mais simples que resolve (prompt -> chain -> agente) e só suba de nível quando o problema realmente exigir autonomia.

Perguntas frequentes (FAQ)

Qual a diferença entre LangChain e LangGraph?

O LangChain oferece os blocos de construção (modelos, prompts, integrações e chains de fluxo fixo). O LangGraph é feito para orquestrar agentes: representa o fluxo como um grafo com estado e ciclos, que é o que um loop de raciocínio precisa. Para sequências lineares, use LangChain; para agentes que decidem em loop, LangGraph.

Preciso de um framework para criar um agente de IA em Python?

Não. Como mostramos, um agente é, na essência, um LLM com tool calling dentro de um while. Dá para fazer só com a biblioteca openai. O framework compensa em produção, quando você quer memória persistente, streaming, paralelismo e tratamento de erros prontos.

Qual modelo usar para um agente?

Qualquer um com bom suporte a tool calling: GPT-4o e GPT-4o-mini, Claude, Gemini ou modelos locais via Ollama que aceitem ferramentas. Para agentes que encadeiam muitos passos, um modelo mais capaz erra menos a decisão de qual ferramenta chamar e economiza voltas no loop.

Um agente de IA é seguro? Ele executa código sozinho?

O agente só executa as ferramentas que você define - ele não roda nada além disso. O risco mora nas ferramentas: dar a ele um eval, acesso ao shell ou ao sistema de arquivos sem limites é perigoso, porque a entrada é gerada por um LLM. Valide os argumentos, restrinja permissões e, quando possível, rode em um sandbox.

Qual a diferença entre um agente e um chatbot comum?

Um chatbot devolve texto. Um agente decide ações, usa ferramentas e repete esse ciclo até concluir uma tarefa concreta - como buscar um dado e fazer um cálculo com ele. O agente age; o chatbot apenas conversa.

Conclusão

Você acabou de construir um agente de IA funcional das duas formas que importam: na mão, para entender que por baixo do hype existe só um LLM, ferramentas e um loop; e com LangGraph, para ver como um framework empacota tudo isso em poucas linhas. Esse mesmo esqueleto - trocando as duas funções de exemplo por ferramentas de verdade - é o que move desde assistentes de código até sistemas autônomos de produção.

É exatamente esse tipo de arquitetura que está por trás do Ebookr.ai, minha plataforma que gera ebooks profissionais com IA: por dentro, é um sistema de agentes que planejam, pesquisam e escrevem em etapas, cada um com suas ferramentas. Se quer ver agentes aplicados de verdade, em escala, dá uma conferida:

E você, qual ferramenta vai plugar no seu primeiro agente? Conta aqui nos comentários!

Nos vemos no próximo artigo!

Por Vinícius Ramos em 03/06/2026

Engenheiro de Computação pela UnB com especialização em Inteligência Artificial. Sr. Software Engineer com 10+ anos de experiência desenvolvendo sistemas críticos em Python e Django. Atuei no Banco do Brasil liderando equipes para monitoramento de mainframe, trabalhei como desenvolvedor sênior em projetos forenses para a Polícia Federal, e atualmente sou engenheiro de software na Labcorp (Estados Unidos), desenvolvendo soluções escaláveis para testes genéticos. Fundador da Python Academy, compartilhando conhecimento técnico com a comunidade brasileira desde 2018.

Minhas redes: