Chamada programática de ferramentas

A chamada programática de ferramentas permite que o Claude escreva código que chama suas ferramentas programaticamente dentro de um contêiner de execução de código, em vez de exigir viagens de ida e volta pelo modelo para cada invocação de ferramenta. Isso reduz a latência para fluxos de trabalho com múltiplas ferramentas e diminui o consumo de tokens ao permitir que o Claude filtre ou processe dados antes que eles cheguem à janela de contexto do modelo. Em benchmarks de busca agêntica como BrowseComp e DeepSearchQA, que testam pesquisa web em múltiplas etapas e recuperação complexa de informações, adicionar chamada programática de ferramentas sobre ferramentas de busca básicas foi o fator chave que desbloqueou completamente o desempenho do agente.

A diferença se multiplica rapidamente em fluxos de trabalho reais. Considere verificar a conformidade de orçamento em 20 funcionários: a abordagem tradicional requer 20 viagens de ida e volta separadas pelo modelo, puxando milhares de itens de despesas para o contexto ao longo do caminho. Com a chamada programática de ferramentas, um único script executa todas as 20 consultas, filtra os resultados e retorna apenas os funcionários que excederam seus limites, reduzindo o que o Claude precisa raciocinar de centenas de kilobytes para apenas algumas linhas.

Compatibilidade de modelos

Para detalhes de compatibilidade de modelos e versões de ferramentas, consulte a Referência de ferramentas. A chamada programática de ferramentas está disponível via API Claude e Microsoft Foundry.

Início rápido

Aqui está um exemplo simples onde o Claude consulta programaticamente um banco de dados várias vezes e agrega resultados:

Como funciona a chamada programática de ferramentas

Quando você configura uma ferramenta para ser chamável a partir da execução de código e o Claude decide usar essa ferramenta:

1. O Claude escreve código Python que invoca a ferramenta como uma função, potencialmente incluindo múltiplas chamadas de ferramentas e lógica de pré/pós-processamento
2. O Claude executa esse código em um contêiner isolado via execução de código
3. Quando uma função de ferramenta é chamada, a execução de código pausa e a API retorna um bloco tool_use
4. Você fornece o resultado da ferramenta, e a execução de código continua (resultados intermediários não são carregados na janela de contexto do Claude)
5. Uma vez que toda a execução de código é concluída, o Claude recebe a saída final e continua trabalhando na tarefa

Essa abordagem é particularmente útil para:

• Processamento de grandes volumes de dados: Filtre ou agregue resultados de ferramentas antes que eles cheguem ao contexto do Claude
• Fluxos de trabalho em múltiplas etapas: Economize tokens e latência chamando ferramentas em série ou em um loop sem amostrar o Claude entre chamadas de ferramentas
• Lógica condicional: Tome decisões com base em resultados intermediários de ferramentas

Conceitos principais

O campo allowed_callers

O campo allowed_callers especifica quais contextos podem invocar uma ferramenta:

{
  "name": "query_database",
  "description": "Execute a SQL query against the database",
  "input_schema": {
    // ...
  },
  "allowed_callers": ["code_execution_20260120"]
}

Valores possíveis:

• ["direct"] - Somente o Claude pode chamar esta ferramenta diretamente (padrão se omitido)
• ["code_execution_20260120"] - Somente chamável de dentro da execução de código
• ["direct", "code_execution_20260120"] - Chamável tanto diretamente quanto a partir da execução de código

O campo caller nas respostas

Cada bloco de uso de ferramenta inclui um campo caller indicando como foi invocado:

Invocação direta (uso tradicional de ferramentas):

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": { "type": "direct" }
}

Invocação programática:

{
  "type": "tool_use",
  "id": "toolu_xyz789",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

O tool_id referencia a ferramenta de execução de código que fez a chamada programática.

Ciclo de vida do contêiner

A chamada programática de ferramentas usa os mesmos contêineres que a execução de código:

• Criação do contêiner: Um novo contêiner é criado para cada sessão, a menos que você reutilize um existente
• Expiração: Os contêineres têm um tempo de vida máximo de 30 dias e são limpos após 4,5 minutos de tempo ocioso
• ID do contêiner: Retornado nas respostas via campo container
• Reutilização: Passe o ID do contêiner para manter o estado entre requisições

Exemplo de fluxo de trabalho

Veja como funciona um fluxo completo de chamada programática de ferramentas:

Etapa 1: Requisição inicial

Envie uma requisição com execução de código e uma ferramenta que permite chamada programática. Para habilitar a chamada programática, adicione o campo allowed_callers à definição da sua ferramenta.

A forma da requisição é idêntica ao exemplo de Início rápido: inclua code_execution na sua lista de ferramentas, adicione allowed_callers: ["code_execution_20260120"] a qualquer ferramenta que você queira que o Claude invoque a partir do código, e envie sua mensagem de usuário.

Etapa 2: Resposta da API com chamada de ferramenta

O Claude escreve código que chama sua ferramenta. A API pausa e retorna:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll query the purchase history and analyze the results."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "code_execution",
      "input": {
        "code": "results = await query_database('<sql>')\ntop_customers = sorted(results, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
      }
    },
    {
      "type": "tool_use",
      "id": "toolu_def456",
      "name": "query_database",
      "input": { "sql": "<sql>" },
      "caller": {
        "type": "code_execution_20260120",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2025-01-15T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Etapa 3: Fornecer resultado da ferramenta

Inclua o histórico completo da conversa mais o resultado da sua ferramenta:

Etapa 4: Próxima chamada de ferramenta ou conclusão

A execução do código continua e processa os resultados. Se chamadas de ferramentas adicionais forem necessárias, repita a Etapa 3 até que todas as chamadas de ferramentas sejam satisfeitas.

Etapa 5: Resposta final

Assim que a execução do código for concluída, Claude fornece a resposta final:

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers by revenue:\n1. Customer C1: $45,000\n2. Customer C2: $38,000\n3. Customer C5: $32,000\n4. Customer C8: $28,500\n5. Customer C3: $24,000",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    },
    {
      "type": "text",
      "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
    }
  ],
  "stop_reason": "end_turn"
}

Padrões avançados

Processamento em lote com loops

Claude pode escrever código que processa múltiplos itens de forma eficiente:

async def _claude_code():
    regions = ["West", "East", "Central", "North", "South"]
    results = {}
    for region in regions:
        data = await query_database(f"<sql for {region}>")
        results[region] = sum(row["revenue"] for row in data)

    # Process results programmatically
    top_region = max(results.items(), key=lambda x: x[1])
    print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

Este padrão:

• Reduz as idas e vindas do modelo de N (uma por região) para 1
• Processa grandes conjuntos de resultados programaticamente antes de retornar para Claude
• Economiza tokens retornando apenas conclusões agregadas em vez de dados brutos

Encerramento antecipado

Claude pode parar o processamento assim que os critérios de sucesso forem atendidos:

async def _claude_code():
    endpoints = ["us-east", "eu-west", "apac"]
    for endpoint in endpoints:
        status = await check_health(endpoint)
        if status == "healthy":
            print(f"Found healthy endpoint: {endpoint}")
            break  # Stop early, don't check remaining

Seleção condicional de ferramentas

async def _claude_code():
    file_info = await get_file_info(path)
    if file_info["size"] < 10000:
        content = await read_full_file(path)
    else:
        content = await read_file_summary(path)
    print(content)

Filtragem de dados

async def _claude_code():
    logs = await fetch_logs(server_id)
    errors = [log for log in logs if "ERROR" in log]
    print(f"Found {len(errors)} errors")
    for error in errors[-10:]:  # Only return last 10 errors
        print(error)

Formato de resposta

Chamada de ferramenta programática

Quando a execução do código chama uma ferramenta:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_xyz789"
  }
}

Tratamento do resultado da ferramenta

O resultado da sua ferramenta é passado de volta para o código em execução:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}

Conclusão da execução do código

Quando todas as chamadas de ferramentas são satisfeitas e o código é concluído:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_xyz789",
  "content": {
    "type": "code_execution_result",
    "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}

Tratamento de erros

Erros comuns

Expiração do contêiner durante chamada de ferramenta

Se sua ferramenta demorar muito para responder, a execução do código recebe um TimeoutError. Claude vê isso no stderr e normalmente tenta novamente:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out.",
    "return_code": 0,
    "content": []
  }
}

Para evitar timeouts:

• Monitore o campo expires_at nas respostas
• Implemente timeouts para a execução da sua ferramenta
• Considere dividir operações longas em partes menores

Erros de execução de ferramentas

Se sua ferramenta retornar um erro:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

O código de Claude recebe esse erro e pode tratá-lo adequadamente.

Restrições e limitações

