Soneto 4 de Claude: Guía práctica para programadores

Con el lanzamiento de Claude Sonnet 4, los programadores tienen ahora acceso a nuevas y potentes funciones, como la ejecución de código nativo, una API de Archivos flexible y el uso de herramientas dinámicas. Estas funciones abren interesantes posibilidades para crear aplicaciones basadas en IA que vayan más allá de las simples interacciones de texto.

En este tutorial, te guiaré a través de estas nuevas funciones construyendo un agente basado en Python que pueda resolver problemas matemáticos avanzados directamente desde tu terminal. Aprenderás a utilizar ta recién introducida herramienta de ejecución de código nativo y la API de archivos.

Al final, tendrás un agente que funcionará con Claude Sonnet 4 para analizar problemas, escribir y ejecutar código Python y mostrar imágenes como las que se muestran a continuación.

Echa un vistazo al repositorio GitHub de este proyecto para vertodo el código para construir la aplicación.

Si estás empezando a construir con LLMs como Claude, esta hoja de ruta para programadores de IA describelas herramientas, habilidades e itinerarios de aprendizaje esenciales para empezar.

Novedades de la API Antrópica

Antes de entrar en el tutorial, veamos todas las nuevas funciones recientemente publicadas y disponibles a través de la API Antrópica. Si ya los conoces, puedes saltártelos.

Creo que todo el anuncio de Claude 4 puederesumirse en esta imagen:

Los modelos Claude 4 (Opus y Sonnet 4) superan a la competencia en tareas verificadas de ingeniería de software por un margen significativo. Anthropic consiguió esta hazaña introduciendo algunos cambios importantes en el comportamiento de los modelos:

1. Tiempos de ejecución largos: Ambos modelos soportan varias horas de ejecución continua de tareas para resolver problemas con miles de pasos.
2. Pensamiento ampliado con uso de herramientas: Ambos modelos pueden ahora utilizar herramientas como la búsqueda en Internet durante el pensamiento extendido, lo que permite a Claude alternar entre el razonamiento y el uso de herramientas para mejorar las respuestas.
3. Ejecución paralela de herramientas: Ahora los modelos pueden utilizar varias herramientas simultáneamente, en lugar de secuencialmente.
4. Instrucción más precisa siguiendo: La direccionabilidad mejorada proporciona a los usuarios un mayor control sobre las implementaciones y sobre cómo responde Claude a las instrucciones.
5. Capacidades de memoria mejoradas: Cuando se les da acceso a archivos locales, los modelos pueden extraer y guardar hechos clave para mantener la continuidad y construir conocimiento tácito a lo largo del tiempo.
6. Comportamiento reducido del acceso directo: En comparación con las versiones anteriores, ambos modelos son un 65% menos propensos a utilizar atajos o lagunas para completar tareas (para más detalles, consulta el post completo del anuncio).

Además, como parte del anuncio de la familia de modelos Claude 4, Anthropic ha añadido cuatro nuevas funciones para que construyen agentes de IA: la herramienta de ejecución de código, la API de archivos, el conector MCP y el almacenamiento en caché de avisos ampliado. Estas herramientas cambian la forma en que los programadores pueden crear aplicaciones de IA.

Herramienta de ejecución de código: Ejecuta código Python de forma segura

La herramienta de ejecución de código permite a Claude ejecutar código Python en un entorno sandbox seguro. En lugar de limitarse a escribir sugerencias de código, Claude puede ahora ejecutar código, analizar los resultados e iterar sobre las soluciones.

Para utilizar la herramienta de ejecución de código, añádela a tu arreglo tools e incluye la cabecera beta necesaria:

from anthropic import Anthropic

# Initialize client with the code execution beta header
client = Anthropic(
   default_headers={
       "anthropic-beta": "code-execution-2025-05-22"
   }
)

# Send a request that triggers code execution
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": "Solve the quadratic equation 2x² + 5x - 3 = 0 and plot the parabola"
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

Cuando Claude ejecuta código, la respuesta contiene tanto el código generado como los resultados de su ejecución. He aquí cómo analizar los distintos componentes:

# Parse the response to extract code and results
for item in response.content:
   if item.type == "server_tool_use":
       # This contains the actual Python code Claude wrote
       print(f"Code executed:\n{item.input['code']}")
   elif item.type == "code_execution_tool_result":
       # This contains the output from running the code
       print(f"Output:\n{item.content['stdout']}")
       if item.content.get('stderr'):
           print(f"Errors:\n{item.content['stderr']}")

