Agentes e Ferramentas

Dois engenheiros recebem a tarefa de implementar "encontre dois assentos abaixo de R$ 300 para sábado e reserve-os".

O primeiro escreve um workflow: extrai date, quantity e max_price da mensagem com uma chamada ao modelo que devolve JSON; chama search_events e search_seats no código; escolhe o par de assentos vizinhos mais barato; chama hold_seats; pede ao modelo que redija a resposta. Duas chamadas ao modelo, cada passo testável, latência previsível.

O segundo escreve um agente: entrega ao modelo as ferramentas e o objetivo, e deixa que ele decida o que chamar, em que ordem e quando parar. Ele atende pedidos que o primeiro projeto nunca previu ("…e, se não houver nada no sábado, tente domingo, mas não no anel superior"), e falha de maneiras que o primeiro projeto jamais falharia (reserva o evento errado, ou fica comparando assentos para sempre).

Os dois projetos estão corretos — para pedidos diferentes. Esta página trata da maquinaria do segundo e de como saber quando escolher o primeiro.

Workflows e agentes

A diferença está em quem decide o próximo passo: o seu código ou o modelo¹.

Comece pelo topo da tabela e desça apenas quando o nível mais simples falhar de forma mensurável no seu conjunto de avaliação. A maioria dos "agentes" em produção em 2026 são workflows com um ou dois passos agênticos.

O loop do agente

Um agente é um loop em torno de uma chamada ao modelo. Na formulação ReAct², o modelo alterna entre raciocinar (o que eu sei, do que eu preciso), agir (pedir uma chamada de ferramenta) e observar (ler o resultado da ferramenta), até conseguir responder.

flowchart TD
    start(["mensagem do usuário"]) --> ctx["montar o contexto:<br/>system prompt + ferramentas + memória + histórico"]
    ctx --> call["chamar o modelo (via gateway de LLM)"]
    call --> decide{"chamadas de ferramenta<br/>na resposta?"}
    decide -- não --> answer(["resposta final ao usuário"])
    decide -- sim --> guard["Safety Mesh:<br/>validar + autorizar cada chamada"]
    guard --> run["executar as ferramentas (em paralelo se independentes)"]
    run --> append["anexar chamadas + resultados ao histórico"]
    append --> budget{"passos, tokens, tempo<br/>dentro do orçamento?"}
    budget -- sim --> call
    budget -- não --> stop(["parar: resposta parcial ou passar para um humano"])

O loop em si é código comum. Eis uma versão mínima, independente de provedor — os três colaboradores são os outros componentes da paleta:

import json

MAX_STEPS, MAX_TOKENS = 8, 40_000


def run_agent(llm, registry, guard, user, question, history):
    """llm: LLM-gateway client; registry: Tool Registry; guard: Safety Mesh.
    All three are this sketch's own interfaces, not a specific SDK."""
    messages = [*history, {"role": "user", "content": question}]
    used = 0
    for step in range(MAX_STEPS):
        reply = llm.chat(alias="assistant-default", system=SYSTEM_PROMPT,
                         messages=messages, tools=registry.schemas_for(user))
        used += reply.input_tokens + reply.output_tokens
        messages.append(reply.message)          # the assistant turn, with its tool calls
        if not reply.tool_calls:                # no action requested: this is the answer
            return reply.text
        for call in reply.tool_calls:           # the model may request several at once
            verdict = guard.check_tool_call(call.name, call.arguments, user)
            if verdict == "allow":
                result = registry.call(call.name, call.arguments, as_user=user)
            else:                               # denied, or needs the user's confirmation
                result = {"error": verdict}
            messages.append({"role": "tool", "tool_call_id": call.id,
                             "content": json.dumps(result)})
        if used > MAX_TOKENS:
            break
    return "I could not finish this request. A human agent will contact you."

Cinco detalhes nessas 25 linhas concentram a maior parte da engenharia:

1. O modelo nunca executa nada. Ele devolve um pedido (tool_calls); o orquestrador valida, autoriza como o usuário (as_user=user) e executa.
2. Erros voltam ao modelo como dados. Uma chamada negada ou que falhou vira um resultado de ferramenta ({"error": ...}), para que o modelo possa se recuperar — perguntar ao fã, escolher outro assento — em vez de derrubar o loop.
3. Todo loop tem orçamentos: passos, tokens e (em produção) tempo de relógio. Sem eles, um modelo confuso fica em loop até que a cota ou a fatura o interrompa.
4. As ferramentas oferecidas dependem do usuário (schemas_for(user)): um visitante anônimo nem sequer vê hold_seats. Uma ferramenta que o modelo não enxerga é uma ferramenta que ele não pode usar indevidamente.
5. O histórico cresce a cada passo — o crescimento quadrático de tokens calculado na visão geral.

# 2. the agent loop: at most max_steps model calls; tools in between
answer = ""
for step in range(settings.max_steps):
    last_step = step == settings.max_steps - 1
    stream = await router.acompletion(
        model=route, messages=messages, stream=True,
        tools=None if last_step else [t.spec() for t in tools.REGISTRY.values()],
        stream_options={"include_usage": True},
    )
    chunks = []
    async for chunk in stream:
        chunks.append(chunk)
        served_by = getattr(chunk, "model", None) or served_by
        delta = chunk.choices[0].delta if chunk.choices else None
        text = getattr(delta, "content", None) if delta else None
        if text:
            if first_token_at is None:
                first_token_at = time.monotonic()
            answer += text
            yield "token", text
    message = litellm.stream_chunk_builder(split_tool_calls(chunks), messages=messages)
    if message.usage:
        usage["prompt_tokens"] += message.usage.prompt_tokens or 0
        usage["completion_tokens"] += message.usage.completion_tokens or 0
    reply = message.choices[0].message
    calls = reply.tool_calls or []
    if not calls:
        break
    messages.append({"role": "assistant", "content": reply.content or "",
                     "tool_calls": [c.model_dump() for c in calls]})
    for c in calls:  # tools run between model calls; results go back as data
        result = await tools.call(c.function.name, c.function.arguments, ctx)
        tool_log.append(c.function.name)
        messages.append({"role": "tool", "tool_call_id": c.id, "name": c.function.name, "content": result})

Parada e gerenciamento de contexto

À medida que o histórico cresce, a engenharia de contexto o mantém útil: as ferramentas devolvem resultados compactos (5 opções de assento, não 5.000 assentos); turnos antigos são compactados em um resumo; documentos grandes são referenciados por ID e buscados só quando necessário. Um contexto focado é mais barato, mais rápido e mais preciso do que um longo³.

Chamada de ferramentas

A chamada de ferramentas (tool calling, também conhecida como function calling) é o contrato entre o modelo e o seu código:

1. A requisição declara as ferramentas: nome, descrição e um JSON Schema dos argumentos.
2. O modelo responde com texto ou com uma ou mais chamadas de ferramenta: {id, name, arguments}, em que arguments deve seguir o schema. Muitas APIs conseguem impor o schema com decodificação restrita (saídas estruturadas), de modo que o JSON sempre sai bem formado.
3. O orquestrador executa a chamada e envia o resultado de volta em uma mensagem vinculada ao id da chamada.
4. O modelo continua com o resultado em seu contexto.

O modelo escolhe as ferramentas lendo seus nomes e descrições, então a interface da ferramenta é, ao mesmo tempo, um prompt e uma API. Boas ferramentas são projetadas para o modelo, não copiadas da API interna:

Ferramentas são efeitos colaterais

Uma chamada ao modelo pode ser repetida à vontade. Uma chamada de ferramenta muda o mundo. Se hold_seats estoura o tempo e o loop tenta de novo, a primeira reserva aconteceu ou não? Esse é o problema de integração de Computação e serviços, e as respostas são as mesmas:

