Tool use em AI Agents: MCP, CLI, Skills e execução de código

Viacheslav Dubrov

2026-03-24 · Atualizado 2026-09-06 · 27 min · Agentes de IA

Tradução automática Este artigo foi traduzido automaticamente a partir da versão original em inglês.

Atualização do artigo

Publicado originalmente em 24 de março de 2026. Revisto e atualizado em 6 de setembro de 2026. A atualização abrange a especificação MCP revista, programmatic tool calling e evidência mais recente sobre os custos e limitações do tool use.

Um agent precisa de uma forma de agir: um JSON tool call, um serviço MCP, um comando CLI ou código num sandbox. Pode também precisar de instruções para escolher e utilizar esse mecanismo. As Skills fornecem essas instruções. O harness é o programa convencional que envolve o modelo: constrói prompts, verifica um call proposto, executa um call aprovado e decide quando a tarefa está concluída.

Este terceiro artigo da série acrescenta a camada de ação aos reasoning loops da Parte 1 e à memória da Parte 2. A Parte 4 analisa a verificação de policy antes da execução, e a Parte 6 analisa o harness que executa tanto o call como essa verificação.

A história das ferramentas mudou em 2025–2026. O MCP, Model Context Protocol, forneceu aos vendors uma forma partilhada de expor serviços externos. Agents com execução de código mostraram que, por vezes, um modelo consegue compor um pequeno programa de forma mais eficiente do que emitir uma longa sequência de JSON calls. A Anthropic reportou uma redução de 98,7% nos tokens num workflow do Google Drive para o Salesforce, e o artigo CodeAct reportou ganhos de até 20 pontos percentuais na taxa de sucesso das tarefas na sua configuração de benchmark. Estes resultados descrevem as suas tarefas e harnesses, não uma vantagem universal da execução de código.

Comparo JSON tool calling, ferramentas MCP, CLI e execução de código, mostrando depois onde se enquadram as Skills. Uma secção posterior aplica princípios de design de Agent-Computer Interface (ACI) ao Market Analyst Agent, um pequeno agent de investigação em LangGraph que construí para a Parte 1 e que obtém dados de mercado e escreve um relatório de analista.

Para uma decisão rápida sobre interfaces, consulte AI Agent Tool Interfaces.

Em resumo: use JSON tool calls para ações pequenas e tipadas, MCP para integrações partilhadas, comandos CLI para trabalho local já estabelecido e código em sandbox para trabalho com várias etapas. As Skills fornecem instruções reutilizáveis para utilizar qualquer uma destas opções. Antes da execução de um call, o harness tem de verificar os argumentos e aprovar o seu efeito; um schema ou transporte não faz isso por si só. Em todas as superfícies, a Agent-Computer Interface (ACI) deve tornar as ações claras, o feedback compacto e os erros recuperáveis.

Superfícies de execução e orientação processual

O reasoning loop propõe um call. O harness verifica os argumentos e se o call é permitido, envia-o para uma ferramenta ou sandbox e devolve o resultado. JSON schemas, o transporte MCP, wrappers CLI e code runners podem restringir os inputs, mas nenhum deles decide se a ação solicitada é permitida. As Skills fornecem instruções para esse percurso. Estas superfícies de execução fazem compromissos diferentes entre custo em tokens, flexibilidade e enforcement.

1. JSON tool calling: a referência

O padrão original: define tool schemas em JSON, o LLM emite function calls estruturados e o seu código executa-os. É bem compreendido e funciona bem para conjuntos pequenos de ferramentas.

# Schema cost depends on its text, structure, and the model tokenizer
tools = [
    {
        "name": "get_stock_price",
        "description": "Get the current stock price for a ticker symbol",
        "input_schema": {
            "type": "object",
            "properties": {
                "ticker": {"type": "string", "description": "Stock ticker (e.g., NVDA)"}
            },
            "required": ["ticker"]
        }
    }
]

Conte os tokens dos seus schemas reais. O custo depende do comprimento e do número de schemas carregados pelo host; uma consulta compacta de preços e um contrato de API profundamente aninhado não são unidades equivalentes. A descoberta adiada pode evitar o carregamento de todo o registry.

2. MCP para integrações partilhadas

O MCP é o standard para o qual a maioria dos vendors convergiu. Um servidor MCP é um processo que anuncia uma lista de ferramentas através de um protocolo de rede definido — stdio para um processo local e HTTP para um remoto. O seu agent executa um cliente MCP que se liga, pergunta ao servidor que ferramentas disponibiliza e encaminha para ele os calls do modelo, permitindo que o mesmo servidor funcione com qualquer cliente que implemente o protocolo. A Anthropic doou o protocolo à Linux Foundation em dezembro de 2025, no âmbito da Agentic AI Foundation, que cofundou com a OpenAI e a Block. Google, Microsoft e AWS apoiam a fundação como membros platinum. A OpenAI acrescentou suporte para MCP à sua Responses API. Segundo o anúncio da doação da Anthropic em dezembro de 2025, o ecossistema contava com mais de 10 000 servidores MCP públicos ativos e mais de 97 milhões de downloads mensais dos SDKs, entre os SDKs de Python e TypeScript.

