Ejecuciones de flujos de trabajo

Un workflow (flujo de trabajo) es un programa que un agente escribe para ejecutar muchos agentes y combinar lo que devuelven. Una workflow run (ejecución de flujo de trabajo) es la ejecución de un flujo de trabajo. Dynamic workflows (flujos de trabajo dinámicos) es la función que permite a un agente escribir flujos de trabajo e iniciar ejecuciones. La activas o desactivas con la configuración workflows en el bloque multiagent del agente.

El servidor ejecuta un flujo de trabajo en segundo plano. Sus agentes trabajan en hilos de sesión que el servidor crea a medida que el flujo de trabajo los necesita. Sigues las ejecuciones en el flujo de eventos de la sesión. Solo el agente inicia una ejecución. Ningún evento que envíes termina una; archivar la sesión sí puede hacerlo.

Cómo funcionan los flujos de trabajo dinámicos

El agente que ejecuta la sesión escribe cada flujo de trabajo para el trabajo que describes. Un flujo de trabajo es un programa: ejecuta otros agentes, recopila lo que cada uno devuelve y combina los resultados. De esa manera, el agente puede asumir una tarea demasiado grande para una sola conversación, como la revisión de cientos de documentos. Durante una ejecución, el agente puede seguir trabajando o terminar su turno, y puede consultar el estado de la ejecución.

El diagrama muestra un ejemplo. Cada flujo de trabajo que escribe el agente tiene sus propias fases y agentes. Una ejecución tiene estas capas:

• Ejecución de flujo de trabajo: El servidor ejecuta el flujo de trabajo en segundo plano, como una ejecución de flujo de trabajo. Una sesión puede tener varias ejecuciones abiertas al mismo tiempo.
• Fases: Un flujo de trabajo puede dividir su trabajo en fases. Una fase es una etapa con nombre de la ejecución, como "Read the contracts" (leer los contratos). Sigues el progreso de una ejecución mediante sus eventos de fase.
• Hilos de agente: En una fase, el programa ejecuta agentes. Cada agente trabaja en su propio hilo de sesión, con un prompt que escribió el programa. Un agente en una ejecución puede ser un agente inline, que el propio programa define, o un agente predefinido, que enumeras en workflows.predefined_agents. Para saber qué muestra cada hilo, consulta Los hilos de una ejecución.

El programa puede hacer lo siguiente:

• Ejecutar agentes al mismo tiempo: El programa puede ejecutar muchos agentes al mismo tiempo, lo que se llama "fanning out" (distribución en abanico). En el diagrama, tres agentes leen contratos en la primera fase.
• Pasar resultados de un agente a otro: Cada agente devuelve su resultado al programa. El programa puede pasar ese resultado a otro agente. En el diagrama, el agente de la segunda fase trabaja con lo que devolvieron los tres primeros. Los agentes de una ejecución también trabajan con los mismos archivos, en el sandbox de la sesión.
• Dar el siguiente paso por sí mismo: El resultado de un agente va al programa, no al agente que ejecuta la sesión. El programa determina qué agentes se ejecutan a continuación y escribe sus prompts.
• Repetir y elegir: Dentro de una fase, el programa puede repetir trabajo y elegir su siguiente paso según lo que devolvió un agente. Por ejemplo, puede hacer que se revise un borrador hasta que pase una revisión o se agote un número determinado de rondas. En el diagrama, el programa puede repetir un paso dentro de la segunda fase.
• Manejar un agente que falla: Cuando uno de sus agentes falla, el programa puede manejar el fallo o dejar que termine la ejecución.

Cuando la ejecución termina, el agente que ejecuta la sesión obtiene un turno para leer lo que hizo la ejecución. Luego puede responderte o iniciar otra ejecución. Eventos de ejecución enumera los casos en los que ese turno llega más tarde o no llega.

Puedes orientar cómo una ejecución realiza el trabajo, por ejemplo cómo divide el trabajo y qué hace cuando un agente falla. Consulta Indicarle al agente cuándo usar una ejecución.

