Code execution tool

在沙箱容器中运行 Python 和 bash 代码,用于分析数据、生成文件和迭代解决方案。


Claude 可以在 API 对话中直接分析数据、创建可视化、执行复杂计算、运行系统命令、创建和编辑文件以及处理上传的文件。Code execution tool 允许 Claude 在安全的沙箱环境中运行 Bash 命令和操作文件,包括编写代码。

与 web search 或 web fetch 一起使用时,code execution 免费。 当你的请求中包含 web_search_20260209web_fetch_20260209 时,除了标准的输入和输出 token 费用外,code execution tool 调用不收取额外费用。不包含这些工具时,按标准 code execution 费率计费。

Code execution 是构建高性能 agent 的核心原语。它支持 web search 和 web fetch 工具中的动态过滤,允许 Claude 在结果到达上下文窗口之前处理它们,提高准确性并减少 token 消耗。

Note

请通过反馈表分享你对此功能的反馈。

Note

此功能符合零数据留存 (ZDR) 条件。数据按照该功能的标准留存策略保留。

模型兼容性

Code execution tool 可在以下模型上使用:

模型工具版本
Claude Opus 4.7 (claude-opus-4-7)code_execution_20250825, code_execution_20260120
Claude Opus 4.6 (claude-opus-4-6)code_execution_20250825, code_execution_20260120
Claude Sonnet 4.6 (claude-sonnet-4-6)code_execution_20250825, code_execution_20260120
Claude Opus 4.5 (claude-opus-4-5-20251101)code_execution_20250825, code_execution_20260120
Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)code_execution_20250825, code_execution_20260120
Claude Haiku 4.5 (claude-haiku-4-5-20251001)code_execution_20250825
Claude Opus 4.1 (claude-opus-4-1-20250805)code_execution_20250825
Claude Opus 4 (claude-opus-4-20250514) (已弃用)code_execution_20250825
Claude Sonnet 4 (claude-sonnet-4-20250514) (已弃用)code_execution_20250825
Note

code_execution_20250825 支持 Bash 命令和文件操作,可在上述所有模型上使用。code_execution_20260120 新增了 REPL 状态持久化和从沙箱内进行程序化工具调用的功能,仅在 Opus 4.5+ 和 Sonnet 4.5+ 上可用。如果你仍在使用旧版 code_execution_20250522(仅 Python),请参阅升级到最新工具版本了解迁移方法。

Warning

旧版工具不保证与较新模型向后兼容。请始终使用与你的模型版本对应的工具版本。

平台可用性

Code execution 可在以下平台使用:

Code execution 目前不在 Amazon Bedrock 或 Vertex AI 上提供。

Note

对于 Claude Mythos Preview,code execution 仅在 Claude API 和 Microsoft Foundry 上支持。在 Amazon Bedrock、Vertex AI 或 Claude Platform on AWS 上的 Mythos Preview 不可用。

快速开始

以下是一个让 Claude 执行计算的简单示例:

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-4-7",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
            }
        ],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'
ant messages create \
  --model claude-opus-4-7 \
  --max-tokens 4096 \
  --message '{role: user, content: "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"}' \
  --tool '{type: code_execution_20250825, name: code_execution}'
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response)
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  const response = await client.messages.create({
    model: "claude-opus-4-7",
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
      }
    ],
    tools: [
      {
        type: "code_execution_20250825",
        name: "code_execution"
      }
    ]
  });

  console.log(response);
}

main().catch(console.error);
using System;
using System.Threading.Tasks;
using Anthropic;
using Anthropic.Models.Messages;

class Program
{
    static async Task Main(string[] args)
    {
        AnthropicClient client = new();

        var parameters = new MessageCreateParams
        {
            Model = Model.ClaudeOpus4_7,
            MaxTokens = 4096,
            Messages = [
                new() {
                    Role = Role.User,
                    Content = "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
                }
            ],
            Tools = [new ToolUnion(new CodeExecutionTool20250825())]
        };

        var message = await client.Messages.Create(parameters);
        Console.WriteLine(message);
    }
}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 4096,
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]")),
		},
		Tools: []anthropic.BetaToolUnionParam{
			{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
		},
		Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.CodeExecutionTool20250825;

public class CodeExecution {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params = MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_4_7)
            .maxTokens(4096L)
            .addUserMessage("Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]")
            .addTool(CodeExecutionTool20250825.builder().build())
            .build();

        Message response = client.messages().create(params);
        System.out.println(response);
    }
}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$message = $client->messages->create(
    maxTokens: 4096,
    messages: [
        [
            'role' => 'user',
            'content' => 'Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]'
        ]
    ],
    model: 'claude-opus-4-7',
    tools: [
        [
            'type' => 'code_execution_20250825',
            'name' => 'code_execution'
        ]
    ],
);

echo $message;
require "anthropic"

client = Anthropic::Client.new

message = client.messages.create(
  model: "claude-opus-4-7",
  max_tokens: 4096,
  messages: [
    {
      role: "user",
      content: "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
    }
  ],
  tools: [
    {
      type: "code_execution_20250825",
      name: "code_execution"
    }
  ]
)

puts message

