Execution Pipeline
The pipeline is the path one run follows from input to output. Not every run uses every stage, but when a stage runs it should emit events you can see in traces and Studio.
Stages#
1. Engine creates Runner
2. Load session context
3. Retrieve memory
4. Call provider
5. Execute requested tools (approval may pause here)
6. Process handoffs
7. Repeat provider/tools as needed
8. Validate structured output
9. Persist memory
10. Complete run + exportable trace eventsWhy order matters#
| If you reorder… | What breaks |
|---|---|
| Memory after provider | Model answers without context you already paid to store |
| Tools before approval | Side effects escape the gate |
| Output validation after external write | Bad JSON already landed in your DB |
| Handoff outside the runner | Studio / traces miss the transfer |
The runner exists to keep this order honest.
Mapping to code#
| Stage | You configure |
|---|---|
| Session load | execute(..., { sessionId }) |
| Tools | tool() on the agent |
| Approval | requiresApproval on tools |
| Handoff | handoff strategy + registerAgent |
| Structured output | agent output schema |
| Trace export | TraceManager on the engine |
Best practices#
- Trace every stage that mutates state
- Keep tools small so failures pinpoint a stage
- Do not disable approvals in “just this once” production paths
- Validate output before dependent writes
Common mistakes#
- Calling tools in application code between provider calls
- Reading memory only in your route after
executereturns - Treating validation as a UI concern