Como criar um agente de IA empresarial: arquitetura passo a passo

Agentes de IA são o próximo nível depois de chatbots e pipelines de LLM.

Um chatbot responde perguntas. Um pipeline executa uma sequência fixa de passos. Um agente decide autonomamente quais passos executar para atingir um objetivo.

Essa autonomia é o que torna agentes poderosos — e é também o que os torna mais difíceis de construir e operar com confiabilidade em produção.

Este artigo é um guia técnico e prático para quem quer construir agentes empresariais que realmente funcionem em produção.

O que é (e o que não é) um agente de IA

Primeiro, clareza de definição.

Não é agente: um sistema que sempre executa os mesmos passos na mesma ordem, mesmo que use um LLM em algum passo. Exemplo: um sistema de extração de dados que sempre segue recebe PDF → extrai campos → valida → salva no banco. Isso é um pipeline, não um agente.

É agente: um sistema onde o LLM decide, em tempo de execução, qual ação tomar em seguida com base no estado atual — e continua decidindo até completar o objetivo ou determinar que não consegue.

O loop fundamental de um agente

1. Recebe objetivo (ex: "responda a dúvida do cliente sobre o pedido #12345")
2. Raciocina sobre o estado atual (o que sei? o que preciso saber?)
3. Decide qual ação tomar (de um conjunto de ferramentas disponíveis)
4. Executa a ação e observa o resultado
5. Atualiza estado interno
6. Repete 2-5 até atingir o objetivo ou atingir limite de iterações

A diferença crítica: o LLM decide a próxima ação dinamicamente, não segue um script fixo.

Os componentes essenciais de um agente empresarial

1. LLM (o “cérebro”)

O LLM é responsável pelo raciocínio: dado o objetivo e o estado atual, qual é a próxima ação?

Escolha do modelo importa: modelos melhores em raciocínio produzem agentes mais confiáveis. Para produção empresarial:

Tier 1 (recomendado para produção):

• GPT-4o (OpenAI)
• Claude 3.5 Sonnet (Anthropic)
• o1 (OpenAI) para casos que exigem raciocínio muito profundo

Tier 2 (aceitável para casos mais simples):

• GPT-4o mini
• Claude 3.5 Haiku
• Gemini 1.5 Pro

Modelos menores economizam custo mas aumentam taxa de erro. Para casos de uso onde um erro custa caro (compras, aprovações, comunicação externa), sempre use Tier 1.

2. Ferramentas (tools / function calling)

As ações que o agente pode executar. Cada ferramenta tem:

Nome descritivo: buscar_pedido, enviar_email, criar_tarefa

Descrição em linguagem natural (para o LLM entender quando usar):

{
    "name": "buscar_pedido",
    "description": "Busca informações de um pedido específico no sistema. Use quando o usuário mencionar um número de pedido ou perguntar sobre status de entrega.",
    "parameters": {
        "pedido_id": "string - ID do pedido (ex: '12345')"
    }
}

Implementação (código que executa a ação):

def buscar_pedido(pedido_id: str) -> dict:
    # Consulta ao banco de dados ou API
    pedido = db.query(f"SELECT * FROM pedidos WHERE id = {pedido_id}")
    return {
        "status": pedido.status,
        "data_entrega_prevista": pedido.data_entrega,
        "transportadora": pedido.transportadora
    }

Regra crítica para produção: ferramentas devem ser idempotentes (executar múltiplas vezes não causa problema) ou reversíveis sempre que possível.

Ferramentas que alteram estado (enviar e-mail, criar pedido, aprovar pagamento) devem ter confirmação humana ou logging robusto para auditoria.

3. Memória (três tipos)

LLMs são stateless — não têm memória nativa. Para agentes, você precisa implementar memória externa:

Memória de trabalho (working memory)

O histórico da execução atual: ações tomadas e resultados observados. Fica no contexto da requisição ao LLM.