Code execution 的工作原理

当你将 code execution tool 添加到 API 请求时:

  1. Claude 评估代码执行是否有助于回答你的问题
  2. 该工具自动为 Claude 提供以下功能:
    • Bash 命令:执行 shell 命令进行系统操作和包管理
    • 文件操作:直接创建、查看和编辑文件,包括编写代码
  3. Claude 可以在单个请求中使用这些功能的任意组合
  4. 所有操作在安全的沙箱环境中运行
  5. Claude 提供结果以及生成的图表、计算或分析

将 code execution 与其他执行工具一起使用

当你将 code execution 与客户端提供的也运行代码的工具(如 bash tool 或自定义 REPL)一起提供时,Claude 运行在多计算机环境中。Code execution tool 在 Anthropic 的沙箱容器中运行,而你的客户端提供的工具在你控制的单独环境中运行。Claude 有时会混淆这些环境,尝试使用错误的工具或假设状态在它们之间共享。

为避免这种情况,请在系统提示中添加说明来澄清区别:

When multiple code execution environments are available, be aware that:
- Variables, files, and state do NOT persist between different execution environments
- Use the code_execution tool for general-purpose computation in Anthropic's sandboxed environment
- Use client-provided execution tools (e.g., bash) when you need access to the user's local system, files, or data
- If you need to pass results between environments, explicitly include outputs in subsequent tool calls rather than assuming shared state

这在将 code execution 与 web searchweb fetch 结合使用时尤其重要,因为它们会自动启用 code execution。如果你的应用程序已经提供了客户端 shell 工具,自动 code execution 会创建第二个执行环境,Claude 需要区分它们。

如何使用该工具

上传和分析你自己的文件

要分析你自己的数据文件(如 CSV、Excel 或图片),请通过 Files API 上传它们并在请求中引用:

Note

将 Files API 与 Code Execution 一起使用需要 Files API beta header:"anthropic-beta": "files-api-2025-04-14"

Python 环境可以处理通过 Files API 上传的各种文件类型,包括:

  • CSV
  • Excel (.xlsx, .xls)
  • JSON
  • XML
  • 图片 (JPEG, PNG, GIF, WebP)
  • 文本文件 (.txt, .md, .py 等)

上传和分析文件

  1. 上传你的文件 使用 Files API
  2. 在消息中引用文件 使用 container_upload 内容块
  3. 在 API 请求中包含 code execution tool
cd "$(mktemp -d)"
printf 'name,value\nfoo,1\nbar,2\n' > data.csv
# 首先,上传文件
curl https://api.anthropic.com/v1/files \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --form 'file=@"data.csv"'

# 然后将 file_id 与 code execution 一起使用
curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: files-api-2025-04-14" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-7",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": "file_abc123"}
            ]
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'
printf 'name,value\nfoo,1\nbar,2\n' > data.csv
# 上传文件
FILE_ID=$(ant beta:files upload \
  --file ./data.csv \
  --transform id --raw-output)

# 将 file_id 与 code execution 一起使用
ant beta:messages create \
  --beta files-api-2025-04-14 <<YAML
model: claude-opus-4-7
max_tokens: 4096
messages:
  - role: user
    content:
      - type: text
        text: Analyze this CSV data
      - type: container_upload
        file_id: $FILE_ID
tools:
  - type: code_execution_20250825
    name: code_execution
YAML
import anthropic

client = anthropic.Anthropic()

# 上传文件
file_object = client.beta.files.upload(
    file=open("data.csv", "rb"),
)

# 将 file_id 与 code execution 一起使用
response = client.beta.messages.create(
    model="claude-opus-4-7",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Analyze this CSV data"},
                {"type": "container_upload", "file_id": file_object.id},
            ],
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response)
import Anthropic, { toFile } from "@anthropic-ai/sdk";
import { createReadStream } from "fs";

const client = new Anthropic();

async function main() {
  // 上传文件
  const fileObject = await client.beta.files.upload({
    file: await toFile(createReadStream("data.csv"), undefined, { type: "text/csv" })
  });

  // 将 file_id 与 code execution 一起使用
  const response = await client.beta.messages.create({
    model: "claude-opus-4-7",
    betas: ["files-api-2025-04-14"],
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Analyze this CSV data" },
          { type: "container_upload", file_id: fileObject.id }
        ]
      }
    ],
    tools: [
      {
        type: "code_execution_20250825",
        name: "code_execution"
      }
    ]
  });

  console.log(response);
}

main().catch(console.error);
using Anthropic;
using Anthropic.Models.Beta.Files;
using Anthropic.Models.Beta.Messages;

class Program
{
    static async Task Main(string[] args)
    {
        AnthropicClient client = new();

        // 上传文件
        var fileObject = await client.Beta.Files.Upload(new FileUploadParams
        {
            File = File.OpenRead("data.csv")
        });

        // 将 file_id 与 code execution 一起使用
        var parameters = new MessageCreateParams
        {
            Model = Model.ClaudeOpus4_7,
            Betas = ["files-api-2025-04-14"],
            MaxTokens = 4096,
            Messages = [
                new()
                {
                    Role = Role.User,
                    Content = [
                        new() { Type = "text", Text = "Analyze this CSV data" },
                        new() { Type = "container_upload", FileId = fileObject.Id }
                    ]
                }
            ],
            Tools = [new ToolUnion(new CodeExecutionTool20250825())]
        };

        var response = await client.Beta.Messages.Create(parameters);
        Console.WriteLine(response);
    }
}
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/anthropics/anthropic-sdk-go"
)

