---
title: Chamada programática de ferramentas
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling
description: Permita que Claude chame suas ferramentas a partir de código no contêiner de execução de código, reduzindo as idas e voltas ao modelo e o uso de tokens em fluxos de trabalho com várias ferramentas.
featureMetadata:
status: ga
zdr: not-eligible
supportedModels:
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-opus-5-5
- claude-opus-5
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-opus-4-5-20251101
- claude-sonnet-5-5
- claude-sonnet-5
- claude-sonnet-4-6
- claude-sonnet-4-5-20250929
- claude-haiku-5-5
supportedPlatforms:
Claude API: ga
Claude Platform on AWS: ga
Microsoft Foundry:
availability: ga
note: No [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry), a chamada programática de ferramentas requer uma [implantação Hosted on Anthropic](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
details:
- A chamada programática de ferramentas requer a ferramenta de execução de código com a [versão da ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#tool-versions) `code_execution_20260120` ou posterior.
- Claude Haiku 4.5 aceita as versões da ferramenta `code_execution_20260120` e posteriores, mas não oferece suporte à 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool), 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](https://arxiv.org/abs/2504.12516) e [DeepSearchQA](https://github.com/google-deepmind/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](https://claude.com/blog/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.
Para uma análise mais aprofundada dos custos de inferência e de contexto que a chamada programática de ferramentas resolve, consulte [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use).
A chamada programática de ferramentas requer a [ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool) 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](https://platform.claude.com/docs/pt-BR/models/overview#using-the-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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling#the-allowed-callers-field)):
```bash cURL
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"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"]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
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
YAML
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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" as const,
properties: {
sql: {
type: "string",
description: "SQL query to execute"
}
},
required: ["sql"]
},
allowed_callers: ["code_execution_20260120"]
}
]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Messages = [
new() {
Role = Role.User,
Content = "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue"
}
],
Tools = [
new CodeExecutionTool20260120(),
new ToolUnion(new Tool()
{
Name = "query_database",
Description = "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["sql"] = JsonSerializer.SerializeToElement(new { type = "string", description = "SQL query to execute" }),
},
Required = ["sql"],
},
AllowedCallers = ["code_execution_20260120"]
}),
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue")),
},
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
{OfTool: &anthropic.ToolParam{
Name: "query_database",
Description: anthropic.String("Execute a SQL query against the sales database. Returns a list of rows as JSON objects."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"sql": map[string]any{
"type": "string",
"description": "SQL query to execute",
},
},
Required: []string{"sql"},
},
AllowedCallers: []string{"code_execution_20260120"},
}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.CodeExecutionTool20260120;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.addUserMessage("Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue")
.addTool(CodeExecutionTool20260120.builder().build())
.addTool(Tool.builder()
.name("query_database")
.description("Execute a SQL query against the sales database. Returns a list of rows as JSON objects.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"sql", Map.of(
"type", "string",
"description", "SQL query to execute"
)
)))
.putAdditionalProperty("required", JsonValue.from(List.of("sql")))
.build())
.allowedCallers(List.of(Tool.AllowedCaller.of("code_execution_20260120")))
.build())
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue'],
],
model: 'claude-opus-5-5',
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'],
],
],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
message = 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"]
}
]
)
puts message
```
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling#step-3-provide-tool-result) 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
As ferramentas que permitem um chamador de execução de código são expostas ao código de Claude como funções Python assíncronas, de modo que Claude pode executá-las em paralelo com `asyncio.gather`. Cada função recebe um único dict de argumentos e retorna uma string: o texto do `tool_result` que você envia de volta. O código de Claude aguarda essas funções com `await` de nível superior e analisa os resultados de que precisa como dados estruturados, por exemplo `rows = json.loads(await query_database({"sql": ""}))`.
## Conceitos principais
### O campo `allowed_callers`
O campo `allowed_callers` especifica quais contextos podem invocar uma ferramenta:
```json
{
"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.
Escolha `["direct"]` ou `["code_execution_20260120"]` para cada ferramenta em vez de habilitar ambos, pois isso fornece uma orientação mais clara a Claude sobre a melhor forma de usar a ferramenta.
`allowed_callers` controla como a ferramenta é apresentada a Claude e é validado em relação a `tool_choice`, mas não é um bloqueio rígido no nível da API contra invocação direta. Claude é fortemente orientado a respeitá-lo, mas seu cliente ainda deve estar preparado para lidar com um `tool_use` direto para qualquer ferramenta que ele defina. Não confie em `allowed_callers` como uma fronteira de segurança.
### 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):**
```json
{
"type": "tool_use",
"id": "toolu_abc123",
"name": "query_database",
"input": { "sql": "" },
"caller": { "type": "direct" }
}
```
**Invocação programática:**
```json
{
"type": "tool_use",
"id": "toolu_xyz789",
"name": "query_database",
"input": { "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.
Enquanto o código de Claude está aguardando um resultado de ferramenta programático, a chamada pendente expira após cerca de 4 minutos e gera um `TimeoutError` dentro do código. Retorne cada resultado de ferramenta bem antes do timestamp `expires_at` na resposta pausada. Consulte [Expiração do contêiner durante a chamada de ferramenta](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling#container-expiration-during-tool-call).
## 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.
Forneça descrições detalhadas do formato de saída da sua ferramenta na descrição da ferramenta. Se você especificar que a ferramenta retorna JSON, Claude tentará desserializar e processar o resultado em código. Quanto mais detalhes você fornecer sobre o esquema de saída, melhor Claude poderá lidar com a resposta programaticamente.
O formato da requisição é idêntico ao exemplo do [Início rápido](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling#quick-start): 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:
```json Output
{
"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': ''}))\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": "" },
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling#message-formatting-restrictions).
* 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.
```bash cURL
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "claude-opus-5-5",
"max_tokens": 4096,
"container": "container_xyz789",
"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": ""},
"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": [
{
"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"]
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 4096
container: container_xyz789
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: ""
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
YAML
```
```python Python
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": ""},
"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)
```
```typescript TypeScript
const response = await 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: "" },
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" as const,
properties: {
sql: {
type: "string",
description: "SQL query to execute"
}
},
required: ["sql"]
},
allowed_callers: ["code_execution_20260120"]
}
]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 4096,
Container = "container_xyz789",
Messages =
[
new()
{
Role = Role.User,
Content = "Query customer purchase history from the last quarter and identify our top 5 customers by revenue"
},
new()
{
Role = Role.Assistant,
Content = new ContentBlock[]
{
new TextBlock { Text = "I'll query the purchase history and analyze the results." },
new ServerToolUseBlock
{
Id = "srvtoolu_abc123",
Name = "code_execution",
Input = new { code = "..." }
},
new ToolUseBlock
{
Id = "toolu_def456",
Name = "query_database",
Input = new { sql = "" },
Caller = new ToolCaller
{
Type = "code_execution_20260120",
ToolId = "srvtoolu_abc123"
}
}
}
},
new()
{
Role = Role.User,
Content = new ContentBlockParam[]
{
new ToolResultBlockParam
{
ToolUseID = "toolu_def456",
Content = "[{\"customer_id\": \"C1\", \"revenue\": 45000}, {\"customer_id\": \"C2\", \"revenue\": 38000}, ...]"
}
}
}
],
// Mesmo array de ferramentas da requisição original
Tools = [
new CodeExecutionTool20260120(),
new ToolUnion(new Tool()
{
Name = "query_database",
Description = "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["sql"] = JsonSerializer.SerializeToElement(new { type = "string", description = "SQL query to execute" }),
},
Required = ["sql"],
},
AllowedCallers = ["code_execution_20260120"]
}),
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 4096,
Container: anthropic.MessageCreateParamsContainerUnion{
OfString: anthropic.String("container_xyz789"),
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Query customer purchase history from the last quarter and identify our top 5 customers by revenue")),
{
Role: anthropic.MessageParamRoleAssistant,
Content: []anthropic.ContentBlockParamUnion{
anthropic.NewTextBlock("I'll query the purchase history and analyze the results."),
{OfServerToolUse: &anthropic.ServerToolUseBlockParam{
ID: "srvtoolu_abc123",
Name: anthropic.ServerToolUseBlockParamNameCodeExecution,
Input: map[string]any{"code": "..."},
}},
{OfToolUse: &anthropic.ToolUseBlockParam{
ID: "toolu_def456",
Name: "query_database",
Input: map[string]any{"sql": ""},
Caller: anthropic.ServerToolUseBlockParamCallerUnion{
OfCodeExecution20260120: &anthropic.ServerToolCaller20260120Param{
ToolID: "srvtoolu_abc123",
},
},
}},
},
},
{
Role: anthropic.MessageParamRoleUser,
Content: []anthropic.ContentBlockParamUnion{
{OfToolResult: &anthropic.ToolResultBlockParam{
ToolUseID: "toolu_def456",
Content: []anthropic.ToolResultBlockParamContentUnion{
{OfText: &anthropic.TextBlockParam{
Text: `[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]`,
}},
},
}},
},
},
},
// Mesmo array de tools da requisição original
Tools: []anthropic.ToolUnionParam{
{OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}},
{OfTool: &anthropic.ToolParam{
Name: "query_database",
Description: anthropic.String("Execute a SQL query against the sales database. Returns a list of rows as JSON objects."),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"sql": map[string]any{
"type": "string",
"description": "SQL query to execute",
},
},
Required: []string{"sql"},
},
AllowedCallers: []string{"code_execution_20260120"},
}},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.CodeExecutionTool20260120;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(4096L)
.container("container_xyz789")
.addUserMessage("Query customer purchase history from the last quarter and identify our top 5 customers by revenue")
.addAssistantMessageOfBlockParams(List.of(
ContentBlockParam.ofText(
TextBlockParam.builder()
.text("I'll query the purchase history and analyze the results.")
.build()),
ContentBlockParam.ofServerToolUse(
ServerToolUseBlockParam.builder()
.id("srvtoolu_abc123")
.name("code_execution")
.input(JsonValue.from(Map.of("code", "...")))
.build()),
ContentBlockParam.ofToolUse(
ToolUseBlockParam.builder()
.id("toolu_def456")
.name("query_database")
.input(JsonValue.from(Map.of("sql", "")))
.codeExecution20260120Caller("srvtoolu_abc123")
.build())
))
.addUserMessageOfBlockParams(List.of(
ContentBlockParam.ofToolResult(
ToolResultBlockParam.builder()
.toolUseId("toolu_def456")
.content("[{\"customer_id\": \"C1\", \"revenue\": 45000}, {\"customer_id\": \"C2\", \"revenue\": 38000}, ...]")
.build())
))
// Mesmo array de ferramentas da requisição original
.addTool(CodeExecutionTool20260120.builder().build())
.addTool(Tool.builder()
.name("query_database")
.description("Execute a SQL query against the sales database. Returns a list of rows as JSON objects.")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"sql", Map.of(
"type", "string",
"description", "SQL query to execute"
)
)))
.putAdditionalProperty("required", JsonValue.from(List.of("sql")))
.build())
.allowedCallers(List.of(Tool.AllowedCaller.of("code_execution_20260120")))
.build())
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 4096,
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' => ''],
'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}, ...]',
],
],
],
],
model: 'claude-opus-5-5',
container: 'container_xyz789',
// 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'],
],
],
);
echo $message;
```
```ruby Ruby
require "anthropic"
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 4096,
container: "container_xyz789",
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: "" },
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"]
}
]
)
puts message
```
### 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:
```json Output
{
"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:
```python
regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
rows = json.loads(await query_database({"sql": f""}))
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:
```python
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
```python
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
```python
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:
```json
{
"type": "tool_use",
"id": "toolu_abc123",
"name": "query_database",
"input": { "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:
```json
{
"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:
```json
{
"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
| Erro | Onde aparece | Descrição | Solução |
| ------------------------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_tool_input` | `error_code` no bloco de erro `code_execution_tool_result` na resposta | Parâmetros inválidos foram passados para a ferramenta de execução de código | Consulte os [erros da ferramenta de execução de código](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#errors) |
| `invalid_request_error` (em `tool_choice`) | Resposta de erro HTTP 400 | `tool_choice` nomeia uma ferramenta cujo `allowed_callers` não inclui `"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 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:
```json
{
"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:
```json
{
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector)
* Os conjuntos de ferramentas de [uso de computador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/computer-use-tool) e [uso de navegador](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/browser-use-tool) (`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:
```json
{
"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:
```json
{
"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](https://arxiv.org/abs/2506.07982) (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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/programmatic-tool-calling#when-to-use-programmatic-calling).
## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/code-execution-tool#usage-and-pricing) para detalhes.
Contagem de tokens para chamadas programáticas de ferramentas: Os resultados de ferramentas de invocações programáticas não contam para o seu uso de tokens de entrada/saída. Apenas o resultado final da execução de código e a resposta de Claude contam.
## 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](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws) ou o [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry). No Microsoft Foundry, a chamada programática de ferramentas requer uma [implantação Hosted on Anthropic](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
## 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](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
## Próximos passos
Faça streaming de entradas de ferramentas sem buffer de JSON no lado do servidor para aplicações sensíveis à latência.
Execute código Python e bash em um contêiner isolado para analisar dados, gerar arquivos e iterar em soluções.
Conecte Claude a ferramentas e APIs externas. Veja onde as ferramentas são executadas, quando Claude as chama e qual ferramenta se adequa à sua tarefa.
Especifique esquemas de ferramentas, escreva descrições eficazes e controle quando Claude chama suas ferramentas.