Cómo pasa una ejecución por sus estados

Una ejecución comienza en ejecución o inactiva. Alcanzar el presupuesto, por ejemplo, pausa una ejecución en curso, lo que la deja inactiva; aumentar o eliminar el presupuesto hace que vuelva a ejecutarse, a menos que una interrupción también la haya pausado. Una ejecución en curso termina cuando su flujo de trabajo finaliza, el agente la detiene, falla, se cumple su tiempo de vida o la sesión se archiva. Una ejecución inactiva también puede terminar, por ejemplo cuando el agente la detiene o la sesión se archiva.

Una ejecución está abierta desde su evento workflow_run.created hasta su evento workflow_run.status_ended, ya sea que esté en ejecución o inactiva. Una ejecución está inactiva mientras está pausada, por ejemplo al alcanzar el presupuesto de la sesión. El tiempo de vida de una ejecución es de 24 horas de forma predeterminada. El agente puede establecer un tiempo de vida más corto cuando inicia la ejecución. El tiempo que una ejecución pasa esperando a tu cliente cuenta para ese tiempo de vida. Una pausa no impide que transcurra el tiempo de vida de una ejecución, por lo que una ejecución que permanece pausada puede terminar con timeout_error. Los siguientes eventos informan el inicio de una ejecución, sus fases y su final. Una pausa al alcanzar el presupuesto también envía uno. Una pausa después de una interrupción podría no enviar ninguno. Cada evento workflow_run.* incluye workflow_run_id, que es null solo en un workflow_run.error cuando no se creó ninguna ejecución.

Eventos de ejecución

Los eventos de ejecución llegan al flujo de eventos de la sesión, que es el flujo del hilo principal, y listar los eventos de la sesión también los devuelve. Los eventos de ejecución no activan webhooks. Los eventos de estado de los hilos de la ejecución llegan al mismo flujo. Cada uno nombra su hilo en session_thread_id, y los hilos de una ejecución son aquellos cuyo evento session.thread_created tenía el workflow_run_id de la ejecución.

Un resultado de error tiene el aspecto {"type": "error", "error": {"type": "timeout_error", "message": "..."}}, donde es seguro registrar message. Trata un result.type no reconocido como una ejecución que terminó de alguna otra manera, y un error.type no reconocido como un error. Cuando falla algo de lo que depende la sesión, como el modelo, un servidor MCP, las credenciales o la facturación, el flujo del hilo que falla recibe un session.error. Eso no termina una ejecución por sí solo. Pero si hace que falle uno de los hilos de la ejecución, y el flujo de trabajo deja que eso termine la ejecución, la ejecución termina con program_error.

Por ejemplo, le preguntas al agente de revisión de contratos cuáles de 300 contratos tienen una cláusula de cambio de control, y el agente inicia una ejecución:

1. workflow_run.created nombra la ejecución "Find change-of-control clauses" y enumera las fases "Read the contracts" y "Reconcile the findings" en phases. Luego sigue workflow_run.status_running.
2. Los eventos de fase marcan cada fase, y cada hilo que crea la ejecución envía session.thread_created con el workflow_run_id de la ejecución.
3. workflow_run.status_ended llega con result: {"type": "completed"}.
4. El agente responde: "41 de los 300 contratos tienen una", y session.status_idle llega con end_turn.

El primer evento de la ejecución enumera sus fases:

{
  "type": "workflow_run.created",
  "id": "sevt_01abc...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "name": "Find change-of-control clauses",
  "description": "Reads each contract and lists those that have the clause.",
  "phases": [
    {
      "id": "wrph_01Kd3a1f3",
      "name": "Read the contracts",
      "description": "Reads each contract for the clause."
    },
    { "id": "wrph_01Kd3b7c9", "name": "Reconcile the findings", "description": null }
  ],
  "processed_at": "2026-10-09T14:01:45Z"
}

