User Guide
Choose A Workflow Style
| Need | Use |
|---|---|
| fixed input-to-output pipeline | chain |
| resumable multi-step business flow | Workflow |
| model may need external actions | agent |
| multiple named values from one input | RunnableMap |
| independent branches | RunnableParallel |
| provider model inside a chain | ModelRunnable |
Chains
Use chains for predictable workflows such as extraction, classification, rewriting, and structured generation.
Typical shape:
input -> prompt -> model -> parser
Agents
Use agents when a response may require one or more tool calls before completion.
Typical shape:
user input -> model -> tool call or final response -> repeat until final
Workflows
Use Workflow when you need explicit step checkpoints and resumability.
Typical shape:
input -> step-1 -> step-2 -> ... -> output
Workflow gives you:
- step snapshots with per-step input/output
resumeStatefor continuing partially completed runs- optional
when(...)conditions for step-level branching
Use Workflow for operational/business orchestration and use runnables/chains for model-centric transformations.
Hooks And Passes
Use agent hooks for lifecycle instrumentation:
hooks.onStart(state)hooks.onEnd(state, result)
Use instruction passes when you need to inspect or transform interpreted agent instructions before execution.
Error Handling
Framework errors include:
ModelErrorToolNotFoundErrorToolValidationErrorMaxStepsExceededErrorPromptTemplateErrorOutputParserError
Handle them at the application boundary and convert them into user-safe responses as needed.
Testing
- test runnables independently
- test parser output shape
- test tool validation failures
- keep end-to-end examples for core flows