Skip to main content
Workflow tools let an agent call a deployed workflow endpoint variant during an agent run.

​
Overview

Add a workflow tool when an agent should hand part of a task to an existing workflow. Fetch Hive starts the workflow as a normal workflow run, so it gets its own request ID, workflow run ID, workflow logs, and step trace. The parent agent also records the call as an agent tool span, with the workflow trace nested under that tool call in the agent run trace. Workflow tools use the selected workflow endpoint variant’s latest active version. The tool input schema is generated from the workflow’s start input declarations, so the model can pass the same top-level inputs that the workflow expects from an API call.

​
How do I add a workflow tool?

  1. Open the parent agent in the agent editor.
  2. Click the add-tool button in the editor header.
  3. Choose a deployed workflow endpoint and variant from Workflow Tools.
  4. Enter the tool name and description the model should see.
  5. Save the tool.
The workflow endpoint and variant must belong to the same workspace as the agent. Tool names must be unique across the agent’s MCP tools, workflow tools, and sub agents.

​
How can an agent discover workflows without binding each one?

In agent settings, Workflow Catalog controls whether the agent can list and run workspace workflows on its own:
  • None — the agent only uses separately bound workflow tools.
  • Explicit — the agent only uses the named workflow tools you added. It cannot discover other workspace workflows.
  • All published — the agent can list and run every active workflow deployment in the workspace, even if you did not add each one as a tool.
When All published is selected, the agent can call list_workflows to see available deployments, then run_workflow to run one. Bound workflow tools still work as named tools. run_workflow can wait for the workflow (mode: sync or auto for short runs) or start it in the background (mode: async). Background mode is required for workflows that pause for a person, and is also used automatically when a run typically takes two minutes or more. The tool then returns a pending status so the agent turn can finish. When the workflow completes, the agent follows up in the same conversation with the result — you do not need to stay connected.

​
What do I see in chat while a workflow runs in the background?

In Fetch Chat and the agent editor test chat, a background workflow appears as a card with the workflow name, an in-progress indicator, and when it is usually expected to finish. Refreshing the page keeps the card in the thread. When the workflow finishes, the agent sends a follow-up in the same conversation. Use Cancel on the card if you no longer need the run. If you invoke an agent from your own app without a conversation thread, background workflows stay off unless you opt in:
  • Pass thread_id so the agent can follow up in that conversation, or
  • Pass async.callback_url to receive a signed agent.delegation.completed webhook, or
  • Set async.allow_background to true and poll GET /v1/agent/delegations/{id}.
When a turn starts background work, the invoke response includes pending_delegations with each delegation id, kind, target, and expected_by. You can cancel an in-progress run with POST /v1/agent/delegations/{id}/cancel. List open background work for a conversation with GET /v1/agent/threads/{thread_id}/delegations. Callback requests use the same HMAC headers as other Fetch Hive callbacks (X-Fetch-Hive-Signature, X-Fetch-Hive-Timestamp, X-Fetch-Hive-Webhook-Id). Verify them with the agent’s signing secret. See Callback Delivery and Webhook Triggers.

​
What gets logged?

Every workflow tool call creates two linked records:
  • A normal workflow run with its own request ID and workflow run ID.
  • A parent agent tool call with metadata that identifies the workflow tool and the child workflow run.
You can inspect the child workflow from workflow logs exactly like any other workflow invocation. In the agent trace, the parent tool span is named agent.tool.workflow, and the child workflow spans are attached below that span.

​
When should I use workflow tools?

Use workflow tools when the delegated work is already modeled as a workflow, especially if it includes multiple deterministic steps, branching, integrations, or reusable workflow-specific logging. Use sub agents when the delegated work should be handled by another agent with its own instructions and tool set.