func init() {
	os.WriteFile("data.csv", []byte("name,value\nalpha,1\nbeta,2\ngamma,3\n"), 0644)
}

func main() {
	client := anthropic.NewClient()

	// 上传文件
	file, err := os.Open("data.csv")
	if err != nil {
		log.Fatal(err)
	}
	defer file.Close()

	fileObject, err := client.Beta.Files.Upload(context.TODO(), anthropic.BetaFileUploadParams{
		File: file,
	})
	if err != nil {
		log.Fatal(err)
	}

	// 将 file_id 与 code execution 一起使用
	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 4096,
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(
				anthropic.NewBetaTextBlock("Analyze this CSV data"),
				anthropic.NewBetaContainerUploadBlock(fileObject.ID),
			),
		},
		Tools: []anthropic.BetaToolUnionParam{
			{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
		},
		Betas: []anthropic.AnthropicBeta{
			"code-execution-2025-08-25",
			anthropic.AnthropicBetaFilesAPI2025_04_14,
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response)
}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.beta.files.FileMetadata;
import com.anthropic.models.beta.files.FileUploadParams;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaTextBlockParam;
import com.anthropic.models.beta.messages.BetaContainerUploadBlockParam;
import java.nio.file.Paths;
import java.util.List;

public class CodeExecutionWithFiles {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        // 上传文件
        FileMetadata fileMetadata = client.beta().files().upload(
            FileUploadParams.builder()
                .file(Paths.get("data.csv"))
                .build()
        );

        // 将 file_id 与 code execution 一起使用
        BetaMessage response = client.beta().messages().create(
            MessageCreateParams.builder()
                .model("claude-opus-4-7")
                .addBeta("files-api-2025-04-14")
                .maxTokens(4096L)
                .addUserMessageOfBetaContentBlockParams(List.of(
                    BetaContentBlockParam.ofText(BetaTextBlockParam.builder()
                        .text("Analyze this CSV data")
                        .build()),
                    BetaContentBlockParam.ofContainerUpload(BetaContainerUploadBlockParam.builder()
                        .fileId(fileMetadata.id())
                        .build())
                ))
                .addTool(BetaCodeExecutionTool20250825.builder().build())
                .build()
        );

        System.out.println(response);
    }
}
<?php

use Anthropic\Client;
use Anthropic\Core\FileParam;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

// 上传文件
$fileObject = $client->beta->files->upload(
    file: FileParam::fromResource(fopen('data.csv', 'r')),
);

// 将 file_id 与 code execution 一起使用
$response = $client->beta->messages->create(
    maxTokens: 4096,
    messages: [
        [
            'role' => 'user',
            'content' => [
                ['type' => 'text', 'text' => 'Analyze this CSV data'],
                ['type' => 'container_upload', 'file_id' => $fileObject->id],
            ],
        ],
    ],
    model: 'claude-opus-4-7',
    betas: ['files-api-2025-04-14'],
    tools: [
        ['type' => 'code_execution_20250825', 'name' => 'code_execution'],
    ],
);

echo $response;
require "anthropic"

client = Anthropic::Client.new

# 上传文件
file_object = client.beta.files.upload(
  file: File.open("data.csv", "rb")
)

# 将 file_id 与 code execution 一起使用
response = client.beta.messages.create(
  model: "claude-opus-4-7",
  betas: ["files-api-2025-04-14"],
  max_tokens: 4096,
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Analyze this CSV data" },
        { type: "container_upload", file_id: file_object.id }
      ]
    }
  ],
  tools: [
    { type: "code_execution_20250825", name: "code_execution" }
  ]
)

puts response

检索生成的文件

当 Claude 在 code execution 期间创建文件时,你可以使用 Files API 检索这些文件:

# 请求创建文件的 code execution;从工具结果中提取 file_ids
TOOL_RESULT='content.#(type=="bash_code_execution_tool_result")#'
FILE_IDS=$(ant beta:messages create \
  --beta files-api-2025-04-14 \
  --transform "${TOOL_RESULT}.content.content|@flatten|#.file_id" \
  --format yaml \
    --model claude-opus-4-7 \
    --max-tokens 4096 \
    --message '{role: user, content: Create a matplotlib visualization and save it as output.png}' \
    --tool '{type: code_execution_20250825, name: code_execution}'
)

# 下载每个创建的文件
while IFS= read -r LINE; do
  [[ "$LINE" != "- "* ]] && continue
  FILE_ID="${LINE#- }"
  FILENAME=$(ant beta:files retrieve-metadata \
    --file-id "$FILE_ID" \
    --transform filename --raw-output)
  ant beta:files download \
    --file-id "$FILE_ID" \
    --output "$FILENAME" > /dev/null
  printf 'Downloaded: %s\n' "$FILENAME"
