code-execution-tool changedagents-and-tools/tool-use/code-execution-tool
Nearest release: v2.1.238, published under an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+67added
Lines−84removed
From line
278
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits23to this page, all time
The whole hunk
from line 278, old and new numbered
/
from line 278
278278To analyze your own data files (such as CSV, Excel, or images), upload them through the Files API and reference them in your request:
279279
280280<Note>
281 This workflow doesn't require a beta header: uploading and downloading files through the Files API and referencing them in `container_upload` blocks are all generally available. The examples on this page send `anthropic-beta: files-api-2025-04-14`, which the API accepts but doesn't require.
281 This workflow doesn't require a beta header: uploading and downloading files through the Files API and referencing them in `container_upload` blocks are all generally available.
282282</Note>
283283
284284The Python environment can process various file types uploaded through the Files API, including:
from line 302
302302 FILE_ID=$(curl --fail-with-body -sS https://api.anthropic.com/v1/files \
303303 -H "x-api-key: $ANTHROPIC_API_KEY" \
304304 -H "anthropic-version: 2023-06-01" \
305 -H "anthropic-beta: files-api-2025-04-14" \
307306
308307 # Then use the file_id with code execution
from line 308
309308 curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
310309 -H "x-api-key: $ANTHROPIC_API_KEY" \
311310 -H "anthropic-version: 2023-06-01" \
312 -H "anthropic-beta: files-api-2025-04-14" \
313311 -H "content-type: application/json" \
314312 -d '{
315313 "model": "claude-opus-5",
from line 328
330328
331329 ```bash CLI
332330 # First, upload a file and capture the file ID
333 FILE_ID=$(ant beta:files upload \
331 FILE_ID=$(ant files upload \
334332 --file ./data.csv \
335333 --transform id --raw-output)
336334
337335 # Then use the file_id with code execution
338 ant beta:messages create \
339 --beta files-api-2025-04-14 <<YAML
336 ant messages create <<YAML
340337 model: claude-opus-5
341338 max_tokens: 4096
342339 messages:
from line 353
356353 client = anthropic.Anthropic()
357354
358355 # Upload a file
359 file_object = client.beta.files.upload(file=Path("data.csv"))
356 file_object = client.files.upload(file=Path("data.csv"))
360357
361358 # Use the file_id with code execution
362 response = client.beta.messages.create(
359 response = client.messages.create(
363360 model="claude-opus-5",
364 betas=["files-api-2025-04-14"],
365361 max_tokens=4096,
366362 messages=[
367363 {
from line 380
384380 const client = new Anthropic();
385381
386382 // Upload a file
387 const fileObject = await client.beta.files.upload({
383 const fileObject = await client.files.upload({
388384 file: createReadStream("data.csv")
389385 });
390386
391387 // Use the file_id with code execution
392 const response = await client.beta.messages.create({
388 const response = await client.messages.create({
393389 model: "claude-opus-5",
394 betas: ["files-api-2025-04-14"],
395390 max_tokens: 4096,
396391 messages: [
397392 {
from line 412
417412 AnthropicClient client = new();
418413
419414 // Upload a file
420 var fileObject = await client.Beta.Files.Upload(new FileUploadParams
415 var fileObject = await client.Files.Upload(new FileUploadParams
421416 {
422417 File = File.OpenRead("data.csv")
423418 });
from line 422
427422 {
428423 Model = Model.ClaudeOpus5,
429424 MaxTokens = 4096,
430 Betas = [AnthropicBeta.FilesApi2025_04_14],
431425 Messages = [
432426 new()
433427 {
434428 Role = Role.User,
435429 Content = new([
436 new BetaTextBlockParam { Text = "Analyze this CSV data" },
437 new BetaContainerUploadBlockParam { FileID = fileObject.ID }
430 new TextBlockParam { Text = "Analyze this CSV data" },
431 new ContainerUploadBlockParam { FileID = fileObject.ID }
438432 ])
439433 }
440434 ],
441 Tools = [new BetaCodeExecutionTool20250825()]
435 Tools = [new CodeExecutionTool20250825()]
442436 };
443437
444 var response = await client.Beta.Messages.Create(parameters);
438 var response = await client.Messages.Create(parameters);
445439 Console.WriteLine(response);
446440 ```
447441
from line 450
456450 }
457451 defer file.Close()
458452
459 fileObject, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
453 fileObject, err := client.Files.Upload(ctx, anthropic.FileUploadParams{
460454 File: file,
461455 })
462456 if err != nil {
from line 458
464458 }
465459
466460 // Use the file_id with code execution
467 response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
461 response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
468462 Model: anthropic.ModelClaudeOpus5,
469463 MaxTokens: 4096,
470 Messages: []anthropic.BetaMessageParam{
471 anthropic.NewBetaUserMessage(
472 anthropic.NewBetaTextBlock("Analyze this CSV data"),
473 anthropic.NewBetaContainerUploadBlock(fileObject.ID),
464 Messages: []anthropic.MessageParam{
465 anthropic.NewUserMessage(
466 anthropic.NewTextBlock("Analyze this CSV data"),
467 anthropic.NewContainerUploadBlock(fileObject.ID),
474468 ),
475469 },
476 Tools: []anthropic.BetaToolUnionParam{
477 {OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
470 Tools: []anthropic.ToolUnionParam{
471 {OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
478472 },
479 Betas: []anthropic.AnthropicBeta{
480 anthropic.AnthropicBetaFilesAPI2025_04_14,
481 },
482473 })
483474 if err != nil {
484475 log.Fatal(err)
from line 482
491482 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
492483
493484 // Upload a file
494 FileMetadata fileObject = client.beta().files().upload(
485 FileMetadata fileObject = client.files().upload(
495486 FileUploadParams.builder()
496487 .file(Path.of("data.csv"))
497488 .build()
from line 489
498489 );
499490
500491 // Use the file_id with code execution
501 BetaMessage response = client.beta().messages().create(
492 Message response = client.messages().create(
502493 MessageCreateParams.builder()
503494 .model(Model.CLAUDE_OPUS_5)
504 .addBeta(AnthropicBeta.FILES_API_2025_04_14)
505495 .maxTokens(4096L)
506 .addUserMessageOfBetaContentBlockParams(List.of(
507 BetaContentBlockParam.ofText(BetaTextBlockParam.builder()
496 .addUserMessageOfBlockParams(List.of(
497 ContentBlockParam.ofText(TextBlockParam.builder()
508498 .text("Analyze this CSV data")
509499 .build()),
510 BetaContentBlockParam.ofContainerUpload(BetaContainerUploadBlockParam.builder()
500 ContentBlockParam.ofContainerUpload(ContainerUploadBlockParam.builder()
511501 .fileId(fileObject.id())
512502 .build())
513503 ))
514 .addTool(BetaCodeExecutionTool20250825.builder().build())
504 .addTool(CodeExecutionTool20250825.builder().build())
515505 .build()
516506 );
517507
from line 540
550540 client = Anthropic::Client.new
551541
552542 # Upload a file
553 file_object = client.beta.files.upload(
543 file_object = client.files.upload(
554544 file: Pathname("data.csv")
555545 )
556546
557547 # Use the file_id with code execution
558 response = client.beta.messages.create(
548 response = client.messages.create(
559549 model: Anthropic::Model::CLAUDE_OPUS_5,
560 betas: [Anthropic::AnthropicBeta::FILES_API_2025_04_14],
561550 max_tokens: 4096,
562551 messages: [
563552 {
from line 558
569558 }
570559 ],
571560 tools: [
572 Anthropic::Beta::BetaCodeExecutionTool20250825.new
561 Anthropic::CodeExecutionTool20250825.new
573562 ]
574563 )
575564
from line 587
598587 client = Anthropic()
599588
600589 # Request code execution that creates files
601 response = client.beta.messages.create(
590 response = client.messages.create(
602591 model="claude-opus-5",
603 betas=["files-api-2025-04-14"],
604592 max_tokens=4096,
605593 messages=[
606594 {
from line 601
613601
614602
615603 # Extract file IDs from the response
616 def extract_file_ids(response: BetaMessage) -> list[str]:
604 def extract_file_ids(response: Message) -> list[str]:
617605 file_ids: list[str] = []
618606 for item in response.content:
619607 if item.type == "bash_code_execution_tool_result":
from line 614
626614
627615 # Download the created files
628616 for file_id in extract_file_ids(response):
629 file_metadata = client.beta.files.retrieve_metadata(file_id)
630 file_content = client.beta.files.download(file_id)
617 file_metadata = client.files.retrieve_metadata(file_id)
618 file_content = client.files.download(file_id)
631619 file_content.write_to_file(file_metadata.filename)
632620 print(f"Downloaded: {file_metadata.filename}")
633621 ```
from line 626
638626 const client = new Anthropic();
639627
640628 // Request code execution that creates files
641 const response = await client.beta.messages.create({
629 const response = await client.messages.create({
642630 model: "claude-opus-5",
643 betas: ["files-api-2025-04-14"],
644631 max_tokens: 4096,
645632 messages: [
646633 {
from line 650
663650 if (result.type === "bash_code_execution_result") {
664651 for (const outputBlock of result.content) {
665652 const [fileMetadata, fileResponse] = await Promise.all([
666 client.beta.files.retrieveMetadata(outputBlock.file_id),
667 client.beta.files.download(outputBlock.file_id)
653 client.files.retrieveMetadata(outputBlock.file_id),
654 client.files.download(outputBlock.file_id)
668655 ]);
669656 await writeFile(fileMetadata.filename, await fileResponse.bytes());
670657 console.log(`Downloaded: ${fileMetadata.filename}`);
from line 668
681668 {
682669 Model = Model.ClaudeOpus5,
683670 MaxTokens = 4096,
684 Betas = [AnthropicBeta.FilesApi2025_04_14],
685671 Messages = [new() { Role = Role.User, Content = "Create a matplotlib visualization and save it as output.png" }],
686 Tools = [new BetaCodeExecutionTool20250825()]
672 Tools = [new CodeExecutionTool20250825()]
687673 };
688674
689 var response = await client.Beta.Messages.Create(parameters);
675 var response = await client.Messages.Create(parameters);
690676
691677 // Collect the file IDs from the tool results
692678 List<string> fileIds = [];
from line 680
694680 {
695681 if (!block.TryPickBashCodeExecutionToolResult(out var toolResult))
696682 continue;
697 if (!toolResult.Content.TryPickBetaBashCodeExecutionResultBlock(out var result))
683 if (!toolResult.Content.TryPickBashCodeExecutionResultBlock(out var result))
698684 continue;
699685 foreach (var output in result.Content)
700686 {
from line 691
705691 // Download each created file
706692 foreach (var fileId in fileIds)
707693 {
708 var fileMetadata = await client.Beta.Files.RetrieveMetadata(fileId);
709 using var download = await client.Beta.Files.Download(fileId);
694 var fileMetadata = await client.Files.RetrieveMetadata(fileId);
695 using var download = await client.Files.Download(fileId);
710696 var downloadStream = await download.ReadAsStream();
711697 await using var target = File.Create(fileMetadata.Filename);
712698 await downloadStream.CopyToAsync(target);
from line 704
718704 client := anthropic.NewClient()
719705 ctx := context.Background()
720706
721 response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
707 response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
722708 Model: anthropic.ModelClaudeOpus5,
723709 MaxTokens: 4096,
724 Messages: []anthropic.BetaMessageParam{
725 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Create a matplotlib visualization and save it as output.png")),
710 Messages: []anthropic.MessageParam{
711 anthropic.NewUserMessage(anthropic.NewTextBlock("Create a matplotlib visualization and save it as output.png")),
726712 },
727 Tools: []anthropic.BetaToolUnionParam{
728 {OfCodeExecutionTool20250825: &anthropic.BetaCodeExecutionTool20250825Param{}},
713 Tools: []anthropic.ToolUnionParam{
714 {OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
729715 },
730 Betas: []anthropic.AnthropicBeta{
731 anthropic.AnthropicBetaFilesAPI2025_04_14,
732 },
733716 })
734717 if err != nil {
735718 log.Fatal(err)
from line 721
738721 fileIDs := extractFileIDs(response)
739722
740723 for _, fileID := range fileIDs {
741 fileMetadata, err := client.Beta.Files.GetMetadata(ctx, fileID, anthropic.BetaFileGetMetadataParams{})
724 fileMetadata, err := client.Files.GetMetadata(ctx, fileID)
742725 if err != nil {
743726 log.Fatal(err)
744727 }
745728
746 fileContent, err := client.Beta.Files.Download(ctx, fileID, anthropic.BetaFileDownloadParams{})
729 fileContent, err := client.Files.Download(ctx, fileID)
747730 if err != nil {
748731 log.Fatal(err)
749732 }
from line 747
764747 }
765748 // ...
766749
767 func extractFileIDs(response *anthropic.BetaMessage) []string {
750 func extractFileIDs(response *anthropic.Message) []string {
768751 var fileIDs []string
769752 for _, item := range response.Content {
770753 switch variant := item.AsAny().(type) {
771 case anthropic.BetaBashCodeExecutionToolResultBlock:
754 case anthropic.BashCodeExecutionToolResultBlock:
772755 // Collect the file IDs from the tool result
773756 for _, file := range variant.Content.Content {
774757 if file.FileID != "" {
from line 770
787770
788771 MessageCreateParams params = MessageCreateParams.builder()
789772 .model(Model.CLAUDE_OPUS_5)
790 .addBeta(AnthropicBeta.FILES_API_2025_04_14)
791773 .maxTokens(4096L)
792774 .addUserMessage("Create a matplotlib visualization and save it as output.png")
793 .addTool(BetaCodeExecutionTool20250825.builder().build())
775 .addTool(CodeExecutionTool20250825.builder().build())
794776 .build();
795777
796 BetaMessage response = client.beta().messages().create(params);
778 Message response = client.messages().create(params);
797779
798780 List<String> fileIds = extractFileIds(response);
799781
800782 for (String fileId : fileIds) {
801 FileMetadata fileMetadata = client.beta().files().retrieveMetadata(fileId);
802 try (HttpResponse fileContent = client.beta().files().download(fileId)) {
783 FileMetadata fileMetadata = client.files().retrieveMetadata(fileId);
784 try (HttpResponse fileContent = client.files().download(fileId)) {
803785 Files.copy(
804786 fileContent.body(),
805787 Path.of(fileMetadata.filename()),
from line 791
809791 }
810792 }
811793
812 List<String> extractFileIds(BetaMessage response) {
794 List<String> extractFileIds(Message response) {
813795 List<String> fileIds = new ArrayList<>();
814796 // Collect the file IDs from the tool results
815 for (BetaContentBlock item : response.content()) {
797 for (ContentBlock item : response.content()) {
816798 item.bashCodeExecutionToolResult().ifPresent(toolResult -> {
817 if (toolResult.content().isBetaBashCodeExecutionResultBlock()) {
818 BetaBashCodeExecutionResultBlock result =
819 toolResult.content().asBetaBashCodeExecutionResultBlock();
820 for (BetaBashCodeExecutionOutputBlock output : result.content()) {
799 if (toolResult.content().isBashCodeExecutionResultBlock()) {
800 BashCodeExecutionResultBlock result =
801 toolResult.content().asBashCodeExecutionResultBlock();
802 for (BashCodeExecutionOutputBlock output : result.content()) {
821803 fileIds.add(output.fileId());
822804 }
823805 }
from line 862
880862 ```ruby Ruby
881863 client = Anthropic::Client.new
882864
883 response = client.beta.messages.create(
865 response = client.messages.create(
884866 model: Anthropic::Model::CLAUDE_OPUS_5,
885 betas: ["files-api-2025-04-14"],
886867 max_tokens: 4096,
887868 messages: [
888869 {
from line 898
917898 end
918899
919900 extract_file_ids(response).each do |file_id|
920 file_metadata = client.beta.files.retrieve_metadata(file_id)
921 file_content = client.beta.files.download(file_id)
901 file_metadata = client.files.retrieve_metadata(file_id)
902 file_content = client.files.download(file_id)
922903
923904 File.open(file_metadata.filename, "wb") do |f|
924905 f.write(file_content.read)
from line 1320
13391320
13401321 // Reuse the container from the first request so the file is still there.
13411322 response2, err := client.Messages.New(ctx, anthropic.MessageNewParams{
1342 Container: anthropic.String(response1.Container.ID),
1323 Container: anthropic.MessageCreateParamsContainerUnion{
1324 OfString: anthropic.String(response1.Container.ID),
1325 },
13431326 Model: anthropic.ModelClaudeOpus5,
13441327 MaxTokens: 4096,
13451328 Messages: []anthropic.MessageParam{
from line 1532
15491532
15501533## Data retention
15511534
1552Code execution runs in server-side sandbox containers. Container data, including execution artifacts, uploaded files, and outputs, is retained for up to 30 days. This retention applies to all data processed within the container environment. Files that code execution creates in the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) (retrievable with `client.beta.files.download()`) persist until explicitly deleted.
1535Code execution runs in server-side sandbox containers. Container data, including execution artifacts, uploaded files, and outputs, is retained for up to 30 days. This retention applies to all data processed within the container environment. Files that code execution creates in the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) (retrievable with `client.files.download()`) persist until explicitly deleted.
15531536
15541537For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
15551538
No line in this hunk matches that.