Cada evento de fase nombra su fase mediante workflow_run_phase_id. Ese es un id en phases, pero la API no lo garantiza:

{
  "type": "workflow_run.phase_started",
  "id": "sevt_01def...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "workflow_run_phase_id": "wrph_01Kd3a1f3",
  "processed_at": "2026-10-09T14:01:46Z"
}

El último evento de la ejecución informa cómo terminó:

{
  "type": "workflow_run.status_ended",
  "id": "sevt_01ghi...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "result": { "type": "completed" },
  "processed_at": "2026-10-09T14:09:12Z"
}

Los hilos de una ejecución

Cada agente de una ejecución trabaja en su propio hilo de sesión, que el servidor crea a medida que el flujo de trabajo lo necesita. Puedes listar, leer y hacer streaming de los hilos de una ejecución como con cualquier hilo hijo, y responder a sus llamadas a herramientas desde el flujo principal. Para detenerlos, pídele al agente que detenga la ejecución (consulta Interrumpir una sesión con ejecuciones abiertas). No puedes detener uno por su ID, ni archivar uno mientras su ejecución está abierta.

• Agrupación: El hilo de una ejecución lleva el workflow_run_id de la ejecución, al igual que el evento session.thread_created que lo anuncia. Los demás hilos, y los eventos session.thread_created que los anuncian, tienen workflow_run_id establecido en null.
• Agente: agent muestra el agente que ejecuta el hilo. Para un agente que enumeraste en multiagent.workflows.predefined_agents, agent tiene el id y la version de ese agente, como en el hilo de un subagente que enumeraste. Para un agente que define el flujo de trabajo (un agente inline), agent tiene type inline y no tiene id ni version. Tiene la indicación del sistema que escribió el flujo de trabajo, no la del agente de la sesión. También tiene el nombre y la descripción que le dio el flujo de trabajo; el servidor asigna un nombre si el flujo de trabajo no le dio ninguno. Usa el modelo del agente de la sesión, el agente que ejecuta la sesión. Sus herramientas, servidores MCP y skills son un subconjunto de los del agente de la sesión. Los recibe todos, pero la API no lo garantiza. Sus herramientas conservan sus políticas de permisos.
• Lo que comparten los hilos: Los hilos de una ejecución trabajan en el sandbox de la sesión, por lo que todos los hilos trabajan con los mismos archivos. Eso incluye los archivos de un almacén de memoria que monta la sesión. Un agente que define el flujo de trabajo usa sus servidores MCP con las credenciales que la sesión resuelve para ellos. Cada hilo tiene su propio historial de conversación.
• Eventos: Los eventos session.thread_created, session.thread_status_running, session.thread_status_idle y session.thread_status_terminated de un hilo de ejecución también llegan al flujo principal (consulta Eventos de ejecución). Sus eventos de mensaje permanecen en su propio flujo. Sus webhooks de hilo se envían como para cualquier hilo hijo. Para saber qué registra el propio flujo del hilo, consulta Eventos del hilo de sesión.
• Fases: Ningún evento ni campo indica en qué fase trabaja un hilo, y los hilos de una misma ejecución pueden tener el mismo agent_name. Sigue el progreso de una ejecución mediante sus eventos de fase, y distingue sus hilos por session_thread_id.
• Límite de hilos: Los hilos de una ejecución están exentos del límite de hilos hijos de la sesión.
• Inicio de ejecuciones: Solo el agente del hilo principal de la sesión inicia ejecuciones. Un agente que trabaja en el hilo de una ejecución no puede iniciar una ejecución propia, por lo que las ejecuciones no se anidan.
• Archivado: El servidor archiva cada hilo a más tardar al final de su ejecución. Puede archivar uno antes, una vez que el hilo devuelve su resultado o la ejecución termina con él. Si en ese momento el hilo sigue en ejecución o esperando a tu cliente, el servidor lo detiene primero. Un hilo archivado permanece en la lista de hilos, con estado terminated. No necesitas archivar tú mismo los hilos de una ejecución. Mientras la ejecución está abierta, una solicitud para archivar uno que el servidor aún no ha archivado devuelve 400 con error.details.error_code: "workflow_run_open".
• Visibilidad: No ves el código del flujo de trabajo, pero puedes pedirle al agente el flujo de trabajo, como describe el consejo que sigue a esta lista. Tampoco ves las llamadas a herramientas que hace el agente para iniciar y gestionar ejecuciones, ni el resultado que cada hilo devuelve al flujo de trabajo.