O MCP é adequado para integrações SaaS entre vendors (Figma, Notion, Salesforce), serviços sem equivalentes CLI e ambientes que necessitam de orquestração OAuth. O seu valor está numa camada partilhada de descoberta e transporte. A governance continua a depender dos controlos de autenticação, autorização, logging e deployment do servidor.

A versão do protocolo é agora uma decisão prática de migração. A revisão de 28-07-2026 altera comportamentos assumidos por tutoriais mais antigos:

A mesma revisão descontinua Roots, Sampling, Logging e OAuth Dynamic Client Registration; a descontinuação não implica remoção imediata. O registo atual de clientes privilegia Client ID Metadata Documents. As integrações existentes podem ainda utilizar uma revisão anterior, por isso inspecione o SDK instalado e o contrato do servidor antes de adotar uma nova funcionalidade.

A realidade de produção é mais complexa do que os números de destaque sugerem.

O Vulnerable MCP Project reúne relatórios relacionados com prompt injection, validação de inputs, autenticação e controlos de rede. Esta coleção ajuda a identificar casos de teste; sem um denominador de exposição, não pode classificar o MCP face a shell ou a API calls diretos.

Tool poisoning é a classe de ataque que mais me preocupa. A Invariant Labs demonstrou que ferramentas MCP envenenadas podem exfiltrar dados mesmo quando nunca são invocadas. Basta o modelo ler a metadata da ferramenta para desencadear o ataque. Os benchmarks MCPTox, que testaram 20 LLM agents contra 45 servidores MCP reais, reportaram 72,8% de sucesso médio dos ataques para o o1-mini na sua configuração de tool poisoning. Trata-se do resultado de benchmark de um modelo, não de uma média dos 20 agents nem de uma taxa de incidentes no mundo real.

O overhead de tokens é o problema operacional. Uma equipa que executava servidores MCP para GitHub, Slack e Sentry (cerca de 40 ferramentas no total) encontrou 55 000 tokens de definições de schemas injetados antes de o utilizador perguntar alguma coisa. Outra reportou que 143 000 de 200 000 tokens disponíveis (72%) eram consumidos apenas pelas definições das ferramentas.

O relatório da Anthropic sobre o Tool Search Tool reportou endpoints aproximados de contexto de 77 000 tokens antes do início do trabalho e 8 700 após a descoberta adiada, com cerca de 72 000 tokens de definições de ferramentas na configuração tradicional. Carrega apenas as três a cinco ferramentas de que um request necessita, mas acrescenta uma etapa de descoberta antes da invocação; é menos útil para conjuntos pequenos e compactos de ferramentas utilizadas frequentemente em todas as sessões.

3. Skills empacotam conhecimento especializado, não execução

As agent skills são um formato aberto para empacotar instruções e ficheiros de suporte. As ferramentas fornecem capacidades (o que os agents podem fazer) e as skills fornecem conhecimento especializado (o que os agents sabem sobre como realizar tarefas complexas).

O formato SKILL.md define uma skill como um ficheiro markdown com YAML frontmatter. O standard aberto exige apenas name e description; o exemplo abaixo utiliza também duas extensões do Claude Code, argument-hint e user-invocable, além do seu placeholder posicional de argumentos $0:

---
name: deploy
description: Deploy the application to production
argument-hint: "[environment]"
user-invocable: true
---
Deploy the application to the $0 environment (default: staging).
Steps:
1. Run the test suite
2. Build the production bundle
3. Deploy using the deploy script
4. Verify the deployment health check

As Skills utilizam progressive disclosure. No arranque, o agent recebe cerca de 100 tokens de name e description. Só carrega o SKILL.md completo quando precisa da skill e, depois, carrega scripts, documentos ou assets referenciados conforme necessário. Esse custo inicial é muito inferior aos cerca de 55 000 tokens que aproximadamente 40 ferramentas MCP podem consumir antes de o reasoning começar. Uma skill ativa continua a acrescentar as suas instruções e recursos ao contexto.

Use skills para conhecimento de domínio, procedimentos com várias etapas e trabalho recorrente, como migrações de bases de dados ou integrações de pagamentos. São adequadas para tarefas em que o agent precisa de instruções sobre como utilizar uma capacidade existente.

4. Ferramentas CLI e shell

As interfaces CLI podem ser bastante mais económicas em contexto quando o modelo já conhece o comando. A Scalekit reportou uma diferença de 4 a 32 vezes nos tokens entre os percursos CLI e MCP em 75 execuções. Esse case study mede as suas ferramentas e tarefas; não substitui uma comparação com as suas próprias definições de ferramentas e outputs de comandos.

Comandos amplamente documentados, como git, docker, kubectl, gh, curl e jq, precisam frequentemente de pouco texto introdutório de schema. CLIs menos comuns ou internos continuam a precisar de help descobrível, exemplos e output estável em formato legível por máquinas.

