Uso de ferramentas por AI Agents: MCP, CLI, Skills e execução de código

Viacheslav Dubrov

2026-03-24 · Atualizado 2026-08-01 · 24 min · Agentes de IA

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

A Parte 1 abordou os reasoning loops, e a Parte 2 abordou a memória. Este artigo acrescenta a camada de ação: como um agent expõe, seleciona e executa ferramentas. A memória determina o que o agent sabe ao iniciar uma interação; esta camada determina o que consegue fazer com esse conhecimento. A Parte 4 aborda a verificação que determina se uma chamada identificada pelo nome chega sequer a ser executada, e a Parte 6 aborda o harness que executa tanto a chamada como a verificação. Ao longo deste artigo, harness significa o programa de controlo que compõe cada prompt, despacha os tool calls que aceita e decide quando a tarefa está concluída — tudo o que envolve o modelo e que corresponde a código normal escrito por si.

A história das ferramentas mudou em 2025–2026. O MCP, o Model Context Protocol, deu aos fornecedores uma forma partilhada de expor serviços externos. Os agents com execução de código demonstraram que, por vezes, um modelo consegue compor um pequeno programa de forma mais eficiente do que emitir uma longa sequência de chamadas JSON. A Anthropic comunicou uma redução de 98,7% nos tokens num workflow Google Drive-to-Salesforce, e o artigo CodeAct comunicou ganhos de até 20% na configuração do seu benchmark. Estes resultados descrevem as respetivas tarefas e harnesses, não uma vantagem universal da execução de código.

Comparo JSON tool calling, MCP, Skills, ferramentas CLI e execução de código, por esta ordem. 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 criei para a Parte 1, que obtém dados de mercado e escreve um relatório de analista.

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

Em resumo: cinco padrões de interface úteis cobrem a maioria dos casos de uso de ferramentas por agents. As Skills transportam instruções, as ferramentas CLI adequam-se ao desenvolvimento local, o MCP liga serviços partilhados e a execução de código compõe trabalho com vários passos dentro de um sandbox. O JSON tool calling continua a ser a opção mais simples para ações atómicas pequenas. Seja qual for o protocolo, a Agent-Computer Interface (ACI) deve tornar as ações claras, o feedback compacto e os erros recuperáveis.

Cinco formas de os AI agents usarem ferramentas

Na Parte 1, o reasoning loop escolhia o passo seguinte. A Parte 2 armazenava o estado necessário para o retomar. A fronteira das ferramentas situa-se entre ambos: valida o que o loop propôs, encaminha a chamada para execução e devolve o resultado ao loop. Estes cinco padrões fazem compromissos diferentes em custo de 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 estruturadas e o seu código executa-as. É bem compreendido e funciona adequadamente para conjuntos pequenos de ferramentas.

# Traditional tool definition — each tool consumes ~550-1,400 tokens (Apideck benchmark)
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"]
        }
    }
]

Com 5–10 ferramentas, o overhead é aceitável. O problema surge à escala: cada definição de ferramenta custa 550–1.400 tokens. Com 20 ferramentas, está a gastar 11–28 mil tokens antes de o agent sequer começar a raciocinar.

2. MCP para integrações partilhadas

O MCP é o standard em torno do qual a maioria dos fornecedores 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, HTTP para um processo remoto. O seu agent executa um cliente MCP que estabelece a ligação, pergunta ao servidor que ferramentas possui e encaminha para ele as chamadas do modelo; assim, o mesmo servidor funciona com qualquer cliente compatível com 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. De acordo com 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 de SDKs, entre os SDKs de Python e TypeScript.

O MCP adequa-se a integrações SaaS entre fornecedores (Figma, Notion, Salesforce), a serviços sem equivalentes CLI e a 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 realidade em produção é mais complexa do que os números de destaque sugerem.

