​

Herramientas de flujo de trabajo

Las herramientas de flujo de trabajo permiten que un agente llame a una variante de endpoint de un flujo de trabajo implementado durante una ejecución de agente.

​

Descripción general

Agrega una herramienta de flujo de trabajo cuando un agente deba delegar parte de una tarea a un flujo de trabajo existente. Fetch Hive inicia el flujo de trabajo como una ejecución de flujo de trabajo normal, por lo que obtiene su propio ID de solicitud, ID de ejecución del flujo de trabajo, registros del flujo de trabajo y traza de pasos. El agente principal también registra la llamada como un span de herramienta de agente, con la traza del flujo de trabajo anidada bajo esa llamada a herramienta en la traza de la ejecución del agente. Las herramientas de flujo de trabajo usan la última versión activa de la variante del endpoint del flujo de trabajo seleccionado. El esquema de entrada de la herramienta se genera a partir de las declaraciones de entrada del paso inicial del flujo de trabajo, por lo que el modelo puede pasar las mismas entradas de nivel superior que el flujo de trabajo espera de una llamada a la API.

​

¿Cómo agrego una herramienta de flujo de trabajo?

1. Abre el agente principal en el editor de agentes.
2. Haz clic en el botón de agregar herramienta en el encabezado del editor.
3. Elige un endpoint y variante de flujo de trabajo implementado en Workflow Tools.
4. Ingresa el nombre y la descripción de la herramienta que verá el modelo.
5. Guarda la herramienta.

El endpoint y la variante del flujo de trabajo deben pertenecer al mismo espacio de trabajo que el agente. Los nombres de herramienta deben ser únicos entre las herramientas MCP del agente, las herramientas de flujo de trabajo y los subagentes.

​

¿Cómo puede un agente descubrir flujos sin vincular cada uno?

En la configuración del agente, Catálogo de flujos controla si el agente puede listar y ejecutar flujos del espacio de trabajo por sí mismo:

• Ninguno — el agente solo usa las herramientas de flujo que hayas vinculado por separado.
• Explícito — el agente solo usa las herramientas de flujo con nombre que le hayas añadido. No puede descubrir otros flujos del espacio de trabajo.
• Todos los publicados — el agente puede listar y ejecutar cada despliegue de flujo activo del espacio de trabajo, aunque no hayas añadido cada uno como herramienta.

Cuando está seleccionado Todos los publicados, el agente puede llamar a list_workflows para ver los despliegues disponibles y luego a run_workflow para ejecutar uno. Las herramientas de flujo vinculadas siguen funcionando como herramientas con nombre. run_workflow puede esperar al flujo (mode: sync o auto para ejecuciones cortas) o iniciarlo en segundo plano (mode: async). El modo en segundo plano es obligatorio para los flujos que se detienen para una persona, y también se usa automáticamente cuando una ejecución suele tardar dos minutos o más. La herramienta entonces devuelve un estado pendiente para que el turno del agente pueda terminar. Cuando el flujo termina, el agente continúa en la misma conversación con el resultado: no hace falta que sigas conectado.

​

¿Qué veo en el chat mientras un flujo corre en segundo plano?

En Fetch Chat y en el chat de prueba del editor de agentes, un flujo en segundo plano aparece como una tarjeta con el nombre del flujo, un indicador de progreso y la hora en la que suele terminar. Si actualizas la página, la tarjeta permanece en el hilo. Cuando el flujo termina, el agente envía un seguimiento en la misma conversación. Usa Cancelar en la tarjeta si ya no necesitas la ejecución. Si invocas un agente desde tu propia app sin un hilo de conversación, los flujos en segundo plano permanecen desactivados salvo que lo actives:

• Pasa thread_id para que el agente pueda continuar en esa conversación, o
• Pasa async.callback_url para recibir un webhook firmado agent.delegation.completed, o
• Establece async.allow_background en true y consulta GET /v1/agent/delegations/{id}.

Cuando un turno inicia trabajo en segundo plano, la respuesta incluye pending_delegations con el id, el tipo, el destino y expected_by de cada delegación. Puedes cancelar una ejecución en curso con POST /v1/agent/delegations/{id}/cancel. Lista el trabajo en segundo plano abierto de una conversación con GET /v1/agent/threads/{thread_id}/delegations. Las solicitudes de callback usan las mismas cabeceras HMAC que el resto de callbacks de Fetch Hive (X-Fetch-Hive-Signature, X-Fetch-Hive-Timestamp, X-Fetch-Hive-Webhook-Id). Verifícalas con el secreto de firma del agente. Consulta Entrega con callback y disparadores webhook.

​

¿Qué se registra?

Cada llamada a una herramienta de flujo de trabajo crea dos registros vinculados:

• Una ejecución de flujo de trabajo normal con su propio ID de solicitud e ID de ejecución del flujo de trabajo.
• Una llamada a herramienta del agente principal con metadatos que identifican la herramienta de flujo de trabajo y la ejecución hija del flujo de trabajo.

Puedes inspeccionar el flujo de trabajo hijo desde los registros del flujo de trabajo exactamente como cualquier otra invocación de flujo de trabajo. En la traza del agente, el span de la herramienta principal se llama agent.tool.workflow, y los spans del flujo de trabajo hijo se adjuntan debajo de ese span.

​

¿Cuándo debo usar herramientas de flujo de trabajo?

Usa herramientas de flujo de trabajo cuando el trabajo delegado ya esté modelado como un flujo de trabajo, especialmente si incluye múltiples pasos deterministas, ramificaciones, integraciones o registro reutilizable específico del flujo de trabajo. Usa subagentes cuando el trabajo delegado deba ser manejado por otro agente con sus propias instrucciones y conjunto de herramientas.