Thought: Preciso verificar o status do pedido.
Action: buscar_pedido(pedido_id="12345")
Observation: Pedido está "Em trânsito", previsão de entrega 15/08.
Thought: Agora tenho a informação para responder ao cliente.
Action: responder_cliente(mensagem="Seu pedido está a caminho...")

Esse histórico cresce a cada iteração e precisa ser gerenciado para não estourar o limite de contexto.

Memória episódica (histórico de execuções)

Histórico de execuções anteriores do agente, armazenado externamente (banco de dados).

Permite que o agente “aprenda” com o passado: “Na última vez que um cliente perguntou sobre atraso de entrega, a ação X resolveu bem. Vou tentar X novamente.”

Implementação: cada execução do agente gera um registro com (objetivo, ações tomadas, resultado, sucesso/falha). Em execuções futuras, agente consulta casos similares.

Memória semântica (base de conhecimento)

Fatos sobre o domínio que o agente pode consultar via RAG: políticas da empresa, manuais de produto, FAQs, documentos internos.

Exemplo: agente de suporte consulta a base de conhecimento antes de responder para garantir que a resposta está alinhada com as políticas oficiais.

4. Orquestrador (o loop de execução)

O código que controla o loop do agente:

1. Chama o LLM com (objetivo + estado + ferramentas disponíveis)
2. Parseia a resposta (qual ação o LLM decidiu tomar?)
3. Executa a ferramenta escolhida
4. Captura o resultado
5. Atualiza o estado (adiciona ao histórico)
6. Decide se continua (se objetivo foi atingido ou limite de iterações foi atingido)

Exemplo simplificado em Python:

def run_agent(objective: str, max_iterations: int = 10):
    state = {"history": [], "objective": objective}

    for i in range(max_iterations):
        # LLM decide próxima ação
        response = llm.call(
            system_prompt=AGENT_SYSTEM_PROMPT,
            context=state,
            tools=AVAILABLE_TOOLS
        )

        # Parseia a decisão
        action = response["tool"]
        params = response["parameters"]

        # Executa a ferramenta
        result = execute_tool(action, params)

        # Atualiza estado
        state["history"].append({
            "action": action,
            "params": params,
            "result": result
        })

        # Verifica se terminou
        if response["status"] == "completed":
            return state

    raise TimeoutError("Limite de iterações atingido")

5. Guardrails (controles de segurança)

Controles que limitam o que o agente pode fazer:

Ferramentas que requerem aprovação humana:

RESTRICTED_TOOLS = [
    "enviar_email_externo",
    "criar_pedido_compra",
    "aprovar_pagamento"
]

Se o agente tentar usar uma dessas ferramentas, o sistema pausa e pede confirmação humana antes de executar.

Número máximo de iterações: evita loops infinitos. Típico: 5-15 iterações dependendo da complexidade do objetivo.

Tipos de ações proibidas: não permitir que o agente faça certas coisas sem supervisão (deletar dados, acessar informações de outros clientes, etc.).

Validação de saída: antes de executar uma ação (especialmente se irreversível), validar que os parâmetros fazem sentido.

def validate_action(action, params):
    if action == "enviar_email":
        # Valida que o destinatário é válido
        if not is_valid_email(params["destinatario"]):
            raise ValueError("E-mail inválido")
        # Valida que não está enviando para lista muito grande
        if len(params["destinatarios"]) > 100:
            raise ValueError("Bulk email requer aprovação manual")

Guardrails bem projetados são o que separa um agente seguro para produção de um que pode causar danos.

Padrões de arquitetura para agentes

Padrão 1 — ReAct (Reasoning + Acting)

O padrão mais comum e mais robusto. O LLM alterna entre raciocinar (Thought) e agir (Action), observando o resultado antes de continuar.

User: "Qual o status do meu pedido 12345?"

Thought: O usuário quer saber o status de um pedido específico.
         Preciso buscar as informações desse pedido no sistema.
Action: buscar_pedido(pedido_id="12345")
Observation: {"status": "Em trânsito", "previsão": "2025-11-15", "transportadora": "Correios"}