Saber cuándo termina el trabajo

Mientras una ejecución está en curso, espera que la sesión permanezca running, incluso cuando ninguno de sus hilos está trabajando. Pasa a idle con requires_action cuando ningún hilo está trabajando y un hilo espera a tu cliente. Un estado inactivo por sí solo no significa que el trabajo haya terminado. El trabajo termina cuando se cumplen ambas condiciones:

1. Cada ejecución que has visto crearse tiene su workflow_run.status_ended.
2. Después de eso, llega un session.status_idle con stop_reason end_turn, y no lo causó una solicitud tuya, como una interrupción. Después de interrumpir, cuenta solo un estado inactivo que llegue después de tu siguiente user.message o user.define_outcome.

• Ejecuciones pausadas: Una ejecución pausada no mantiene la sesión en running, por lo que la sesión puede quedar inactiva mientras la ejecución sigue abierta. Al alcanzar el presupuesto, por ejemplo, la sesión queda inactiva con budget_reached. El trabajo no termina hasta que termina la ejecución.
• Otra ejecución: El agente puede iniciar una nueva ejecución cuando lee un resultado, así que vuelve a comprobarlo.
• "Outcomes" (resultados): Si definiste un resultado, no comienza ninguna evaluación mientras una ejecución está abierta, ya sea en ejecución o inactiva. El turno en el que el agente lee el resultado de la ejecución puede iniciar una.
• retries_exhausted: El turno del agente falló por un error: se agotaron los reintentos, o el error no se puede reintentar, como un fallo de facturación. Una ejecución podría seguir en curso cuando llega este estado inactivo. Si una ejecución terminó y el agente aún no ha leído su resultado, el servidor inicia un nuevo turno sin ninguna entrada tuya. La sesión vuelve a running, así que espera al siguiente estado inactivo. Si la sesión permanece inactiva, lee el session.error que llegó antes y corrige la causa. Luego envía un user.message, o lee tú mismo el result de cada ejecución.

Seguir una ejecución

Este ejemplo sigue una sesión desde tu mensaje hasta la respuesta del agente. Abre el flujo y envía el mensaje. Luego hace lo siguiente:

• Registra cada ejecución desde su workflow_run.created hasta su workflow_run.status_ended, e imprime cada fase cuando comienza.
• Responde a las llamadas a herramientas personalizadas cuando llega cada agent.custom_tool_use, porque el hilo de una ejecución puede esperar a tu cliente mientras la sesión permanece running. Si las herramientas de tu agente piden confirmación, agrega una rama que responda a cada agent.tool_use o agent.mcp_tool_use cuyo evaluated_permission sea ask. El ejemplo no tiene ninguna, porque una rama que permita todas las llamadas convertiría always_ask en permitir siempre.
• Se detiene cuando el trabajo termina: no hay ninguna ejecución abierta y la sesión queda inactiva con end_turn. También se detiene si la sesión termina. En un estado inactivo con cualquier otro motivo de detención excepto requires_action, como budget_reached, retries_exhausted o refusal, imprime el motivo y se detiene, así que maneja esos casos en tu propio código. Se detiene en retries_exhausted incluso cuando el servidor está a punto de iniciar un nuevo turno por sí mismo. Sigue esperando en requires_action, y en end_turn mientras una ejecución está abierta.