Incompatibilidades de recursos

• Saídas estruturadas: Ferramentas com strict: true não são suportadas com chamada programática
• Escolha de ferramenta: Você não pode forçar a chamada programática de uma ferramenta específica via tool_choice
• Uso paralelo de ferramentas: disable_parallel_tool_use: true não é suportado com chamada programática

Restrições de ferramentas

As seguintes ferramentas atualmente não podem ser chamadas programaticamente, mas o suporte pode ser adicionado em versões futuras:

• Ferramentas fornecidas por um conector MCP

Restrições de formatação de mensagens

Ao responder a chamadas de ferramentas programáticas, há requisitos estritos de formatação:

Respostas somente com resultado de ferramenta: Se houver chamadas de ferramentas programáticas pendentes aguardando resultados, sua mensagem de resposta deve conter apenas blocos tool_result. Você não pode incluir nenhum conteúdo de texto, mesmo após os resultados das ferramentas.

Inválido - Não é possível incluir texto ao responder a chamadas de ferramentas programáticas:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    },
    { "type": "text", "text": "What should I do next?" }
  ]
}

Válido - Apenas resultados de ferramentas ao responder a chamadas de ferramentas programáticas:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

Essa restrição se aplica apenas ao responder a chamadas de ferramentas programáticas (de execução de código). Para chamadas de ferramentas regulares do lado do cliente, você pode incluir conteúdo de texto após os resultados das ferramentas.

Limites de taxa

As chamadas de ferramentas programáticas estão sujeitas aos mesmos limites de taxa que as chamadas de ferramentas regulares. Cada chamada de ferramenta da execução de código conta como uma invocação separada.

Validar resultados de ferramentas antes do uso

Ao implementar ferramentas definidas pelo usuário que serão chamadas programaticamente:

• Os resultados das ferramentas são retornados como strings: Eles podem conter qualquer conteúdo, incluindo trechos de código ou comandos executáveis que podem ser processados pelo ambiente de execução.
• Valide resultados de ferramentas externas: Se sua ferramenta retornar dados de fontes externas ou aceitar entrada do usuário, esteja ciente dos riscos de injeção de código se a saída for interpretada ou executada como código.

Eficiência de tokens

A chamada programática de ferramentas pode reduzir significativamente o consumo de tokens:

• Os resultados de ferramentas de chamadas programáticas não são adicionados ao contexto de Claude - apenas a saída final do código é
• O processamento intermediário acontece no código - filtragem, agregação, etc. não consomem tokens do modelo
• Múltiplas chamadas de ferramentas em uma execução de código - reduz a sobrecarga em comparação com turnos de modelo separados

Por exemplo, chamar 10 ferramentas diretamente usa aproximadamente 10x os tokens de chamá-las programaticamente e retornar um resumo.

Uso e preços

A chamada programática de ferramentas usa os mesmos preços que a execução de código. Consulte os preços de execução de código para detalhes.

Melhores práticas

Design de ferramentas

• Forneça descrições detalhadas de saída: Como Claude desserializa os resultados das ferramentas no código, documente claramente o formato (estrutura JSON, tipos de campos, etc.)
• Retorne dados estruturados: JSON ou outros formatos facilmente analisáveis funcionam melhor para processamento programático
• Mantenha as respostas concisas: Retorne apenas os dados necessários para minimizar a sobrecarga de processamento

Quando usar chamada programática

Bons casos de uso:

• Processamento de grandes conjuntos de dados onde você precisa apenas de agregados ou resumos
• Fluxos de trabalho de múltiplas etapas com 3 ou mais chamadas de ferramentas dependentes
• Operações que requerem filtragem, classificação ou transformação de resultados de ferramentas
• Tarefas onde dados intermediários não devem influenciar o raciocínio de Claude
• Operações paralelas em muitos itens (por exemplo, verificar 50 endpoints)

Casos de uso menos ideais:

• Chamadas únicas de ferramentas com respostas simples
• Ferramentas que precisam de feedback imediato do usuário
• Operações muito rápidas onde a sobrecarga de execução de código superaria o benefício

Otimização de desempenho

• Reutilize contêineres ao fazer múltiplas solicitações relacionadas para manter o estado
• Agrupe operações semelhantes em uma única execução de código quando possível

Solução de problemas

Problemas comuns

Erro "Tool not allowed"

• Verifique se a definição da sua ferramenta inclui "allowed_callers": ["code_execution_20260120"]