Thought: Tenho as informações. Posso responder ao usuário de forma clara e completa.
Action: responder_usuario(mensagem="Seu pedido #12345 está em trânsito com os Correios e deve chegar até 15 de novembro.")

Vantagens:

• Transparente: você vê o raciocínio do agente
• Debugável: quando falha, você sabe em qual etapa
• Flexível: agente pode adaptar a estratégia com base em resultados intermediários

Desvantagens:

• Mais tokens (cada Thought + Action aumenta o contexto)
• Mais lento (cada iteração é uma chamada ao LLM)

Padrão 2 — Plan-and-Execute

Para tarefas complexas com múltiplas etapas, o agente primeiro gera um plano completo e depois executa passo a passo.

Objective: "Preparar relatório trimestral de vendas com análise por região"

Planning Phase:
Step 1: Extrair dados de vendas do Q3 do banco de dados
Step 2: Agrupar por região (Norte, Nordeste, Sul, Sudeste, Centro-Oeste)
Step 3: Calcular métricas (total, crescimento vs Q2, top produtos)
Step 4: Gerar gráficos de tendência
Step 5: Escrever análise narrativa
Step 6: Compilar em relatório PDF

Execution Phase:
[Executa cada step sequencialmente]

Vantagens:

• Reduz risco de o agente se perder em loops
• Mais previsível: você sabe o que vai acontecer antes de executar
• Bom para tarefas com estrutura clara

Desvantagens:

• Menos flexível: se algo der errado no meio, o plano pode ficar obsoleto
• Planejamento inicial pode ser demorado

Quando usar: tarefas com fluxo bem definido, onde você sabe antecipadamente os passos (geração de relatórios, processamento batch, workflows fixos).

Padrão 3 — Multi-Tool Selection

Para casos onde o agente precisa decidir entre muitas ferramentas simultaneamente, use uma etapa intermediária de seleção:

1. LLM analisa o objetivo e seleciona o subconjunto de ferramentas relevantes (de 50 ferramentas, seleciona 5)
2. Agente opera apenas com essas 5 ferramentas (reduz complexidade de decisão)

Melhora precisão quando o conjunto de ferramentas é muito grande.

Ferramentas e frameworks para construir agentes

LangGraph (LangChain)

Framework específico para agentes com controle de estado explícito. Permite modelar fluxos como grafos, com nós sendo agentes/ferramentas e arestas sendo transições condicionais.

Ideal para: fluxos complexos com lógica condicional, múltiplos agentes, estado compartilhado.

Curva de aprendizado: Média a alta.

from langgraph.graph import StateGraph

# Define o grafo de estados
workflow = StateGraph()
workflow.add_node("buscar_pedido", buscar_pedido_node)
workflow.add_node("responder_usuario", responder_node)
workflow.add_conditional_edges(
    "buscar_pedido",
    should_respond,
    {
        True: "responder_usuario",
        False: "buscar_mais_info"
    }
)

AutoGen (Microsoft)

Framework para sistemas multi-agente com foco em conversação entre agentes.

Ideal para: cenários onde múltiplos agentes especializados precisam colaborar (ex: um agente de pesquisa + um agente de escrita + um agente de revisão).

Curva de aprendizado: Baixa a média.

CrewAI

Abstração de alto nível para “times” de agentes com papéis definidos.

Ideal para: prototipagem rápida, casos mais simples.

Curva de aprendizado: Baixa.

Implementação própria (custom)

Para casos simples (um agente com 3-5 ferramentas e lógica linear), uma implementação direta sem framework pode ser mais simples e mais controlada.

Quando usar custom:

• Caso de uso bem definido e estreito
• Não precisa de colaboração entre múltiplos agentes
• Você quer controle total sobre o comportamento

Os erros que levam agentes a falhar em produção

Erro 1: Ferramentas com side effects irreversíveis sem confirmação