open_runs: dict[str, str] = {}  # workflow_run_id -> run name
phase_names: dict[tuple[str, str], str] = {}  # (run ID, phase ID) -> phase name

# Abre primero el stream y luego envía el mensaje del usuario
with client.beta.sessions.events.stream(session_id) as stream:
    client.beta.sessions.events.send(
        session_id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Which contracts in /contracts have a change-of-control clause?",
                    },
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "workflow_run.created":
                open_runs[event.workflow_run_id] = event.name
                for phase in event.phases:
                    phase_names[event.workflow_run_id, phase.id] = phase.name
                print(f"Run started: {event.name}")
            case "workflow_run.phase_started":
                phase_id = event.workflow_run_phase_id
                key = (event.workflow_run_id, phase_id)
                print(f"  Phase: {phase_names.get(key, phase_id)}")
            case "workflow_run.status_ended":
                name = open_runs.pop(event.workflow_run_id, event.workflow_run_id)
                print(f"Run ended: {name} ({event.result.type})")
            case "agent.custom_tool_use":
                # Responde cuando llegue el evento. El hilo de una ejecución puede esperar a tu
                # cliente mientras la sesión sigue en ejecución.
                result = call_tool(event.name, event.input)
                try:
                    client.beta.sessions.events.send(
                        session_id,
                        events=[
                            {
                                "type": "user.custom_tool_result",
                                "custom_tool_use_id": event.id,
                                "content": [{"type": "text", "text": result}],
                            },
                        ],
                    )
                except anthropic.BadRequestError as error:
                    # El servidor rechaza un resultado que llega demasiado tarde, después de que
                    # archivó el hilo de la llamada. Sigue la ejecución.
                    print(f"  Answer to {event.name} refused: {error.message}")
            case "session.status_idle":
                # Termina cuando todas las ejecuciones han finalizado y el agente ha terminado su turno
                if not open_runs and event.stop_reason.type == "end_turn":
                    break
                # Un idle con requires_action espera a tu cliente, así que sigue leyendo.
                # Ante cualquier otro motivo de parada, imprímelo y detente.
                if event.stop_reason.type not in ("end_turn", "requires_action"):
                    print(f"Session idle: {event.stop_reason.type}")
                    break
            case "session.status_terminated":
                break

Interrumpir una sesión con ejecuciones abiertas

Envía user.interrupt sin session_thread_id, o con el ID del hilo principal. Detiene el turno del agente. No termina ninguna ejecución. Las ejecuciones de la sesión podrían pausarse o seguir en curso, y sus eventos podrían no mostrar cuál de las dos. El tiempo de vida de una ejecución pausada sigue transcurriendo, por lo que la ejecución puede terminar con timeout_error mientras está pausada.

• Llamadas a herramientas en espera: Después de la interrupción, la llamada a una herramienta de un hilo de ejecución podría seguir esperando a tu cliente. Responde a cada una. Para cancelar una llamada que pide confirmación, deniégala. Para cancelar una llamada a una herramienta personalizada, envía un resultado con is_error establecido en true y un texto en content que explique por qué. Mientras la sesión está idle con requires_action, un user.message devuelve 400, así que responde primero a las llamadas.
• Para detener las ejecuciones: Envía un user.message pidiéndole al agente que detenga sus ejecuciones. Una ejecución detenida termina con result {"type": "stopped"}. Mientras la sesión está idle con budget_reached, un user.message devuelve 400 hasta que aumentes o elimines el presupuesto. Aumentarlo o eliminarlo también reanuda las ejecuciones que el presupuesto pausó, a menos que la interrupción también las haya pausado.
• Para continuar: Envía un user.message pidiéndole al agente que continúe sus ejecuciones. Después de una interrupción, las ejecuciones podrían esperar este mensaje. Si la sesión está idle con budget_reached, primero aumenta o elimina el presupuesto.
• Resultados de las ejecuciones: Una ejecución que termina después de la interrupción sigue enviando workflow_run.status_ended.