A superfície de segurança é o primeiro problema. O Vulnerable MCP Project acompanha 50 vulnerabilidades em servidores MCP, 13 das quais classificadas como Critical, identificadas por 32 investigadores de segurança. As classes de ataque incluem prompt injection, falhas de validação de inputs, lacunas de autenticação e vulnerabilidades de segurança de rede. O primeiro servidor MCP malicioso no mundo real surgiu em setembro de 2025: um pacote chamado postmark-mcp que enviava em BCC todos os emails de saída para o endereço do atacante.

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 os metadados da ferramenta para desencadear o ataque. Os benchmarks MCPTox, que testaram 20 agents LLM contra 45 servidores MCP reais, encontraram taxas de sucesso dos ataques de até 72,8%.

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 um utilizador perguntar fosse o que fosse. Outra comunicou 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 mediu uma redução de 85% no consumo total de contexto — de aproximadamente 77.000 tokens antes do início do trabalho para 8.700 — num cenário tradicional com cerca de 72.000 tokens de definições de ferramentas. Carrega apenas as três a cinco ferramentas necessárias para um pedido, mas acrescenta um passo de descoberta antes da invocação; é menos útil para conjuntos pequenos e compactos de ferramentas usadas frequentemente em todas as sessões.

3. As 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 conseguem 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 usa também duas extensões do Claude Code, argument-hint e user-invocable, além do placeholder de argumentos posicionais $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 usam progressive disclosure. Cerca de 100 tokens de metadados são carregados no arranque; as instruções completas só são carregadas quando a skill está ativa. Compare com os cerca de 55.000 tokens que aproximadamente 40 ferramentas MCP podem consumir antes de o raciocínio começar.

Use Skills para conhecimento de domínio, procedimentos com vários passos e trabalho recorrente, como migrações de bases de dados ou integrações de pagamentos. Adequam-se a tarefas em que o agent precisa de instruções sobre como usar uma capacidade já existente.

4. Ferramentas CLI e shell

As interfaces CLI podem ser muito mais económicas em contexto quando o modelo já conhece o comando. A Scalekit comunicou uma diferença de 4–32x 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 o output dos seus comandos.

Comandos amplamente documentados, como git, docker, kubectl, gh, curl e jq, muitas vezes precisam de pouco texto introdutório de schema. CLIs menos comuns ou internos continuam a precisar de ajuda detetável, exemplos e output estável e legível por máquina.

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

1. O output estruturado é obrigatório — suporte --json
2. Os códigos de saída são controlo de fluxo — use códigos distintos para diferentes tipos de erro
3. Os comandos devem ser idempotentes
4. Auto-documentação --help com exemplos realistas
5. Conceba para composição — --quiet para valores simples e suporte de stdin
6. Disponibilize as 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 tem descoberta ao nível do protocolo. O JSON tool calling pode transportar schemas tipados, enquanto o MCP normaliza a descoberta de ferramentas e, nos transportes HTTP, um modelo de autorização. Nenhum dos dois fornece governance por si só: o host, o servidor ou o harness têm de impor a política e registar as chamadas que precisam de ser auditadas. O padrão para o qual vejo a maioria das equipas a convergir é CLI para desenvolvimento e operações locais, e MCP para integrações partilhadas com serviços externos.

5. Execução de código para trabalho com vários passos

Esta é a mudança nas ferramentas 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) como uma de três funcionalidades beta na Claude API. A base académica é o artigo CodeAct (Wang et al., ICML 2024), que testou 17 LLMs e descobriu que as ações em código alcançaram taxas de sucesso até 20% superiores e 30% menos passos do que as alternativas JSON.

Três case studies de primeira parte 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 fornecedores e volte a executar a comparação nas suas próprias tarefas.

• A Vercel reconstruiu o d0, o seu data agent de linguagem natural para SQL. O 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 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 comunica que o sucesso das tarefas passou de 4/5 para 5/5, o tempo médio de execução diminuiu 3,5x (de 274,8 s para 77,4 s) e o uso médio de tokens caiu 37% (cerca de 102 mil para cerca de 61 mil). Nas palavras da empresa: “Os melhores agents podem ser os que têm menos ferramentas.”

• 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 raciocínio apresentado é: “Os LLMs têm uma enorme quantidade de TypeScript do mundo real no seu conjunto de treino, mas apenas um pequeno conjunto de exemplos artificiais de tool calls.”