O guia de Ugo Enyioha, “Writing CLI Tools That AI Agents Actually Want to Use”, codificou oito regras de design:

1. O structured output é obrigatório — suporte --json
2. Os exit codes são control flow — use códigos distintos para diferentes tipos de erro
3. Os comandos devem ser idempotentes
4. Self-documenting --help com exemplos realistas
5. Design para composability — --quiet para valores simples e suporte de stdin
6. Forneça flags --dry-run e --yes
7. Suporte introspeção da versão
8. Trate a autenticação através de variáveis de ambiente

A CLI não dispõe de descoberta ao nível do protocolo. O JSON tool calling pode transportar schemas tipados, enquanto o MCP normaliza a descoberta de ferramentas e, para transportes HTTP, um modelo de autorização. Nenhum dos dois fornece governance por si só: o host, o servidor ou o harness tem de impor a policy e registar os calls necessários para auditoria. Uma opção prática por defeito é CLI para desenvolvimento e operações locais, e MCP para integração com serviços externos partilhados quando a descoberta entre clientes ou a orquestração OAuth justificam o overhead do servidor.

5. Execução de código para trabalho com várias etapas

Esta é a alteração no tooling de agents que considero mais relevante. Em vez de emitir JSON estruturado para invocar funções predefinidas uma a uma, o agent escreve um script Python ou bash. O script chama várias ferramentas, processa resultados com loops e condicionais e devolve apenas o resumo final ao contexto do modelo.

A Anthropic introduziu o Programmatic Tool Calling (PTC) em beta. O guia atual da API utiliza a Messages API normal com code_execution_20260120 ou posterior; o lançamento beta original é contexto histórico. A base académica é o artigo CodeAct (Wang et al., ICML 2024), que testou 17 LLMs e concluiu que as code actions alcançaram até 20 pontos percentuais mais de sucesso nas tarefas e 30% menos actions do que as alternativas JSON.

Três case studies first-party mostram onde este padrão pode ajudar: Vercel e Cloudflare abaixo, seguidos do exemplo de análise de despesas da Anthropic. Trate-os como evidência dos vendors e repita a comparação nas suas próprias tarefas.

• A Vercel reconstruiu o d0, o seu data agent de linguagem natural para SQL. O seu exemplo antigo de código nomeia 17 ferramentas; o novo expõe ExecuteCommand e ExecuteSQL. A Vercel apresenta o redesign como uma remoção de 80% das suas ferramentas, mas essa afirmação é o headline da Vercel, não uma percentagem que resulte das ferramentas nomeadas nos exemplos. Em cinco queries representativas, a Vercel reporta que o sucesso das tarefas passou de 4/5 para 5/5, o tempo médio de execução diminuiu 3,5 vezes (274,8 s para 77,4 s) e o uso médio de tokens caiu 37% (cerca de 102k para cerca de 61k). Nas suas palavras: “The best agents might be the ones with the fewest tools.”

• A Cloudflare desenvolveu o “Code Mode,”, que permite aos agents escrever TypeScript para chamar a sua API em vez de definir tool schemas, reduzindo assim o overhead de contexto. O seu raciocínio foi: “LLMs have an enormous amount of real-world TypeScript in their training set, but only a small set of contrived examples of tool calls.”

Este é o padrão da documentação PTC da Anthropic. Na ilustração de análise sequencial de despesas da Anthropic, o tool calling tradicional requer mais de 20 passes de inferência separados, com os dados intermédios a passar pelo contexto. Depois da pesquisa da equipa, um host que suporte parallel tool calls pode agrupar os requests de despesas independentes; a cifra de mais de 20 não torna isso impossível. A Anthropic reporta que o código gerado para responder à mesma pergunta reduz o que chega ao contexto de 200 KB de linhas de despesas em bruto — mais de 2 000 itens — para 1 KB de resultados. O script abaixo ilustra esse control flow utilizando adapters Python async personalizados: aceitam argumentos posicionais e devolvem listas e dicionários descodificados. Não é o contrato nativo do wrapper PTC.

# Custom decoded Python adapters, not native Claude PTC wrappers.
import asyncio
import json

async def main() -> None:
    team = await get_team_members("engineering")
    levels = list(set(member["level"] for member in team))
    budgets = dict(zip(
        levels,
        await asyncio.gather(*(get_budget_by_level(level) for level in levels)),
    ))
    expenses = await asyncio.gather(
        *(get_expenses(member["id"], "Q3") for member in team)
    )
    over_budget = []
    for member, employee_expenses in zip(team, expenses):
        total = sum(expense["amount"] for expense in employee_expenses)
        limit = budgets[member["level"]]["travel_limit"]
        if total > limit:
            over_budget.append(
                {"name": member["name"], "spent": total, "limit": limit}
            )
    # Only this final summary returns to the LLM context
    print(json.dumps(over_budget))

asyncio.run(main())