• Chaves de idempotência. O orquestrador deriva uma chave de (conversation, step, call) e a passa para toda ferramenta de escrita; o serviço devolve o mesmo resultado para a mesma chave.
• Reversível primeiro. Prefira ações que tenham um "desfazer" natural — uma reserva temporária (hold) expira em 10 minutos; um pedido com pagamento, não.
• Compensação. Se um passo posterior falhar, execute a ação inversa (release_hold), exatamente como em uma saga.
• Níveis de risco decidem o que pode rodar sem um humano:

@dataclass
class Context:
    """Per-request facts the tools may use (identity comes from the gateway, never from the model)."""
    user_email: str | None
    evidence: set[str] = field(default_factory=set)  # ids of the documents the model has seen
async def get_order_status(args: GetOrderStatusArgs, ctx: Context) -> dict:
    if not ctx.user_email:
        return {"error": "the user is not logged in: ask them to log in to see their orders"}
    async with httpx.AsyncClient(base_url=settings.order_url, timeout=5) as http:
        r = await http.get(f"/orders/{args.order_id}")
    if r.status_code == 404:
        return {"error": "order not found"}
    r.raise_for_status()
    order = r.json()
    if order.get("customerEmail", "").lower() != ctx.user_email.lower():
        return {"error": "order not found"}  # same answer as 404: do not reveal that it exists
    return {"id": order["id"], "status": order["status"], "showId": order["showId"], "amount": order["amount"]}

Execução durável

Uma conversa que aguarda a confirmação do fã, ou uma tarefa que roda por minutos, não pode viver só na memória de um processo: pods reiniciam. Persista o estado do agente depois de cada passo — mensagens, chamadas de ferramenta pendentes, chaves de idempotência — em um banco de dados, e retome a partir do último checkpoint. Para tarefas longas de vários passos, um motor de workflow durável (no estilo do Temporal: cada passo registrado, repetido e retomável) entrega isso de graça; para chats curtos, uma linha conversation_state mais o cache de sessão do Memory Fabric bastam.

Planejamento

O loop do agente planeja um passo de cada vez. Para tarefas mais longas, o planejamento explícito ajuda:

Por que cada passo precisa ser verificado

Se cada passo está certo com probabilidade \(p\), de forma independente, uma tarefa de \(n\) passos tem sucesso com probabilidade \(p^n\):

# Probability that an n-step task succeeds when each step succeeds with
# probability p, independently: P(task) = p ** n
steps = [1, 3, 5, 10, 20]
head = ["Per-step success"] + [f"{n} step{'s' if n > 1 else ''}" for n in steps]
print("<table><thead><tr>" + "".join(f"<th>{h}</th>" for h in head) + "</tr></thead><tbody>")
for p in (0.99, 0.97, 0.95, 0.90):
    cells = [f"{p:.0%}"] + [f"{p ** n:.0%}" for n in steps]
    print("<tr>" + "".join(f'<td style="text-align:right">{c}</td>' for c in cells) + "</tr>")
print("</tbody></table>")

Um passo que acerta 95% das vezes parece bom; uma tarefa de 10 passos construída com ele só tem sucesso em 60% das vezes. As alavancas são as mesmas da disponibilidade em série (Estimativas): menos passos (ferramentas melhores, workflows para as partes conhecidas), validação depois de cada passo (schemas, regras de negócio no código) e recuperação (erros devolvidos ao modelo, replanejamento) — o equivalente, no agente, a retries e redundância.

Registro de ferramentas e MCP

Sem um padrão, cada agente precisa de uma integração sob medida com cada ferramenta: N agentes × M ferramentas. O Model Context Protocol (MCP)⁵ faz pelos agentes o que o Language Server Protocol fez pelos editores de código: cada provedor de ferramentas escreve um servidor MCP, cada host de agente embute clientes MCP, e qualquer cliente pode usar qualquer servidor — N + M integrações.

