Chamada programática de ferramentas

A chamada programática de ferramentas permite que Claude escreva código que chama suas ferramentas programaticamente dentro de um container de code execution (execução de código), em vez de exigir idas e voltas ao modelo para cada invocação de ferramenta. Isso reduz a 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 à 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 básicas de busca melhorou o desempenho em média 11% enquanto usava 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 idas e voltas 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 apenas algumas linhas.



Compatibilidade de modelos

A chamada programática de ferramentas requer code_execution_20260120 ou posterior, que é compatível com os 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 programática de ferramentas está disponível na API do Claude, no Claude Platform on AWS e no Microsoft Foundry. No Microsoft Foundry, a chamada programática de ferramentas requer uma implantação Hosted on Anthropic. Atualmente, não está disponível no Amazon Bedrock ou no Google Cloud.



Início rápido

Aqui está um exemplo em que Claude consulta programaticamente um banco de dados várias vezes e agrega os resultados:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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 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 esse código em um container isolado através 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 (resultados intermediários não são carregados na janela de contexto do Claude)
5. Assim que 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 do Claude
• Fluxos de trabalho em múltiplas etapas: Economize tokens e latência chamando ferramentas em série ou em loop sem amostrar Claude entre as chamadas de ferramenta
• 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 callers. Os blocos de resposta sempre marcam o caller 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 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, para que você possa associar cada tool_use programático à execução de código que o produziu.



Ciclo de vida do container

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

• Criação do container: Um novo container é criado para cada requisição, a menos que você reutilize um existente
• ID do container: Retornado nas respostas no campo container, junto com um timestamp expires_at
• Reutilização: Passe o ID do container de volta na próxima requisição para manter o estado. Enquanto uma chamada programática de ferramenta está aguardando seu resultado, o ID do container é 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 container. Containers ociosos são atualmente recuperados após cerca de 5 minutos, e nenhum container 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 permite 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 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 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 são importantes 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 ferramenta pendentes mas nenhum ID de container.
• 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-4-8",
    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 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 diferenciar os dois casos: uma resposta que pausa aguardando 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

Assim que 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)

# Processe os 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 idas e voltas ao modelo de N (uma por região) para 1
• Processa grandes conjuntos de resultados programaticamente antes de retornar ao 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:

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 de 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 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 do container durante 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 do 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 da sua ferramenta
• Considere dividir operações longas em partes 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 do 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 compatíveis com chamada programática
• Tool choice: Você não pode forçar a chamada programática de uma ferramenta específica através de tool_choice
• Uso paralelo de ferramentas: disable_parallel_tool_use: true não é compatível 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 ferramenta.

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

• Mantenha a ferramenta apenas como 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 {"type": "object"} simples 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



Restrições de formatação de mensagens

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

Respostas apenas com resultado de ferramenta: 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 de ferramenta.

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 ferramenta 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 ferramenta programáticas (execução de código). Para chamadas de ferramenta regulares do lado do cliente, você pode incluir conteúdo de texto após os resultados de ferramenta.

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. Tipos de bloco de conteúdo de imagem, documento e outros são rejeitados.



Limites de taxa

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



Valide os resultados de ferramentas antes de usar

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

• Resultados de 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 se a saída for 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:

• Resultados de ferramentas de chamadas programáticas não são adicionados ao contexto do 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 ferramenta 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 companhia aérea, varejo e telecomunicações), onde cada turno faz uma ou duas chamadas sequenciais de ferramenta, a chamada programática de ferramentas deixou 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 veem economias típicas de tokens de 20% a 40% com a chamada programática de ferramentas habilitada.

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



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 resultados de 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 chamada programática

A chamada programática de ferramentas troca uma pequena sobrecarga fixa (inicialização do container, geração de script) por grandes economias em tokens de resultado de ferramenta e idas e voltas ao modelo. Se essa troca compensa depende do formato da carga de trabalho.

Bom ajuste:

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

Ajuste fraco:

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

Se 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 containers ao fazer múltiplas requisiçõ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

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 container

• Responda a cada chamada programática de ferramenta bem antes do timestamp expires_at da resposta pausada. O código do Claude para de aguardar um resultado após cerca de 4 minutos, e containers ociosos são atualmente recuperados após cerca de 5 minutos.
• Considere implementar execução de ferramenta mais rápida

Resultado de 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 e resultados de ferramentas para rastrear o fluxo
2. Verifique o campo caller para confirmar a invocação programática
3. Monitore os IDs de container 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

Claude é treinado em grandes quantidades de código, então 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 idas e voltas ao modelo
• Processamento de resultados: O código do 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 ferramenta 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 em sua própria infraestrutura. Veja como as abordagens se comparam:



Execução direta do lado do cliente

Forneça ao 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 um sandbox
• 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 do Claude, mas o código é executado em um container isolado 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 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 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 containers, execução de código e comunicação segura de invocação de ferramentas.

Vantagens:

• Seguro por padrão
• Habilitado com uma definição de ferramenta, sem infraestrutura para executar
• Ambiente e instruções otimizados para Claude

Considere usar a solução gerenciada da Anthropic se você estiver usando a API do Claude, o 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 containers de sandbox. Os dados do container, incluindo artefatos de execução e saídas, são retidos por até 30 dias.

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



Próximos passos