Para utilizar wrappers PTC nativos do Claude, passe a cada ferramenta um dicionário de argumentos, descodifique a string JSON devolvida e use await no ambiente de execução gerido, em vez de iniciar um event loop com asyncio.run. O exemplo de adapter personalizado acima assume um runtime de script Python convencional; também não é um exemplo drop-in de um connector MCP nativo. As restrições atuais da API PTC excluem ferramentas strict: true e ferramentas de connector MCP nativas do programmatic calling e restringem schemas recursivos. Uma custom code-to-MCP bridge é uma integração separada. allowed_callers orienta a forma como o Claude chama uma ferramenta; não é uma boundary de autorização. O host tem de validar todas as invocações devolvidas, incluindo um call direto inesperado.

O LLM vê apenas o resumo JSON final, não os milhares de itens de despesas processados no sandbox. A poupança não é específica de relatórios de despesas: o artigo separado da Anthropic sobre code execution apresenta o número mais expressivo para este padrão, um workflow do Google Drive para o Salesforce que passou de cerca de 150 000 tokens para cerca de 2 000, uma redução de 98,7%.

O guia PTC atual reporta também um contraexemplo: nas tarefas de companhias aéreas, retalho e telecomunicações do tau2-bench, o PTC não alterou as pontuações e custou cerca de 8% mais. Num benchmark separado de gestão de projetos com 75 ferramentas, reduziu os input tokens faturados em cerca de 38% sem alterar a accuracy. Estas avaliações internas identificam apenas um modelo Claude de produção, não um ID exato. Workflows sequenciais pequenos podem não poupar o suficiente para compensar o overhead de container e de geração de código.

A eficiência em tokens é um ganho potencial. Loops e condicionais não têm custo adicional, e a execução de código pode tratar erros com handlers explícitos em vez de obrigar o modelo a raciocinar sobre falhas em linguagem natural. Um percurso de execução de código pode manter dados intermédios sensíveis fora do contexto do modelo, mas isso não é confidencialidade: isolamento, controlos de egress, credenciais com scope limitado e logging precisam de enforcement separado.

Quando o JSON tool calling continua a fazer sentido: operações atómicas únicas, ambientes sem infraestrutura de sandbox, modelos mais pequenos com code generation fraca ou requisitos de auditoria que exigem o registo de cada tool invocation individual.

Comparação da execução de ferramentas por AI agents

JSON tool calling, MCP, CLI e execução de código são superfícies de execução. As Skills são instruções que orientam uma dessas superfícies, pelo que a sua latência, contexto e configuração dependem do mecanismo selecionado. “Meta-tools” significa os poucos entry points genéricos de que um agent com execução de código necessita — por exemplo, ExecuteCommand e ExecuteSQL da Vercel — em vez de um schema para cada operação. As linhas de composability e latência descrevem calls cujos argumentos seguintes dependem de resultados anteriores. JSON tool calling e MCP podem emitir calls independentes em conjunto, mas calls dependentes normalmente precisam de outro model turn. O PTC move esse control flow e filtering dependentes para um script e devolve depois um resumo ao modelo. As células relativas a tokens e sucesso das tarefas resumem exemplos citados, não um benchmark controlado único entre as cinco colunas.

A Agent-Computer Interface (ACI) para ferramentas de AI agents

O termo “Agent-Computer Interface” (ACI) foi cunhado por John Yang, Carlos E. Jimenez e colegas de Princeton no seu artigo sobre o SWE-agent (NeurIPS 2024). A qualidade das interfaces humanas tem toda uma disciplina dedicada a si — human-computer interaction, ou HCI. O artigo defende que os agents baseados em language models merecem o mesmo tratamento: são “uma nova categoria de utilizadores finais, com necessidades e capacidades próprias, e beneficiariam de interfaces construídas especificamente para eles”.

Os seus resultados de ablation quantificam essa ideia. Utilizando o mesmo modelo base GPT-4 Turbo, a ablation do SWE-bench Lite do artigo alcançou 18,0% com a ACI completa do SWE-agent em 300 tarefas, contra 7,3% na condição apenas com shell e sem demonstração trabalhada, e 11,0% com uma demonstração. A comparação mostra que a interface e as condições de demonstração alteraram materialmente o desempenho nesta configuração; não isola o design da interface de todas as outras diferenças nem demonstra que o modelo não tenha realizado trabalho. Na mesma ablation da interface, ativar linting elevou a condição de edição de 15,0% para 18,0%; em todo o conjunto de teste SWE-bench, 51,7% das execuções do SWE-agent incluíram pelo menos uma edição rejeitada pelo linter antes de poder ser propagada.

A Anthropic adotou ACI como conceito fundamental no seu guia “Building Effective Agents”, apresentando-o como um dos três princípios centrais: “Carefully craft your agent-computer interface through thorough tool documentation and testing.” A sua orientação prática é: “One rule of thumb is to think about how much effort goes into human-computer interfaces, and plan to invest just as much effort in creating good agent-computer interfaces.”

Quatro princípios de ACI na prática

1. As ações devem ser simples e fáceis de compreender. O erro mais comum é envolver API endpoints um-para-um. Em vez de list_users, list_events, create_event, implemente schedule_event, que encontra a disponibilidade e agenda numa única chamada. Em vez de read_logs, implemente search_logs, que devolve apenas as linhas relevantes com contexto.

