IA: Agentes com LangChain, LlamaIndex e CrewAI

1. Chains vs agents

Chain = sequência fixa de passos. Você define a ordem: prompt → modelo → parser → próximo prompt. Previsível, fácil de testar e de limitar custo.

Agent = o modelo escolhe a próxima ação. Você entrega um conjunto de tools (buscar, calcular, chamar API, ler arquivo) e o modelo decide qual usar, com base no objetivo.

• Use chain quando o fluxo é conhecido (classificar ticket → extrair campos → responder template)
• Use agent quando o caminho depende da entrada (pesquisar docs, consultar banco, comparar opções)

2. Tools e function calling

Uma tool é uma função com nome, descrição e schema de parâmetros. O modelo “vê” a descrição e decide chamar ou não. Exemplo de schema mental:

{
  "name": "search_docs",
  "description": "Busca na documentação interna por similaridade semântica",
  "parameters": {
    "query": "string",
    "limit": "integer (default 5)"
  }
}

Na prática (OpenAI / Anthropic / Gemini), isso vira function calling ou tool use: o modelo devolve um JSON estruturado, sua aplicação executa a função e devolve o resultado no próximo turno.

Regras úteis:

• Descrições claras e curtas — o modelo depende delas
• Poucas tools no início (3–6); muitas tools diluem a escolha
• Validar argumentos antes de executar (tipos, limites, path traversal)
• Timeout e sandbox para tools que tocam rede ou filesystem

3. LangChain na prática

LangChain organiza prompts, modelos, parsers e tools. Esqueleto mínimo de agent com tool de busca:

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate

@tool
def search_docs(query: str) -> str:
    """Busca na base de documentação interna."""
    # sua lógica de retrieval (pgvector, etc.)
    return "trechos relevantes..."

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
prompt = ChatPromptTemplate.from_messages([
    ("system", "Você é um assistente técnico. Use tools quando precisar de dados."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])
agent = create_tool_calling_agent(llm, [search_docs], prompt)
executor = AgentExecutor(agent=agent, tools=[search_docs], verbose=True)

result = executor.invoke({"input": "Como configurar o backup 3-2-1?"})
print(result["output"])

Comece com verbose=True para ver o raciocínio e as chamadas. Em produção, desligue e logue só o necessário.

4. LlamaIndex para RAG + agentes

LlamaIndex brilha quando o centro é dados indexados (PDFs, pastas, bancos). O fluxo típico:

1. Carregar documentos → chunking → embeddings → índice
2. Query engine ou agent que consulta o índice
3. Resposta com fontes (citations)

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI

documents = SimpleDirectoryReader("./docs").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(similarity_top_k=4)

response = query_engine.query("Qual o procedimento de restore do Restic?")
print(response)

Para agent: use as_chat_engine ou integre tools extras (SQL, HTTP). LlamaIndex e LangChain se complementam — muitos times usam LlamaIndex no retrieval e LangChain na orquestração.

5. CrewAI: multi-agente

CrewAI modela papéis (researcher, writer, reviewer) e um processo (sequencial ou hierárquico). Útil quando a tarefa naturalmente se divide:

• Pesquisador busca e resume fontes
• Analista compara opções e trade-offs
• Redator gera o relatório final

from crewai import Agent, Task, Crew

researcher = Agent(
    role="Pesquisador técnico",
    goal="Coletar evidências sobre a pergunta",
    backstory="Especialista em documentação de infraestrutura",
    verbose=True,
)
writer = Agent(
    role="Redator técnico",
    goal="Escrever resposta clara e citada",
    backstory="Engenheiro que documenta runbooks",
    verbose=True,
)

task1 = Task(description="Pesquise: {pergunta}", agent=researcher)
task2 = Task(description="Escreva a resposta final com base na pesquisa", agent=writer)

crew = Crew(agents=[researcher, writer], tasks=[task1, task2])
result = crew.kickoff(inputs={"pergunta": "Como endurecer SSH em Ubuntu?"})

Multi-agente aumenta custo e latência. Só vale quando um único agent não consegue manter contexto ou especialização.

6. Quando usar o quê

• Chain simples — fluxo fixo, baixo risco, alta previsibilidade
• Agent + tools — precisa consultar docs, banco ou APIs de forma dinâmica
• LlamaIndex — o núcleo é RAG sobre muitos documentos
• CrewAI — tarefas longas com papéis distintos e revisão

Não comece com crew de 5 agentes. Comece com uma tool e um agent; meça qualidade e custo; só então especialize.

7. Cuidados em produção

• Loop infinito — limite de iterações (max_iterations) e de tokens
• Tools perigosas — shell, escrita em disco e HTTP externo precisam de allowlist
• Custo — logar tokens por tool call; agentes “pensam” em voz alta e gastam
• Observabilidade — trace de cada step (LangSmith, Phoenix, ou logs estruturados)
• Humano no loop — ações irreversíveis (deploy, delete, e-mail) pedem confirmação

Agentes são poderosos e frágeis. Trate-os como sistemas distribuídos: limites, retries, métricas e rollback.

8. O código explicado

Tool e prompt (LangChain)

LlamaIndex e CrewAI

As bibliotecas de agentes mudam com rapidez. Se algum import falhar, confira a documentação da versão instalada (pip show langchain) e fixe as versões no requirements.txt.

9. Erros comuns e como resolver

← RAG com pgvector · hub de IA · demo: gerador de commit →