🔧 Construção de Agentes

Escolher o modelo certo é a primeira decisão de arquitetura de um agente. Claude 3.5, GPT-4o, Gemini Pro, Mistral e Llama têm capacidades e custos muito diferentes para casos de uso específicos.

Usar o modelo errado é a causa mais comum de custo explosivo ou resultado ruim. A escolha certa pode reduzir custo em 10x sem perder qualidade.

Capacidade de raciocínio · Velocidade de resposta · Custo por token · Suporte a function calling · Limite de contexto

O context window é a memória de trabalho do LLM — tudo que ele pode "ver" ao mesmo tempo. Entender o que cabe nele (histórico, tools, documentos, instruções) é essencial para arquitetar bem.

Estourar o contexto derruba o agente. Não usar bem o contexto desperdiça capacidade. Saber estimar o tamanho em tokens de diferentes tipos de conteúdo é uma skill fundamental.

Tokenização · Estimativa de tokens por tipo de conteúdo · Context overflow · Long context vs. RAG · Custo do contexto cheio

Temperatura controla a aleatoriedade das respostas do LLM. Próximo de 0.0 dá respostas determinísticas e previsíveis. Próximo de 1.0 dá respostas mais criativas e variadas.

Temperatura errada é causa silenciosa de bugs difíceis de diagnosticar. Agente de código com temperatura alta produz código não-reproduzível. Agente criativo com temperatura 0 produz textos monótonos.

Temperature vs. top-p · Determinismo em agentes · Quando usar alta vs. baixa temperatura · Seed para reprodutibilidade

Cada chamada ao LLM tem custo em input tokens + output tokens. Em um agente com loop, esses custos se multiplicam. Saber calcular o custo real por tarefa é fundamental para viabilidade econômica.

Agentes sem controle de custo geram surpresas no final do mês. Com planejamento correto, você sabe antes quanto cada tarefa vai custar e define budget limits.

Input vs. output pricing · Cache de prompt · Custo por iteração · Budget limits · ROI do agente

A estratégia de usar modelos diferentes para etapas diferentes do agente. Modelo grande (GPT-4o, Claude Opus) para planejamento complexo; modelo pequeno (Haiku, GPT-4o-mini) para execução simples e repetitiva.

Reduz custo em 80-90% nas etapas de execução sem sacrificar qualidade no planejamento. É a diferença entre um agente economicamente viável e um que custa proibitivo em escala.

Modelos frontier vs. small · Hierarquia de modelos · Routing por complexidade · Latência vs. custo · SLAs por etapa

O processo interno pelo qual o LLM interpreta o estado atual, avalia as tools disponíveis e decide: responder ao usuário, chamar uma tool ou pedir mais informações. É o "cérebro" do loop agentic.

Entender esse processo permite escrever prompts e schemas de tools que guiam o LLM a tomar as decisões corretas, evitando loops infinitos e chamadas desnecessárias.

System prompt como constituição · Tool schema como menu de ações · Condição de parada · Critério de escolha de tool · Stop sequences

O buffer de conversa é a lista de mensagens (user + assistant) passada para o LLM a cada chamada. É a forma mais simples de dar memória ao agente dentro de uma sessão.

Sem buffer, cada chamada ao LLM começa do zero — o agente "esquece" tudo. Com buffer mal gerenciado, o contexto explode e a chamada falha ou fica cara demais.

ConversationBufferMemory · Formato de mensagens (role/content) · Tamanho do histórico · Custo acumulado por iteração

Técnica que mantém apenas as N mensagens mais recentes no contexto, descartando as antigas. Resolve o problema de crescimento infinito do buffer.

É a solução mais simples para evitar context overflow. O custo por chamada fica previsível e estável, mesmo em conversas longas.

Window size · FIFO de mensagens · Perda de contexto histórico · ConversationBufferWindowMemory · Trade-off memória vs. custo

Quando o contexto está prestes a estourar, um LLM (geralmente pequeno) sumariza o histórico antigo em texto comprimido. O sumário substitui as mensagens originais no contexto.