2. As ações devem ser compactas e eficientes. Consolide as operações importantes no menor número possível de ações. No Market Analyst Agent, combino a obtenção de preços com métricas básicas numa única ferramenta get_stock_snapshot, em vez de exigir calls separados para preço, volume, market cap e PE ratio.

3. O feedback do ambiente deve ser informativo, mas conciso. Evite devolver HTML em bruto ou payloads completos de API. Resolva IDs crípticos para nomes semânticos. Os testes da Anthropic acrescentaram um enum response_format, permitindo ao agent pedir uma resposta concisa (cerca de 72 tokens) ou detalhada (cerca de 206 tokens), uma diferença de aproximadamente 3 vezes no custo em tokens.

4. A validação deve mitigar a propagação de erros. A deteção automática de erros ajuda os agents a reconhecer e corrigir rapidamente os seus enganos. No SWE-agent, um editor de ficheiros personalizado com linting integrado rejeita automaticamente erros de sintaxe — a etapa de validação por trás da percentagem de 51,7% acima. Esta é a validação dos inputs e outputs de uma ferramenta, não o content filtering em torno de um model call feito pelos produtos de guardrails da Parte 4; a mesma palavra é usada para ambos. Aplico o mesmo princípio no Market Analyst Agent, validando os argumentos das ferramentas com Pydantic schemas antes da execução:

from pydantic import BaseModel, Field, field_validator

from market_analyst.utils import normalize_ticker

class StockQuery(BaseModel):
    """Validated input for stock queries.

    Pydantic catches malformed tickers before the API call,
    preventing error propagation through the reasoning loop.
    """
    ticker: str = Field(description="Stock ticker symbol (e.g., NVDA)")

    @field_validator("ticker")
    @classmethod
    def validate_ticker(cls, v: str) -> str:
        return normalize_ticker(v)

class StockHistoryQuery(StockQuery):
    """Validated input for price history queries."""

    period: str = Field(default="1mo", description="Time period: 1d, 5d, 1mo, 3mo, 6mo, 1y")

    @field_validator("period")
    @classmethod
    def validate_period(cls, v: str) -> str:
        valid = {"1d", "5d", "1mo", "3mo", "6mo", "1y"}
        if v not in valid:
            raise ValueError(f"Invalid period: {v}. Must be one of {valid}")
        return v

O normalizer partilhado remove espaços e converte o valor para maiúsculas, aceitando depois dígitos de ticker e sufixos com pontos ou hífen, como BRK.B e BF-B; StockHistoryQuery, e não StockQuery, é responsável por period.

Padrões de design de ferramentas para AI agents que funcionam

O guia da Anthropic “Writing effective tools for agents” descreve as ferramentas como “um novo tipo de software que reflete um contrato entre sistemas determinísticos e agents não determinísticos”.

Trate as descrições das ferramentas como prompt engineering

As descrições devem ter pelo menos três ou quatro frases, abrangendo quando utilizar a ferramenta, parâmetros obrigatórios versus opcionais, formato do output e edge cases. A Anthropic reporta que a escolha entre namespacing baseado em prefixo e em sufixo (asana_search versus search_asana) teve “efeitos não triviais” nas suas próprias avaliações de tool use. Não indica qual o esquema vencedor, por isso teste ambos no seu conjunto de ferramentas em vez de assumir que os prefixos são melhores. A Anthropic também passou os transcripts dos seus agents de avaliação pelo Claude Code e permitiu que este reescrevesse as ferramentas. Em test sets held-out, esse loop encontrou melhorias adicionais “mesmo para além do que alcançámos com implementações de ferramentas ‘expert’” — independentemente de essas ferramentas terem sido escritas pelos seus investigadores ou geradas pelo Claude.

# Bad: vague, no context for when to use
tools = [{
    "name": "search",
    "description": "Search for items",
}]

# Good: specific, with input examples and edge cases
tools = [{
    "name": "search_news",
    "description": (
        "Search for recent news articles about a specific stock or company. "
        "Use this tool when the user asks about recent events, earnings, "
        "announcements, or market-moving news for a specific ticker. "
        "Returns up to 10 articles sorted by relevance. "
        "For company competitors rather than news, use search_competitors instead."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Search query. Examples: 'NVDA earnings Q3 2025', 'Tesla delivery numbers'"
            },
            "max_results": {
                "type": "integer",
                "description": "Max articles to return (1-10, default 5)",
                "default": 5
            }
        },
        "required": ["query"]
    }
}]

Os testes internos da Anthropic mostraram que acrescentar um campo input_examples elevou a accuracy no tratamento de parâmetros complexos de 72% para 90%.

Devolva output de alto sinal e legível por máquinas

Use labels semânticas em vez de identificadores de baixo nível (uuid, mime_type) na resposta por defeito. Mantenha um ID quando uma ferramenta posterior precisar dele ou disponibilize uma resposta detalhada que o inclua. Por exemplo, um resultado de pesquisa de Jane pode ser conciso para leitura, enquanto um resultado detalhado inclui o ID de que send_message precisa. Estruture a resposta de modo a que o agent possa raciocinar sobre ela sem fazer parsing de boilerplate:

# Bad: raw API response dumped to agent
def get_stock_snapshot(ticker: str) -> dict:
    response = api.get(f"/v1/quotes/{ticker}")
    return response.json()  # 500+ tokens of nested JSON

# Good: high-signal summary the agent can immediately reason about
def get_stock_snapshot(ticker: str) -> dict:
    data = api.get(f"/v1/quotes/{ticker}").json()
    return {
        "ticker": ticker,
        "price": data["regularMarketPrice"],
        "change_pct": round(data["regularMarketChangePercent"], 2),
        "volume": data["regularMarketVolume"],
        "market_cap_b": round(data["marketCap"] / 1e9, 1),
        "pe_ratio": data.get("trailingPE"),
        "summary": f"{ticker} at ${data['regularMarketPrice']:.2f} "
                   f"({'up' if data['regularMarketChangePercent'] > 0 else 'down'} "
                   f"{abs(data['regularMarketChangePercent']):.1f}%)"
    }

Devolva erros sobre os quais o loop possa agir

O tratamento de erros precisa de quatro mecanismos distintos, porque cada um trata classes de falha diferentes:

1. Retry com exponential backoff para erros transitórios
2. Model fallback chains para indisponibilidade dos providers
3. Routing de classificação de erros — os erros transitórios são repetidos, os erros recuperáveis pelo LLM regressam ao agent com contexto e os erros que exigem intervenção humana são escalados
4. Checkpoint recovery para sobrevivência a crashes

O guia da Anthropic “Writing effective tools for agents” defende erros claros nas ferramentas e design de ferramentas orientado por avaliação, mas não atribui um número universal ao que estes quatro mecanismos conseguem recuperar. Meça a taxa de recuperação, os retries e as escalações no seu próprio conjunto de tarefas.

import httpx
from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential

def is_transient_error(error: BaseException) -> bool:
    if isinstance(error, (httpx.TimeoutException, httpx.NetworkError)):
        return True
    if isinstance(error, httpx.HTTPStatusError):
        return error.response.status_code == 429 or 500 <= error.response.status_code < 600
    return False

@retry(
    retry=retry_if_exception(is_transient_error),
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=10),
    reraise=True,
)
def call_stock_api(ticker: str) -> dict:
    """Fetch stock data with automatic retry on transient failures.

    Mechanism 1 of the four above: exponential backoff for rate limits
    and network blips.
    This only retries transient transport failures. If attempts are exhausted,
    Tenacity re-raises the original httpx exception.
    """
    response = httpx.get(
        f"https://api.example.com/v1/quotes/{ticker}",
        timeout=10.0,
    )
    response.raise_for_status()
    return response.json()

O caller ou harness continua a precisar do passo seguinte: transformar essa exceção num resultado estável que indique que operação falhou, se deve haver retry e o que fazer a seguir. Um 4xx não repetível ignora este decorator e precisa do mesmo tratamento. Repetir um request não classifica o erro nem recupera um checkpoint.

Aplicar os padrões ao Market Analyst Agent

O Market Analyst Agent da Parte 1 torna visível o efeito da interface.

Consolidação de ferramentas

Os módulos de ferramentas originais definiam get_stock_price, get_company_metrics, get_price_history, duas ferramentas de pesquisa e execute_trade. Para uma análise básica, o agent tinha de escolher tanto o call de preço como o de métricas; market cap e P/E eram campos de get_company_metrics, não ferramentas autónomas. O source anterior à consolidação mostra essa superfície anterior.

Reestruturei a superfície de dados de mercado em 5 ferramentas de alto nível, seguindo o princípio de ACI de ações compactas e eficientes. A lista de ferramentas ReAct do repo inclui mais quatro — um skill loader, dois wrappers CLI e um evaluator Python restrito no mesmo processo (uma AST allowlist, não um sandbox; a Parte 4 aborda o tema) — abrangendo três das cinco modalidades acima. O MCP surge como sidecar, e não como ferramenta nesta lista:

Isto coloca preço e valuation numa única definição orientada à tarefa e acrescenta as demonstrações financeiras como ação explícita. Saber se isso melhora a seleção de ferramentas é uma afirmação que deve ser testada contra requests representativos e traces.

Outputs estruturados para resultados de ferramentas

As ferramentas de ações e notícias devolvem respostas validadas por Pydantic. Os wrappers CLI e de execução de código devolvem str, pelo que os modelos abaixo descrevem os resultados estruturados das ferramentas, e não todos os wrappers do repositório:

from pydantic import BaseModel

class StockSnapshot(BaseModel):
    """Structured tool response — the agent never sees raw API noise."""
    ticker: str
    price: float
    change_pct: float
    volume: int
    market_cap_b: float
    pe_ratio: float | None
    summary: str  # Human-readable one-liner for direct use in reports