done <<< "$FILE_IDS"
from anthropic import Anthropic

# 初始化客户端
client = Anthropic()

# 请求创建文件的 code execution
response = client.beta.messages.create(
    model="claude-opus-4-7",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a matplotlib visualization and save it as output.png",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)


# 从响应中提取文件 ID
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == "bash_code_execution_tool_result":
            content_item = item.content
            if content_item.type == "bash_code_execution_result":
                # concrete-typed list: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# 下载创建的文件
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id)
    file_content = client.beta.files.download(file_id)
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")
import Anthropic from "@anthropic-ai/sdk";
import { writeFile } from "fs/promises";

const client = new Anthropic();

async function main() {
  // 请求创建文件的 code execution
  const response = await client.beta.messages.create({
    model: "claude-opus-4-7",
    betas: ["files-api-2025-04-14"],
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Create a matplotlib visualization and save it as output.png"
      }
    ],
    tools: [
      {
        type: "code_execution_20250825",
        name: "code_execution"
      }
    ]
  });

  // 从响应中提取文件 ID
  for (const item of response.content) {
    if (item.type === "bash_code_execution_tool_result") {
      const contentItem = item.content;
      if (contentItem.type === "bash_code_execution_result" && contentItem.content) {
        // concrete-typed list: BashCodeExecutionOutputBlock
        for (const file of contentItem.content) {
          const fileMetadata = await client.beta.files.retrieveMetadata(file.file_id);
          const fileResponse = await client.beta.files.download(file.file_id);
          const fileBytes = Buffer.from(await fileResponse.arrayBuffer());
          await writeFile(fileMetadata.filename, fileBytes);
          console.log(`Downloaded: ${fileMetadata.filename}`);
        }
      }
    }
  }
}

main().catch(console.error);
using System;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using System.Collections.Generic;
using Anthropic;
using Anthropic.Models.Messages;

