Creación de tu primer agente gestionado
Si alguna vez has construido un bucle de agente a mano, ya conoces el procedimiento: bucles while, cambios según la razón de parada, ejecuciones de herramientas. Eso funciona, y para muchas funciones es, de hecho, la forma correcta. Pero a veces ese bucle va a ejecutarse durante mucho tiempo — minutos, quizás incluso horas — a través de muchas herramientas, con un estado que mantener, archivos que escribir y trabajo que reanudar tras un contratiempo de red. En ese punto, no quieres ejecutar el bucle en tu servidor. Quieres delegarlo. Eso es lo que son los agentes gestionados.
¿Qué es un agente gestionado?
Un agente gestionado es un bucle de agente que se ejecuta en la infraestructura de Anthropic en lugar de la tuya. Describes el agente una vez, le das un entorno en el que trabajar, e inicias una sesión. Anthropic ejecuta el bucle, y tú simplemente transmites los eventos de vuelta a medida que trabaja.
Los agentes gestionados están habilitados de forma predeterminada para cada cuenta de API — no se necesita acceso especial.
Las cuatro primitivas
Hay cuatro primitivas, y vienen en orden:
- Agent — la persona: el modelo, la indicación del sistema y el conjunto de herramientas. Esto es reutilizable en muchas ejecuciones.
- Environment — dónde se ejecuta el agente: en la nube o autoalojado, configuración de red, etc.
- Session — una única ejecución de un agente dentro de un cierto entorno. La sesión es la unidad de trabajo.
- Events — los mensajes que fluyen de entrada y salida: las acciones del agente, las llamadas a herramientas, los resultados, las respuestas.
Así es como encajan las piezas: tu aplicación habla con una sesión, la sesión impulsa el trabajo dentro del entorno, y todo lo que ocurre fluye de vuelta a través del flujo de eventos:

Observa el cambio aquí: no estás ejecutando un bucle while. Estás enviando eventos y leyendo eventos.
El agente gestionado más pequeño posible
Construyamos el agente gestionado más pequeño que haga algo útil: crear un archivo en la unidad temporal, contar sus líneas e informar de vuelta.
Para las herramientas, usaremos el conjunto de herramientas del agente — las herramientas de archivos, bash y web incluidas por Anthropic. Funcionan bien para esta tarea, así que no tenemos que definir ninguna herramienta nosotros mismos.
Paso 1: Crear el agente
Primero, creamos el agente. Observa el conjunto de herramientas del agente definido directamente en el array tools — ese es el conjunto de herramientas incluido:
import anthropic
client = anthropic.Anthropic()
agent = client.beta.agents.create(
name="Line Counter",
model="claude-opus-5",
system="You are a helpful agent that completes small file tasks.",
tools=[
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}
],
)Recuerda: el agente es reutilizable. Créalo una vez y ejecútalo a través de muchas sesiones.
Paso 2: Crear el entorno
A continuación, el entorno. Define el sandbox en el que se ejecuta tu agente: en la nube, con red limited. Con limited, el sandbox y las herramientas web solo alcanzan los hosts que enumeres en allowed_hosts. Esta tarea no necesita red, así que no enumeramos ninguno. Usa unrestricted solo cuando el agente deba alcanzar sitios que no puedas enumerar de antemano. Cada sesión obtiene su propio sandbox, y ahí es donde se escribe el archivo:
environment = client.beta.environments.create(
name="line-counter-env",
config={
"type": "cloud",
"networking": {"type": "limited"},
},
)Paso 3: Crear la sesión
Luego creamos una sesión con nuestro agente y entorno, más un título opcional. La sesión es la unidad de trabajo:
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Count lines demo",
)Paso 4: Abrir el flujo, luego enviar el inicio
Ahora abrimos el flujo de eventos — y observa que hacemos esto primero. El flujo solo entrega eventos que ocurren después de que se abre, así que siempre ábrelo antes de enviar el mensaje de inicio. Luego enviamos el mensaje del usuario al flujo en vivo:
with client.beta.sessions.events.stream(session_id=session.id) as stream:
# El stream está abierto: ahora envía el inicio
client.beta.sessions.events.send(
session_id=session.id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Create a file in the temp directory, "
"count its lines, and report back.",
}
],
}
],
)Observa que es events — en plural. Los eventos son cómo fluye todo en esta API.
Paso 5: Consumir el flujo
Finalmente, consumimos el flujo, todavía dentro del bloque with del paso 4. Hay tres tipos de eventos que importan para esta demostración:
agent.message— el texto de Claudeagent.tool_use— qué herramienta eligió Claudesession.status_idle— el agente se ha detenido y está esperando entrada
Esta demostración se detiene en el primer evento idle. En tu propia aplicación, verifica event.stop_reason.type antes de tratar el trabajo como terminado: end_turn significa que el agente terminó su turno o lo interrumpiste, y requires_action significa que una llamada a herramienta necesita una respuesta de tu parte.
for event in stream:
if event.type == "agent.message":
for block in event.content:
if block.type == "text":
print(block.text, end="", flush=True)
elif event.type == "agent.tool_use":
print(f"\n[tool] {event.name}")
elif event.type == "session.status_idle":
print("\n--- Agent done ---")
breakEjecútalo, y la salida es el agente razonando en voz alta — texto real, las herramientas que elige, y una respuesta final. Todo ello ejecutándose dentro del contenedor de Anthropic, no del tuyo:

El intercambio
Normalmente con los agentes, tenemos nuestro propio bucle en el que tenemos que controlar todo. Con los agentes gestionados, delegas ese bucle, el sandbox y la capacidad de reanudación — y simplemente consumes el flujo de eventos a medida que llega. El historial de eventos de la sesión se almacena en el servidor. Así que si tu conexión se cae, abre un nuevo flujo, enumera los eventos pasados para ver lo que te perdiste, y omite cualquier evento en vivo que la lista ya haya devuelto. Consulta Reconectar sin perder eventos(se abre en una pestaña nueva) para ver el código.
En una aplicación de producción, esta es la forma para tareas de larga duración que tocan archivos, del tipo "ve a organizarme esto". Imagina una limpieza de un recurso compartido de archivos: un agente gestionado lee una especificación de estructura de directorio de destino, recorre la carpeta de entrada desordenada, mueve archivos a las carpetas de proyecto correctas, archiva duplicados y basura de cero bytes, y marca cualquier cosa que no pueda colocar con confianza — todo en una sesión que puede ejecutarse durante minutos contra miles de archivos. Así es como se ve eso en una aplicación real — un panel de limpieza de recursos compartidos de archivos que transmite la actividad del agente en vivo mientras clasifica, archiva y marca archivos:

Resumen
- Los agentes gestionados son el bucle de agente, ejecutado para ti — en la infraestructura de Anthropic en lugar de tu servidor.
- El flujo es: crear un agente, crear un entorno, crear una sesión, enviar eventos de entrada, y transmitir eventos de salida.
- El agente (modelo, indicación del sistema, conjunto de herramientas) es reutilizable en varias ejecuciones; la sesión es una única ejecución; los eventos son cómo fluye todo.
- Abre el flujo de eventos antes de enviar tu mensaje de inicio — solo entrega eventos que ocurren después de que se abre.
- Presta atención a tres eventos:
agent.message(texto),agent.tool_use(elecciones de herramientas), ysession.status_idle(detenido y esperando entrada, constop_reason.typeindicando por qué). - Recurre a los agentes gestionados cuando el bucle se ejecutaría durante demasiado tiempo, haría demasiado, o necesitaría sobrevivir a un contratiempo. Recurre a un bucle manual cuando quieras control total.