class NewsItem(BaseModel):
    """One news item pre-processed for agent consumption."""
    headline: str
    source: str
    date: str
    relevance_score: float  # Pre-ranked so the agent doesn't waste tokens sorting
    key_points: list[str]  # Extracted by the tool, not the agent

class NewsSearchResult(BaseModel):
    query: str
    results: list[NewsItem]
    summary: str

O campo summary fornece ao agent uma string pronta a utilizar num relatório. NewsItem.key_points evitam que o modelo tenha de fazer parsing dos corpos dos artigos. Se uma ação posterior precisar de um ID, mantenha-o na resposta detalhada ou disponibilize modos conciso e detalhado; não o remova em todo o lado.

Compromissos e considerações

Além das ressalvas específicas de cada padrão acima, algumas preocupações transversais influenciam a escolha:

• O custo operacional varia por dimensão. A execução de código poupa tokens, mas acrescenta latência de cold start do sandbox. O MCP poupa tempo de desenvolvimento em integrações SaaS, mas acrescenta overhead de deployment do servidor. A CLI não tem custo inicial, mas é mais difícil de governar à escala. Otimize o seu bottleneck real, seja o custo de tokens, a latência ou a complexidade operacional.

• As competências da equipa são importantes. A execução de código pressupõe que os seus agents (e os modelos por trás deles) conseguem gerar Python ou TypeScript fiável. A CLI pressupõe familiaridade com convenções Unix. O MCP exige compreender protocolos de transporte e fluxos OAuth. Alinhe a modalidade com os pontos fortes da equipa.

• A consolidação de ferramentas pode ir longe demais. Se uma ferramenta acumular modos e argumentos não relacionados, o agent depara-se com um problema de seleção diferente dentro do schema. Use avaliações de seleção de ferramentas e sucesso das tarefas para encontrar a superfície adequada ao seu workload.

• As Skills baseiam-se em prompts, não em enforcement. Uma skill contém instruções que o agent deve seguir, não guardrails que tem de seguir. Um skill bundle pode incluir ficheiros arbitrários e scripts executáveis, por isso confie na origem, reveja o bundle e faça com que o host imponha as permissões de cada recurso que este possa ler, alterar ou executar. Para workflows críticos, combine skills com validação determinística.

• Os requisitos de auditoria influenciam a escolha. MCP e JSON calls estruturados são eventos convenientes para registar, mas nenhum dos protocolos cria, por defeito, um audit trail completo. O host, servidor ou harness tem de registar invocações e resultados e, depois, impor autorização, policy, retenção e revisão. A execução de código precisa da mesma instrumentação em torno do sandbox; o script e o output, por si só, não constituem um registo de conformidade.

Três direções para tooling de AI agents à escala

A primeira é tool RAG para escalar. Antes de o modelo escolher uma ferramenta, obtenha as poucas descrições de ferramentas que correspondem ao request e permita que escolha desse subconjunto em vez de todo o registry. Nas tarefas de benchmark e no stress test MCP do RAG-MCP, a accuracy de seleção de ferramentas do baseline foi 13,62%; a retrieval elevou-a para 43,13%, uma melhoria de 3,2 vezes, reduzindo simultaneamente os prompt tokens de 2 133,84 para 1 084 (cerca de 49,2%). O abstract do artigo diz “mais de 50%” e as descrições do generator/evaluator diferem entre secções; estas inconsistências limitam a interpretação. O resultado é evidência para essa configuração de avaliação, não uma taxa universal de seleção ingénua à medida que os toolsets crescem.

A segunda é a criação das próprias ferramentas pelos agents. O framework LATM (“LLMs As Tool Makers”) estabeleceu um paradigma de duas fases em que um LLM poderoso cria funções Python reutilizáveis e um LLM leve as utiliza. No benchmark de 15 tarefas do ToolMaker, baseado em artigos com repositórios públicos de código e fornecido como URLs do GitHub e descrições curtas das tarefas, implementou corretamente 12 de 15 tarefas; o benchmark contém mais de 100 testes no total. Esse pequeno benchmark de tarefas sobre repositórios não estabelece fiabilidade de produção. Ambos apontam para além do tool use, em direção à criação de ferramentas e, depois, à gestão de uma library de ferramentas geradas.

A terceira é a dual-protocol stack A2A + MCP. A Google transferiu o A2A para a Linux Foundation em junho de 2025. A documentação do protocolo A2A separa as suas responsabilidades: o MCP liga um agent a ferramentas e recursos, enquanto o A2A permite que agents independentes se descubram, negoceiem interações, giram tarefas partilhadas e deleguem trabalho.

Compare interfaces em tarefas e operações permitidas idênticas. Registe tokens de descoberta, input cached e uncached, output da execução, retries, latência e sucesso do estado final. Teste tanto a descoberta falhada como as poupanças de tokens; para programas gerados, contabilize erros de sintaxe, erros de runtime e conclusão parcial.

Principais conclusões