public class Program
{
    static async Task Main(string[] args)
    {
        var client = new AnthropicClient();

        var parameters = new MessageCreateParams
        {
            Model = Model.ClaudeOpus4_7,
            MaxTokens = 4096,
            Messages = [
                new() {
                    Role = Role.User,
                    Content = "Create a matplotlib visualization and save it as output.png"
                }
            ],
            Tools = [new ToolUnion(new CodeExecutionTool20250825())]
        };

        var response = await client.Beta.Messages.Create(parameters, ["files-api-2025-04-14"]);

        var fileIds = ExtractFileIds(response);

        foreach (var fileId in fileIds)
        {
            var fileMetadata = await client.Beta.Files.RetrieveMetadata(fileId);
            var fileContent = await client.Beta.Files.Download(fileId);

            await File.WriteAllBytesAsync(fileMetadata.Filename, fileContent);
            Console.WriteLine({{CONTENT}}quot;Downloaded: {fileMetadata.Filename}");
        }
    }

    static List<string> ExtractFileIds(dynamic response)
    {
        var fileIds = new List<string>();
        foreach (var item in response.Content)
        {
            if (item.Type == "bash_code_execution_tool_result")
            {
                var contentItem = item.Content;
                if (contentItem.Type == "bash_code_execution_result")
                {
                    // concrete-typed list: BetaBashCodeExecutionOutputBlock
                    foreach (var file in contentItem.Content)
                    {
                        if (file.FileId != null)
                        {
                            fileIds.Add(file.FileId);
                        }
                    }
                }
            }
        }
        return fileIds;
    }
}
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"os"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 4096,
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Create a matplotlib visualization and save it as output.png")),
		},
		Tools: []anthropic.BetaToolUnionParam{
			{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
		},
		Betas: []anthropic.AnthropicBeta{
			"code-execution-2025-08-25",
			anthropic.AnthropicBetaFilesAPI2025_04_14,
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	fileIDs := extractFileIDs(response)

	for _, fileID := range fileIDs {
		fileMetadata, err := client.Beta.Files.GetMetadata(context.TODO(), fileID, anthropic.BetaFileGetMetadataParams{})
		if err != nil {
			log.Fatal(err)
		}

		fileContent, err := client.Beta.Files.Download(context.TODO(), fileID, anthropic.BetaFileDownloadParams{})
		if err != nil {
			log.Fatal(err)
		}

		outFile, err := os.Create(fileMetadata.Filename)
		if err != nil {
			log.Fatal(err)
		}

		_, err = io.Copy(outFile, fileContent.Body)
		if err != nil {
			log.Fatal(err)
		}
		outFile.Close()
		fileContent.Body.Close()

		fmt.Printf("Downloaded: %s\n", fileMetadata.Filename)
	}
}

func extractFileIDs(response *anthropic.BetaMessage) []string {
	var fileIDs []string
	for _, item := range response.Content {
		switch variant := item.AsAny().(type) {
		case anthropic.BetaBashCodeExecutionToolResultBlock:
			// concrete-typed list: BashCodeExecutionOutputBlock
			for _, file := range variant.Content.Content {
				if file.FileID != "" {
					fileIDs = append(fileIDs, file.FileID)
				}
			}
		}
	}
	return fileIDs
}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.HttpResponse;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaCodeExecutionTool20250825;
import com.anthropic.models.beta.messages.BetaBashCodeExecutionResultBlock;
import com.anthropic.models.beta.messages.BetaBashCodeExecutionOutputBlock;
import com.anthropic.models.beta.files.FileMetadata;
import java.io.FileOutputStream;
import java.util.ArrayList;
import java.util.List;

void main() throws Exception {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model("claude-opus-4-7")
        .addBeta("files-api-2025-04-14")
        .maxTokens(4096L)
        .addUserMessage("Create a matplotlib visualization and save it as output.png")
        .addTool(BetaCodeExecutionTool20250825.builder().build())
        .build();

    BetaMessage response = client.beta().messages().create(params);

    List<String> fileIds = extractFileIds(response);

    for (String fileId : fileIds) {
        FileMetadata fileMetadata = client.beta().files().retrieveMetadata(fileId);
        try (HttpResponse fileContent = client.beta().files().download(fileId)) {
            try (FileOutputStream fos = new FileOutputStream(fileMetadata.filename())) {
                fileContent.body().transferTo(fos);
            }
        }
        IO.println("Downloaded: " + fileMetadata.filename());
    }
}

List<String> extractFileIds(BetaMessage response) {
    List<String> fileIds = new ArrayList<>();
    // .ifPresent() is the discriminator guard (not concrete-typed; scanner can't see lambda guards)
    for (BetaContentBlock item : response.content()) {
        item.bashCodeExecutionToolResult().ifPresent(toolResult -> {
            if (toolResult.content().isBetaBashCodeExecutionResultBlock()) {
                BetaBashCodeExecutionResultBlock result =
                    toolResult.content().asBetaBashCodeExecutionResultBlock();
                // concrete-typed list: BetaBashCodeExecutionOutputBlock
                for (BetaBashCodeExecutionOutputBlock output : result.content()) {
                    fileIds.add(output.fileId());
                }
            }
        });
    }
    return fileIds;
}
<?php

use Anthropic\Beta\Messages\BetaMessage;
use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$response = $client->beta->messages->create(
    maxTokens: 4096,
    messages: [
        [
            'role' => 'user',
            'content' => 'Create a matplotlib visualization and save it as output.png',
        ],
    ],
    model: 'claude-opus-4-7',
    betas: ['files-api-2025-04-14'],
    tools: [
        [
            'type' => 'code_execution_20250825',
            'name' => 'code_execution',
        ],
    ],
);

function extractFileIds(BetaMessage $response): array
{
    $fileIds = [];
    foreach ($response->content as $item) {
        if ($item->type !== 'bash_code_execution_tool_result') {
            continue;
        }
        $contentItem = $item->content;
        if ($contentItem->type !== 'bash_code_execution_result') {
            continue;
        }
        // concrete-typed list: BashCodeExecutionOutputBlock
        foreach ($contentItem->content as $file) {
            $fileIds[] = $file->fileID;
        }
    }
    return $fileIds;
}

foreach (extractFileIds($response) as $fileId) {
    $fileMetadata = $client->beta->files->retrieveMetadata($fileId);
    $fileContent = $client->beta->files->download($fileId);

    file_put_contents($fileMetadata->filename, $fileContent);
    echo "Downloaded: {$fileMetadata->filename}\n";
}
require "anthropic"

client = Anthropic::Client.new

response = client.beta.messages.create(
  model: "claude-opus-4-7",
  betas: ["files-api-2025-04-14"],
  max_tokens: 4096,
  messages: [
    {
      role: "user",
      content: "Create a matplotlib visualization and save it as output.png"
    }
  ],
  tools: [
    {
      type: "code_execution_20250825",
      name: "code_execution"
    }
  ]
)

def extract_file_ids(response)
  file_ids = []
  response.content.each do |item|
    if item.type == :bash_code_execution_tool_result
      content_item = item.content
      if content_item.type == :bash_code_execution_result
        # concrete-typed list: BashCodeExecutionOutputBlock
        content_item.content.each do |file|
          file_ids << file.file_id
        end
      end
    end
  end
  file_ids
end

extract_file_ids(response).each do |file_id|
  file_metadata = client.beta.files.retrieve_metadata(file_id)
  file_content = client.beta.files.download(file_id)

  File.open(file_metadata.filename, "wb") do |f|
    f.write(file_content.read)
  end

  puts "Downloaded: #{file_metadata.filename}"
end

工具定义

Code execution tool 不需要额外参数:

{
  "type": "code_execution_20250825",
  "name": "code_execution"
}

提供此工具后,Claude 自动获得两个子工具的访问权限:

  • bash_code_execution:运行 shell 命令
  • text_editor_code_execution:查看、创建和编辑文件,包括编写代码

响应格式

Code execution tool 可以根据操作返回两种类型的结果:

Bash 命令响应

[
  {
    "type": "server_tool_use",
    "id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
    "name": "bash_code_execution",
    "input": {
      "command": "ls -la | head -5"
    }
  },
  {
    "type": "bash_code_execution_tool_result",
    "tool_use_id": "srvtoolu_01B3C4D5E6F7G8H9I0J1K2L3",
    "content": {
      "type": "bash_code_execution_result",
      "stdout": "total 24\ndrwxr-xr-x 2 user user 4096 Jan 1 12:00 .\ndrwxr-xr-x 3 user user 4096 Jan 1 11:00 ..\n-rw-r--r-- 1 user user  220 Jan 1 12:00 data.csv\n-rw-r--r-- 1 user user  180 Jan 1 12:00 config.json",
      "stderr": "",
      "return_code": 0
    }
  }
]

文件操作响应

查看文件:

[
  {
    "type": "server_tool_use",
    "id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
    "name": "text_editor_code_execution",
    "input": {
      "command": "view",
      "path": "config.json"
    }
  },
  {
    "type": "text_editor_code_execution_tool_result",
    "tool_use_id": "srvtoolu_01C4D5E6F7G8H9I0J1K2L3M4",
    "content": {
      "type": "text_editor_code_execution_result",
      "file_type": "text",
      "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
      "numLines": 4,
      "startLine": 1,
      "totalLines": 4
    }
  }
]

创建文件:

[
  {
    "type": "server_tool_use",
    "id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
    "name": "text_editor_code_execution",
    "input": {
      "command": "create",
      "path": "new_file.txt",
      "file_text": "Hello, World!"
    }
  },
  {
    "type": "text_editor_code_execution_tool_result",
    "tool_use_id": "srvtoolu_01D5E6F7G8H9I0J1K2L3M4N5",
    "content": {
      "type": "text_editor_code_execution_result",
      "is_file_update": false
    }
  }
]

编辑文件 (str_replace):

[
  {
    "type": "server_tool_use",
    "id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
    "name": "text_editor_code_execution",
    "input": {
      "command": "str_replace",
      "path": "config.json",
      "old_str": "\"debug\": true",
      "new_str": "\"debug\": false"
    }
  },
  {
    "type": "text_editor_code_execution_tool_result",
    "tool_use_id": "srvtoolu_01E6F7G8H9I0J1K2L3M4N5O6",
    "content": {
      "type": "text_editor_code_execution_result",
      "oldStart": 3,
      "oldLines": 1,
      "newStart": 3,
      "newLines": 1,
      "lines": ["-  \"debug\": true", "+  \"debug\": false"]
    }
  }
]

结果

所有执行结果包括:

  • stdout:成功执行的输出
  • stderr:执行失败时的错误消息
  • return_code:0 表示成功,非零表示失败

文件操作的附加字段:

  • 查看file_typecontentnumLinesstartLinetotalLines
  • 创建is_file_update(文件是否已存在)
  • 编辑oldStartoldLinesnewStartnewLineslines(diff 格式)

错误

每种工具类型可以返回特定错误:

常见错误(所有工具):

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "srvtoolu_01VfmxgZ46TiHbmXgy928hQR",
  "content": {
    "type": "bash_code_execution_tool_result_error",
    "error_code": "unavailable"
  }
}