Eis o padrão da documentação da Anthropic sobre PTC. Na ilustração sequencial de análise de despesas da Anthropic, o tool calling tradicional exige mais de 20 passes de inferência separados, com os dados intermédios a circularem pelo contexto. Depois da pesquisa da equipa, um host que suporte tool calls em paralelo pode agrupar os pedidos de despesas independentes; a referência a mais de 20 não torna isso impossível. A Anthropic comunica 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. Com execução de código, o agent escreve um único script:

# Agent generates this code, executes in sandbox
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())

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 dos relatórios de despesas: o artigo separado da Anthropic sobre execução de código apresenta o número mais expressivo para este padrão, num workflow Google Drive-to-Salesforce que passou de cerca de 150.000 tokens para cerca de 2.000, uma redução de 98,7%.

A eficiência de tokens é o ganho mais óbvio. Os loops e condicionais não têm custo adicional significativo, 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 equivale a confidencialidade: o isolamento, os controlos de egress, as credenciais com âmbito limitado e o logging precisam de enforcement separado.

Quando o JSON tool calling continua a fazer sentido: operações atómicas individuais, ambientes sem infraestrutura de sandboxing, modelos mais pequenos com geração de código fraca ou requisitos de auditoria que necessitem do registo de cada invocação individual de ferramenta.

Tabela comparativa de tool calling para AI agents

“Meta-tools” na linha do overhead de tokens significa o pequeno conjunto de entry points genéricos de que um agent com execução de código precisa — por exemplo, ExecuteCommand e ExecuteSQL da Vercel — em vez de um schema por cada operação subjacente. As linhas de componibilidade e latência dizem respeito a chamadas cujos argumentos posteriores dependem de resultados anteriores no harness ou loop discutido. O JSON tool calling e o MCP podem emitir chamadas independentes em conjunto, e um host pode executá-las concorrentemente; as chamadas dependentes precisam normalmente de outro turn do modelo para escolher a ação seguinte. O PTC transfere o controlo de fluxo dependente e a filtragem no código para o script, devolvendo depois um resumo ao modelo; também pode emitir chamadas independentes concorrentemente. As células relativas a tokens e sucesso das tarefas resumem os 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 artigo SWE-agent (NeurIPS 2024). A qualidade das interfaces humanas dispõe de uma disciplina inteira dedicada ao tema — interação humano-computador, ou HCI. O artigo defende que os agents baseados em modelos de linguagem merecem o mesmo tratamento: são “uma nova categoria de utilizadores finais, com necessidades e capacidades próprias, que beneficiaria de interfaces construídas especificamente para si”.

Os seus resultados de ablation quantificam esse efeito. Usando o mesmo modelo base GPT-4 Turbo, a ablation do SWE-bench Lite alcançou 18,0% com a ACI completa do SWE-agent em 300 tarefas, contra 7,3% na condição apenas com shell, sem demonstração trabalhada, e 11,0% com uma demonstração. A comparação mostra que, nesta configuração, a interface e as condições da demonstração alteraram materialmente o desempenho; 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 o linting elevou a condição de edição de 15,0% para 18,0%; em todo o conjunto de testes SWE-bench, 51,7% das execuções do SWE-agent encontraram pelo menos uma edição rejeitada pelo linter antes de esta poder propagar-se.

A Anthropic adotou ACI como conceito fundamental no seu guia “Building Effective Agents”, apresentando-o como um dos três princípios centrais: “Conceba cuidadosamente a sua agent-computer interface através de documentação e testes exaustivos das ferramentas.” A sua orientação prática é: “Uma regra prática é pensar no esforço dedicado às interfaces humano-computador e planear investir exatamente o mesmo esforço na criação de boas 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 é encapsular endpoints de API numa relação de 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 chamadas separadas para preço, volume, capitalização bolsista e rácio PE.

