Chamada programática de ferramentas

A "programmatic tool calling" (chamada programática de ferramentas) 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 pelo modelo para cada invocação de ferramenta. Isso reduz a "latency" (latência) em fluxos de trabalho com múltiplas ferramentas e diminui o consumo de tokens ao permitir que Claude filtre ou processe dados antes que eles cheguem à "context window" (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 a chamada programática de ferramentas sobre ferramentas básicas de busca melhorou o desempenho em uma média de 11%, usando 24% menos tokens de entrada (consulte Improved web search with dynamic filtering).

Considere verificar a conformidade orçamentária de 20 funcionários: a abordagem tradicional requer 20 viagens de ida e volta separadas ao modelo, trazendo milhares de itens de linha 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 Claude precisa analisar de centenas de kilobytes para um punhado de linhas.

A chamada programática de ferramentas requer a ferramenta de execução de código com a versão da ferramenta code_execution_20260120 ou posterior. Para verificar se um modelo oferece suporte à chamada programática de ferramentas antes de enviar uma requisição, leia o valor de capabilities.code_execution.supported do modelo na Models API. Usando a Models API descreve o campo.

Início rápido

Aqui está um exemplo em que Claude consulta programaticamente um banco de dados várias vezes e agrega os resultados. Adicionar allowed_callers: ["code_execution_20260120"] a uma definição de ferramenta é o que torna essa ferramenta chamável de dentro da execução de código (consulte O campo allowed_callers):

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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)

A resposta para com stop_reason: "tool_use", um ID de container e um bloco tool_use para query_database cujo campo caller identifica a execução de código que o chamou. Retorne o resultado conforme mostrado na Etapa 3 do fluxo de trabalho de exemplo para que o código possa terminar.

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 Claude determina que essa ferramenta é necessária:

1. 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. Claude executa esse código em um contêiner isolado (sandbox) por meio da 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 (os resultados intermediários não são carregados na janela de contexto de Claude)
5. Quando toda a execução de código é concluída, 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 cheguem ao contexto de 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 as 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"] - Claude é orientado a chamar esta ferramenta diretamente (padrão se omitido)
• ["code_execution_20260120"] - Claude é orientado a chamar esta ferramenta apenas de dentro da execução de código
• ["direct", "code_execution_20260120"] - Claude pode chamar esta ferramenta diretamente ou de dentro da execução de código

Tanto "code_execution_20260120" quanto "code_execution_20260521" são aceitos em allowed_callers e são intercambiáveis: uma requisição usando qualquer uma das versões da ferramenta de execução de código satisfaz ferramentas que listam qualquer um dos chamadores. Os blocos de resposta sempre marcam o chamador como code_execution_20260120, independentemente de qual versão a requisição declarou.

O campo caller nas respostas

Todo bloco de uso de ferramentas inclui um campo caller indicando como ele foi invocado:

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

{
  "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 é o id do bloco server_tool_use de execução de código que fez a chamada, de modo que você pode associar cada tool_use programático à execução de código que o produziu.

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 requisição, a menos que você reutilize um existente
• ID do contêiner: Retornado nas respostas no campo container, junto com um timestamp expires_at
• Reutilização: Passe o ID do contêiner de volta na próxima requisição para manter o estado. Enquanto uma chamada programática de ferramenta estiver aguardando seu resultado, o ID do contêiner é obrigatório nessa requisição, não opcional: a API rejeita a requisição sem ele.
• Expiração: expires_at informa quanto tempo resta ao contêiner. Contêineres ociosos são atualmente recuperados após cerca de 5 minutos, e nenhum contêiner pode ser reutilizado mais de 30 dias após sua criação.

Fluxo de trabalho de exemplo

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 permita chamada programática. Para habilitar a chamada programática, adicione o campo allowed_callers à definição da sua ferramenta.

O formato da requisição é idêntico ao exemplo do 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 Claude invoque a partir do código e envie sua mensagem de usuário. As etapas restantes deste fluxo de trabalho usam a mensagem de usuário "Query customer purchase history from the last quarter and identify our top 5 customers by revenue".

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": "import json\n\nrows = json.loads(await query_database({'sql': '<sql>'}))\ntop_customers = sorted(rows, 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": "2026-01-20T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Etapa 3: Fornecer o resultado da ferramenta

Envie o histórico completo da conversa mais o resultado da sua ferramenta. Três detalhes importam nesta requisição:

• A mensagem de usuário que carrega seu resultado pode conter apenas blocos tool_result. Consulte Restrições de formatação de mensagens.
• Passe o ID do container da resposta pausada. A API rejeita uma continuação que tenha chamadas programáticas de ferramentas pendentes, mas nenhum ID de contêiner.
• Envie o mesmo array tools da requisição original. A ferramenta de execução de código ainda deve estar presente para que o código pausado seja retomado, e as ferramentas que você envia nesta requisição são as definições que Claude e o código em execução podem usar pelo restante do turno.

response = client.messages.create(
    model="claude-opus-5-5",
    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}, ...]',
                }
            ],
        },
    ],
    # Mesmo array de ferramentas da requisição original
    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)

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