Expiração do contêiner

• Certifique-se de responder às chamadas de ferramentas antes que o contêiner fique inativo (4,5 minutos de inatividade; máximo absoluto de 30 dias)
• Monitore o campo expires_at nas respostas
• Considere implementar execução de ferramentas mais rápida

Resultado da ferramenta não analisado corretamente

• Certifique-se de que sua ferramenta retorna dados em string que Claude pode desserializar
• Forneça documentação clara do formato de saída na descrição da sua ferramenta

Dicas de depuração

1. Registre todas as chamadas de ferramentas e resultados para rastrear o fluxo
2. Verifique o campo caller para confirmar a invocação programática
3. Monitore os IDs dos contêineres para garantir a reutilização adequada
4. Teste as ferramentas independentemente antes de habilitar a chamada programática

Por que a chamada programática de ferramentas funciona

O treinamento de Claude inclui ampla exposição a código, tornando-o eficaz no raciocínio e encadeamento de chamadas de funções. Quando as ferramentas são apresentadas como funções chamáveis dentro de um ambiente de execução de código, Claude pode aproveitar essa força para:

• Raciocinar naturalmente sobre composição de ferramentas: Encadear operações e lidar com dependências tão naturalmente quanto escrever qualquer código Python
• Processar grandes resultados de forma eficiente: Filtrar grandes saídas de ferramentas, extrair apenas dados relevantes ou escrever resultados intermediários em arquivos antes de retornar resumos para a janela de contexto
• Reduzir a latência significativamente: Eliminar a sobrecarga de re-amostrar Claude entre cada chamada de ferramenta em fluxos de trabalho de múltiplas etapas

Essa abordagem permite fluxos de trabalho que seriam impraticáveis com o uso tradicional de ferramentas (como processar arquivos com mais de 1 milhão de tokens), permitindo que Claude trabalhe com dados programaticamente em vez de carregar tudo no contexto da conversa.

Implementações alternativas

A chamada programática de ferramentas é um padrão generalizável que pode ser implementado fora da execução de código gerenciada da Anthropic. Aqui está uma visão geral das abordagens:

Execução direta no lado do cliente

Forneça a Claude uma ferramenta de execução de código e descreva quais funções estão disponíveis nesse ambiente. Quando Claude invoca a ferramenta com código, sua aplicação o executa localmente onde essas funções estão definidas.

Vantagens:

• Simples de implementar com mínima reestruturação
• Controle total sobre o ambiente e as instruções

Desvantagens:

• Executa código não confiável fora de um sandbox
• As invocações de ferramentas podem ser vetores para injeção de código

Use quando: Sua aplicação pode executar código arbitrário com segurança, você quer uma solução simples e a oferta gerenciada da Anthropic não atende às suas necessidades.

Execução em sandbox autogerenciada

Mesma abordagem da perspectiva de Claude, mas o código é executado em um contêiner em sandbox com restrições de segurança (por exemplo, sem saída de rede). Se suas ferramentas precisarem de recursos externos, você precisará de um protocolo para executar chamadas de ferramentas fora do sandbox.

Vantagens:

• Chamada programática de ferramentas segura em sua própria infraestrutura
• Controle total sobre o ambiente de execução

Desvantagens:

• Complexo de construir e manter
• Requer gerenciamento tanto de infraestrutura quanto de comunicação entre processos

Use quando: A segurança é crítica e a solução gerenciada da Anthropic não atende aos seus requisitos.

Execução gerenciada pela Anthropic

A chamada programática de ferramentas da Anthropic é uma versão gerenciada da execução em sandbox com um ambiente Python opinativo ajustado para Claude. A Anthropic lida com o gerenciamento de contêineres, execução de código e comunicação segura de invocação de ferramentas.

Vantagens:

• Seguro e protegido por padrão
• Fácil de habilitar com configuração mínima
• Ambiente e instruções otimizados para Claude

Considere usar a solução gerenciada da Anthropic se você estiver usando a API Claude.

Retenção de dados

A chamada programática de ferramentas é construída sobre a infraestrutura de execução de código e usa os mesmos contêineres sandbox. Os dados do contêiner, incluindo artefatos e saídas de execução, são retidos por até 30 dias.

Para elegibilidade de ZDR em todos os recursos, consulte API e retenção de dados.

Recursos relacionados

Entenda os fundamentos do uso de ferramentas com Claude.