3. O feedback do ambiente deve ser informativo, mas conciso. Evite devolver HTML bruto ou payloads completos de API. Resolva IDs criptográficos para nomes semânticos. Nos testes da Anthropic, foi acrescentado um enum response_format para que o agent possa pedir uma resposta concisa (cerca de 72 tokens) ou detalhada (cerca de 206 tokens), uma diferença de aproximadamente 3x no custo de 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 — o passo de validação subjacente à percentagem de 51,7% acima. Trata-se de validação dos inputs e outputs de uma ferramenta, não da filtragem de conteúdo em torno de uma chamada ao modelo realizada 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 schemas Pydantic 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 normalizador partilhado remove espaços e converte o valor para maiúsculas, aceitando depois dígitos no 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, cobrindo quando usar a ferramenta, parâmetros obrigatórios e opcionais, formato do output e casos limite. A Anthropic comunica que a escolha entre namespacing baseado em prefixos e em sufixos (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 toolset em vez de assumir que os prefixos são melhores. A Anthropic também forneceu os transcripts dos seus agents de avaliação ao Claude Code e permitiu que este reescrevesse as ferramentas. Em conjuntos de testes não utilizados no treino, esse loop encontrou melhorias adicionais “mesmo além do que alcançámos com implementações de ferramentas ‘especializadas’” — independentemente de estas terem sido escritas manualmente 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 precisão no tratamento de parâmetros complexos de 72% para 90%.

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

Evite identificadores de baixo nível (uuid, mime_type). Resolva IDs criptográficos para nomes semânticos. Estruture a resposta para que o agent consiga raciocinar sobre ela sem analisar 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 separados, porque cada um trata classes de falhas diferentes:

1. Retry com exponential backoff para erros transitórios
2. Cadeias de fallback de modelos para indisponibilidade do fornecedor
3. Routing por 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. Recuperação a partir de checkpoints para sobreviver a crashes

O artigo da Anthropic “Writing effective tools for agents” defende erros de ferramentas claros e design de ferramentas orientado por avaliações, mas não apresenta um número universal para aquilo que estes quatro mecanismos conseguem recuperar. Meça a taxa de recuperação, os retries e os escalamentos na sua própria suite 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.
    If all retries fail, the error propagates to the agent with
    enough context to decide whether to try a different approach.
    """
    response = httpx.get(
        f"https://api.example.com/v1/quotes/{ticker}",
        timeout=10.0,
    )
    response.raise_for_status()
    return response.json()

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 a chamada de preço como a chamada de métricas; a capitalização bolsista e o P/E eram campos de get_company_metrics, não ferramentas autónomas. O código-fonte 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 repositório inclui mais quatro — um carregador de skills, dois wrappers CLI e um avaliador Python restrito no processo (uma allowlist de AST, não um sandbox; a Parte 4 aborda este tema) — cobrindo três das cinco modalidades acima. O MCP surge como sidecar, e não como uma ferramenta nesta lista:

Isto coloca o preço e o valuation numa única definição orientada para a tarefa e acrescenta as demonstrações financeiras como ação explícita. Se tal melhora a seleção de ferramentas é uma hipótese que deve ser testada com pedidos e traces representativos.

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; por isso, 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 usar, que pode ser inserida diretamente num relatório. Os NewsItem.key_points são extraídos pela ferramenta, e não pelo agent, poupando tokens de inferência que, de outro modo, seriam usados para analisar o corpo dos artigos.

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 é gratuita para começar, mas é mais difícil de governar à escala. Otimize para o seu verdadeiro bottleneck, seja ele 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 que os suportam) conseguem gerar Python ou TypeScript fiável. A CLI pressupõe familiaridade com as convenções Unix. O MCP exige compreensão dos protocolos de transporte e dos fluxos OAuth. Adeque a modalidade às competências da sua equipa.

• A consolidação de ferramentas pode ser excessiva. Se uma ferramenta acumular modos e argumentos sem relação entre si, o agent enfrenta um problema de seleção diferente dentro do schema. Use avaliações de seleção de ferramentas e sucesso de tarefas para encontrar a superfície adequada ao seu workload.

• As Skills são baseadas em prompts, não impostas. Uma skill contém instruções que o agent deve seguir, não guardrails que tenha obrigatoriamente de seguir. Um bundle de skills 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 relativas a todos os recursos que este pode ler, alterar ou executar. Em workflows críticos, combine Skills com validação determinística.

• Os requisitos de auditoria influenciam a escolha. As chamadas MCP e JSON estruturadas são eventos convenientes para registar, mas nenhum dos protocolos cria, por si só, um audit trail completo. O host, o servidor ou o harness têm de registar invocações e resultados e impor autorização, política, 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 ferramentas de AI agents à escala

A primeira é tool RAG para escalar. Nas tarefas de benchmark e no stress test MCP do RAG-MCP, a precisão de seleção de ferramentas da baseline foi de 13,62%; a retrieval elevou-a para 43,13%, uma melhoria de 3,2x, reduzindo simultaneamente os tokens do prompt em mais de 50%. 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 são os agents que criam as suas próprias ferramentas. O framework LATM (“LLMs As Tool Makers”) estabeleceu um paradigma em duas fases, no qual um LLM poderoso cria funções Python reutilizáveis e um LLM leve utiliza-as. No benchmark ToolMaker, com 15 tarefas baseadas em artigos com repositórios de código públicos, fornecidos como URLs do GitHub e descrições curtas das tarefas, implementou corretamente 80% das tarefas. Ambos apontam para além do tool use, em direção à criação de ferramentas e, depois, à gestão de uma biblioteca de ferramentas geradas.

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

Principais conclusões

1. Escolha a interface a partir da ação: JSON calling para operações pequenas e tipadas, MCP para serviços partilhados, Skills para procedimentos, CLI para comandos estabelecidos e código em sandbox para composição local.
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 às alterações de 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 uma superfície menor melhora a seleção ou o sucesso das tarefas.
5. A segurança acompanha o poder de execução. As interfaces shell e de código precisam de sandboxing; o MCP precisa de identidade com âmbito limitado e política no servidor; as Skills continuam a ser instruções, e não enforcement.

A camada seguinte é a política

A Parte 4, AI Agent Security, coloca uma verificação de política entre um tool call proposto e a execução. É a mesma fronteira de ferramentas descrita acima, vista do lado que diz não. A Parte 5 coloca depois a ferramenta e o seu sandbox dentro de um runtime recuperável, e a Parte 6 acrescenta um segundo contrato que o modelo nunca vê: uma categoria de efeitos, uma regra de retry e um resultado estruturado que uma verificação de aceitação pode ler sem analisar prosa.

Referências

Artigos

• Executable Code Actions Elicit Better LLM Agents (CodeAct) — Wang et al., ICML 2024 — As ações baseadas em código alcançam até mais 20% de sucesso em tarefas do que JSON
• 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 SWE-agent contra 7,3% apenas com shell, 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 precisão de seleção de 13,62% para 43,13%
• LLMs As Tool Makers (LATM) — Cai et al., 2023 — Paradigma em 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 com artigos que possuem repositórios de código públicos
• MCPTox: A Comprehensive MCP Toxicity Benchmark — Taxa de sucesso de ataques de 72,8% em 20 agents LLM e 45 servidores MCP

Engenharia da Anthropic

• Advanced Tool Use / Programmatic Tool Calling — Tool Search (85% menos consumo total de contexto, cerca de 77K para 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) através de orquestração de ferramentas baseada em código
• Writing Effective Tools for Agents — Engenharia das descrições de ferramentas; exemplos de inputs melhoram a precisão; 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,5x mais rápido, menos 37% de tokens
• Cloudflare: Code Mode — Chamadas de API orientadas por TypeScript em substituição dos 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–32x para MCP contra CLI em 75 execuções de benchmark

Segurança

• Vulnerable MCP Project — 50 vulnerabilidades acompanhadas, 13 Critical, de 32 investigadores
• AuthZed: Timeline of MCP Breaches — 9 incidentes de segurança MCP importantes (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, 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 de ferramentas descritos nesta publicação, está no GitHub.