O que torna um agente diferente de um chatbot
Um chatbot recebe uma mensagem e gera uma resposta. Um agente recebe um objetivo, planeja passos, chama ferramentas (busca na web, banco de dados, APIs externas) e itera até atingir o objetivo, potencialmente com dezenas de chamadas ao LLM por interação. Isso exige estado persistente entre turnos e tratamento de erros robusto.
Stack mínima para agente em produção
A stack abaixo cobre a maioria dos casos: LLM via Ollama, memória com Redis e orquestração com n8n ou código Python:
services:
ollama:
image: ollama/ollama:latest
restart: always
ports:
- "11434:11434"
volumes:
- ollama_data:/root/.ollama
redis:
image: redis:7-alpine
restart: always
ports:
- "6379:6379"
volumes:
- redis_data:/data
command: redis-server --appendonly yes
# Seu agente (Python, Node.js, n8n, etc.)
agent:
build: ./agent
restart: always
environment:
- OLLAMA_URL=http://ollama:11434
- REDIS_URL=redis://redis:6379
depends_on:
- ollama
- redis
volumes:
ollama_data:
redis_data:Gerenciar memória e contexto
LLMs têm janela de contexto limitada. Para conversas longas, você precisa estratégias para não extrapolar o limite:
Conectar o agente a ferramentas externas
Ferramentas (tools) são funções que o LLM pode chamar para buscar informações ou executar ações. Com a API de function calling / tool use:
# Exemplo de tool em Python (compatível com LLMs que suportam function calling)
import json, httpx
def buscar_produto(nome: str) -> dict:
"""Busca informações de produto no banco de dados interno."""
resp = httpx.get(f"https://api.interna.com/produtos?q={nome}")
return resp.json()
# Definição da tool para o LLM
tools = [{
"type": "function",
"function": {
"name": "buscar_produto",
"description": "Busca informações de produto pelo nome",
"parameters": {
"type": "object",
"properties": {"nome": {"type": "string"}},
"required": ["nome"]
}
}
}]Monitorar e debugar o agente em produção
Agentes falham silenciosamente, o LLM pode gerar uma chamada de tool com parâmetro errado, ou entrar em loop. Implemente logging de cada passo:
# Logar cada interação do agente
import logging
logging.basicConfig(level=logging.INFO)
def run_agent_step(messages, tools):
logging.info(f"Turno {len(messages)}: enviando {len(messages)} mensagens ao LLM")
response = llm.chat(messages=messages, tools=tools)
logging.info(f"LLM retornou: tool_calls={response.tool_calls}, finish_reason={response.finish_reason}")
return response