flowchart LR
    subgraph Host["Host: serviço do assistente (orquestrador)"]
        c1["cliente MCP"]
        c2["cliente MCP"]
        c3["cliente MCP"]
    end
    c1 -- "Streamable HTTP + OAuth" --> s1["servidor MCP<br/>time do catalog"]
    c2 -- "Streamable HTTP + OAuth" --> s2["servidor MCP<br/>time do inventory"]
    c3 -- "stdio (processo local)" --> s3["servidor MCP<br/>arquivos locais / ferramentas de dev"]
    s1 --> catalog["serviço catalog"]
    s2 --> inventory["serviço inventory"]

O essencial do protocolo:

• Papéis. O host é a aplicação (o assistente do BoxOffice); ele roda um cliente por conexão; cada servidor expõe capacidades.
• Primitivas do servidor. Tools (ações que o modelo pode chamar), resources (dados que a aplicação pode ler para o contexto, identificados por URIs) e prompts (templates reutilizáveis oferecidos ao usuário). Os clientes, por sua vez, podem oferecer aos servidores capacidades como sampling (o servidor pede ao modelo do host uma completion) e elicitation (o servidor pede uma entrada ao usuário).
• Mensagens. JSON-RPC 2.0. Uma sessão começa com initialize (negociação de versão e de capacidades); depois tools/list descobre as ferramentas e tools/call as invoca; os servidores podem notificar tools/list_changed.
• Transportes. stdio para um servidor que roda como subprocesso local; Streamable HTTP para servidores remotos, com autorização baseada em OAuth 2.1.

O time do inventory publica suas capacidades como um servidor MCP. Com o SDK oficial em Python, uma ferramenta é uma função tipada e documentada — o SDK deriva o JSON Schema das anotações de tipo e a descrição da docstring:

# Official MCP Python SDK (package "mcp"); check its docs for the current API.
from mcp.server.fastmcp import FastMCP

from inventory_client import InventoryClient  # the team's existing HTTP client

mcp = FastMCP("boxoffice-inventory")
inventory = InventoryClient("http://inventory:8080")


@mcp.tool()
def search_seats(event_id: str, quantity: int, max_price_brl: float) -> list[dict]:
    """Find available seats for an event, adjacent when possible, priced at or
    below max_price_brl each. Returns at most 5 options, cheapest first."""
    return inventory.search(event_id, quantity, max_price_brl, limit=5)


@mcp.tool()
def hold_seats(event_id: str, seat_ids: list[str], idempotency_key: str) -> dict:
    """Hold seats for 10 minutes so the fan can pay. Reversible: an unpaid hold
    expires. Calling again with the same idempotency_key returns the same hold."""
    return inventory.hold(event_id, seat_ids, ttl_seconds=600, key=idempotency_key)


if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Na rede, é isto que o cliente do orquestrador vê quando descobre a ferramenta (resultado de tools/list, resumido) e depois a chama:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "hold_seats",
        "description": "Hold seats for 10 minutes so the fan can pay. Reversible: an unpaid hold expires. Calling again with the same idempotency_key returns the same hold.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "event_id": {"type": "string"},
            "seat_ids": {"type": "array", "items": {"type": "string"}},
            "idempotency_key": {"type": "string"}
          },
          "required": ["event_id", "seat_ids", "idempotency_key"]
        },
        "annotations": {"readOnlyHint": false, "destructiveHint": false, "idempotentHint": true}
      }
    ]
  }
}

{"jsonrpc": "2.0", "id": 7, "method": "tools/call",
 "params": {"name": "hold_seats",
            "arguments": {"event_id": "evt_8812", "seat_ids": ["C12", "C13"],
                          "idempotency_key": "conv_51f3:step3:call1"}}}

{"jsonrpc": "2.0", "id": 7,
 "result": {"content": [{"type": "text",
                         "text": "{\"hold_id\": \"h_77a\", \"expires_at\": \"2027-03-13T10:12:00Z\", \"total_brl\": 560.00}"}],
            "isError": false}}

