Skip to main content
Workflows give you precise control over how an assistant navigates a conversation. Instead of relying purely on the LLM to decide what to do next, you describe a sequence of steps and let the assistant follow that graph — executing steps in order and branching on conditions or model decisions. This makes complex, multi-step interactions reliable, auditable, and testable.

​
What is a workflow?

A workflow is a directed graph of steps. You author it by writing natural-language instructions, and Feather’s compiler translates them into a compiled_graph the runtime executes. Steps include model-driven agent steps, deterministic tool/action steps, handoffs to a human, and approval gates. There are two ways a workflow relates to an assistant:
  • Bound flow — every assistant has a workflow provisioned with it. You edit that flow directly on the assistant revision and toggle it with workflow_enabled.
  • Standalone workflow — a reusable workflow (/v1/workflows) you author, compile, and bind independently. Use WorkflowKind component to build reusable pieces and assistant for top-level flows.
A workflow runs as part of an assistant revision, so your flow, system prompt, tools, and policies are versioned together. Changing the flow means editing a revision and activating it — there is no separate “publish” step.

​
Authoring a standalone workflow

1

Create the workflow and a revision

Create a workflow with POST /v1/workflows, then add a revision with POST /v1/workflows/{workflow_id}/revisions. A revision carries an instructions block describing each step in plain language. You can also scaffold one from a brief or template with POST /v1/workflows/generate.
2

Compile the revision

Compilation runs asynchronously. Scaffolding a revision from a brief with POST /v1/workflows/generate enqueues the compile pipeline for you (HTTP 202); pass a compilation_strategy of fast, standard, or strong to trade speed for thoroughness. Poll the revision’s compilation_status until it’s terminal, then review the result below.
3

Review the compiled graph

Inspect compiled_graph (and quality_report/warnings) to confirm Feather interpreted your instructions correctly, or edit it in the dashboard workflow editor. You can also apply incremental edits with POST /v1/workflows/revisions/{revision_id}/graph/ops and validate with .../graph/validate.
4

Bind the revision

Make a revision live with POST /v1/workflows/{workflow_id}/set-active-revision. See which assistants and teams depend on the workflow with GET /v1/workflows/{workflow_id}/dependents.
5

Test in the playground

Run interactive sessions with POST /v1/workflow/playground/sessions before using the workflow in production.

​
Compilation status

Compilation runs as a background task. Poll the revision until compilation_status is terminal:
If compilation fails, check the compilation_errors and warnings fields. Common causes include ambiguous branch conditions, unreachable steps, and references to tools that aren’t on the assistant’s surface. Fix the instructions and recompile.

​
Triggers

A workflow revision declares a trigger_type that controls when it activates within a conversation:

​
The bound flow on an assistant revision

To edit the flow that ships with an assistant, work directly on its revision:
  • GET/PUT /v1/assistants/{agent_id}/revisions/{revision_id}/graph — read or replace the flow’s compiled_graph.
  • POST /v1/assistants/{agent_id}/revisions/{revision_id}/graph/ops — apply incremental graph edits.
  • Set workflow_enabled on the revision to turn the flow on or off.
Both the standalone and bound editors support optimistic locking via base_version so concurrent edits don’t clobber one another.

​
The playground

Before using a workflow in production, run interactive test sessions with the workflow playground (POST /v1/workflow/playground/sessions). You submit turns and observe how the flow traverses steps, which branches it takes, and what each step returns. Playground sessions do not count as production conversations and do not affect end-user records.
Use the playground to walk approval and handoff branches by responding as the human reviewer, so you validate every path before deploying.

​
Next steps

Workflows API reference

Full reference for workflow, revision, compilation, graph, and playground endpoints.