Preserva a essência da conversa sem estourar o contexto. Melhor que sliding window quando o histórico contém informações críticas que não podem ser descartadas.

ConversationSummaryMemory · Trigger de sumarização · Qualidade do sumário · Custo extra da chamada de resumo · Degradação progressiva

LLMs têm dificuldade em usar informações do meio de um contexto muito longo ("lost in the middle"). As informações no início e no fim são usadas melhor do que as do centro.

Contexto longo não é garantia de melhor resultado. Em alguns casos, menos contexto mais relevante supera contexto enorme com ruído. Isso impacta diretamente o design do agente.

Lost in the middle · Primacy/recency effect · Relevância vs. tamanho · Ordenação estratégica do contexto · Chunk filtering

Técnicas avançadas de compressão além da sliding window: extração de fatos-chave em lista estruturada, sumarização por tópico, e compressão semântica que preserva o essencial.

Diferentes casos de uso requerem diferentes estratégias. Um agente de suporte precisa de estratégia diferente de um agente de pesquisa. Conhecer o arsenal permite escolher a ferramenta certa.

Extração de entidades · Fact list compression · Entity memory · Hybrid memory · Compressão por importância

Sintomas e causas de falhas de memória curta: agente esquece informações críticas, contradiz respostas anteriores, ou repete perguntas já respondidas. Como identificar e diagnosticar cada caso.

Bugs de memória são difíceis de diagnosticar porque o agente "parece" funcionar mas produz resultados inconsistentes. Saber os padrões de falha economiza horas de debug.

Context truncation silenciosa · Inconsistência entre turnos · Esquecimento de instrução · Debug de histórico · Testes de regressão de memória

Agentes sem memória longo prazo começam do zero em cada sessão. Para um agente de suporte, isso significa esquecer o histórico do cliente. Para um agente de pesquisa, esquecer o que já foi descoberto.

Memória longo prazo é o que separa um agente útil de um agente brinquedo. Sem ela, você não constrói sistemas que ficam mais inteligentes com o tempo.

Sessão vs. persistência · Tipos de memória (episódica, semântica, procedural) · Quando RAG vs. fine-tuning · Custo de persistência

FAISS (Meta) e Chroma são bancos de dados especializados em armazenar e buscar vetores de embeddings. Permitem encontrar documentos semanticamente similares a uma query em milissegundos.

São a base de qualquer sistema RAG. FAISS é rápido e local; Chroma é fácil de usar e tem metadata filtering. Escolher e usar o banco certo é skill central em RAG.

Similaridade cosseno · HNSW index · Metadata filtering · Persistência em disco · Escalabilidade: FAISS vs. Chroma vs. Pinecone

Embeddings transformam texto em vetores numéricos de alta dimensão onde textos com significado similar ficam próximos no espaço. "Cachorro" e "cão" ficam perto; "cachorro" e "avião" ficam distantes.

Entender embeddings permite escolher o modelo de embedding correto, determinar o tamanho ideal dos chunks e debugar quando a busca retorna resultados irrelevantes.

Dimensionalidade do vetor · text-embedding-3-small vs. large · Chunk size · Overlap · Qualidade de embedding por domínio

O pipeline completo de RAG em 4 fases: (1) Indexação — chunking e embedding dos documentos; (2) Recuperação — busca vetorial por similaridade; (3) Injeção — adicionar chunks ao contexto; (4) Geração — LLM responde com o contexto.

RAG é a técnica mais usada para dar conhecimento especializado a agentes sem fine-tuning. Entender o pipeline completo permite otimizar cada fase separadamente.

Document loaders · Text splitters · Retriever · top-k · Score threshold · Prompt template com contexto

Quando o RAG retorna chunks irrelevantes, o problema pode ser: chunk muito pequeno (perde contexto), chunk muito grande (dilui o sinal), top-k baixo (perde o chunk relevante) ou threshold errado (inclui lixo).

"O RAG não funciona" é o bug mais comum e menos bem diagnosticado. Saber identificar qual fase do pipeline está falhando economiza dias de trabalho.