Repare no que não é argumento: a identidade do fã. O servidor MCP obtém o usuário da sessão autenticada (o access token OAuth que o host obteve em nome do fã, como em Identidade) — nunca de um campo preenchido pelo modelo, ou uma injeção de prompt poderia reservar assentos para outra pessoa.

O registro em torno do MCP

O MCP padroniza o protocolo de rede; o componente Tool Registry é a governança em torno dele:

Para a comunicação entre agentes de times ou empresas diferentes, estão surgindo protocolos próprios (por exemplo, o Agent2Agent, A2A). A distinção a guardar: o MCP conecta um agente a ferramentas e dados; os protocolos agente-a-agente conectam um agente a outro agente.

Orquestração multiagente

Quando um agente tem ferramentas demais, um prompt longo demais ou tarefas que podem rodar em paralelo, o trabalho é dividido entre vários agentes.

sequenceDiagram
    actor F as Fã
    participant S as Agente supervisor
    participant T as Agente de ingressos
    participant L as Agente de hospedagem
    F->>S: "fim de semana de festival no Rio, orçamento R$ 2.000"
    par em paralelo
        S->>T: encontrar 2 passaportes ≤ R$ 900
        S->>L: encontrar hospedagem perto do local ≤ R$ 1.100
    end
    T-->>S: 2 opções (reserva ainda não feita)
    L-->>S: 3 opções
    S-->>F: proposta combinada: confirmar?

Sistemas multiagente trocam dinheiro e latência por modularidade. Cada agente tem seu próprio contexto (mais tokens no total), cada handoff perde informação a menos que o estado seja passado explicitamente, e as falhas ficam mais difíceis de rastrear. Passe artefatos explícitos e estruturados entre os agentes (uma lista de assentos candidatos com IDs), não transcrições inteiras, e rastreie a árvore completa de chamadas (Observabilidade).

Quando NÃO usar agentes

BoxOffice: o rastro de uma tarefa

As chamadas de ferramenta em paralelo economizaram uma rodada inteira (≈ 2 s). Se o modelo tivesse pedido uma reserva de 40 assentos, o passo 3 teria devolvido {"error": "deny: invalid arguments: List should have at most 6 items after validation, not 40"} (a verificação do guardrail) e o modelo teria explicado o limite ao fã.

Como se conecta

flowchart LR
    WF{"steps known<br/>in advance?"} -->|"yes"| FLOW["workflow<br/>(code decides)"]
    WF -->|"no"| LOOP["agent loop<br/>(model decides)"]
    LOOP --> BUD["budgets: steps,<br/>tokens, time"]
    LOOP --> DUR["durable execution:<br/>state after every step"]
    LOOP --> MATH["0.95^10 ≈ 60 %<br/>→ Estimation availability math"]
    LOOP --> TOOLS["tool calls via MCP<br/>→ tool registry"]
    TOOLS --> AUTH["authorized as the user<br/>→ Network & Security identity"]
    TOOLS --> IDEM["idempotency keys, compensation<br/>→ Messaging sagas"]
    LOOP --> CTX["context<br/>→ RAG & Memory"]
    TOOLS --> HITL["confirmation for risky actions<br/>→ Safety mesh"]

Componentes da paleta: orchestrator (executa o loop e controla os orçamentos) · toolreg (servidores MCP, permissões, níveis de risco) · llmgw (toda chamada ao modelo) · safety (aprovação de ações arriscadas) · auth (a identidade do usuário em cada chamada de ferramenta) · app (os mesmos serviços catalog e inventory que o front end web chama). Cenários: ai-assistant. Continua em: Mensageria — padrões (sagas e compensação), Rede e Segurança — identidade, Estimativas — matemática da disponibilidade, Compute — integrações (chaves de idempotência), RAG e memória, Segurança, avaliações e observabilidade.