---
title: Herramienta de ejecución de código
url: https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool
description: Ejecuta código Python y bash en un contenedor aislado para analizar datos, generar archivos e iterar sobre soluciones.
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
    - claude-haiku-4-5-20251001
  supportedPlatforms:
    Claude API: ga
    Claude Platform on AWS: ga
    Microsoft Foundry:
      availability: ga
      note: En [Microsoft Foundry](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry), la ejecución de código requiere una [implementación alojada en Anthropic](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure).
  details:
    - Todos los modelos compatibles aceptan las tres [versiones de la herramienta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#tool-versions). En Claude Haiku 4.5, la llamada programática de herramientas y la persistencia del estado del REPL no están disponibles, por lo que las versiones más recientes se comportan allí como `code_execution_20250825`.
    - Para [Claude Mythos Preview](https://anthropic.com/glasswing), la ejecución de código es compatible en la Claude API y en Microsoft Foundry.
---

Claude puede analizar datos, crear visualizaciones, realizar cálculos complejos, ejecutar comandos del sistema, crear y editar archivos y procesar archivos cargados directamente dentro de la conversación de la API. La herramienta de ejecución de código permite a Claude ejecutar comandos Bash y manipular archivos, incluida la escritura de código, en un entorno seguro y "sandboxed" (aislado).

**La ejecución de código es gratuita cuando se usa con búsqueda web o recuperación web (`web_search_20260209`, `web_fetch_20260209` o posteriores).** Cuando una de esas herramientas está en tu solicitud, no hay cargos adicionales por la ejecución de código en esa solicitud más allá de los costos estándar de tokens. Esto cubre tanto la ejecución de código detrás del filtrado dinámico como cualquier código que Claude ejecute directamente. Se aplican los precios estándar de ejecución de código cuando no se incluyen.

La ejecución de código también impulsa el "dynamic filtering" (filtrado dinámico) en las herramientas de [búsqueda web](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool) y [recuperación web](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-fetch-tool): Claude filtra los resultados dentro del entorno de ejecución de código antes de que lleguen a la "context window" (ventana de contexto). Cuando se ejecuta el filtrado dinámico, la API aprovisiona automáticamente la ejecución de código que necesita para la solicitud, por lo que no necesitas agregar la herramienta de ejecución de código a tu solicitud para ello.

<Note>
  Comunícate a través del [formulario de comentarios](https://forms.gle/LTAU6Xn2puCJMi1n6) para compartir tus comentarios sobre esta función.
</Note>

## Versiones de la herramienta

La herramienta de ejecución de código tiene tres versiones actuales, y todos los [modelos compatibles](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#compatibility) aceptan las tres. Cada versión se basa en la anterior:

* `code_execution_20250825` admite comandos Bash y operaciones con archivos.
* `code_execution_20260120` agrega la persistencia del estado del "REPL" (entorno interactivo de lectura-evaluación-impresión) y la [llamada programática de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/programmatic-tool-calling) desde dentro del sandbox. Claude Haiku 4.5 acepta los tipos de herramienta `code_execution_20260120` y `code_execution_20260521`, pero la llamada programática de herramientas y la persistencia del estado del REPL que depende de ella no están disponibles en ese modelo, por lo que las versiones más recientes se comportan allí como `code_execution_20250825`.
* `code_execution_20260521` es el mismo entorno de ejecución que `code_execution_20260120`. La diferencia es que la descripción de la herramienta le informa a Claude sobre el límite de 90 segundos de tiempo real en cada celda de Python en la llamada programática de herramientas, para que Claude pueda planificar las celdas de larga duración. Una celda que excede el límite devuelve un resultado normal de ejecución de código con un `return_code` distinto de cero y un mensaje de estado `detection_timeout` en su salida. Esto es independiente del [código de error](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#errors) `execution_time_exceeded`, que la API devuelve cuando una invocación completa de la herramienta excede el tiempo máximo de ejecución.

Ninguna de las tres versiones de la herramienta requiere un encabezado `anthropic-beta`. Los encabezados beta heredados de ejecución de código siguen siendo opciones de activación válidas.

Los ejemplos de esta página usan `code_execution_20250825`, que cubre las operaciones de Bash y de archivos que demuestran y se comporta de la misma manera en todos los modelos compatibles; usa `code_execution_20260120` o posterior cuando necesites la llamada programática de herramientas o la persistencia del estado del REPL. Las herramientas actuales de [búsqueda web](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool) y [recuperación web](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-fetch-tool) (`web_search_20260209`, `web_fetch_20260209` y posteriores) requieren `code_execution_20260120` o posterior como su versión de ejecución de código.

No se garantiza que las versiones anteriores de la herramienta sigan siendo compatibles con los modelos más nuevos. Cuando adoptes un modelo nuevo, consulta [Versiones de la herramienta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#tool-versions) y [Compatibilidad](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#compatibility), y prefiere la versión más reciente de la herramienta que admita tu integración.

Para comprobar si un modelo acepta la herramienta de ejecución de código antes de enviar una solicitud, lee su valor `capabilities.server_tools.code_execution.supported` desde la Models API. No uses el valor de nivel superior `capabilities.code_execution` para esto. Ese valor indica si el código que se ejecuta en esta herramienta puede llamar a las demás herramientas de tu solicitud, como en la llamada programática de herramientas. [Uso de la API de Models](https://platform.claude.com/docs/es/models/overview#using-the-models-api) describe ambos campos.

<Note>
  Si todavía usas la versión heredada `code_execution_20250522` (solo Python), consulta [Actualizar a la última versión de la herramienta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#upgrade-to-latest-tool-version) para migrar desde ella.
</Note>

## Inicio rápido

Aquí tienes un ejemplo que le pide a Claude que realice un cálculo:

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 4096,
      "messages": [
        {
          "role": "user",
          "content": "Use the code execution tool to 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"
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create \
    --model claude-opus-5-5 \
    --max-tokens 4096 \
    --message '{
      role: user,
      content: "Use the code execution tool to 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}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=4096,
      messages=[
          {
              "role": "user",
              "content": "Use the code execution tool to 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.to_json())
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content:
          "Use the code execution tool to 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(JSON.stringify(response));
  ```

  ```csharp C#
  AnthropicClient client = new();

  var message = await client.Messages.Create(new()
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" }],
      Tools = [new CodeExecutionTool20250825()]
  });

  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]")),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .maxTokens(4096L)
      .addUserMessage("Use the code execution tool to 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);
  IO.println(ObjectMappers.jsonMapper().valueToTree(response));
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => 'Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]',
          ],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [new CodeExecutionTool20250825()],
  );

  echo json_encode($message, JSON_PRETTY_PRINT), PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Use the code execution tool to calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]"
      }
    ],
    tools: [Anthropic::CodeExecutionTool20250825.new]
  )

  puts message.to_json
  ```
</CodeGroup>

La respuesta intercala bloques `server_tool_use` (los comandos que Claude ejecutó) con sus bloques de resultado de herramienta, seguidos del texto de Claude. El nivel superior también incluye un objeto `container` cuyo `id` puedes [reutilizar entre solicitudes](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#container-reuse). Consulta [Formato de respuesta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#response-format) para ver la estructura de los bloques.

## Cómo funciona la ejecución de código

Cuando agregas la herramienta de ejecución de código a tu solicitud de API:

1. Claude evalúa si la ejecución de código ayudaría a responder tu pregunta

2. La herramienta proporciona automáticamente a Claude las siguientes capacidades:

   * **Comandos Bash:** Ejecutar comandos de shell para operaciones del sistema
   * **Operaciones con archivos:** Crear, ver y editar archivos directamente, incluida la escritura de código

3. Claude puede usar cualquier combinación de estas capacidades en una sola solicitud

4. Todas las operaciones se ejecutan en un contenedor seguro y aislado. El contenedor no tiene acceso a internet, por lo que Claude no puede descargar paquetes en tiempo de ejecución: solo están disponibles las [bibliotecas preinstaladas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#pre-installed-libraries)

5. La API ejecuta cada comando del lado del servidor y devuelve los resultados a Claude dentro de la misma solicitud, por lo que nunca ejecutas código ni envías bloques `tool_result` tú mismo. Una excepción es cuando Claude llama a una de tus herramientas de cliente junto con la ejecución de código: la API devuelve la llamada de ejecución de código sin su resultado. El resultado llega en una respuesta posterior, después de que envíes los bloques `tool_result` de tus herramientas de cliente

6. Cada solicitud se ejecuta en un contenedor nuevo, a menos que devuelvas el ID del contenedor de una respuesta anterior (consulta [Reutilización de contenedores](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#container-reuse))

7. Claude proporciona los resultados con cualquier gráfico, cálculo o análisis generado

El contenedor tiene Python preinstalado. Claude escribe Python con la subherramienta de operaciones con archivos y lo ejecuta con un comando Bash. Con `code_execution_20260120` o posterior y la [llamada programática de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/programmatic-tool-calling), el estado del intérprete de Python (como las asignaciones de variables) también persiste entre las solicitudes que reutilizan el contenedor.

### Cuándo Claude ejecuta código

Claude ejecuta código cuando la solicitud se beneficia del cómputo o del manejo de archivos:

* Matemáticas no triviales (números grandes, muchos pasos, resultados sensibles a la precisión)
* Análisis de datos, análisis sintáctico de archivos o visualización
* Ejecución de algoritmos o simulaciones
* Solicitudes explícitas de "ejecutar", "calcular" o "correr"

Claude responde directamente sin ejecutar código para:

* Aritmética simple y hechos matemáticos bien conocidos
* Solicitudes fácticas, conversacionales o creativas
* Conversiones de unidades o traducciones simples

Si quieres que Claude ejecute código para una solicitud dudosa, pídelo explícitamente (por ejemplo, "ejecuta código para verificar esto").

## Trabajar con archivos

### Cargar y analizar tus propios archivos

Para analizar tus propios archivos de datos (como CSV, Excel o imágenes), cárgalos a través de la Files API y haz referencia a ellos en tu solicitud.

El entorno de Python puede procesar varios tipos de archivos cargados a través de la Files API, entre ellos:

* CSV
* Excel (.xlsx, .xls)
* JSON
* XML
* Imágenes (JPEG, PNG, GIF, WebP)
* Archivos de texto (.txt, .md, .py y otros)

#### Cargar y analizar archivos

1. **Carga tu archivo** usando la [Files API](https://platform.claude.com/docs/es/build-with-claude/files)
2. **Haz referencia al archivo** en tu mensaje usando un bloque de contenido `container_upload`
3. **Incluye la herramienta de ejecución de código** en tu solicitud de API

<CodeGroup>
  ```bash cURL
  # Primero, sube un archivo y guarda el ID del archivo (usando jq)
  FILE_ID=$(curl --fail-with-body -sS https://api.anthropic.com/v1/files \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -F "file=@data.csv" | jq -r '.id')

  # Luego usa el file_id con la ejecución de código
  curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "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"
      }]
    }'
  ```

  ```bash CLI
  # Primero, sube un archivo y guarda el ID del archivo
  FILE_ID=$(ant files upload --file ./data.csv --transform id --raw-output)

  # Luego usa el file_id con la ejecución de código
  ant messages create <<YAML
  model: claude-opus-5-5
  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
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Sube un archivo
  file_object = client.files.upload(file=Path("data.csv"))

  # Usa el file_id con la ejecución de código
  response = client.messages.create(
      model="claude-opus-5-5",
      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.to_json())
  ```

  ```typescript TypeScript
  import { createReadStream } from "node:fs";
  // ...
  const client = new Anthropic();

  // Sube un archivo
  const fileObject = await client.files.upload({
    file: createReadStream("data.csv")
  });

  // Usa el file_id con la ejecución de código
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    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(JSON.stringify(response));
  ```

  ```csharp C#
  AnthropicClient client = new();

  // Sube un archivo
  var fileObject = await client.Files.Upload(new FileUploadParams
  {
      File = File.OpenRead("data.csv")
  });

  // Usa el file_id con la ejecución de código
  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [
          new()
          {
              Role = Role.User,
              Content = new([
                  new TextBlockParam { Text = "Analyze this CSV data" },
                  new ContainerUploadBlockParam { FileID = fileObject.ID }
              ])
          }
      ],
      Tools = [new CodeExecutionTool20250825()]
  };

  var response = await client.Messages.Create(parameters);
  Console.WriteLine(response);
  ```

  ```go Go
  ctx := context.Background()
  client := anthropic.NewClient()

  // Sube un archivo
  file, err := os.Open("data.csv")
  if err != nil {
  	log.Fatal(err)
  }
  defer file.Close()

  fileObject, err := client.Files.Upload(ctx, anthropic.FileUploadParams{
  	File: file,
  })
  if err != nil {
  	log.Fatal(err)
  }

  // Usa el file_id con la ejecución de código
  response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(
  			anthropic.NewTextBlock("Analyze this CSV data"),
  			anthropic.NewContainerUploadBlock(fileObject.ID),
  		),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(response.RawJSON())
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Sube un archivo
  FileMetadata fileObject = client.files().upload(
      FileUploadParams.builder()
          .file(Path.of("data.csv"))
          .build()
  );

  // Usa el file_id con la ejecución de código
  Message response = client.messages().create(
      MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addUserMessageOfBlockParams(List.of(
              ContentBlockParam.ofText(TextBlockParam.builder()
                  .text("Analyze this CSV data")
                  .build()),
              ContentBlockParam.ofContainerUpload(ContainerUploadBlockParam.builder()
                  .fileId(fileObject.id())
                  .build())
          ))
          .addTool(CodeExecutionTool20250825.builder().build())
          .build()
  );

  IO.println(ObjectMappers.jsonMapper().valueToTree(response));
  ```

  ```php PHP
  $client = new Client();

  // Sube un archivo
  $fileObject = $client->files->upload(
      file: FileParam::fromResource(fopen('data.csv', 'r')),
  );

  // Usa el file_id con la ejecución de código
  $response = $client->messages->create(
      model: Model::CLAUDE_OPUS_5_5,
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => [
                  TextBlockParam::with(text: 'Analyze this CSV data'),
                  ContainerUploadBlockParam::with(fileID: $fileObject->id),
              ],
          ],
      ],
      tools: [new CodeExecutionTool20250825()],
  );

  echo json_encode($response), PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Sube un archivo
  file_object = client.files.upload(
    file: Pathname("data.csv")
  )

  # Usa el file_id con la ejecución de código
  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Analyze this CSV data" },
          { type: "container_upload", file_id: file_object.id }
        ]
      }
    ],
    tools: [
      Anthropic::CodeExecutionTool20250825.new
    ]
  )

  puts response.to_json
  ```
</CodeGroup>

### Recuperar archivos generados

Cuando Claude guarda archivos en su directorio de salida durante la ejecución de código (consulta [Cómo se capturan los archivos generados](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#how-generated-files-are-captured)), el ID de cada archivo aparece en el resultado de la herramienta de ejecución de código, y puedes descargarlo con la [Files API](https://platform.claude.com/docs/es/build-with-claude/files):

<CodeGroup exclude="shell">
  <CodeGroupItem language="cURL">
    Descargar cada archivo generado requiere un bucle sobre los ID de archivo en el resultado de la herramienta, lo que necesita más lógica que un solo comando de shell. Usa el [SDK de Claude](https://platform.claude.com/docs/es/cli-sdks-libraries/overview) para esto.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Descargar cada archivo generado requiere un bucle sobre los ID de archivo en el resultado de la herramienta, lo que necesita más lógica que un solo comando de shell. Usa el [SDK de Claude](https://platform.claude.com/docs/es/cli-sdks-libraries/overview) para esto.
  </CodeGroupItem>

  ```python Python
  client = Anthropic()

  # Solicita una ejecución de código que cree archivos
  response = client.messages.create(
      model="claude-opus-5-5",
      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"}],
  )


  # Extrae los IDs de archivo de la respuesta
  def extract_file_ids(response: Message) -> list[str]:
      file_ids: list[str] = []
      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":
                  for output_block in content_item.content:
                      file_ids.append(output_block.file_id)
      return file_ids


  # Descarga los archivos creados
  for file_id in extract_file_ids(response):
      file_metadata = client.files.retrieve_metadata(file_id)
      file_content = client.files.download(file_id)
      file_content.write_to_file(file_metadata.filename)
      print(f"Downloaded: {file_metadata.filename}")
  ```

  ```typescript TypeScript
  import { writeFile } from "node:fs/promises";

  const client = new Anthropic();

  // Solicita una ejecución de código que cree archivos
  const response = await client.messages.create({
    model: "claude-opus-5-5",
    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"
      }
    ]
  });

  // Extrae los IDs de archivo de la respuesta y descarga cada archivo creado
  for (const block of response.content) {
    if (block.type === "bash_code_execution_tool_result") {
      const result = block.content;
      if (result.type === "bash_code_execution_result") {
        for (const outputBlock of result.content) {
          const [fileMetadata, fileResponse] = await Promise.all([
            client.files.retrieveMetadata(outputBlock.file_id),
            client.files.download(outputBlock.file_id)
          ]);
          await writeFile(fileMetadata.filename, await fileResponse.bytes());
          console.log(`Downloaded: ${fileMetadata.filename}`);
        }
      }
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

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

  var response = await client.Messages.Create(parameters);

  // Recopila los ID de archivo de los resultados de las herramientas
  List<string> fileIds = [];
  foreach (var block in response.Content)
  {
      if (!block.TryPickBashCodeExecutionToolResult(out var toolResult))
          continue;
      if (!toolResult.Content.TryPickBashCodeExecutionResultBlock(out var result))
          continue;
      foreach (var output in result.Content)
      {
          fileIds.Add(output.FileID);
      }
  }

  // Descarga cada archivo creado
  foreach (var fileId in fileIds)
  {
      var fileMetadata = await client.Files.RetrieveMetadata(fileId);
      using var download = await client.Files.Download(fileId);
      var downloadStream = await download.ReadAsStream();
      await using var target = File.Create(fileMetadata.Filename);
      await downloadStream.CopyToAsync(target);
      Console.WriteLine($"Downloaded: {fileMetadata.Filename}");
  }
  ```

  ```go Go
  	client := anthropic.NewClient()
  	ctx := context.Background()

  	response, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  		Model:     anthropic.ModelClaudeOpus5_5,
  		MaxTokens: 4096,
  		Messages: []anthropic.MessageParam{
  			anthropic.NewUserMessage(anthropic.NewTextBlock("Create a matplotlib visualization and save it as output.png")),
  		},
  		Tools: []anthropic.ToolUnionParam{
  			{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  		},
  	})
  	if err != nil {
  		log.Fatal(err)
  	}

  	fileIDs := extractFileIDs(response)

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

  		fileContent, err := client.Files.Download(ctx, fileID, anthropic.FileDownloadParams{})
  		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.Message) []string {
  	var fileIDs []string
  	for _, item := range response.Content {
  		switch variant := item.AsAny().(type) {
  		case anthropic.BashCodeExecutionToolResultBlock:
  			// Recopila los IDs de archivo del resultado de la herramienta
  			for _, file := range variant.Content.Content {
  				if file.FileID != "" {
  					fileIDs = append(fileIDs, file.FileID)
  				}
  			}
  		}
  	}
  	return fileIDs
  }
  ```

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

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(4096L)
          .addUserMessage("Create a matplotlib visualization and save it as output.png")
          .addTool(CodeExecutionTool20250825.builder().build())
          .build();

      Message response = client.messages().create(params);

      List<String> fileIds = extractFileIds(response);

      for (String fileId : fileIds) {
          FileMetadata fileMetadata = client.files().retrieveMetadata(fileId);
          try (HttpResponse fileContent = client.files().download(fileId)) {
              Files.copy(
                  fileContent.body(),
                  Path.of(fileMetadata.filename()),
                  StandardCopyOption.REPLACE_EXISTING);
          }
          IO.println("Downloaded: " + fileMetadata.filename());
      }
  }

  List<String> extractFileIds(Message response) {
      List<String> fileIds = new ArrayList<>();
      // Recopila los IDs de archivo de los resultados de las herramientas
      for (ContentBlock item : response.content()) {
          item.bashCodeExecutionToolResult().ifPresent(toolResult -> {
              if (toolResult.content().isBashCodeExecutionResultBlock()) {
                  BashCodeExecutionResultBlock result =
                      toolResult.content().asBashCodeExecutionResultBlock();
                  for (BashCodeExecutionOutputBlock output : result.content()) {
                      fileIds.add(output.fileId());
                  }
              }
          });
      }
      return fileIds;
  }
  ```

  ```php PHP
  $client = new Client();

  // Solicita la ejecución de código que crea archivos
  $response = $client->messages->create(
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => 'Create a matplotlib visualization and save it as output.png',
          ],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [new CodeExecutionTool20250825()],
  );

  /**
   * Extract file IDs from the response.
   *
   * @return list<string>
   */
  function extractFileIds(Message $response): array
  {
      $fileIds = [];
      foreach ($response->content as $block) {
          if ($block->type !== 'bash_code_execution_tool_result') {
              continue;
          }
          $resultBlock = $block->content;
          if ($resultBlock->type !== 'bash_code_execution_result') {
              continue;
          }
          foreach ($resultBlock->content as $outputBlock) {
              $fileIds[] = $outputBlock->fileID;
          }
      }
      return $fileIds;
  }

  // Descarga los archivos creados
  foreach (extractFileIds($response) as $fileId) {
      $fileMetadata = $client->files->retrieveMetadata($fileId);
      $fileContent = $client->files->download($fileId);

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

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    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
        # SOLUCIÓN ALTERNATIVA para el bug de coerción de uniones de anthropic-sdk-ruby (SDK-636): item.content es una
        # unión de contenido anidada, así que los accesores tipados de `item.content` no son fiables.
        # En su lugar, lee los datos sin procesar de la respuesta mediante la API pública `BaseModel#[]`.
        content_item = item.content
        if content_item[:type].to_s == "bash_code_execution_result"
          Array(content_item[:content]).each do |output_block|
            file_ids << output_block[:file_id]
          end
        end
      end
    end
    file_ids
  end

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

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

    puts "Downloaded: #{file_metadata.filename}"
  end
  ```
</CodeGroup>

#### Cómo se capturan los archivos generados

Cada llamada a `bash_code_execution` obtiene un directorio nuevo y vacío, disponible para el comando como `$OUTPUT_DIR`. Cuando el comando termina, los archivos del nivel superior de ese directorio se capturan y se devuelven como las entradas `file_id` en la lista `content` del resultado. Los archivos escritos en cualquier otro lugar permanecen en el contenedor y no se devuelven.

La descripción de la herramienta le indica a Claude que comparta archivos copiándolos en `$OUTPUT_DIR`. Si tu aplicación depende de recibir un archivo, pídele a Claude que lo copie en `$OUTPUT_DIR` y que liste el directorio en el mismo comando, para que la salida de `ls` confirme la captura (Claude no ve la lista `content`):

```bash
python /tmp/make_report.py && cp /tmp/report.pdf "$OUTPUT_DIR/" && ls "$OUTPUT_DIR"
```

Un archivo que Claude escribió en otro lugar sigue estando en el contenedor, por lo que puedes [reutilizar el contenedor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#container-reuse) y pedirle a Claude que lo copie en `$OUTPUT_DIR`.

### Content Credentials en los archivos generados

En la Claude API, los archivos de imagen, video y audio compatibles que Claude produce en el sandbox de ejecución de código incluyen "Content Credentials" (credenciales de contenido) de [C2PA](https://c2pa.org/) cuando los descargas a través de la [Files API](https://platform.claude.com/docs/es/build-with-claude/files). Los [formatos compatibles](https://opensource.contentauthenticity.org/docs/sdk-repos/c2pa-python/docs/supported-formats/) incluyen PNG, JPEG, GIF, WebP, TIFF, HEIC, AVIF, SVG, MP4, MOV, MP3, WAV, FLAC y M4A. La credencial es un manifiesto firmado criptográficamente e incrustado en los metadatos del archivo. Identifica a Anthropic como emisor, incluye una marca de tiempo y registra la descripción de la acción "Claude provided this file at the request of a user and may have created or modified the file contents."

La firma no requiere cambios en tus solicitudes ni en el manejo de las respuestas, y el manifiesto no registra nada sobre ti, tu organización ni tu solicitud. El contenido visible del archivo no cambia. El manifiesto agrega unos pocos kilobytes, por lo que el tamaño y la suma de verificación del archivo descargado difieren de los del archivo tal como existe dentro del contenedor. Los archivos de texto, los PDF y los documentos de oficina no se firman porque no son formatos compatibles con la firma. Los archivos que cargas se almacenan tal cual, incluidas las Content Credentials que ya tengan.

Para verificar una credencial, inspecciona el archivo con cualquier herramienta compatible con C2PA, como la [utilidad de línea de comandos c2patool](https://github.com/contentauth/c2pa-rs) de código abierto. La recodificación, la conversión de formato, las capturas de pantalla y las herramientas que eliminan metadatos quitan la credencial, por lo que la ausencia de una credencial no significa que un archivo no se haya producido con Claude. Para obtener más información sobre por qué puede faltar una credencial, consulta [Cómo Claude marca el contenido generado por IA](https://support.claude.com/en/articles/16266773-how-claude-marks-ai-generated-content).

## Definición de la herramienta

La herramienta de ejecución de código no requiere parámetros adicionales:

```json JSON
{
  "type": "code_execution_20250825",
  "name": "code_execution"
}
```

Ambos campos son fijos: `type` selecciona la versión de la herramienta, y `name` debe ser `code_execution`.

Cuando proporcionas esta herramienta, Claude obtiene automáticamente acceso a dos subherramientas:

* `bash_code_execution`: Ejecutar comandos de shell
* `text_editor_code_execution`: Ver, crear y editar archivos, incluida la escritura de código

Cuando Claude ejecuta código, la respuesta también incluye un objeto `container` de nivel superior con el `id` del contenedor y la marca de tiempo `expires_at`. Devuelve ese ID en el parámetro de solicitud `container` de nivel superior para seguir usando el mismo contenedor. Consulta [Reutilización de contenedores](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#container-reuse).

## Formato de respuesta

La herramienta de ejecución de código puede devolver dos tipos de resultados según la operación:

### Respuesta de comando Bash

```json Output
{
  "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,
    "content": []
  }
}
```

### Respuestas de operaciones con archivos

**Ver archivo:**

```json Output
{
  "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_view_result",
    "file_type": "text",
    "content": "{\n  \"setting\": \"value\",\n  \"debug\": true\n}",
    "num_lines": 4,
    "start_line": 1,
    "total_lines": 4
  }
}
```

**Crear archivo:**

```json Output
{
  "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_create_result",
    "is_file_update": false
  }
}
```

**Editar archivo (str\_replace):**

```json Output
{
  "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_str_replace_result",
    "old_start": 3,
    "old_lines": 1,
    "new_start": 3,
    "new_lines": 1,
    "lines": ["-  \"debug\": true", "+  \"debug\": false"]
  }
}
```

### Resultados

Los resultados de comandos Bash (`bash_code_execution_result`) incluyen:

* `stdout`: Salida de una ejecución exitosa
* `stderr`: Mensajes de error si la ejecución falla
* `return_code`: 0 para éxito, distinto de cero para fallo
* `content`: Una lista con una entrada por cada archivo que el comando dejó en `$OUTPUT_DIR` (consulta [Cómo se capturan los archivos generados](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#how-generated-files-are-captured)). Cada entrada contiene el `file_id` para [recuperar el archivo](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#retrieve-generated-files) con la Files API

Los resultados de operaciones con archivos tienen sus propios campos:

* **Ver** (`text_editor_code_execution_view_result`): `file_type`, `content`, `num_lines`, `start_line`, `total_lines`
* **Crear** (`text_editor_code_execution_create_result`): `is_file_update` (si el archivo ya existía)
* **Editar** (`text_editor_code_execution_str_replace_result`): `old_start`, `old_lines`, `new_start`, `new_lines`, `lines` (formato diff)

### Errores

Cada tipo de herramienta puede devolver errores específicos:

**Errores comunes (todas las herramientas):**

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

**Códigos de error por tipo de herramienta:**

| Herramienta            | Código de error           | Descripción                                                                    |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------ |
| Todas las herramientas | `unavailable`             | La herramienta no está disponible temporalmente                                |
| Todas las herramientas | `execution_time_exceeded` | La invocación de la herramienta excedió el tiempo máximo de ejecución          |
| Todas las herramientas | `invalid_tool_input`      | Se proporcionaron parámetros no válidos a la herramienta                       |
| Todas las herramientas | `too_many_requests`       | Se excedió el "rate limit" (límite de velocidad) para el uso de la herramienta |
| bash                   | `output_file_too_large`   | La salida del comando excedió el tamaño máximo                                 |
| text\_editor           | `file_not_found`          | El archivo no existe (para operaciones de ver/editar)                          |

Un contenedor vencido no se puede reutilizar: las solicitudes que hacen referencia a él devuelven un error en lugar de restaurarlo. Envía la solicitud de nuevo sin el parámetro `container` para obtener un contenedor nuevo.

### Motivo de detención `pause_turn`

La respuesta puede incluir un motivo de detención `pause_turn`, que indica que la API pausó un turno de larga duración. Puedes devolver la respuesta tal cual en una solicitud posterior para permitir que Claude continúe su turno, o modificar el contenido si quieres interrumpir la conversación.

## Contenedores

La herramienta de ejecución de código se ejecuta en un entorno seguro y en contenedores, diseñado específicamente para la ejecución de código, con un mayor enfoque en Python.

### Entorno de ejecución

* **Versión de Python:** 3.11
* **Sistema operativo:** Contenedor basado en Linux
* **Arquitectura:** x86\_64 (AMD64)

### Límites de recursos

* **Memoria:** 5 GiB de RAM
* **Espacio en disco:** 5 GiB de almacenamiento en el espacio de trabajo
* **CPU:** 1 CPU
* **Tiempo de ejecución:** Una invocación de la herramienta que supera el tiempo máximo de ejecución devuelve un [error](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#errors) `execution_time_exceeded`. Con la [llamada programática de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/programmatic-tool-calling), cada celda del REPL también tiene un límite de 90 segundos de tiempo real

### Redes y seguridad

* **Acceso a internet:** Completamente deshabilitado por seguridad
* **Conexiones externas:** No se permiten solicitudes de red salientes
* **Aislamiento del sandbox:** Aislamiento total del sistema anfitrión y de otros contenedores
* **Acceso a archivos:** Limitado únicamente al directorio del espacio de trabajo
* **Alcance del espacio de trabajo:** Al igual que la [Files API](https://platform.claude.com/docs/es/build-with-claude/files), los contenedores están limitados al espacio de trabajo de la solicitud
* **Vencimiento:** Los contenedores vencen 30 días después de su creación

### Bibliotecas preinstaladas

El entorno aislado de Python incluye estas bibliotecas de uso común:

* **Ciencia de datos:** pandas, numpy, scipy, scikit-learn, statsmodels
* **Visualización:** matplotlib, seaborn
* **Procesamiento de archivos:** pyarrow, openpyxl, xlsxwriter, xlrd, pillow, python-pptx, python-docx, pypdf, pdfplumber, pypdfium2, pdf2image, pdfkit, tabula-py, reportlab\[pycairo], Img2pdf
* **Matemáticas y cómputo:** sympy, mpmath
* **Utilidades:** tqdm, python-dateutil, pytz, joblib

El contenedor también incluye herramientas de línea de comandos como unzip, unrar, 7zip, bc, rg (ripgrep), fd y sqlite.

El contenedor no tiene acceso a internet, por lo que Claude no puede descargar ni instalar paquetes adicionales en tiempo de ejecución: solo están disponibles las bibliotecas preinstaladas.

## Reutilización de contenedores

Puedes reutilizar un contenedor existente en varias solicitudes de API proporcionando el ID del contenedor de una respuesta anterior. Esto te permite conservar los archivos creados entre solicitudes. Con `code_execution_20260120` o posterior y la [llamada programática de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/programmatic-tool-calling), el estado del intérprete de Python también persiste.

Los contenedores vencen 30 días después de su creación. Después de unos 5 minutos de inactividad, se guarda un punto de control del contenedor, y enviar una solicitud con su ID dentro del período de 30 días lo restaura. La marca de tiempo `expires_at` en el objeto `container` de la respuesta es un valor móvil más corto y no refleja el límite de 30 días. Un contenedor que ha vencido no se puede reutilizar. Envía la solicitud de nuevo sin el parámetro `container` para obtener un contenedor nuevo.

### Ejemplo

<CodeGroup>
  ```bash cURL
  # Primera solicitud: crea un archivo con un número aleatorio y captura el ID del contenedor (con jq)
  CONTAINER_ID=$(curl -s https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "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"
      }]
    }' | jq -r '.container.id')

  # Segunda solicitud: reutiliza el contenedor para leer el archivo
  curl https://api.anthropic.com/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "container": "'"$CONTAINER_ID"'",
      "model": "claude-opus-5-5",
      "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"
      }]
    }'
  ```

  ```bash CLI
  # Primera solicitud: crea un archivo con un número aleatorio
  CONTAINER_ID=$(ant messages create \
    --model claude-opus-5-5 \
    --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}' \
    --transform container.id --raw-output)

  # Segunda solicitud: reutiliza el contenedor para leer el archivo
  ant messages create \
    --container "$CONTAINER_ID" \
    --model claude-opus-5-5 \
    --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}'
  ```

  ```python Python
  client = anthropic.Anthropic()

  # Primera solicitud: crea un archivo con un número aleatorio en un contenedor nuevo
  response1 = client.messages.create(
      model="claude-opus-5-5",
      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"}],
  )

  # Segunda solicitud: devuelve el ID del contenedor para que Claude reutilice el mismo contenedor
  response2 = client.messages.create(
      container=response1.container.id,
      model="claude-opus-5-5",
      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.to_json())
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  // Primera solicitud: Claude crea un archivo dentro de un contenedor nuevo de ejecución de código
  const response1 = await client.messages.create({
    model: "claude-opus-5-5",
    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" }]
  });

  // La respuesta incluye el contenedor una vez que se ha ejecutado la herramienta de ejecución de código
  if (!response1.container) {
    throw new Error("Expected the first response to include a container");
  }

  // Segunda solicitud: devuelve el ID del contenedor para que se reutilice el mismo contenedor
  const response2 = await client.messages.create({
    container: response1.container.id,
    model: "claude-opus-5-5",
    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(JSON.stringify(response2));
  ```

  ```csharp C#
  AnthropicClient client = new();

  // Primera solicitud: Claude crea un archivo dentro de un contenedor nuevo de ejecución de código
  var response1 = await client.Messages.Create(new()
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Write a file with a random number and save it to '/tmp/number.txt'" }],
      Tools = [new CodeExecutionTool20250825()]
  });

  // Segunda solicitud: pasa de nuevo el ID del contenedor para que Claude reutilice el mismo contenedor
  var response2 = await client.Messages.Create(new()
  {
      Container = response1.Container!.ID,
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 4096,
      Messages = [new() { Role = Role.User, Content = "Read the number from '/tmp/number.txt' and calculate its square" }],
      Tools = [new CodeExecutionTool20250825()]
  });

  Console.WriteLine(response2);
  ```

  ```go Go
  client := anthropic.NewClient()
  ctx := context.Background()

  codeExecution := []anthropic.ToolUnionParam{
  	{OfCodeExecutionTool20250825: &anthropic.CodeExecutionTool20250825Param{}},
  }

  // Primera solicitud: crea un archivo con un número aleatorio en un contenedor nuevo
  response1, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Write a file with a random number and save it to '/tmp/number.txt'")),
  	},
  	Tools: codeExecution,
  })
  if err != nil {
  	log.Fatal(err)
  }

  // Reutiliza el contenedor de la primera solicitud para que el archivo siga ahí.
  response2, err := client.Messages.New(ctx, anthropic.MessageNewParams{
  	Container: anthropic.MessageCreateParamsContainerUnion{
  		OfString: anthropic.String(response1.Container.ID),
  	},
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 4096,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Read the number from '/tmp/number.txt' and calculate its square")),
  	},
  	Tools: codeExecution,
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(response2.RawJSON())
  ```

  ```java Java
  AnthropicClient client = AnthropicOkHttpClient.fromEnv();

  // Primera solicitud: crea un archivo con un número aleatorio en un contenedor nuevo
  MessageCreateParams params1 = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_5_5)
      .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);

  // Segunda solicitud: devuelve el ID del contenedor para que reutilice el mismo contenedor
  MessageCreateParams params2 = MessageCreateParams.builder()
      .container(response1.container().orElseThrow().id())
      .model(Model.CLAUDE_OPUS_5_5)
      .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);
  IO.println(ObjectMappers.jsonMapper().valueToTree(response2));
  ```

  ```php PHP
  $client = new Client();

  // Primera solicitud: Claude escribe el archivo dentro de un contenedor nuevo de ejecución de código
  $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: Model::CLAUDE_OPUS_5_5,
      tools: [new CodeExecutionTool20250825()],
  );

  // Segunda solicitud: reutiliza el contenedor para que '/tmp/number.txt' siga ahí
  $response2 = $client->messages->create(
      container: $response1->container->id,
      maxTokens: 4096,
      messages: [
          [
              'role' => 'user',
              'content' => "Read the number from '/tmp/number.txt' and calculate its square",
          ],
      ],
      model: Model::CLAUDE_OPUS_5_5,
      tools: [new CodeExecutionTool20250825()],
  );

  echo json_encode($response2), PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  # Primera solicitud: Claude crea el archivo dentro de un nuevo contenedor de ejecución de código
  response1 = client.messages.create(
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Write a file with a random number and save it to '/tmp/number.txt'"
      }
    ],
    tools: [Anthropic::CodeExecutionTool20250825.new]
  )

  # Segunda solicitud: devuelve el ID del contenedor para que Claude reutilice el mismo contenedor
  response2 = client.messages.create(
    container: response1.container.id,
    model: Anthropic::Model::CLAUDE_OPUS_5_5,
    max_tokens: 4096,
    messages: [
      {
        role: "user",
        content: "Read the number from '/tmp/number.txt' and calculate its square"
      }
    ],
    tools: [Anthropic::CodeExecutionTool20250825.new]
  )

  puts response2.to_json
  ```
</CodeGroup>

## Usar la ejecución de código con otras herramientas de ejecución

Cuando proporcionas la ejecución de código junto con herramientas proporcionadas por el cliente que también ejecutan código (como una [herramienta Bash](https://platform.claude.com/docs/es/agents-and-tools/tool-use/bash-tool) o un REPL personalizado), Claude opera en un entorno de múltiples computadoras. La herramienta de ejecución de código se ejecuta en el contenedor aislado de Anthropic, mientras que tus herramientas proporcionadas por el cliente se ejecutan en un entorno separado que tú controlas. A veces Claude puede confundir estos entornos, intentando usar la herramienta equivocada o suponiendo que el estado se comparte entre ellos.

Para evitarlo, agrega instrucciones a tu "system prompt" (indicación del sistema) que aclaren la distinción:

```text wrap
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
```

Esto es especialmente importante al combinar la ejecución de código con la [búsqueda web](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-search-tool) o la [recuperación web](https://platform.claude.com/docs/es/agents-and-tools/tool-use/web-fetch-tool), que habilitan la ejecución de código automáticamente. Si tu aplicación ya proporciona una herramienta de shell del lado del cliente, la ejecución de código automática crea un segundo entorno de ejecución que Claude necesita distinguir.

Cuando Claude llama a una de tus herramientas de cliente junto con la ejecución de código, la API devuelve la llamada de ejecución de código sin su resultado. El resultado llega en una respuesta posterior, después de que envíes los bloques `tool_result` de tus herramientas de cliente.

## Streaming

Con el [streaming](https://platform.claude.com/docs/es/build-with-claude/streaming) habilitado (`"stream": true`), recibirás los eventos de ejecución de código a medida que ocurren. La entrada de la subherramienta se transmite como eventos `input_json_delta`, y cada bloque de resultado llega completo en un único evento `content_block_start`:

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

// Tool input streamed as partial JSON
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"command\": \"python analyze.py\"}"}}

// Pause while the command runs

// Execution result delivered as a complete block
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "bash_code_execution_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "bash_code_execution_result", "stdout": "   A  B  C\n0  1  2  3\n1  4  5  6", "stderr": "", "return_code": 0, "content": []}}}
```