Chunk size 256 vs. 512 vs. 1024 · MMR retrieval · Hybrid search · Reranking · Evaluation com RAGAS

Custo de um sistema RAG tem duas partes: indexação (embedding de todos os documentos — pago uma vez) e busca (embedding da query a cada chamada — pago sempre). Em escala, esses custos ficam significativos.

Um corpus de 10.000 documentos pode custar centavos para indexar mas dólares por dia em buscas. Planejamento de custo de RAG é diferente de planejamento de custo de LLM.

Custo de embedding por token · Cache de embeddings · Custos de vector DB hosted (Pinecone) vs. self-hosted (FAISS) · Atualização incremental de índice

Tools são funções externas que o LLM pode chamar para executar ações além de gerar texto: buscar na web, ler arquivos, consultar banco de dados, chamar APIs, executar código.

Sem tools, o agente é apenas um gerador de texto sofisticado. Com tools, ele pode agir no mundo real. Tools são o que transforma um LLM em um agente executável.

Function calling · Tool use · Tool schema · Tool result injection · Ciclo: LLM decide → tool executa → resultado volta ao LLM

Cada tool é definida por um JSON Schema com: name (identificador), description (o LLM usa isso para decidir quando chamar), parameters (o que precisa ser passado) e required (campos obrigatórios).

A qualidade da description determina se o LLM vai chamar a tool certa na hora certa. Um schema mal descrito faz o agente ignorar tools disponíveis ou chamar a errada.

OpenAI function calling format · Anthropic tool use format · Description como instrução · Type annotations · Enum parameters

Pydantic permite definir modelos de dados que o LLM deve seguir ao responder. A resposta do LLM é validada e parseada automaticamente em objetos Python tipados, eliminando parsing manual e erros de formato.

Agentes que dependem de parsing manual de texto quebram facilmente. Structured outputs garantem que a saída do LLM seja sempre válida e utilizável pelo código seguinte.

BaseModel · Field com description · response_format · Nested models · Validation errors e retry · instructor library

Qualquer função Python pode se tornar uma tool. Exemplos práticos: busca web com Tavily, calculadora com eval seguro, leitor de arquivo com tratamento de encoding. Cada uma com schema JSON correto.

Tools customizadas são o coração do valor que você entrega. A diferença entre um agente genérico e um agente útil para seu negócio está nas tools específicas que você cria.

@tool decorator · StructuredTool · Tool com estado · Async tools · Error handling na tool · Retorno padronizado

O agente usa o resultado de uma tool como input para chamar outra. Exemplo: busca web → extrai dados relevantes → chama API com esses dados → sumariza resultado. Cada etapa depende da anterior.

Tool chaining é o que permite tarefas complexas de múltiplas etapas. É também onde a maioria dos bugs ocorre — a saída da tool A não é o formato esperado pela tool B.

Tool result parsing · Passagem de estado entre tools · Dependência entre tools · Erro de chaining · Retry em falhas parciais

Tools sem proteção são vetores de ataque. Um agente pode ser induzido (prompt injection) a chamar tools com parâmetros maliciosos. Validação de input, allowlists de ações e logging obrigatório são as defesas essenciais.

Em produção, tools têm acesso a sistemas reais. Um agente comprometido que pode deletar arquivos, enviar emails ou fazer transações é um risco crítico de negócio.

Prompt injection · Input sanitization · Allowlist de operações · Human-in-the-loop para ações críticas · Audit log de tool calls

Chain-of-Thought (CoT) é a técnica de fazer o LLM explicitar seu raciocínio passo a passo antes de dar a resposta final. "Pense passo a passo" melhora significativamente a qualidade em problemas complexos.

CoT melhora até 40% a precisão em problemas de lógica e matemática. É o padrão mais simples de implementar e o ponto de partida antes de qualquer padrão mais sofisticado.

Zero-shot CoT ("think step by step") · Few-shot CoT (exemplos de raciocínio) · Scratchpad interno · CoT em tool selection · Custo extra de tokens