O código retoma de onde pausou e processa seu resultado. Cada resposta de continuação ou pausa novamente com mais blocos tool_use programáticos, ou conclui a execução de código e permite que Claude continue o turno (Etapa 5). Verifique stop_reason e o caller de cada bloco tool_use para distinguir os dois casos: uma resposta que pausa para você tem stop_reason: "tool_use" e um bloco tool_use cujo caller nomeia uma versão de execução de código, e você repete a Etapa 3 com um tool_result para cada chamada programática pendente em uma única mensagem de usuário.

Etapa 5: Resposta final

Quando a execução de código é 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: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
        "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:

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    rows = json.loads(await query_database({"sql": f"<sql for {region}>"}))
    results[region] = sum(row["revenue"] for row in rows)

# Processar resultados programaticamente
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 viagens de ida e volta ao modelo de N (uma por região) para 1
• Processa grandes conjuntos de resultados programaticamente antes de retornar a Claude
• Economiza tokens ao retornar 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:

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

Seleção condicional de ferramentas

path = "/tmp/example.txt"
file_info = json.loads(await get_file_info({"path": path}))
if file_info["size"] < 10000:
    content = await read_full_file({"path": path})
else:
    content = await read_file_summary({"path": path})
print(content)

Filtragem de dados

server_id = "srv-01"
log_text = await fetch_logs({"server_id": server_id})
errors = [line for line in log_text.splitlines() if "ERROR" in line]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:  # Only return last 10 errors
    print(error)

Formato da resposta

Chamada programática de ferramenta

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 do resultado da ferramenta

O resultado da sua ferramenta é passado de volta ao 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 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 a chamada de ferramenta

Se o resultado da sua ferramenta não chegar em cerca de 4 minutos, a chamada pendente gera um TimeoutError dentro do código em execução de Claude. Claude vê o erro em stderr e normalmente tenta a chamada 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 (no response after 270s).",
    "return_code": 0,
    "content": []
  }
}

Para evitar timeouts:

• Monitore o campo expires_at nas respostas
• Implemente timeouts para a execução das suas ferramentas
• 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 por meio de tool_choice
• Uso paralelo de ferramentas: disable_parallel_tool_use: true não é suportado com chamada programática

Limitações do esquema de entrada

Ferramentas personalizadas cujo input_schema contém um $ref recursivo (um ciclo de referência, como um esquema que se refere a si mesmo) não podem ser habilitadas para chamada programática. Incluir uma versão da ferramenta de execução de código em allowed_callers para tal ferramenta faz com que a requisição falhe com um 400 invalid_request_error cuja mensagem contém Circular $ref detected. O mesmo esquema é aceito para chamada direta de ferramentas.

Para contornar isso, faça uma das seguintes opções:

• Mantenha a ferramenta apenas direta omitindo allowed_callers (ou definindo-o como ["direct"]). Outras ferramentas na mesma requisição ainda podem usar chamada programática.
• Remova o ciclo do esquema. Por exemplo, desenrole a recursão até uma profundidade fixa e descreva qualquer aninhamento mais profundo na description do nível mais interno, ou substitua a propriedade recursiva por um simples {"type": "object"} cuja description explique o formato esperado.

Restrições de ferramentas

As seguintes ferramentas não podem ser chamadas programaticamente:

• Ferramentas fornecidas por um conector MCP
• Os conjuntos de ferramentas de uso de computador e uso de navegador (computer_toolset_20260801 e browser_toolset_20260801), cujo campo allowed_callers aceita apenas "direct"

Restrições de formatação de mensagens

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

Respostas apenas com resultados de ferramentas: Se houver chamadas programáticas de ferramentas 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 programáticas de ferramentas:

{
  "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 programáticas de ferramentas:

{
  "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 (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.

Conteúdo de resultado de ferramenta apenas em texto: O content de cada tool_result que responde a uma chamada programática deve ser uma string ou blocos text. Imagens, documentos e outros tipos de blocos de conteúdo são rejeitados.

Limites de taxa

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

Valide os resultados das ferramentas antes de usar

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 retorna dados de fontes externas ou aceita entrada do usuário, esteja ciente dos riscos de injeção de código caso a saída seja interpretada ou executada como código.

Eficiência de tokens

A chamada programática de ferramentas reduz o consumo de tokens de três maneiras:

• 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 e outras transformações não consomem tokens do modelo
• Múltiplas chamadas de ferramentas em uma única execução de código - reduz a sobrecarga em comparação com turnos separados do modelo

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

Nas avaliações internas da Anthropic em um modelo Claude de produção:

• Em um benchmark de agente de gerenciamento de projetos com 75 ferramentas, habilitar a chamada programática de ferramentas reduziu os tokens de entrada cobrados em aproximadamente 38%, sem alteração na precisão das tarefas.
• No τ²-bench (domínios de companhias aéreas, varejo e telecomunicações), onde cada turno faz uma ou duas chamadas de ferramentas sequenciais, a chamada programática de ferramentas manteve as pontuações inalteradas e custou aproximadamente 8% a mais. Fluxos de trabalho sequenciais de chamada única não se beneficiam.
• No tráfego de produção da API, requisições cujo array tools contém de 10 a 49 definições de ferramentas apresentam economias típicas de tokens de 20% a 40% com a chamada programática de ferramentas habilitada.

As economias reais variam de acordo com o formato da carga de trabalho. Consulte Quando usar a chamada programática.

Uso e preços

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

Melhores práticas

Design de ferramentas

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

Quando usar a chamada programática

A chamada programática de ferramentas troca uma pequena sobrecarga fixa (inicialização do contêiner, geração do script) por grandes economias em tokens de resultados de ferramentas e viagens de ida e volta ao modelo. Se essa troca compensa depende do formato da carga de trabalho.

Boa adequação:

• Operações de fan-out ou paralelas em muitos itens (por exemplo, verificar 50 endpoints ou consultar 20 registros)
• Grandes resultados de ferramentas que podem ser filtrados, agregados ou resumidos antes de chegar ao contexto de Claude
• Busca e recuperação agêntica, onde consultas iterativas e filtragem de resultados dominam o fluxo de trabalho

Adequação fraca:

• Fluxos de trabalho estritamente sequenciais em que cada chamada depende de Claude raciocinar sobre o resultado anterior, porque o script não pode pular a viagem de ida e volta ao modelo nesse caso
• Um pequeno número de chamadas de ferramentas com respostas pequenas, especialmente no primeiro turno de uma conversa, onde a sobrecarga do contêiner e do script pode exceder as economias
• Ferramentas que exigem feedback imediato do usuário entre as chamadas

Se você não tiver certeza, meça os tokens de entrada cobrados com e sem allowed_callers em uma amostra representativa do seu tráfego antes de habilitá-lo amplamente.

Otimização de desempenho

• Reutilize contêineres ao fazer múltiplas requisiçõ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

invalid_request_error ao definir tool_choice

• tool_choice não pode nomear uma ferramenta cujo allowed_callers omite "direct". Adicione "direct" ao allowed_callers dessa ferramenta ou remova a ferramenta de tool_choice e deixe Claude invocá-la a partir do código.

Expiração do contêiner

• Responda a cada chamada programática de ferramenta bem antes do timestamp expires_at da resposta pausada. O código de Claude para de aguardar um resultado após cerca de 4 minutos, e contêineres ociosos são atualmente recuperados após cerca de 5 minutos.
• Considere implementar uma 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 possa 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 acompanhar 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 de forma independente antes de habilitar a chamada programática

Por que a chamada programática de ferramentas funciona

Claude é treinado em grandes quantidades de código, portanto apresentar ferramentas como funções Python chamáveis permite que ele use essa força:

• Composição de ferramentas: Chamadas encadeadas, loops e condicionais são fluxo de controle Python comum em vez de uma série de viagens de ida e volta ao modelo
• Processamento de resultados: O código de Claude filtra e agrega grandes saídas de ferramentas, ou as grava em arquivos, e apenas a saída final entra na janela de contexto
• Latência: O modelo não é reamostrado entre as chamadas de ferramentas dentro de uma execução de código

Implementações alternativas

A chamada programática de ferramentas é um padrão generalizável que também pode ser implementado na sua própria infraestrutura. Veja como as abordagens se comparam:

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 nesse ambiente. Quando Claude invoca a ferramenta com código, sua aplicação o executa localmente onde essas funções estão definidas.

Vantagens:

• Rearquitetura mínima da sua aplicação
• Controle total sobre o ambiente e as instruções

Desvantagens:

• Executa código não confiável fora de uma 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 a menor implementação possível 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 isolado com restrições de segurança (por exemplo, sem saída de rede). Se suas ferramentas exigirem recursos externos, você precisará de um protocolo para executar chamadas de ferramentas fora da sandbox.

Vantagens:

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

Desvantagens:

• Complexo de construir e manter
• Requer gerenciar tanto a infraestrutura quanto a 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 cuida do gerenciamento de contêineres, da execução de código e da comunicação segura de invocação de ferramentas.

Vantagens:

• Segura e protegida por padrão
• Habilitada com uma definição de ferramenta, sem infraestrutura para operar
• Ambiente e instruções otimizados para Claude

Considere usar a solução gerenciada da Anthropic se você estiver usando a Claude API, a Claude Platform on AWS ou o Microsoft Foundry. No Microsoft Foundry, a chamada programática de ferramentas requer uma implantação Hosted on Anthropic.

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 de sandbox. Os dados do contêiner, incluindo artefatos de execução e saídas, são retidos por até 30 dias.

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

Próximos passos

Compatibility