按工具类型的错误代码:

工具错误代码描述
所有工具unavailable工具暂时不可用
所有工具execution_time_exceeded执行超过最大时间限制
所有工具container_expired容器已过期且不再可用
所有工具invalid_tool_input提供给工具的参数无效
所有工具too_many_requests工具使用超出速率限制
bashoutput_file_too_large命令输出超过最大大小
text_editorfile_not_found文件不存在(用于查看/编辑操作)
text_editorstring_not_found在文件中未找到 old_str(用于 str_replace)

pause_turn 停止原因

响应可能包含 pause_turn 停止原因,表示 API 暂停了一个长时间运行的轮次。你可以在后续请求中原样提供响应以让 Claude 继续其轮次,或者如果你想中断对话,可以修改内容。

容器

Code execution tool 在专为代码执行设计的安全容器化环境中运行,重点关注 Python。

运行时环境

  • Python 版本:3.11.12
  • 操作系统:基于 Linux 的容器
  • 架构:x86_64 (AMD64)

资源限制

  • 内存:5GiB RAM
  • 磁盘空间:5GiB 工作区存储
  • CPU:1 CPU

网络和安全

  • 互联网访问:出于安全考虑完全禁用
  • 外部连接:不允许出站网络请求
  • 沙箱隔离:与宿主系统和其他容器完全隔离
  • 文件访问:仅限于工作区目录
  • 工作区作用域:与 Files 类似,容器的作用域为 API 密钥的工作区
  • 过期时间:容器在创建后 30 天过期

预安装库

沙箱 Python 环境包含以下常用库:

  • 数据科学:pandas、numpy、scipy、scikit-learn、statsmodels
  • 可视化:matplotlib、seaborn
  • 文件处理:pyarrow、openpyxl、xlsxwriter、xlrd、pillow、python-pptx、python-docx、pypdf、pdfplumber、pypdfium2、pdf2image、pdfkit、tabula-py、reportlab[pycairo]、Img2pdf
  • 数学与计算:sympy、mpmath
  • 实用工具:tqdm、python-dateutil、pytz、joblib、unzip、unrar、7zip、bc、rg (ripgrep)、fd、sqlite