ReAct intercala Pensamento (Thought), Ação (Action) e Observação (Observation) em loop. O LLM pensa em voz alta, chama uma tool, observa o resultado e repete até ter a resposta final.

É o padrão default do LangChain AgentExecutor e do maioria dos frameworks. Entender ReAct é entender como 80% dos agentes em produção funcionam hoje.

Thought/Action/Observation loop · Trace de raciocínio · Tool selection pelo pensamento · Condição de parada · Número máximo de iterações

Separa o agente em dois: um Planner (LLM grande) que cria o plano completo da tarefa, e um Executor (LLM pequeno) que executa cada passo do plano. Reduz custo drasticamente nas etapas de execução.

Para tarefas longas com muitos passos previsíveis, Plan-and-Execute reduz custo em até 90% em relação ao ReAct puro (que usa modelo caro a cada iteração). É o padrão de agentes de produção custosos.

Planner vs. Executor · Plan como lista de passos · Replanejamento quando passo falha · DAG de dependências · Hierarquia de modelos por custo

Após gerar uma resposta, o agente usa um segundo LLM (ou o mesmo com prompt diferente) para criticar a resposta, identificar erros e sugerir melhorias. A resposta melhorada passa por nova rodada de crítica.

Melhora qualidade significativamente em tarefas criativas, código e análise crítica. O agente que se auto-corrige frequentemente supera o agente que tenta acertar de primeira.

Actor vs. Critic · Self-critique prompt · Número de iterações de refinamento · Critério de qualidade · Custo vs. ganho de qualidade

Guia prático: CoT para problemas analíticos pontuais, ReAct para exploração com tools, Plan-and-Execute para pipelines longos e previsíveis, Reflexion para geração de alta qualidade onde erro é caro.

Usar o padrão errado é gastar dinheiro sem ganhar qualidade. A escolha correta depende de: número de passos, previsibilidade da tarefa, tolerância a custo e requisito de qualidade.

Dimensões de escolha: latência, custo, qualidade, previsibilidade · Combinação de padrões · Padrão por domínio (código, escrita, análise, pesquisa)

Análise comparativa de custo em tokens por padrão: CoT gasta ~2x mais tokens que prompt direto. ReAct gasta N×(raciocínio + context) por iteração. Reflexion gasta 3-5x mais mas pode ser necessário.

Decisão de arquitetura com impacto financeiro direto. Um agente de produção com milhares de execuções diárias pode ter 10x diferença de custo dependendo do padrão escolhido.

Token budget por padrão · Custo por tarefa completa · Quality-cost tradeoff · Benchmark de qualidade · Break-even analysis

Model Context Protocol (MCP) é o padrão aberto da Anthropic para conectar agentes a ferramentas externas de forma padronizada. Assim como USB padronizou periféricos, MCP padroniza a conexão de tools a agentes.

MCP está rapidamente se tornando o padrão da indústria. Ferramentas que suportam MCP funcionam automaticamente com qualquer cliente MCP — você escreve uma vez e usa em qualquer agente.

Protocolo aberto · Servidor MCP · Cliente MCP · Transport (stdio, HTTP) · Tool discovery automático · Adoção pela indústria

O servidor MCP expõe tools (funções) via protocolo padronizado. O cliente MCP (o agente) descobre e chama essas tools. A comunicação pode ser via stdio (processo local) ou HTTP (serviço remoto).

Entender a arquitetura permite depurar problemas de conexão, escolher o transport correto (stdio para local, HTTP para produção) e escalar servidores MCP independentemente dos agentes.

JSON-RPC 2.0 · Tool registration · Tool invocation · Stdio transport · HTTP + SSE · Lifecycle de conexão

Usando o servidor MCP oficial de Postgres, você conecta qualquer agente ao seu banco de dados em minutos. O agente pode executar queries, listar tabelas e analisar dados sem nenhum código extra.

Conectar o agente ao banco de dados transforma consultas em linguagem natural em resultados reais. É um dos casos de uso de maior ROI imediato para agentes em empresas com dados estruturados.

