Curso
Software Development with Claude Code
4 h
6.1K
¿Alguna vez has querido ejecutar un flujo de trabajo al estilo Claude Code desde un script de Python, donde el modelo trabaja en un entorno gestionado con acceso a herramientas, archivos, skills e instrucciones?
Los agentes gestionados de Claude están pensados para este tipo de flujo: te ayudan a crear agentes capaces de realizar tareas de varios pasos en un entorno controlado.
En este tutorial, te mostraré cómo usar Claude Sonnet 5, un modelo reciente de Anthropic diseñado para tareas avanzadas de razonamiento, programación y análisis de datos. Es el motor que permite al agente inspeccionar datos, usar herramientas, escribir y ejecutar código y producir resultados estructurados.
Crearás un agente gestionado, configurarás su entorno, subirás un archivo CSV y le darás acceso a herramientas y a una skill de XLSX.
El agente analizará los datos, generará archivos en Python, JSON y Excel, verificará los resultados y pondrá los entregables finales a tu disposición para su descarga.
Si eres totalmente nuevo en Claude, te recomiendo empezar por el curso Claude Code 101.
¿Qué son los agentes gestionados de Claude?
Los agentes gestionados son el framework gestionado de Anthropic para ejecutar Claude como un agente autónomo.
En lugar de escribir tu propio bucle para enviar prompts, ejecutar llamadas a herramientas, guardar resultados y gestionar la ejecución, defines el agente y dejas que Anthropic se encargue de esa infraestructura.
Está pensado para tareas más largas y de varios pasos, donde el modelo puede necesitar usar varias herramientas antes de completar el trabajo.
Los agentes gestionados se estructuran en cuatro partes principales:
- Agente: la configuración reutilizable que contiene el modelo, el prompt del sistema, las herramientas, los servidores MCP y las skills.
- Entorno: donde se ejecuta el agente, ya sea en el sandbox en la nube de Anthropic o en tu propio sandbox autogestionado.
- Sesión: una instancia en ejecución del agente que realiza una tarea concreta.
- Eventos: los mensajes, llamadas a herramientas, resultados y cambios de estado que se intercambian mientras la sesión está en marcha.
1. Requisitos previos para tu espacio de trabajo con Claude Agent
Para seguir este tutorial, instala Python 3.12 o superior y Jupyter Notebook en tu ordenador. Usaremos un Jupyter Notebook para crear, ejecutar e inspeccionar el agente gestionado paso a paso.
También necesitarás una cuenta en Anthropic Console.
Crea una nueva clave de API en la consola, añade al menos 5 $ en créditos de API y guarda la clave de forma segura.
Los agentes gestionados pueden realizar varias llamadas a modelos y herramientas en una sola sesión, por lo que pueden costar más que una solicitud estándar a la API.
Guarda la clave como una variable de entorno ANTHROPIC_API_KEY en lugar de añadirla directamente al notebook o subirla a GitHub.
En macOS, Linux o WSL, ejecuta esto en tu terminal:
export ANTHROPIC_API_KEY="your-api-key-here"En Windows PowerShell, usa:
$env:ANTHROPIC_API_KEY="your-api-key-here"2. Configura el SDK de Python de Anthropic
Antes de crear un agente gestionado, instala el SDK oficial de Anthropic para Python e importa los módulos necesarios para este notebook.
El SDK ofrece el cliente Anthropic, que usarás para crear agentes, entornos, archivos y sesiones.
%pip install -q --upgrade anthropicA continuación, carga tu clave de API de Anthropic desde una variable de entorno.
Mantener la clave fuera del notebook es más seguro que ponerla directamente en el código, especialmente si vas a compartir el proyecto o subirlo a GitHub.
import os
from anthropic import Anthropic
api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."Actualmente, los agentes gestionados se acceden a través de la API beta de Anthropic. La marca beta managed-agents-2026-04-01 activa esta función, aunque el SDK oficial ya envía automáticamente la cabecera beta requerida para las solicitudes de Managed Agents.
Mantenemos la marca en el notebook porque luego se necesita para listar y descargar archivos de la sesión.
BETA_FLAG = "managed-agents-2026-04-01"
client = Anthropic(api_key=api_key)Por último, crea un diccionario para almacenar los IDs de cada recurso creado durante el tutorial.
Esto incluye el agente, el entorno, el archivo subido y la sesión. Guardar estos IDs facilita la limpieza al final, incluso si un paso posterior falla.
created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")El cliente ya está listo.
3. Crea el agente gestionado
Un agente gestionado es la configuración reutilizable de tu flujo de trabajo.
Al crearlo, eliges el modelo de Claude, escribes el prompt del sistema que define su rol e instrucciones y le adjuntas las herramientas y skills que puede usar.
Luego podrás reutilizar el mismo agente en múltiples sesiones en lugar de recrear la configuración cada vez.
Llamaremos a nuestro agente Sonnet 5 Data Analyst y usaremos claude-sonnet-5.
El prompt del sistema le indica que actúe como un analista de datos meticuloso: que inspeccione los archivos montados en /workspace, utilice la ejecución de código para el análisis, mantenga sus resultados concisos y guarde los archivos finales en /mnt/session/outputs.
agent = client.beta.agents.create(
name="Sonnet 5 Data Analyst",
model="claude-sonnet-5",
system=(
"You are a meticulous data analyst. When asked about data, always read the "
"file mounted at /workspace, analyse it with the code execution tool, and "
"report concise, numeric results. Use the XLSX skill for spreadsheet work. "
"Save final artifacts to /mnt/session/outputs."
),
tools=[
{"type": "agent_toolset_20260401"},
],
skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)El agent_toolset_20260401 da al agente acceso a las herramientas integradas de Anthropic en una sesión, mientras que la skill xlsx le proporciona pautas específicas para crear y analizar libros de Excel.
Anthropic también ofrece skills prediseñadas para flujos de PowerPoint, Word y PDF.
Por último, guarda el ID del agente.
Lo usarás al crear una sesión más adelante, y también permitirá que la sección de limpieza archive el agente cuando termines el tutorial.
created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")Deberías ver una salida similar a:
✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm4. Configura el sandbox en la nube de Anthropic
Ahora crearemos el entorno donde se ejecutará el agente gestionado durante una sesión.
Un entorno actúa como un sandbox seguro, dándole al agente un espacio separado para leer archivos montados, escribir código y ejecutar comandos.
Usaremos el entorno en la nube de Anthropic con redes limitadas. Más adelante, el agente usará este sandbox para analizar con Python el archivo CSV subido.
environment = client.beta.environments.create(
name="code-exec-sandbox",
config={"type": "cloud", "networking": {"type": "limited"}},
)
created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")Tras ejecutar la celda, verás un ID de entorno similar a:
✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf5. Sube datos con la Files API de Anthropic
A continuación, subiremos el conjunto de datos que analizará el agente.
Los agentes gestionados utilizan la Files API de Anthropic para subir archivos locales, que luego pueden montarse dentro del entorno de la sesión.
En esta guía usamos el dataset de ejemplo de 12 filas llamado sales_data.csv.
Antes de subirlo, comprobamos que el archivo existe y confirmamos que contiene el número esperado de filas de datos.
from pathlib import Path
csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"
row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"Luego subimos el archivo y guardamos su ID para limpiarlo después.
uploaded = client.beta.files.upload(file=csv_path)
created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")Tras ejecutar la celda, verás una salida similar a:
✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)6. Inicia una sesión de ejecución del agente
Ahora crearemos una sesión.
Una sesión conecta el agente, el entorno y los recursos que necesita para una tarea específica. Aquí montamos el archivo CSV subido en /workspace/sales_data.csv para que el agente pueda acceder a él desde el sandbox.
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
resources=[
{
"type": "file",
"file_id": uploaded.id,
"mount_path": "/workspace/sales_data.csv",
},
],
)
created["session"] = session.id
print(f"✓ Created session: {session.id}")Deberías ver un ID de sesión similar a:
✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr7. Transmite la respuesta del agente
Ahora enviaremos la tarea a la sesión y transmitiremos en tiempo real la actividad del agente mientras trabaja.
Crear una sesión solo prepara el agente y el sandbox; el agente empieza a trabajar cuando recibe un evento user.message.
La transmisión de eventos nos permite ver en tiempo real los mensajes del agente, las llamadas a herramientas y el estado final de la sesión.
El prompt indica al agente que analice el CSV montado, que escriba y ejecute un script en Python, que cree un resumen en JSON y que construya un informe en Excel.
También creamos tres variables para recopilar el texto del agente, registrar las herramientas que usa y confirmar si la sesión finaliza correctamente.
agent_text_parts = []
tools_used = []
final_status = None
with client.beta.sessions.events.stream(session.id) as stream:
# Send the user message once the stream is open.
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": (
"Use the XLSX skill and analyze /workspace/sales_data.csv. "
"Write /mnt/session/outputs/analyze_sales.py, run that Python "
"script, and have it create /mnt/session/outputs/summary.json. "
"Also create /mnt/session/outputs/sales_report.xlsx with the "
"source data, monthly profit, and a summary sheet."
),
}
],
}
],
)
for event in stream:
etype = getattr(event, "type", None)
if etype == "agent.message":
for block in event.content:
txt = getattr(block, "text", None)
if txt:
print(txt, end="")
agent_text_parts.append(txt)
elif etype == "agent.tool_use":
name = getattr(event, "name", "<tool>")
print(f"\n[tool_use] {name}")
tools_used.append(name)
elif etype == "session.status_idle":
final_status = "idle"
print("\n\n✓ Agent finished; session is idle.")
break
elif etype == "session.status_error":
final_status = "error"
print("\n✗ Session reported an error.")
break
print("Tools used:", tools_used)Durante la ejecución, deberías ver eventos de herramientas como read, bash, write y edit.
Esto indica que el agente está inspeccionando las instrucciones y archivos disponibles, escribiendo el script de análisis, ejecutándolo dentro del sandbox y corrigiendo los problemas que encuentra.
Una sesión queda inactiva cuando el agente no tiene más trabajo que hacer. En este ejemplo, session.status_idle indica que la tarea ha terminado, así que dejamos de escuchar el stream.
Anthropic gestiona la ejecución de sus herramientas integradas dentro del sandbox; solo necesitas manejar tú mismo los resultados de las herramientas cuando uses herramientas personalizadas.
8. Recupera los archivos generados y el historial de eventos
Una vez que la sesión ha terminado, podemos inspeccionar su historial de eventos guardado y descargar los archivos creados por el agente.
El historial de eventos proporciona un registro completo de la sesión, incluidas las solicitudes al modelo, llamadas a herramientas, resultados de herramientas y cambios de estado.
history = client.beta.sessions.events.list(session.id, order="asc")
print("--- Session event history ---")
for event in history.data:
print(event.type)
print(f"({len(history.data)} events total)")
Después, listamos los archivos adjuntos a la sesión y descargamos aquellos marcados como descargables. Los archivos se guardan localmente en una carpeta outputs.
import os
os.makedirs("outputs", exist_ok=True)
files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]
print(f"Found {len(downloadable)} downloadable file(s) for this session.")
downloaded_paths = []
for f in downloadable:
try:
content = client.beta.files.download(f.id, betas=[BETA_FLAG])
local_path = os.path.join("outputs", f.filename)
content.write_to_file(local_path)
downloaded_paths.append(local_path)
print(f" downloaded {f.id} -> {local_path}")
except Exception as exc:
print(f" skip {f.id}: {exc}")Por último, comprobamos que se hayan descargado correctamente todas las salidas esperadas:
expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}
assert expected_outputs <= downloaded_names, (
f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)El script de Python, el resumen en JSON y el informe de Excel generados ya están disponibles en la carpeta local outputs.
9. Analiza las salidas en Python, JSON y Excel
Tras completar la tarea, los archivos generados se descargan en el directorio local outputs/.
Estos archivos demuestran que el agente hizo algo más que devolver texto: escribió y ejecutó código, creó datos estructurados y produjo un informe en hoja de cálculo que puede revisarse de forma independiente.
|
Archivo |
Qué contiene |
Por qué importa |
|
|
El script de Python creado y ejecutado por el agente. Carga el CSV, calcula ingresos, costes, beneficio y márgenes, escribe el resumen en JSON y construye el libro. |
Puedes inspeccionar, modificar o volver a ejecutar el análisis sin depender solo de la respuesta del agente. |
|
|
Totales y medias legibles por máquina, mejores y peores meses y el desglose mensual completo. |
Útil para paneles, APIs, comprobaciones automatizadas o aplicaciones posteriores. |
|
|
Un libro formateado con los datos origen, cálculos de beneficio mensual, fórmulas, hojas de resumen y gráficos. |
Ofrece un informe legible para personas que puedes abrir en Excel o LibreOffice. |
Las capturas de pantalla siguientes muestran los tres artefactos generados.
Este archivo contiene el código de análisis que el agente escribió y ejecutó, lo que hace que el flujo sea reproducible y fácil de inspeccionar.
Este archivo almacena los resultados en un formato estructurado que pueden usar paneles, APIs u otros programas.
Este archivo de Excel presenta visualmente los cálculos mensuales, con ingresos, costes, beneficio, márgenes, totales y un gráfico.
Para las 12 filas de sales_data.csv, los resultados verificados son:
- Ingresos totales: 32.900 $
- Costes totales: 14.750 $
- Beneficio total: 18.150 $
- Beneficio medio mensual: 1.512,50 $
- Mejor mes: diciembre (2.550 $ de beneficio)
- Peor mes: enero (400 $ de beneficio)
El libro está impulsado por fórmulas en lugar de depender solo de valores fijos.
Durante la ejecución, el agente leyó las instrucciones de la skill de XLSX adjunta, creó el libro, lo recalculó con LibreOffice, comprobó las fórmulas y corrigió un problema de referencias circulares antes de completar la tarea.
10. Limpia los recursos de la API de Managed Agents
Los recursos de un agente gestionado permanecen disponibles hasta que los elimines, así que es importante limpiarlos cuando termines la tarea.
Los recursos activos, especialmente las sesiones y entornos en ejecución, pueden seguir generando costes si se dejan abiertos.
Una sesión debe estar inactiva antes de poder eliminarla.
En este último paso, eliminamos la sesión, el archivo subido y el entorno, y después archivamos el agente.
Cada acción de limpieza está envuelta en una función auxiliar para que un fallo al borrar un recurso no impida eliminar el resto.
def safe(label, fn):
try:
fn()
print(f"✓ deleted {label}")
except Exception as exc:
print(f"· could not delete {label}: {exc}")
if created["session"]:
safe("session", lambda: client.beta.sessions.delete(created["session"]))
if created["file"]:
safe("file", lambda: client.beta.files.delete(created["file"]))
if created["environment"]:
safe("environment", lambda: client.beta.environments.delete(created["environment"]))
if created["agent"]:
safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))
print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")Deberías ver una salida similar a:
✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)
🎉 Cleanup complete. The agent is archived; other resources were deleted.El proyecto completo, incluido el notebook, el archivo CSV de ejemplo y las instrucciones de configuración, está disponible en GitHub.
Puedes clonar el repositorio y volver a ejecutar el notebook para reproducir los resultados de esta guía.
Reflexiones finales
Me ha resultado fácil configurar y trabajar con los agentes gestionados de Claude.
Creas un agente, le das las herramientas, skills y el sandbox que necesita, y luego lo ejecutas en una sesión.
A partir de ahí, puede encargarse de un flujo de trabajo completo, como escribir código, crear archivos, verificar sus propias salidas y devolverte los resultados finales.
Primero intenté usar un Modal Sandbox porque quería un entorno externo más flexible.
Sin embargo, la configuración se volvió demasiado compleja para el alcance de esta guía, así que decidí centrar el proyecto en el sandbox en la nube gestionado de Anthropic.
El principal inconveniente para mí fue el coste. Ejecuté este ejemplo dos veces con un CSV pequeño de solo 12 filas y costó alrededor de 0,25 $.
El panel mostraba el cargo bajo el modelo, pero no pude encontrar un desglose detallado. Para un cálculo sencillo y una tarea de hoja de cálculo, parece caro en comparación con opciones de código abierto más económicas.
En conjunto, este proyecto muestra todo el flujo de trabajo con Managed Agents: crear un agente, subir un archivo CSV, ejecutar Python en un sandbox gestionado, generar informes en JSON y Excel, verificar las salidas, descargar los archivos y limpiar los recursos al final.