容器复用

你可以通过提供先前响应中的容器 ID 来跨多个 API 请求复用现有容器。这允许你在请求之间维护创建的文件。

示例

cd "$(mktemp -d)"
# 第一个请求:创建一个包含随机数的文件
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-4-7",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Write a file with a random number and save it to \"/tmp/number.txt\""
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }' > response1.json

# 从响应中提取容器 ID(使用 jq)
CONTAINER_ID=$(jq -r '.container.id' response1.json)

# 第二个请求:复用容器来读取文件
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 '{
        "container": "'$CONTAINER_ID'",
        "model": "claude-opus-4-7",
        "max_tokens": 4096,
        "messages": [{
            "role": "user",
            "content": "Read the number from \"/tmp/number.txt\" and calculate its square"
        }],
        "tools": [{
            "type": "code_execution_20250825",
            "name": "code_execution"
        }]
    }'
# 第一个请求:创建一个包含随机数的文件
CONTAINER_ID=$(ant messages create \
  --transform container.id --raw-output \
    --model claude-opus-4-7 \
    --max-tokens 4096 \
    --message '{role: user, content: Write a file with a random number and save it to "/tmp/number.txt"}' \
    --tool '{type: code_execution_20250825, name: code_execution}'
)

# 第二个请求:复用容器来读取文件
ant messages create --container "$CONTAINER_ID" \
  --model claude-opus-4-7 \
  --max-tokens 4096 \
  --message '{role: user, content: Read the number from "/tmp/number.txt" and calculate its square}' \
  --tool '{type: code_execution_20250825, name: code_execution}'
import os
from anthropic import Anthropic

# 初始化客户端
client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

# 第一个请求:创建一个包含随机数的文件
response1 = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Write a file with a random number and save it to '/tmp/number.txt'",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# 从第一个响应中提取容器 ID
container_id = response1.container.id

# 第二个请求:复用容器来读取文件
response2 = client.messages.create(
    container=container_id,  # 复用同一容器
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Read the number from '/tmp/number.txt' and calculate its square",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

print(response2)
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  // 第一个请求:创建一个包含随机数的文件
  const response1 = await client.beta.messages.create({
    model: "claude-opus-4-7",
    betas: ["code-execution-2025-08-25"],
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Write a file with a random number and save it to '/tmp/number.txt'"
      }
    ],
    tools: [
      {
        type: "code_execution_20250825",
        name: "code_execution"
      }
    ]
  });

  // 从第一个响应中提取容器 ID
  const containerId = response1.container!.id;

  // 第二个请求:复用容器来读取文件
  const response2 = await client.beta.messages.create({
    container: containerId,
    model: "claude-opus-4-7",
    betas: ["code-execution-2025-08-25"],
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Read the number from '/tmp/number.txt' and calculate its square"
      }
    ],
    tools: [
      {
        type: "code_execution_20250825",
        name: "code_execution"
      }
    ]
  });

  console.log(response2.content);
}

main().catch(console.error);
using Anthropic;
using Anthropic.Models.Messages;
using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        AnthropicClient client = new();

        var parameters1 = new MessageCreateParams
        {
            Model = Model.ClaudeOpus4_7,
            MaxTokens = 4096,
            Messages = [new() { Role = Role.User, Content = "Write a file with a random number and save it to '/tmp/number.txt'" }],
            Tools = [new ToolUnion(new CodeExecutionTool20250825())]
        };

        var response1 = await client.Messages.Create(parameters1);
        var containerId = response1.Container!.ID;

        var parameters2 = new MessageCreateParams
        {
            Container = containerId,
            Model = Model.ClaudeOpus4_7,
            MaxTokens = 4096,
            Messages = [new() { Role = Role.User, Content = "Read the number from '/tmp/number.txt' and calculate its square" }],
            Tools = [new ToolUnion(new CodeExecutionTool20250825())]
        };

        var response2 = await client.Messages.Create(parameters2);
        Console.WriteLine(response2);
    }
}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response1, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 4096,
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Write a file with a random number and save it to '/tmp/number.txt'")),
		},
		Tools: []anthropic.BetaToolUnionParam{
			{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
		},
		Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"},
	})
	if err != nil {
		log.Fatal(err)
	}

	containerID := response1.Container.ID

	response2, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Container: anthropic.BetaMessageNewParamsContainerUnion{
			OfString: anthropic.String(containerID),
		},
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 4096,
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Read the number from '/tmp/number.txt' and calculate its square")),
		},
		Tools: []anthropic.BetaToolUnionParam{
			{OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
		},
		Betas: []anthropic.AnthropicBeta{"code-execution-2025-08-25"},
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, block := range response2.Content {
		if block.Type == "text" {
			fmt.Println(block.Text)
		}
	}
}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.Model;
import com.anthropic.models.messages.CodeExecutionTool20250825;

