Cargando

Ejecución de código y la Files API

Lección 4610 min
Cargando

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

Files API

La Files API proporciona una forma alternativa de gestionar la carga de archivos. En lugar de codificar imágenes o PDFs directamente en tus mensajes como datos base64, puedes cargar archivos con antelación y hacer referencia a ellos más tarde.

Nuestro servidor envía a Claude datos sin procesar de una imagen y el texto "¿Qué ves en esta imagen?", y Claude responde "Veo un árbol alto".

Así es como funciona:

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

Nuestro servidor envía el ID del archivo en un bloque de imagen más "¿Qué ves en esta imagen?", y Claude responde "Veo un árbol alto".

Este enfoque es particularmente útil cuando quieres hacer referencia al 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 el servidor que no requiere que proporciones una implementación. Simplemente incluyes un esquema de herramienta predefinido en tu solicitud, y Claude puede, de forma opcional, ejecutar código Python en un contenedor Docker aislado.

Nuestro servidor le pide a Claude PI hasta el decimal número 50; Claude devuelve código, el resultado "3.1415926535" y una respuesta de texto.

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

  • Se ejecuta en un contenedor Docker aislado
  • No tiene 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 Files API y la ejecución de código

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

Flujo de trabajo indicado a continuación: un mensaje del usuario con un bloque de carga de contenedor y texto, luego la respuesta de Claude con código, resultados y texto.

Este es un flujo de trabajo típico:

  1. Carga tu archivo de datos (como un CSV) usando la Files API
  2. Incluye un bloque de carga de contenedor en tu mensaje con el ID del archivo
  3. Pídele 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 hecho churn (cancelado su suscripción).

Archivo streaming.csv con columnas como UserID, SubscriptionTier y TotalViewingHoursLastMonth, y filas desde USER_00001.

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_20250825", "name": "code_execution"}]
)

Entendiendo la respuesta

Cuando Claude usa la ejecución de código, la respuesta contiene varios 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 resultados de la herramienta de ejecución de código: la salida de ejecutar el código

Respuesta impresa: un bloque de texto sobre los factores de churn, un bloque de uso de herramienta del servidor cuyo código importa pandas, y luego un resultado de herramienta.

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 ponerlos a disposición para su descarga. Cuando Claude crea una visualización, esta se almacena en el contenedor y puedes descargarla usando la Files API.

Busca bloques con type: "bash_code_execution_output" en la respuesta: estos contienen los ID de archivo del contenido generado:

python
download_file("file_id_from_response")

Gráfico de análisis de churn multipanel descargado: 500 usuarios, tasa de churn del 38.6%, el principal factor de churn son las interacciones con servicio al cliente.

El resultado es un análisis integral con visualizaciones profesionales que habría tomado una cantidad significativa de código manual producir.

Más allá del análisis de datos

Si bien el análisis de datos es un caso de uso natural, la combinación de la Files API 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 a Claude tareas complejas y computacionales mientras mantienes el control sobre las entradas y salidas a través de la Files API. Esto crea un flujo de trabajo potente en el que Claude se convierte en tu asistente de programación, capaz de ejecutar e iterar soluciones de forma efectiva.