Creación de tu primer agente administrado
Si has construido un bucle de agente a mano, ya conoces la rutina: bucles while, switches de 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, tal vez incluso horas — a través de muchas herramientas, con estado que mantener, archivos que escribir y trabajo que reanudar después de un contratiempo de red. En ese punto, no quieres ejecutar el bucle en tu servidor. Quieres delegarlo. Eso es lo que son los agentes administrados.
¿Qué es un agente administrado?
Un agente administrado 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 administrados 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:
- Agente — la persona: modelo, indicación del sistema y conjunto de herramientas. Esto es reutilizable en muchas ejecuciones.
- Entorno — dónde se ejecuta el agente: en la nube o autoalojado, configuración de red, etc.
- Sesión — una única ejecución de un agente dentro de un entorno determinado. La sesión es la unidad de trabajo.
- Eventos — 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 sucede 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 administrado más pequeño posible
Construyamos el agente administrado más pequeño que haga algo útil: crear un archivo en la unidad temporal, contar sus líneas e informar el resultado.
Para las herramientas, usaremos el conjunto de herramientas del agente — las herramientas integradas de archivos, bash y web de 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 integrado:
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 en 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 enumeras en allowed_hosts. Esta tarea no necesita red, así que no enumeramos ninguno. Usa unrestricted solo cuando el agente deba alcanzar sitios que no puedes 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 y 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 mensaje inicial
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 — plural. Los eventos son la forma en que todo fluye en esta API.
Paso 5: Consumir el flujo
Finalmente, consumimos el flujo. 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 que lo interrumpiste, y requires_action significa que una llamada a herramienta necesita una respuesta tuya.
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 donde tenemos que controlar todo. Con los agentes administrados, 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 qué 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 y organiza esto por mí". Imagina una limpieza de un recurso compartido de archivos: un agente administrado lee una especificación de estructura de directorios objetivo, 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 ubicar 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 administrados son el bucle del 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 y transmitir eventos de salida.
- El agente (modelo, indicación del sistema, conjunto de herramientas) es reutilizable en todas las ejecuciones; la sesión es una única ejecución; los eventos son la forma en que todo fluye.
- 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 administrados cuando el bucle se ejecutaría demasiado tiempo, haría demasiado, o necesitaría sobrevivir a un contratiempo. Recurre a un bucle manual cuando quieras control total.