Mientras una ejecución está abierta

Reconstruir el estado de la ejecución después de reconectarte

Reconstruye el estado de cada ejecución a partir de los eventos de la sesión. El flujo no reproduce lo que te perdiste: una nueva conexión entrega solo los eventos emitidos después de abrirse. Así que lista los eventos con un filtro types, una entrada types[] por cada tipo de evento, como en Listar eventos anteriores. Pasa el next_page de cada respuesta como page hasta que next_page sea null o no esté presente. workflow_run.created, workflow_run.status_running, workflow_run.status_idle y workflow_run.status_ended dan el estado de cada ejecución, salvo que una ejecución pausada después de una interrupción podría seguir apareciendo como en ejecución. workflow_run.phase_started y workflow_run.phase_ended reconstruyen el progreso. Una ejecución que aún no tiene ningún evento de estado no ha comenzado a ejecutarse. Ningún endpoint lista las ejecuciones.

Presupuestos y límites

Las solicitudes al modelo de una ejecución cuentan para el presupuesto de la sesión. Una ejecución no tiene precio propio. Los tokens que usan sus agentes se facturan como los demás tokens de la sesión, a las tarifas de cada modelo. Para conocer todos los cargos de una sesión, consulta Precios de Claude Managed Agents.

• Uso de una ejecución: Lista los hilos de la sesión y suma los recuentos de tokens en usage de los hilos con el workflow_run_id de la ejecución. La lista incluye los hilos archivados, cuyo estado es terminated, por lo que se cuentan los hilos de una ejecución terminada. Pasa el next_page de cada respuesta como page hasta que next_page sea null o no esté presente, y omite un hilo cuyo usage sea null. Si en su lugar sumas el list_cost de los hilos, el total excluye el tiempo de ejecución de la sesión, y cada cifra se redondea por separado.
• Al alcanzar el presupuesto: Cada ejecución abierta se pausa, y la sesión informa idle con budget_reached, o requires_action si además hay una llamada a herramienta en espera. Cada hilo termina la solicitud al modelo que ya inició, por lo que una ejecución puede superar el presupuesto en una solicitud por cada hilo que esté trabajando. Aumentar o eliminar el presupuesto reanuda las ejecuciones que pausó, a menos que una interrupción también las haya pausado. Si el uso de la sesión incluye un modelo sin precio de lista, solo eliminar el presupuesto lo hace; consulta Modelos sin precio de lista.

El servidor acorta el name de una ejecución o fase a 64 caracteres y su description a 256. El servidor tiene otros límites sobre los flujos de trabajo, y reglas para ellos, que no se enumeran aquí. Lo que ves depende de cuándo el servidor detecta el problema:

Una sesión puede iniciar cualquier número de ejecuciones a lo largo de su vida.

Límites de velocidad

El trabajo de una ejecución cuenta para los "rate limits" (límites de velocidad) que tu organización ya tiene.

Cuando una solicitud al modelo de uno de los hilos de una ejecución alcanza un límite de velocidad, o el modelo está sobrecargado, el propio flujo del hilo puede recibir un session.error de tipo model_rate_limited_error o model_overloaded_error:

• Si su retry_status.type es retrying, el servidor está reintentando la solicitud y el hilo sigue trabajando.
• Si es exhausted, el hilo ha fallado. Si el flujo de trabajo deja que ese fallo termine la ejecución, la ejecución termina con program_error, que no nombra la causa. Lee los eventos de los hilos que fallaron para encontrarla.

El servidor también limita cuánto hacen por minuto todas las sesiones de tu organización. Un hilo que alcanza este límite se detiene, con un session.error en su propio flujo cuyo mensaje nombra un límite de velocidad. Espera un minuto antes de pedirle al agente que continúe.

Una ejecución puede crear más de un hilo para la misma parte del trabajo, así que haz que las herramientas que llaman tus agentes sean seguras de llamar dos veces.