mcp-server-postgres · Connection string · Read-only vs. read-write · SQL sanitization · Permissões mínimas · Schema discovery

Qualquer API REST pode ser exposta como servidor MCP. Você define as tools (endpoints) com seus schemas e o agente passa a poder chamar a API naturalmente, como se fosse uma função Python.

Permite integrar CRMs, ERPs, APIs de pagamento e qualquer serviço externo ao agente sem escrever código de integração customizado. Um servidor MCP bem feito é reutilizável por múltiplos agentes.

API wrapper como MCP server · Auth handling (Bearer token) · Rate limiting · Error propagation · OpenAPI → MCP conversion

Claude Code usa MCP nativamente para se conectar a ferramentas externas. Exemplo: adicionar um servidor MCP de Jira permite que o Claude Code leia issues e crie PRs linkados diretamente à tarefa.

Ver MCP em ação em um produto real (Claude Code) torna concreto o que era abstrato. Você vê exatamente como a configuração se traduz em comportamento do agente.

claude_desktop_config.json · mcpServers section · Servidor local vs. remoto · Tool approval no Claude · Debug de MCP connection

Com o SDK oficial do MCP em Python, você cria um servidor funcional em menos de 30 linhas. Define ferramentas com decorator @server.tool(), implementa a lógica e registra no cliente.

Criar servidores MCP próprios permite expor qualquer lógica de negócio como tool reutilizável. É a base para construir um ecossistema de ferramentas compartilhadas entre múltiplos agentes.

mcp Python SDK · @server.tool decorator · Tool schema gerado automaticamente · stdio_server() · Testando com MCP Inspector · Publicando para outros agentes

LangChain abstrai o loop agentic (chamar LLM → processar tool call → retornar resultado → chamar LLM de novo) em componentes reutilizáveis: chains, tools, memory, agents — sem você reescrever o boilerplate.

É o framework mais adotado do ecossistema Python para agentes. Saber LangChain significa acesso a centenas de integrações prontas (tools, vectorstores, LLMs) sem implementar do zero.

Chain abstraction · LLM interface unificada · Integrations ecosystem · Quando LangChain ajuda vs. quando complica · Alternativas: LlamaIndex, smolagents

AgentExecutor é a API legada que ainda domina tutoriais. LCEL (LangChain Expression Language) é o novo paradigma baseado em composição de Runnables com operador |. LCEL é mais flexível e observável.

Você vai encontrar ambos na prática. Entender a diferença evita usar API depreciada em código novo e permite migrar projetos legados para LCEL de forma consciente.

Runnable interface · Pipe operator (|) · invoke vs. stream · create_react_agent + AgentExecutor · LCEL com RunnableWithMessageHistory

Adicionando ConversationBufferMemory ou RunnableWithMessageHistory ao agente para que ele lembre o histórico da conversa entre chamadas. Inclui persistência em SQLite para memória entre sessões.

Sem memória, cada interação com o agente começa do zero. Com memória bem implementada, o agente acumula contexto e fica progressivamente mais útil ao longo de uma conversa.

memory_key · return_messages · session_id · ChatMessageHistory · SQLChatMessageHistory · Passagem de memória para o prompt

LangChain tem dois jeitos de criar tools: @tool decorator (simples, gera schema automaticamente da docstring) e StructuredTool.from_function() (para tools com múltiplos parâmetros tipados com Pydantic).

Criar tools corretas em LangChain é o que permite ao AgentExecutor ou LCEL chamar funções externas. A docstring da tool diretamente influencia quando e como o LLM a usa.

@tool decorator · args_schema com Pydantic · handle_tool_error · Tool com async · Passando state para tools · DuckDuckGoSearchRun, TavilySearchResults

Projeto completo: agente que lê emails de uma caixa de entrada simulada, classifica por prioridade (urgente/normal/spam), e rascunha respostas personalizadas para os urgentes. Código funcional e comentado.