Limitaciones del Sandbox: El entorno de ejecución del código tiene varias restricciones de seguridad incorporadas. Claude se ejecuta en un contenedor aislado sin acceso a Internet, con recursos informáticos limitados (1 GB de RAM, 5 GB de espacio en disco y 1 CPU), y no puede acceder a tu sistema de archivos local. El entorno viene preinstalado con bibliotecas populares como numpy, pandas, matplotlib, y scipy, pero no puedes instalar paquetes adicionales durante la ejecución.

Archivos API: Contexto de archivo persistente para tareas complejas

La API de archivos permite a subir documentos una vez y hacer referencia a ellos en varias conversaciones. Esto elimina la necesidad de incluir grandes documentos en cada solicitud de API.

Primero, sube tu archivo a los servidores de Anthropic:

# Upload a file once - this stores it on Anthropic's servers
uploaded_file = client.beta.files.upload(
   file=open("sales_data.csv", "rb"),
   purpose="user_upload"
)
# The uploaded_file.id can now be referenced in multiple conversations

Una vez subido, haz referencia al archivo en tus llamadas a la API utilizando el tipo de contenido container_upload:

# Reference the uploaded file in a conversation
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": [
           {"type": "text", "text": "Create a quarterly sales report from this data"},
           {"type": "container_upload", "file_id": uploaded_file.id}
       ]
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

Cuando Claude crea archivos durante la ejecución del código (como gráficos o datos procesados), puedes extraerlos y descargarlos:

# Extract file IDs of any files Claude created during execution
def extract_created_files(response):
   file_ids = []
   for item in response.content:
       if item.type == 'code_execution_tool_result':
           content = item.content
           if content.get('type') == 'code_execution_result':
               # Look for file objects in the execution results
               for file_obj in content.get('content', []):
                   if 'file_id' in file_obj:
                       file_ids.append(file_obj['file_id'])
   return file_ids

# Download any files Claude created
created_files = extract_created_files(response)
for file_id in created_files:
   file_content = client.beta.files.download(file_id)
   file_content.write_to_file(f"output_{file_id}.png")

Conector MCP: Conecta a Claude a cualquier flujo de trabajo

El conector MCP lleva la compatibilidad con el Protocolo de Contexto de Modelo directamente a la API. Los MCP permiten a Claude conectarse a servicios externos como bases de datos, API y herramientas de productividad sin código de integración personalizado.

Antes, para conectarse a los servidores MCP era necesario crear una infraestructura de cliente. Ahora, sólo tienes que proporcionar la URL de un servidor MCP remoto en tu solicitud de API, y Claude descubrirá automáticamente las herramientas disponibles, gestionará las conexiones y se encargará de la autenticación.

Esto abre el acceso a un creciente ecosistema de servidores MCP de empresas como Zapier y Asana, permitiéndote crear agentes que puedan leer tu calendario, actualizar herramientas de gestión de proyectos o integrarse con cientos de otros servicios.

Introducción al Soneto Claude 4: Visión general y configuración del proyecto

Ahora que ya conocemos las nuevas funciones de la API, vamos a construir nuestro solucionador interactivo de problemas matemáticos. Combinará las capacidades de ejecución de código de Claude con el manejo de archivos para crear un asistente matemático completo.

Nuestra aplicación aceptará preguntas matemáticas en lenguaje natural, ejecutará código Python para resolverlas, generará visualizaciones y guardará informes completos.

Para un enfoque estructurado de la creación de proyectos como éste, consulta el tema Desarrollo de aplicaciones de IA.

> Nota: Dado que dividiremos los bloques de código largos con explicaciones, es posible que la sangría del código no sea del todo exacta en los fragmentos. Por este motivo, te recomendamos que abras el repositorio de GitHub de este proyecto en una pestaña aparte mientras sigues el proceso.

Paso 0: Configura el entorno de tu proyecto Claude Sonnet 4

Antes de escribir ningún código, vamos a configurar nuestro entorno de desarrollo y las dependencias.

Crea un nuevo directorio para tu proyecto y configura los archivos necesarios:

mkdir math-solver
cd math-solver
touch math_solver.py demo_problems.py requirements.txt README.md

Crea un archivo requirements.txt con las dependencias necesarias:

anthropic>=0.42.0

Instala las dependencias:

pip install -r requirements.txt

Establece tu clave de la API de Anthropic como variable de entorno:

export ANTHROPIC_API_KEY="your-api-key-here"

Paso 1: Diseña la estructura de la aplicación