Um agente que pode enviar e-mails, criar pedidos ou modificar dados sem confirmação humana vai eventualmente fazer algo errado em escala.

Solução: ferramentas críticas requerem aprovação humana na primeira vez que são usadas em produção. Só depois de confiança estabelecida (semanas ou meses), automatize completamente.

Erro 2: Loops infinitos sem condição de parada

Sem limite de iterações, agentes podem ficar presos em ciclos:

Thought: Preciso de mais informações.
Action: buscar_info()
Observation: Informação insuficiente.
Thought: Preciso de mais informações.
Action: buscar_info()
[repete infinitamente]

Solução: sempre defina max_iterations e trate o timeout explicitamente (salvar estado, alertar humano, registrar falha).

Erro 3: Prompts do sistema muito vagos

“Você é um assistente útil que ajuda com tarefas” não é suficiente para um agente em produção.

O system prompt precisa definir:

• Escopo de atuação (“Você ajuda clientes com dúvidas sobre pedidos e entregas. Não responde sobre questões técnicas do produto.”)
• Restrições (“Nunca forneça informações de outros clientes. Sempre valide que o cliente está autorizado a ver os dados.”)
• Comportamento em caso de dúvida (“Se não tiver certeza da resposta, diga explicitamente e escale para um humano.”)
• Quando pedir ajuda humana (“Se o cliente estiver insatisfeito ou mencionar cancelamento, escale imediatamente para o time de retenção.”)

Erro 4: Não logar o raciocínio

Em produção, você precisa entender por que o agente tomou cada decisão.

Log de cada Thought/Action/Observation é essencial para:

• Debug quando algo dá errado
• Auditoria (compliance, segurança)
• Melhoria contínua (identificar padrões de erro)

Estrutura de log recomendada:

{
  "execution_id": "uuid",
  "timestamp": "2025-11-15T14:32:01Z",
  "objective": "Responder dúvida sobre pedido 12345",
  "iterations": [
    {
      "iteration": 1,
      "thought": "Preciso buscar informações do pedido",
      "action": "buscar_pedido",
      "parameters": {"pedido_id": "12345"},
      "result": {"status": "Em trânsito"},
      "success": true
    }
  ],
  "final_status": "completed",
  "total_cost_tokens": 1240
}

Erro 5: Não testar com casos adversariais

Teste o agente com inputs maliciosos ou inesperados:

• Usuário tenta acessar dados de outro cliente
• Usuário pede para o agente fazer algo fora do escopo
• Ferramentas retornam erros ou timeouts
• Múltiplos usuários simultâneos criam condições de corrida

Cada um desses casos precisa de tratamento específico.

Por onde começar (checklist prático)

Se você está construindo seu primeiro agente empresarial:

1. Defina um escopo estreito

Um agente que faz uma coisa muito bem é mais valioso e mais seguro do que um agente genérico que faz tudo mal.

Exemplo bom: “Agente que responde dúvidas sobre status de pedidos e rastreamento de entregas”

Exemplo ruim: “Agente que ajuda com qualquer coisa relacionada à empresa”

2. Comece com ferramentas read-only

Agentes que só consultam dados (sem escrever ou enviar) são mais seguros para validar o comportamento.

Primeiro prove que o agente raciocina bem, escolhe as ferramentas certas e responde corretamente. Só depois adicione ações que alteram estado.

3. Human-in-the-loop nas primeiras semanas

Deixe o agente sugerir as ações e um humano aprovar antes de executar. Só depois de confiança estabelecida (com dados de produção!), automatize completamente.

4. Monitore cada execução em produção

Análise de logs de produção revela padrões de falha que testes não pegam. Configure:

• Alertas para taxa de erro > threshold
• Review semanal de execuções falhadas
• Amostragem de execuções bem-sucedidas (para validar qualidade)

---

Se você quer construir um agente de IA para automatizar um processo específico na sua empresa com arquitetura segura para produção, agende uma conversa. Projetamos e implementamos agentes com guardrails robustos, logging completo e ROI mensurável.