public class ContainerReuse {
    public static void main(String[] args) {
        AnthropicClient client = AnthropicOkHttpClient.fromEnv();

        MessageCreateParams params1 = MessageCreateParams.builder()
            .model(Model.CLAUDE_OPUS_4_7)
            .maxTokens(4096L)
            .addUserMessage("Write a file with a random number and save it to '/tmp/number.txt'")
            .addTool(CodeExecutionTool20250825.builder().build())
            .build();

        Message response1 = client.messages().create(params1);
        String containerId = response1.container().get().id();

        MessageCreateParams params2 = MessageCreateParams.builder()
            .container(containerId)
            .model(Model.CLAUDE_OPUS_4_7)
            .maxTokens(4096L)
            .addUserMessage("Read the number from '/tmp/number.txt' and calculate its square")
            .addTool(CodeExecutionTool20250825.builder().build())
            .build();

        Message response2 = client.messages().create(params2);
        System.out.println(response2);
    }
}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$response1 = $client->messages->create(
    maxTokens: 4096,
    messages: [
        ['role' => 'user', 'content' => "Write a file with a random number and save it to '/tmp/number.txt'"]
    ],
    model: 'claude-opus-4-7',
    tools: [
        ['type' => 'code_execution_20250825', 'name' => 'code_execution']
    ],
);

$containerId = $response1->container->id;

$response2 = $client->messages->create(
    container: $containerId,
    maxTokens: 4096,
    messages: [
        ['role' => 'user', 'content' => "Read the number from '/tmp/number.txt' and calculate its square"]
    ],
    model: 'claude-opus-4-7',
    tools: [
        ['type' => 'code_execution_20250825', 'name' => 'code_execution']
    ],
);
require "anthropic"

client = Anthropic::Client.new

response1 = client.messages.create(
  model: "claude-opus-4-7",
  max_tokens: 4096,
  messages: [
    { role: "user", content: "Write a file with a random number and save it to '/tmp/number.txt'" }
  ],
  tools: [
    { type: "code_execution_20250825", name: "code_execution" }
  ]
)

container_id = response1.container.id

response2 = client.messages.create(
  container: container_id,
  model: "claude-opus-4-7",
  max_tokens: 4096,
  messages: [
    { role: "user", content: "Read the number from '/tmp/number.txt' and calculate its square" }
  ],
  tools: [
    { type: "code_execution_20250825", name: "code_execution" }
  ]
)

puts response2.content

流式传输

启用流式传输后,你将在 code execution 事件发生时收到它们:

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "code_execution"}}

// 代码执行流式传输
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"code\":\"import pandas as pd\\ndf = pd.read_csv('data.csv')\\nprint(df.head())\"}"}}

// 代码执行期间暂停

// 执行结果流式传输
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": ""}}}

批量请求

你可以在 Messages Batches API 中包含 code execution tool。通过 Messages Batches API 的 code execution tool 调用与常规 Messages API 请求中的定价相同。

用量和定价

与 web search 或 web fetch 一起使用时,code execution 免费。 当你的 API 请求中包含 web_search_20260209web_fetch_20260209 时,除了标准的输入和输出 token 费用外,code execution tool 调用不收取额外费用。

不与这些工具一起使用时,code execution 按执行时间计费,与 token 使用量分开跟踪:

  • 执行时间最低为 5 分钟
  • 每个组织每月获得 1,550 小时的免费使用量
  • 超出 1,550 小时的部分按每小时每容器 $0.05计费
  • 如果请求中包含文件,即使未调用工具也会收取执行时间费用,因为文件会被预加载到容器上

Code execution 使用量在响应中跟踪:

{
  "usage": {
    "input_tokens": 105,
    "output_tokens": 239,
    "server_tool_use": {
      "code_execution_requests": 1
    }
  }
}

升级到最新工具版本

通过升级到 code-execution-2025-08-25,你可以获得文件操作和 Bash 功能,包括多语言代码支持。价格没有差异。

变更内容

组件旧版当前
Beta headercode-execution-2025-05-22code-execution-2025-08-25
工具类型code_execution_20250522code_execution_20250825
功能仅 PythonBash 命令、文件操作
响应类型code_execution_resultbash_code_execution_resulttext_editor_code_execution_result

向后兼容性

  • 所有现有 Python 代码执行继续正常工作
  • 现有仅 Python 工作流无需更改

升级步骤

要升级,请更新 API 请求中的工具类型:

- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"

检查响应处理(如果以编程方式解析响应):

  • 之前的 Python 执行响应块将不再发送
  • 将发送 Bash 和文件操作的新响应类型(参见响应格式部分)

程序化工具调用

有关在 code execution 容器内运行工具的信息,请参阅程序化工具调用

数据留存

Code execution 在服务端沙箱容器中运行。容器数据(包括执行产物、上传的文件和输出)保留最长 30 天。此留存适用于容器环境中处理的所有数据。Code execution 在 Files API 中创建的文件(可通过 client.beta.files.download() 检索)会持续存在,直到被显式删除。

有关所有功能的 ZDR 资格,请参阅 API 和数据留存

将 code execution 与 Agent Skills 一起使用

Code execution tool 使 Claude 能够使用 Agent Skills。Skills 是由指令、脚本和资源组成的模块化功能,用于扩展 Claude 的功能。

更多信息请参阅 Agent Skills将 Agent Skills 与 API 一起使用