Claude Academy
Cargando

Ejecución de código y la API de archivos

Lección 4610 min

La API de Anthropic ofrece dos funciones potentes que funcionan excepcionalmente bien juntas: la API de archivos y la ejecución de código. Aunque puedan parecer independientes a primera vista, combinarlas abre posibilidades realmente interesantes para delegar tareas complejas a Claude.

API de archivos

La API de archivos proporciona una forma alternativa de gestionar las cargas de archivos. En lugar de codificar imágenes o PDFs directamente en tus mensajes como datos base64, puedes cargar archivos con anticipación y referenciarlos más adelante.

Así es como funciona:

  • Carga tu archivo (imagen, PDF, texto, etc.) a Claude usando una llamada a la API independiente
  • Recibe un objeto de metadatos del archivo que contiene un ID de archivo único
  • Referencia ese ID de archivo en mensajes futuros en lugar de incluir los datos del archivo sin procesar

Este enfoque es particularmente útil cuando quieres referenciar el mismo archivo varias veces o cuando trabajas con archivos más grandes que serían engorrosos de incluir en cada solicitud.

Herramienta de ejecución de código

La ejecución de código es una herramienta basada en servidor que no requiere que proporciones una implementación. Simplemente incluyes un esquema de herramienta predefinido en tu solicitud, y Claude puede ejecutar opcionalmente código Python en un contenedor Docker aislado.

Características clave del entorno de ejecución de código:

  • Se ejecuta en un contenedor Docker aislado
  • Sin acceso a la red (no puede hacer llamadas a API externas)
  • Claude puede ejecutar código varias veces durante una sola conversación
  • Los resultados son capturados e interpretados por Claude para la respuesta final

Combinando la API de archivos y la ejecución de código

El verdadero poder surge al usar estas funciones juntas. Dado que los contenedores Docker no tienen acceso a la red, la API de archivos se convierte en la forma principal de ingresar y extraer datos del entorno de ejecución.

Este es un flujo de trabajo típico:

  1. Carga tu archivo de datos (como un CSV) usando la API de archivos
  2. Incluye un bloque de carga de contenedor en tu mensaje con el ID del archivo
  3. Pide a Claude que analice los datos
  4. Claude escribe y ejecuta código para procesar tu archivo
  5. Claude puede generar resultados (como gráficos) que puedes descargar

Ejemplo práctico

Veamos un ejemplo real usando datos de un servicio de streaming. El archivo CSV contiene información de usuarios, incluyendo niveles de suscripción, hábitos de visualización y si han cancelado (dado de baja su suscripción).

Primero, carga el archivo usando una función auxiliar:

python
file_metadata = upload('streaming.csv')

Luego crea un mensaje que incluya tanto el archivo cargado como una solicitud de análisis:

python
messages = []
add_user_message(
    messages,
    [
        {
            "type": "text",
            "text": """Run a detailed analysis to determine major drivers of churn.
            Your final output should include at least one detailed plot summarizing your findings."""
        },
        {"type": "container_upload", "file_id": file_metadata.id},
    ],
)

chat(
    messages,
    tools=[{"type": "code_execution_20250522", "name": "code_execution"}]
)

Entendiendo la respuesta

Cuando Claude usa la ejecución de código, la respuesta contiene múltiples tipos de bloques:

  • Bloques de texto - El análisis y las explicaciones de Claude
  • Bloques de uso de herramientas del servidor - El código real que Claude decidió ejecutar
  • Bloques de resultado de la herramienta de ejecución de código - La salida de ejecutar el código

Claude puede ejecutar código varias veces durante una sola respuesta, construyendo su análisis de forma iterativa. Cada ciclo de ejecución incluye el código y sus resultados.

Descargando archivos generados

Una de las funciones más potentes es la capacidad de Claude para generar archivos (como gráficos o informes) y hacerlos disponibles para descargar. Cuando Claude crea una visualización, se almacena en el contenedor y puedes descargarla usando la API de archivos.

Busca bloques con type: "code_execution_output" en la respuesta: estos contienen IDs de archivo para el contenido generado:

python
download_file("file_id_from_response")

El resultado es un análisis completo con visualizaciones profesionales que habrían requerido una cantidad significativa de codificación manual para producirse.

Más allá del análisis de datos

Aunque el análisis de datos es un caso de uso natural, la combinación de la API de archivos y la ejecución de código abre muchas posibilidades:

  • Procesamiento y manipulación de imágenes
  • Análisis y transformación de documentos
  • Cálculos matemáticos y modelado
  • Generación de informes con formato personalizado

La clave es que puedes delegar tareas complejas y computacionales a Claude mientras mantienes el control sobre las entradas y salidas a través de la API de archivos. Esto crea un flujo de trabajo potente donde Claude se convierte en tu asistente de codificación que puede realmente ejecutar e iterar sobre soluciones.