Empecemos creando la estructura básica de nuestra clase MathSolver. Esta clase se encargará de toda la funcionalidad principal: Comunicación API, gestión de archivos e interacción con el usuario.

En primer lugar, vamos a establecer las importaciones y la estructura básica:

#!/usr/bin/env python3
"""
Interactive Math Problem Solver using Claude 4 Code Execution Tool

This application allows users to ask math questions in natural language,
gets solutions using Claude's code execution capabilities, and saves
both visualizations and detailed markdown reports.
"""

import os
import json
import datetime
from pathlib import Path
from typing import List, Dict, Any
from anthropic import Anthropic

Ahora vamos a definir la estructura de nuestra clase principal:

class MathSolver:
   def __init__(self, api_key: str = None):
       """Initialize the Math Solver with Anthropic client."""
       # API setup and directory creation will go here
       pass

   def solve_problem(self, question: str) -> Dict[str, Any]:
       """Send a math question to Claude and get solution with code execution."""
       pass
Here are the methods for file and report handling:
def extract_files_from_response(self, response) -> List[str]:
       """Extract file IDs from Claude's response."""
       pass

   def download_files(self, file_ids: List[str]) -> List[str]:
       """Download files created by code execution to local storage."""
       pass

   def extract_code_blocks(self, response) -> List[str]:
       """Extract all code blocks from the response."""
       Pass

Por último, añadimos la gestión de la sesión y el punto de entrada:

def generate_markdown_report(self, result: Dict[str, Any], downloaded_files: List[str]) -> str:
       """Generate a comprehensive markdown report of the solution."""
       pass

   def run_interactive_session(self):
       """Run the main interactive session loop."""
       pass


def main():
   """Main entry point for the application."""
   pass

Esta estructura nos proporciona una hoja de ruta clara: inicialización, resolución de problemas, manejo de archivos, generación de informes e interacción con el usuario. Cada método tiene una responsabilidad específica en nuestra cadena de resolución de problemas matemáticos.

Construir un solucionador matemático con Claude Sonnet 4 Ejecución del código

Ahora, vamos a implementar la funcionalidad básica utilizando la herramienta de ejecución de código de Claude y las respuestas en streaming.

Paso 2: Inicializar Claude con cabeceras API seguras

Implementemos el método __init__() para gestionar la configuración del cliente API y la creación del directorio.

En primer lugar, nos encargamos de la gestión de las claves API:

def __init__(self, api_key: str = None):
   """Initialize the Math Solver with Anthropic client."""
   if not api_key:
       api_key = os.getenv("ANTHROPIC_API_KEY")
       if not api_key:
           raise ValueError(
               "Please set ANTHROPIC_API_KEY environment variable or provide api_key"
           )

A continuación, configuramos el cliente Anthropic con las cabeceras beta necesarias:

# Initialize client with both code execution and files API headers
   self.client = Anthropic(
       api_key=api_key,
       default_headers={
           "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"
       },
   )

Por último, creamos la estructura de directorios de salida:

# Create organized output directories
   self.output_dir = Path("math_solver_output")
   self.images_dir = self.output_dir / "images"
   self.reports_dir = self.output_dir / "reports"

   self.output_dir.mkdir(exist_ok=True)
   self.images_dir.mkdir(exist_ok=True)
   self.reports_dir.mkdir(exist_ok=True)

   print(f"📁 Output directories created:")
   print(f"   • Images: {self.images_dir}")
   print(f"   • Reports: {self.reports_dir}")

Esta inicialización hace tres cosas importantes:

1. Gestión de claves API: Comprueba primero la clave en las variables de entorno y luego recurre a un parámetro.
2. Configuración del cliente: Crea un cliente Anthropic con cabeceras beta para la ejecución de código y archivos API.
3. Estructura del directorio: Crea carpetas organizadas para almacenar imágenes e informes.

Paso 3: Escribe la función principal del solucionador

El método solve_problem() es el corazón de nuestra aplicación. Envía peticiones a Claude con soporte de streaming.

Empecemos por la firma de la función y la configuración inicial:

def solve_problem(self, question: str) -> Dict[str, Any]:
   """
   Send a math question to Claude and get solution with code execution.
   """
   print(f"\n🤔 Thinking about: {question}")

   try:
       # Use streaming to show real-time progress
       with self.client.messages.stream(
           model="claude-sonnet-4-20250514",
           max_tokens=4096,
Now we configure the message and tool specification:
messages=[
               {
                   "role": "user",
                   "content": f"""Solve this math problem using code execution:

Problem: {question}

Please:
1. Solve the problem with actual Python code
2. Create visualizations using matplotlib if helpful
3. Save any plots as PNG files using plt.savefig()
4. Show your calculations step by step
5. Use descriptive filenames for saved plots

Execute Python code to solve this problem.""",
               }
           ],
           tools=[{"type": "code_execution_20250522", "name": "code_execution"}],
       ) as stream:
The streaming event processing handles real-time updates:
print("\n💭 Claude is working...")

           # Process streaming events and show progress
           for event in stream:
               if event.type == "content_block_start":
                   if hasattr(event.content_block, "type"):
                       if event.content_block.type == "text":
                           print("\n📝 Response:", end=" ", flush=True)
                       elif event.content_block.type == "server_tool_use":
                           print(f"\n🔧 Using tool: {event.content_block.name}")

Gestionamos distintos tipos de eventos de streaming:

	elif event.type == "content_block_delta":
                   if hasattr(event.delta, "text"):
                       print(event.delta.text, end="", flush=True)

               elif event.type == "content_block_stop":
                   print("", flush=True)  # New line

               elif event.type == "message_delta":
                   if hasattr(event.delta, "stop_reason"):
                       print(f"\n✅ Completed: {event.delta.stop_reason}")

Por último, devolvemos el resultado o gestionamos los errores:

	# Get the final message
           final_message = stream.get_final_message()

           return {
               "response": final_message,
               "question": question,
               "timestamp": datetime.datetime.now().isoformat(),
           }

   except Exception as e:
       print(f"❌ Error solving problem: {e}")
       return None

Esta función demuestra varios conceptos importantes:

• Compatible con streaming: Utilizamos client.messages.stream() en lugar de client.messages.create() para obtener información en tiempo real mientras Claude resuelve el problema.
• Gestión de eventos: La API de streaming envía diferentes tipos de eventos:
• content_block_start: Cuando Claude empieza a escribir un texto o a utilizar una herramienta
• content_block_delta: A medida que se generan contenidos
• content_block_stop: Cuando termina un bloque de contenido
• message_delta: Cuando el mensaje esté completo
• Especificación de la herramienta: Incluimos la herramienta de ejecución de código en el arreglo tools con el tipo exacto "code_execution_20250522".
• Estimulación estructurada: Nuestro aviso indica claramente a Claude que utilice la ejecución de código y guarde las visualizaciones.

Paso 4: Resuelve problemas matemáticos con la ejecución de código en streaming

Cuando Claude crea archivos durante la ejecución del código (como los gráficos de matplotlib), tenemos que extraer sus ID de archivo y descargarlos localmente.

El método de extracción de archivos navega por la estructura de respuesta:

def extract_files_from_response(self, response) -> List[str]:
   """Extract file IDs from Claude's response."""
   file_ids = []

   for item in response.content:
       if item.type == "code_execution_tool_result":
           content_item = item.content
          
           if isinstance(content_item, dict):
               if content_item.get("type") == "code_execution_result":
                   content_list = content_item.get("content", [])

Luego buscamos los ID de archivo en el contenido:

  for file_item in content_list:
                       if isinstance(file_item, dict) and "file_id" in file_item:
                           file_ids.append(file_item["file_id"])

   return file_ids

El proceso de descarga recupera los archivos y los guarda localmente:

def download_files(self, file_ids: List[str]) -> List[str]:
   """Download files created by code execution to local storage."""
   downloaded_files = []

   for file_id in file_ids:
       try:
           # Get file metadata and download content
           file_metadata = self.client.beta.files.retrieve_metadata(file_id)
           filename = file_metadata.filename
          
           file_content = self.client.beta.files.download(file_id)
           local_path = self.images_dir / filename
           file_content.write_to_file(str(local_path))

Hacemos un seguimiento de los archivos descargados y gestionamos los errores:

downloaded_files.append(str(local_path))
           print(f"✅ Downloaded: {filename}")

       except Exception as e:
           print(f"❌ Error downloading file {file_id}: {e}")

   return downloaded_files

• Lógica de extracción de archivos: El método extract_files_from_response() navega por la estructura de la respuesta para encontrar los identificadores de los archivos. Los resultados de la ejecución del código se anidan en un formato específico en el que los archivos aparecen en el arreglo content.
• Proceso de descarga de archivos: El método download_files():
• Obtiene los metadatos de cada archivo (incluido el nombre original del archivo)
• Descarga el contenido del archivo utilizando la API de archivos
• Guarda los archivos en nuestra estructura de directorios organizada
• Devuelve una lista de rutas de archivos locales para su uso posterior