What Is a Workflow?
A workflow is a directed graph composed of nodes and edges. Nodes represent discrete steps in a conversation. Edges represent transitions between steps, optionally conditioned on data from the previous node. You author a workflow by writing structured instructions — natural language descriptions of each step, what the agent should do, and when to move on. Feather’s compiler translates these instructions into acompiled_graph object, which the runtime executes.
A workflow is attached to an agent revision, not directly to an agent. This means your workflow and your agent’s system prompt, tools, and policies are all versioned together. Updating your workflow requires creating and publishing a new agent revision.
The Authoring Model
Write instructions
Create a workflow with a human-readable
instructions block. Describe each step you want the agent to take, in plain language. Reference node types by name to signal what kind of step each one is (e.g. “Ask the user for their order number. This is an agent step.”).Compile the workflow
Call
POST /v1/workflows/revisions/{revision_id}/compile. Feather’s compiler parses your instructions and generates a compiled_graph — a structured JSON representation of all nodes, edges, and conditions.Compilation is asynchronous. Poll compilation_status on the revision until it reaches completed or failed.Review the compiled graph
Inspect the
compiled_graph to verify that Feather interpreted your instructions correctly. You can also visualize the graph in the Feather dashboard’s workflow editor.Attach to an agent revision
Call
POST /v1/agents/revisions/{agent_revision_id}/workflows with the workflow revision ID. The workflow is now active for any conversation that uses this agent revision.Node Types
Feather workflows support four node types, each serving a distinct role in a conversation graph:Agent node
An LLM-powered step. The agent receives instructions, the current conversation context, and any attached tools and knowledge bases. It generates a response and determines the next edge to follow based on the outcome.
Action node
A deterministic, code-like step that executes a specific API call or data transformation without LLM involvement. Use action nodes for reliable, repeatable operations like looking up an order status or sending a confirmation email.
Handoff node
Transfers the conversation to a human agent queue. Execution of the workflow pauses while the conversation status moves to
waiting_for_human. The workflow resumes (or closes) based on your configured resume policy.Approval node
Pauses execution and creates an approval request for a human reviewer. The workflow branches based on the reviewer’s decision — one edge for
approved, another for rejected. Use approval nodes to gate high-stakes actions like issuing refunds or modifying account data.Node configuration
Each node type accepts different configuration fields:Agent node fields
Agent node fields
| Field | Description |
|---|---|
instructions | The system-level guidance for this specific step (appended to the agent’s base system prompt) |
tool_refs | Optional override of which tools are available in this node only |
knowledge_base_refs | Optional override of which KBs are searched in this node only |
exit_conditions | Array of conditions that define which edge to take when the node completes |
Action node fields
Action node fields
| Field | Description |
|---|---|
tool_id | The tool to invoke deterministically |
input_mapping | JSONPath expressions mapping conversation context to tool input fields |
output_mapping | JSONPath expressions mapping tool output to conversation context variables |
on_error | Edge to follow if the tool call fails |
Handoff node fields
Handoff node fields
| Field | Description |
|---|---|
queue_id | The human agent queue to route to |
handoff_message | Optional message shown to the human agent on pickup |
resume_on_return | Whether to continue the workflow after the human returns control (true) or close the conversation (false) |
Approval node fields
Approval node fields
| Field | Description |
|---|---|
approval_prompt | The question shown to the human reviewer |
timeout_hours | How long to wait for a decision before taking the timeout_edge |
approved_edge | Node to transition to on approval |
rejected_edge | Node to transition to on rejection |
timeout_edge | Node to transition to if the timeout elapses |
The Revision Model
Workflows follow the same revision model as agents:| Stage | Description |
|---|---|
| Draft | The workflow revision is editable. You can update instructions and recompile as many times as needed. |
| Compiled | The compiled_graph has been generated. The revision is still in draft but ready to be attached. |
| Attached | The workflow revision has been attached to an agent revision. It cannot be modified while attached. |
Compilation
CallingPOST /v1/workflows/revisions/{revision_id}/compile kicks off the async compilation process. You should poll the revision until compilation_status is no longer pending:
compilation_status | Meaning |
|---|---|
pending | Compilation is queued or in progress |
completed | compiled_graph is populated and ready |
failed | Compilation encountered errors; see compilation_errors |
compiled_graph with the full node and edge definitions. You can inspect this field to verify the structure before attaching the workflow to an agent revision.
The Playground
Before attaching a workflow to a production agent revision, use the workflow playground to run interactive test sessions:live conversations and do not affect end user records.
Next Steps
Workflows API Reference
Full reference for workflow, revision, compilation, and playground endpoints — including complete request schemas and compiled graph examples.