Workflows Overview
A workflow is a multi-step pipeline whose every stage is traced. The engine is deliberately minimal: two tables (WorkflowRun, WorkflowStep), three helpers, and plain sequential Python doing the orchestration.
What "workflow" means here
| Concept | Implementation |
|---|---|
| Workflow definition | code in the router — there is no workflow DSL or registry |
| Execution record | WorkflowRun row: name, input, final output JSON, status (running → success/failed), quality score |
| Stage record | WorkflowStep row per stage: name, input/output JSON, status, latency |
| Engine helpers | create_workflow_run (commits immediately), log_workflow_step, log_tool_call in routers/agents.py |
The run is created before any work and committed instantly — so even a hard crash leaves a discoverable running run rather than silence. Success finalizes status + score + a final_output JSON snapshot of everything; failure records the error twice (run + error step). Full failure semantics: Error Handling.
Registered workflows
workflow_name | Endpoint | Stages |
|---|---|---|
multi_agent_email_workflow | POST /agents/{id}/workflows/email | analysis → tasks → reply → review — full walkthrough |
One today; the engine's helpers are generic and ready for the next one (guide: add a workflow-style endpoint).
Reading a trace
curl http://localhost:8001/agents/1/workflow-runs # runs, newest first
curl http://localhost:8001/agents/workflow-runs/1/steps # one run's stages, in orderA healthy run's steps read: analysis_agent → task_agent → reply_agent → reviewer_agent, each with JSON inputs/outputs and latency. A failed run ends with a workflow_error step naming the exception. This is the platform's flight recorder — when a workflow misbehaves, read the trace before the code.
Why plain Python instead of LangGraph here?
The email pipeline has no branching — every stage always follows the last (conditionals like "skip tasks" are simple ifs, not routes). LangGraph is reserved for genuinely conditional flows like corrective RAG. Two orchestration styles, each earning its complexity — the reasoning is laid out in Design Decisions.
Quality scoring
The reviewer stage's 0–1 quality_score lands on the run and averages into the dashboard's average_quality_score — making workflow quality a first-class per-agent KPI (Evaluation).
What the engine does not do (yet)
No async/background execution (the HTTP request holds until all stages finish — several seconds), no retries or resumption of failed runs, no parallel stages, no scheduling. All are natural extensions of the current tables; see the Roadmap.
Related pages
- Email Workflow — the flagship pipeline, stage by stage
- Observability — the tracing contract
- API Reference: Workflows — the endpoints