1. Escolha a superfície de execução a partir da ação: JSON calls para operações pequenas e tipadas, MCP para serviços partilhados, CLI para comandos estabelecidos e código em sandbox para composição local. Use Skills para documentar como escolher e utilizar essa superfície.
2. Mantenha as condições do benchmark associadas ao resultado. CodeAct, Anthropic, Vercel, Cloudflare, Apideck e Scalekit mediram modelos, tarefas, ferramentas e harnesses diferentes.
3. A qualidade da ACI sobrevive a alterações do protocolo. Ações claras, feedback compacto, validação e erros úteis ajudam todas as modalidades.
4. Consolide ferramentas sobrepostas apenas quando as avaliações mostrarem que a superfície mais pequena melhora a seleção ou o sucesso das tarefas.
5. A segurança acompanha o poder de execução. Interfaces shell e de código precisam de sandboxing; o MCP precisa de identidade com scope limitado e policy do servidor; as Skills continuam a ser instruções, não enforcement.

A camada seguinte é a policy

A Parte 4, AI Agent Security, aborda a verificação do harness entre um tool call proposto e a execução. A Parte 5 coloca a ferramenta e o seu sandbox num runtime recuperável. A Parte 6 acrescenta um contrato que o modelo não vê: uma categoria de efeito, uma regra de retry e um resultado estruturado que uma acceptance check pode ler sem fazer parsing de prosa.

Referências

Artigos

• Executable Code Actions Elicit Better LLM Agents (CodeAct) — Wang et al., ICML 2024 — As code-based actions reportam até 20 pontos percentuais mais de sucesso nas tarefas do artigo
• SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering — Yang, Jimenez et al., NeurIPS 2024 — Princípios de design de ACI e avaliação SWE-bench (18,0% para o SWE-agent contra 7,3% apenas com shell e sem demonstração na ablation de 300 tarefas SWE-bench Lite do artigo; as condições de interface e demonstração diferem)
• RAG-MCP: Mitigating Prompt Bloat in LLM Tool Selection — As suas tarefas de benchmark e o stress test MCP melhoraram a accuracy de seleção de 13,62% para 43,13%
• LLMs As Tool Makers (LATM) — Cai et al., 2023 — Paradigma de duas fases para criação de ferramentas por agents
• ToolMaker: LLM Agents Making Agent Tools — Wolflein et al., ACL 2025 — 80% no seu benchmark de 15 tarefas baseado em artigos com repositórios públicos de código
• MCPTox: A Benchmark for Tool Poisoning Attack on Real-World MCP Servers — 72,8% de sucesso médio dos ataques para o o1-mini num benchmark que abrange 20 agents e 45 servidores

Engenharia da Anthropic

• Advanced Tool Use / Programmatic Tool Calling — Tool Search (endpoints aproximados de contexto de cerca de 77K e cerca de 8,7K), PTC e exemplos de tool use
• Code Execution with MCP — Redução de 98,7% nos tokens (de 150K para 2K tokens) através de orquestração de ferramentas baseada em código
• Writing Effective Tools for Agents — Engenharia de descrições de ferramentas; exemplos de input melhoram a accuracy; enum response_format (72 contra 206 tokens)
• Building Effective Agents — ACI como princípio fundamental de design

Especificações de protocolos

• Google Cloud donates A2A to Linux Foundation — Anúncio de 23 de junho de 2025 sobre a transferência do protocolo, SDK e tooling
• A2A and MCP: Detailed Comparison — Documentação do protocolo A2A sobre as responsabilidades complementares entre agents e entre agents e ferramentas

Case studies da indústria

• Vercel: We Removed 80% of Our Agent’s Tools — o exemplo antigo nomeia 17 ferramentas; o novo expõe ExecuteCommand e ExecuteSQL; a Vercel apresenta o redesign como uma remoção de 80%; sucesso de 4/5 para 5/5 em cinco queries representativas, 3,5 vezes mais rápido e 37% menos tokens
• Cloudflare: Code Mode — API calls orientados por TypeScript que substituem tool schemas
• Apideck: MCP Server Eating Your Context Window — 550–1 400 tokens por ferramenta, 55K tokens para cerca de 40 ferramentas MCP, 143K/200K de contexto consumido
• Scalekit: MCP vs CLI Token Benchmark — Overhead de tokens de 4 a 32 vezes para MCP face a CLI em 75 execuções de benchmark

Segurança

• Vulnerable MCP Project — Relatórios de vulnerabilidades para construir testes de threat model
• AuthZed: Timeline of MCP Breaches — 9 incidentes de segurança MCP graves (abril–outubro de 2025)
• Invariant Labs: MCP Tool Poisoning Attacks — Tool poisoning, rug pulls e escalada cross-origin
• Pivot Point Security: MCP Security Analysis — 43% de command injection e 43% de falhas de autenticação OAuth

Design de CLI

• Writing CLI Tools That AI Agents Actually Want to Use — Ugo Enyioha — Oito regras de design para CLIs adequadas a agents

Projeto de demonstração

• Market Analyst Agent — Implementação completa com consolidação de ferramentas e padrões de ACI

O código completo do Market Analyst Agent, incluindo os designs das ferramentas descritos neste artigo, está no GitHub.