code-execution

Code Execution Tool

The Code Execution tool runs Python in an Anthropic-hosted sandbox as part of a model response. Use it when you need the model to actually compute, not just describe.

When to Use

• Data analysis and transformation (CSV, JSON, parquet)
• Chart and plot generation (matplotlib, plotly)
• Math verification — let the model check its own work
• Running unit tests the model just wrote
• Any task where "the answer is whatever the code prints"

Enabling

const response = await client.beta.messages.create(
  {
    model: "claude-sonnet-4-6",
    max_tokens: 4096,
    tools: [{ type: "code_execution_20250522", name: "code_execution" }],
    messages: [{ role: "user", content: "Analyze the attached CSV and plot monthly revenue." }],
  },
  { headers: { "anthropic-beta": "code-execution-2025-05-22" } },
);

No tool-use loop to manage — execution happens server-side and results flow back in the response.

What's in the Sandbox

• Python 3.12+
• Preinstalled: pandas, numpy, matplotlib, scipy, scikit-learn, pillow, requests, beautifulsoup4, and more
• Ephemeral filesystem (cleared between calls unless using container persistence — see below)
• No network access by default (some betas allow it)
• CPU + RAM limits (conservative — don't train models here)

File Upload

Upload files with the Files API, then reference them in the message:

const file = await client.beta.files.upload({ file: fs.createReadStream("sales.csv") });

const response = await client.beta.messages.create(
  {
    model: "claude-sonnet-4-6",
    max_tokens: 4096,
    tools: [{ type: "code_execution_20250522", name: "code_execution" }],
    messages: [
      {
        role: "user",
        content: [
          { type: "container_upload", file_id: file.id },
          { type: "text", text: "Compute YoY growth from sales.csv." },
        ],
      },
    ],
  },
  { headers: { "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14" } },
);

The file appears at /mnt/user-data/ inside the sandbox.