Projeto real que integra todos os conceitos: tools customizadas, memória, LLM como decisor. Ao final você tem um agente funcional que pode ser adaptado para seu próprio caso de uso.

Tool: read_inbox, classify_email, draft_reply · System prompt especializado · Structured output para classificação · Loop de processamento · Logging de decisões

Técnicas de debug sem ferramentas externas: verbose=True no AgentExecutor, callbacks customizados que printam cada step, logging estruturado de tool calls e rastreamento manual do loop agentic.

LangSmith não está sempre disponível e tem custo. Saber debugar com ferramentas básicas garante que você possa diagnosticar problemas em qualquer ambiente, inclusive produção com acesso limitado.

verbose=True · BaseCallbackHandler · on_tool_start/end · on_llm_start/end · Logging de input/output de cada step · Identificando o passo que falhou

Agentes são não-determinísticos (o LLM pode tomar decisões diferentes com o mesmo input), têm múltiplas etapas interdependentes, e o erro em uma etapa pode se manifestar como resultado incorreto muito depois.

Entender por que agentes são difíceis de debugar é o primeiro passo para debugar bem. Aplicar técnicas de script sequencial em um agente não-determinístico é uma armadilha comum.

Não-determinismo do LLM · Propagação de erro entre steps · Dependência de estado externo · Reproduzibilidade de bugs · Por que logs são obrigatórios

LangSmith é a plataforma de observabilidade oficial do LangChain. Com 3 variáveis de ambiente (LANGCHAIN_TRACING_V2, LANGCHAIN_API_KEY, LANGCHAIN_PROJECT), toda execução do agente fica visível como trace.

LangSmith transforma o debug de agentes de "imprimir prints aleatórios" para "visualizar o grafo de execução completo". É o maior ganho de produtividade em debugging de agentes disponível hoje.

LANGCHAIN_TRACING_V2=true · LANGCHAIN_API_KEY · LANGCHAIN_PROJECT · Tier gratuito (generoso) · Traces automáticos sem código extra

No LangSmith, cada execução do agente aparece como uma árvore de nós: cada LLM call, cada tool call, cada chain é um nó com input, output, latência e custo. Você vê exatamente o que aconteceu.

Visualizar a trace completa reduz o tempo de debug de horas para minutos. Você vê qual LLM call gerou o raciocínio errado, qual tool retornou o resultado inesperado, e onde o loop entrou em crise.

Trace tree · Run hierarchy · LLM span · Tool span · Tokens por nó · Latência por nó · Exportar trace para compartilhar

Metodologia para identificar a root cause de uma falha no agente: começar pelo output incorreto, rastrear para trás na trace, identificar qual step introduziu o erro e determinar se é bug do prompt, da tool ou do código.

Sem metodologia, o debug de agentes é um caça-fantasmas. Com metodologia de rastreamento reverso, você encontra a root cause em minutos mesmo em agentes com dezenas de steps.

Rastreamento reverso · Comparação de traces (run ok vs. run com erro) · Erro de prompt vs. erro de tool vs. erro de lógica · Anotações no LangSmith · Replay de trace

Métricas objetivas para avaliar agentes em produção: latência p50/p95 por tarefa, custo médio por execução, taxa de sucesso (tarefa completada sem erro), taxa de fallback e satisfação do usuário.

Sem métricas, você não sabe se o agente está melhorando ou piorando com mudanças. Métricas permitem detectar regressões antes que o usuário reclame e justificar investimentos com dados.

Datasets no LangSmith · Evaluators customizados · LLM-as-judge · Success rate tracking · Cost per run dashboard · Alertas de threshold

Padrões de logging para agentes em produção: logar cada tool call com input/output/custo/latência, logar decisões do LLM, usar correlation IDs para rastrear execuções, e definir níveis de log por ambiente.

Um agente sem logs é uma caixa preta em produção. Quando algo falha (e vai falhar), os logs são a única forma de entender o que aconteceu sem reproduzir o problema.

Structured logging (JSON) · Correlation ID · Log de tool call com latência · Log de decisão do LLM · Retention policy · Alertas em produção