Chamadas de ferramentas em agentes: faça a IA acessar APIs e serviços externos

Você já tentou pedir à IA para consultar a previsão do tempo, ler um arquivo ou acessar uma API e recebeu apenas a resposta “não consigo acessar dados externos”?

É frustrante, não é?

Na verdade, isso não acontece porque a IA não é inteligente o bastante, mas porque lhe falta uma capacidade essencial: a chamada de ferramentas. Hoje vamos entender essa tecnologia que transforma a IA de algo que “só conversa” em algo que realmente “executa tarefas”.

O que são chamadas de ferramentas em IA?

Em termos simples, chamar ferramentas é como dar mãos à IA.

Os modelos de linguagem tradicionais só conseguem responder com base nos dados de treinamento. Se você perguntar “como está o tempo em Pequim hoje?”, eles só poderão dizer “não consigo obter dados em tempo real”. Com chamadas de ferramentas, porém, a IA pode solicitar ativamente a execução de uma função, como consultar uma API meteorológica, e depois apresentar o resultado a você.

Qual é a importância disso? É mais ou menos a diferença entre um estrategista que só sabe falar sobre teoria e um general capaz de liderar as tropas no campo de batalha.

Três abordagens principais

Hoje, há três abordagens predominantes para chamadas de ferramentas:

Qual escolher? Depende da sua necessidade. Para casos simples, o OpenAI Function Calling é suficiente. Em sistemas de agentes complexos, o Claude Tool Use é mais adequado. Se a ideia é criar um ecossistema de ferramentas, o MCP é a tendência.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

OpenAI Function Calling: dos conceitos básicos à prática

Vamos começar pela solução da OpenAI. O Function Calling tem um design bastante simples, resumido em três etapas:

1. Definir as ferramentas, informando à IA quais estão disponíveis
2. A IA decide qual ferramenta chamar e retorna o nome da função e os parâmetros
3. Você executa a ferramenta e devolve o resultado à IA

Um exemplo completo

Suponha que queremos criar uma ferramenta de consulta meteorológica. Primeiro, definimos o Schema da ferramenta:

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "获取指定城市的当前天气信息",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "城市名称，如'北京'、'上海'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "温度单位，默认摄氏度"
                }
            },
            "required": ["city"]
        }
    }
}]

Preste atenção ao campo description: não o trate de qualquer jeito. É com base nele que a IA decide quando deve chamar a ferramenta. Já vi alguém escrever apenas “obter clima”, e a IA simplesmente não entendia em quais situações deveria usá-la. Depois de trocar para “obtém as condições meteorológicas atuais de uma cidade”, a taxa de acerto das chamadas saltou de 60% para 95%.

Em seguida, enviamos a solicitação:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "北京今天热不热？"}
    ],
    tools=tools
)

A IA retorna uma solicitação de chamada de ferramenta:

tool_call = response.choices[0].message.tool_calls[0]
# tool_call.function.name = "get_weather"
# tool_call.function.arguments = '{"city": "北京"}'

Depois, você executa a função de verdade e devolve o resultado:

# Executa a chamada à sua API meteorológica
weather_result = get_weather_from_api("北京")

# Devolve o resultado à IA
final_response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "北京今天热不热？"},
        response.choices[0].message,  # Solicitação de ferramenta feita pela IA
        {
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(weather_result)
        }
    ]
)

Com base nos dados meteorológicos, a IA dará uma resposta natural: “Hoje faz 28 graus em Pequim. Está bem quente, então não se esqueça do protetor solar ao sair.”

Strict Mode: mais estabilidade na saída

Em 2024, a OpenAI lançou o Strict Mode, que resolveu o problema da correspondência instável com JSON Schema. Ativá-lo é simples:

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "strict": True,  # Adicione esta linha
        # ... Outros campos
    }
}]

Depois de ativado, os parâmetros retornados pela IA têm garantia de 100% de conformidade com o Schema definido. Em produção, é altamente recomendável deixá-lo ligado; caso contrário, você poderá encontrar vários erros estranhos de parsing.

Claude Tool Use: uma cadeia de ferramentas mais poderosa

O Tool Use do Claude tem algumas diferenças importantes de concepção em relação à solução da OpenAI.

Chamadas paralelas

O Claude permite retornar várias chamadas de ferramentas de uma só vez. Por exemplo, se o usuário perguntar “compare o tempo em Pequim e Xangai”, o Claude solicitará duas chamadas a get_weather de uma vez:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "对比一下北京和上海的天气"}],
    tools=tools
)

# response.content pode conter dois blocos tool_use
for block in response.content:
    if block.type == "tool_use":
        print(f"调用 {block.name}，参数：{block.input}")

Isso é especialmente útil em tarefas complexas. A OpenAI também permite chamadas paralelas, mas a implementação do Claude é mais elegante: ele identifica de forma inteligente quais chamadas podem rodar em paralelo e quais precisam ser sequenciais.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Estratégias de Tool Choice

O Claude oferece um controle mais granular sobre a escolha de ferramentas:

# Seleção automática (padrão)
tool_choice = {"type": "auto"}

# Obriga o uso de uma ferramenta (não responde sem usá-la)
tool_choice = {"type": "any"}