## Solicitudes por lotes

Puedes incluir la herramienta de ejecución de código en la [Messages Batches API](https://platform.claude.com/docs/es/build-with-claude/batch-processing). Las llamadas a la herramienta de ejecución de código a través de la Messages Batches API tienen el mismo precio que las de las solicitudes normales de la Messages API.

## Uso y precios

**La ejecución de código es gratuita cuando se usa con web search o web fetch.** Cuando `web_search_20260209` (o posterior) o `web_fetch_20260209` (o posterior) se incluye en tu solicitud a la API, no hay cargos adicionales por las llamadas a la herramienta de ejecución de código más allá de los costos estándar de tokens de entrada y salida.

Cuando se usa sin estas herramientas, la ejecución de código se factura por tiempo de ejecución, registrado por separado del uso de tokens:

* El tiempo de ejecución tiene un mínimo de 5 minutos
* Cada organización recibe **1,550 horas gratuitas** de uso por mes
* El uso adicional más allá de las 1,550 horas se factura a **$0.05 USD por hora, por contenedor**
* Si se incluyen archivos en la solicitud, el tiempo de ejecución se factura incluso si no se llama a la herramienta, porque los archivos se precargan en el contenedor

El uso de la ejecución de código se registra en la respuesta:

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

## Actualizar a la última versión de la herramienta

La última versión de la herramienta es `code_execution_20260521`. Para cambiar entre las tres versiones actuales, actualiza la cadena `type` en tu solicitud: las tres devuelven los bloques de respuesta documentados en [Formato de respuesta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#response-format). Consulta [Versiones de la herramienta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#tool-versions) para ver lo que agrega cada versión y [Compatibilidad](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#compatibility) para conocer los modelos que las admiten.

El resto de esta sección trata sobre la migración desde la versión heredada `code_execution_20250522`, solo para Python, a las versiones actuales de la herramienta.

### Qué ha cambiado

| Componente          | Heredada                    | Actual                                                              |
| ------------------- | --------------------------- | ------------------------------------------------------------------- |
| Encabezado beta     | `code-execution-2025-05-22` | No se requiere                                                      |
| Tipo de herramienta | `code_execution_20250522`   | `code_execution_20250825` o posterior                               |
| Capacidades         | Solo Python                 | Comandos Bash, operaciones con archivos                             |
| Tipos de respuesta  | `code_execution_result`     | `bash_code_execution_result`, `text_editor_code_execution_*_result` |

### Compatibilidad con versiones anteriores

* Toda la ejecución de código Python existente sigue funcionando exactamente igual que antes
* No se requieren cambios en los flujos de trabajo existentes que solo usan Python

### Pasos de actualización

Para actualizar, cambia el tipo de herramienta en tus solicitudes de API:

```diff
- "type": "code_execution_20250522"
+ "type": "code_execution_20250825"
```

**Revisa el manejo de respuestas** (si analizas las respuestas de forma programática):

* La API ya no envía los bloques anteriores para las respuestas de ejecución de Python
* En su lugar, la API envía nuevos tipos de respuesta para las operaciones de Bash y de archivos (consulta [Formato de respuesta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/code-execution-tool#response-format))

## Retención de datos

La ejecución de código se ejecuta en contenedores aislados del lado del servidor. Los datos del contenedor, incluidos los artefactos de ejecución, los archivos cargados y las salidas, se conservan hasta por 30 días. Esta retención se aplica a todos los datos procesados dentro del entorno del contenedor. Los archivos que la ejecución de código crea en la [Files API](https://platform.claude.com/docs/es/build-with-claude/files) (recuperables con `client.files.download()` (csharp, go: `client.Files.Download()`; java: `client.files().download()`; php: `$client->files->download()`)) persisten hasta que se eliminan explícitamente.

Para conocer la elegibilidad para ZDR en todas las funciones, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Herramienta de asesor" icon="compass" href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool">
    Combina un modelo ejecutor más rápido con un modelo asesor de mayor inteligencia que proporciona orientación estratégica durante la generación.
  </Card>

  <Card title="Llamada programática de herramientas" icon="code" href="https://platform.claude.com/docs/es/agents-and-tools/tool-use/programmatic-tool-calling">
    Llama a tus propias herramientas desde código que se ejecuta dentro del contenedor de ejecución de código.
  </Card>

  <Card title="Files API" icon="file" href="https://platform.claude.com/docs/es/build-with-claude/files">
    Carga archivos para su análisis y descarga los archivos que crea la ejecución de código.
  </Card>

  <Card title="Usar Agent Skills con la API" icon="book" href="https://platform.claude.com/docs/es/build-with-claude/skills-guide">
    Aprende a usar Agent Skills para ampliar las capacidades de Claude a través de la API.
  </Card>
</CardGroup>