Chamada de ferramentas programática

A chamada de ferramentas programática permite que 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 através do 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 Claude filtre ou processe dados antes que atinjam a janela de contexto do modelo. Em benchmarks de busca agentic como BrowseComp e DeepSearchQA, que testam pesquisa na web em múltiplas etapas e recuperação de informações complexas, adicionar chamada de ferramentas programática em cima de ferramentas de busca básicas foi o fator-chave que desbloqueou completamente o desempenho do agente.

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

Compatibilidade de modelos

A chamada de ferramentas programática requer code_execution_20260120, que é suportada nos seguintes modelos:

Para a matriz completa de versões da ferramenta de execução de código, consulte a tabela de compatibilidade de modelos da ferramenta de execução de código. A chamada de ferramentas programática está disponível via Claude API e Microsoft Foundry.

Início rápido

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
        }
    ],
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

Como funciona a chamada de ferramentas programática

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

1. Claude escreve código Python que invoca a ferramenta como uma função, potencialmente incluindo múltiplas chamadas de ferramenta e lógica de pré/pós-processamento
2. Claude executa este código em um contêiner em sandbox 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. Quando toda a execução de código é concluída, Claude recebe a saída final e continua trabalhando na tarefa

Esta abordagem é particularmente útil para:

• Processamento de dados grandes: Filtre ou agregue resultados de ferramentas antes que atinjam o 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 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"] - Apenas Claude pode chamar esta ferramenta diretamente (padrão se omitido)
• ["code_execution_20260120"] - Apenas 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 em 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 de ferramentas programática usa os mesmos contêineres que a execução de código:

• Criação de 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 uma vida útil máxima de 30 dias e são limpos após 4,5 minutos de tempo ocioso
• ID do contêiner: Retornado em respostas via campo container
• Reutilização: Passe o ID do contêiner para manter o estado entre solicitações

Fluxo de trabalho de exemplo

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

Etapa 1: Solicitação inicial

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

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

Etapa 2: Resposta da API com chamada de ferramenta

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 seu resultado da ferramenta:

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    messages=[
        {
            "role": "user",
            "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
        },
        {
            "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": "..."},
                },
                {
                    "type": "tool_use",
                    "id": "toolu_def456",
                    "name": "query_database",
                    "input": {"sql": "<sql>"},
                    "caller": {
                        "type": "code_execution_20260120",
                        "tool_id": "srvtoolu_abc123",
                    },
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_def456",
                    "content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]',
                }
            ],
        },
    ],
    tools=[...],
)

print(response)

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

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

Etapa 5: Resposta final

Após a conclusão da execução de código, 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 rodadas do modelo de N (uma por região) para 1
• Processa conjuntos de resultados grandes de forma programática antes de retornar a Claude
• Economiza tokens retornando apenas conclusões agregadas em vez de dados brutos

Encerramento antecipado

Claude pode parar de processar 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 ferramenta

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 de 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 de resultado de ferramenta

Seu resultado de 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 de código

Quando todas as chamadas de ferramenta 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 de contêiner durante chamada de ferramenta

Se sua ferramenta levar muito tempo para responder, a execução de código recebe um TimeoutError. Claude vê isso em 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 sua execução de ferramenta
• Considere dividir operações longas em pedaços menores

Erros de execução de ferramenta

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 este erro e pode tratá-lo apropriadamente.

Restrições e limitações

Incompatibilidades de recursos

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

Restrições de ferramenta

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

• Ferramentas fornecidas por um conector MCP

Restrições de formatação de mensagem

Ao responder a chamadas de ferramenta programática, há requisitos rigorosos de formatação:

Respostas apenas de resultado de ferramenta: Se houver chamadas de ferramenta programática 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 da ferramenta.

Inválido - Não pode incluir texto ao responder a chamadas de ferramenta programática:

{
  "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 ferramenta ao responder a chamadas de ferramenta programática:

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

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

Limites de taxa

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

Validar resultados de ferramenta antes do uso

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

• Resultados de ferramenta são retornados como strings: Podem conter qualquer conteúdo, incluindo trechos de código ou comandos executáveis que podem ser processados pelo ambiente de execução.
• Validar resultados de ferramenta externa: Se sua ferramenta retorna dados de fontes externas ou aceita 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

Chamadas de ferramenta programática podem reduzir significativamente o consumo de tokens:

• Resultados de ferramenta de chamadas programáticas não são adicionados ao contexto de Claude - apenas a saída final do código é
• Processamento intermediário acontece em código - filtragem, agregação, etc. não consomem tokens do modelo
• Múltiplas chamadas de ferramenta em uma execução de código - reduz overhead comparado a turnos de modelo separados

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

Uso e preços

Chamadas de ferramenta programática usam o mesmo preço que execução de código. Veja preços de execução de código para detalhes.

Melhores práticas

Design de ferramenta

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

Quando usar chamadas programáticas

Bons casos de uso:

• Processamento de grandes conjuntos de dados onde você precisa apenas de agregados ou resumos
• Fluxos de trabalho com 3+ chamadas de ferramenta dependentes
• Operações que requerem filtragem, classificação ou transformação de resultados de ferramenta
• 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 de ferramenta única com respostas simples
• Ferramentas que precisam de feedback imediato do usuário
• Operações muito rápidas onde o overhead 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 similares em uma única execução de código quando possível

Solução de problemas

Problemas comuns

Erro "Tool not allowed"

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

Expiração de contêiner

• Certifique-se de responder a chamadas de ferramenta antes do contêiner ficar inativo (4,5 minutos de inatividade; máximo de 30 dias)
• Monitore o campo expires_at nas respostas
• Considere implementar execução de ferramenta mais rápida

Resultado de ferramenta não analisado corretamente

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

Dicas de depuração

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

Por que chamadas de ferramenta programática funcionam

O treinamento de Claude inclui exposição extensiva a código, tornando-o eficaz no raciocínio e encadeamento de chamadas de função. Quando 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 ferramenta: Encadear operações e lidar com dependências tão naturalmente quanto escrever qualquer código Python
• Processar resultados grandes de forma eficiente: Filtrar grandes saídas de ferramenta, extrair apenas dados relevantes, ou escrever resultados intermediários em arquivos antes de retornar resumos à janela de contexto
• Reduzir latência significativamente: Eliminar o overhead de re-amostragem de Claude entre cada chamada de ferramenta em fluxos de trabalho com múltiplas etapas

Esta abordagem permite fluxos de trabalho que seriam impraticáveis com uso de ferramenta tradicional (como processar arquivos com mais de 1M tokens) permitindo que Claude trabalhe com dados programaticamente em vez de carregar tudo na janela de conversa.

Implementações alternativas

Chamadas de ferramenta programática são 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 do lado do cliente

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

Vantagens:

• Simples de implementar com re-arquitetura mínima
• Controle total sobre o ambiente e instruções

Desvantagens:

• Executa código não confiável fora de uma sandbox
• Invocações de ferramenta podem ser vetores para injeção de código

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

Execução em sandbox auto-gerenciada

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 requerem recursos externos, você precisará de um protocolo para executar chamadas de ferramenta fora da sandbox.

Vantagens:

• Chamadas de ferramenta programática seguras em sua própria infraestrutura
• Controle total sobre o ambiente de execução

Desvantagens:

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

Use quando: Segurança é crítica e a solução gerenciada da Anthropic não se encaixa em seus requisitos.

Execução gerenciada pela Anthropic

Chamadas de ferramenta programática da Anthropic são uma versão gerenciada de execução em sandbox com um ambiente Python opinado ajustado para Claude. Anthropic gerencia gerenciamento de contêiner, execução de código e comunicação segura de invocação de ferramenta.

Vantagens:

• Seguro e seguro 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 estiver usando a Claude API.

Retenção de dados

Chamadas de ferramenta programática são construídas na infraestrutura de execução de código e usam os mesmos contêineres de sandbox. Dados de contêiner, incluindo artefatos de execução e saídas, são retidos por até 30 dias.

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

Recursos relacionados