# Define uma ferramenta específica
tool_choice = {"type": "tool", "name": "get_weather"}

Quando usar any? Quando você tem certeza de que a pergunta do usuário só pode ser respondida por meio de uma ferramenta. Para consultar o status de um pedido, por exemplo, não há como responder sem acessar o banco de dados. Nesse caso, obrigue a IA a usar uma ferramenta.

Tratamento de erros

Falhas nas chamadas de ferramentas são comuns. Timeout da API, instabilidade de rede, parâmetros incorretos… O Claude oferece um mecanismo elegante para lidar com erros:

tool_result = {
    "type": "tool_result",
    "tool_use_id": tool_use.id,
    "content": "API 调用失败：连接超时",  # Informa diretamente a causa à IA
    "is_error": True  # Marca como erro
}

Ao identificar o erro, a IA tenta outra abordagem ou apresenta uma mensagem amigável ao usuário. Isso é muito melhor do que simplesmente lançar uma exceção: em vez de ver uma pilha de mensagens técnicas, a pessoa recebe algo como “desculpe, o serviço meteorológico está temporariamente indisponível. Tente novamente mais tarde”.

MCP: o futuro da padronização de ferramentas

Não dá para falar de chamadas de ferramentas sem mencionar o MCP (Model Context Protocol).

Por que precisamos do MCP?

O ecossistema atual de ferramentas é fragmentado demais. Para conectar uma ferramenta do GitHub ao Claude e outra do Slack ao ChatGPT, é preciso desenvolver cada integração separadamente. O objetivo do MCP é estabelecer um padrão único: escrever uma vez e usar em qualquer lugar.

A arquitetura é simples:

MCP Client (Claude Code/Claude Desktop)
        ↕
    MCP Server (provedor da ferramenta)
        ↕
   External Tool/API

MCP na prática com o Claude Code

Atualmente, o Claude Code é o produto com o melhor suporte a MCP. Você configura as ferramentas com o comando /mcp:

# Adiciona um servidor MCP remoto
claude mcp add my-server --transport sse --url https://api.example.com/mcp

# Adiciona uma ferramenta local
claude mcp add local-tool --command node ./my-tool.js

Depois da configuração, o Claude Code descobre automaticamente as ferramentas oferecidas pelo servidor. Quando você menciona um assunto relacionado na conversa, ele faz a chamada sem precisar de mais instruções.

Um exemplo: configurei uma ferramenta chamada get-github-issues e perguntei ao Claude Code: “quais são as issues abertas deste projeto?”. Ele chamou a ferramenta diretamente e organizou os resultados para mim.

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Durante todo o processo, nem percebi que havia uma ferramenta nos bastidores. Esse é o estado ideal das chamadas de ferramentas.

Algumas armadilhas em produção

As chamadas de ferramentas parecem simples, mas, quando chegam à produção, surgem vários problemas.

Segurança: não deixe a IA agir sem controle

A IA pode chamar uma API que você não gostaria que ela acessasse. Algumas soluções:

1. Níveis de permissão para ferramentas: ofereça apenas as ferramentas necessárias e exija confirmação humana para operações sensíveis
2. Validação de entrada: valide novamente os parâmetros gerados pela IA antes de enviá-los à API
3. Auditoria de chamadas: registre os parâmetros e os resultados de cada chamada para facilitar investigações posteriores

Já vi um caso que serve de alerta: a IA enviava a entrada livre do usuário diretamente para uma interface de consulta ao banco de dados. O resultado… injeção de SQL. Embora a injeção não tenha sido feita diretamente pela IA, foi ela que repassou a entrada maliciosa. Por isso, nunca confie nos parâmetros gerados pela IA.

Timeout e novas tentativas

As chamadas de ferramentas podem falhar. Defina um timeout adequado e combine-o com um mecanismo de repetição:

async def call_tool_with_retry(tool_func, args, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await asyncio.wait_for(
                tool_func(**args),
                timeout=10.0  # Timeout de 10 segundos
            )
        except asyncio.TimeoutError:
            if attempt == max_retries - 1:
                return {"error": "工具调用超时"}
            await asyncio.sleep(1)  # Aguarda 1 segundo antes de tentar novamente

Custo de tokens

Tanto as definições das ferramentas quanto os resultados retornados consomem tokens. Quando há um grande volume de dados na resposta, o custo pode ser alto. Algumas recomendações:

1. Simplifique a descrição da ferramenta: mantenha o description curto, mas claro
2. Limite os dados retornados: filtre a resposta da API e mantenha somente os campos necessários
3. Use cache: resultados de consultas iguais podem ficar em cache por alguns minutos

Para concluir

As chamadas de ferramentas são uma capacidade essencial dos agentes de IA. Sem elas, a IA só fala sobre o que poderia fazer; com elas, passa a realmente ajudar na execução de tarefas.

O Function Calling da OpenAI é simples e fácil de usar, sendo indicado para começar e para cenários básicos. O Tool Use do Claude é mais poderoso e adequado a sistemas de agentes complexos. Já o MCP é a tendência de padronização de ferramentas e merece atenção no longo prazo.