Approvals
These cookbooks demonstrate the **@approval** decorator for human-in-the-loop (HITL) approval workflows.
These examples simulate approval decisions with fixed confirmations, rejections, user input, or external results. The deployment, email, payment, and scan demonstrations use placeholder actions. The Hacker News examples make real HTTP requests after confirmation. In an application, obtain the authorized user's decision before updating a requirement or approval record.
There are two continuation paths:
- Explicit requirements: update the paused run's requirements and pass them to
continue_run()oracontinue_run(). This supplies the decision directly; a pending database approval record does not gate that path. Keep its audit record in sync. - Database resolution: resolve the approval record first, then continue by run ID without supplying requirements. Required approvals are checked before execution. See Approval Post Hook for this pattern and its resolved approval metadata.
With @approval(type="audit"), records describe HITL resolution, including rejection and externally supplied results. A record does not establish that the tool body executed or that a real person supplied the decision.
| Example | Description |
|---|---|
| Approval Basic | Approval-backed HITL: @approval + @tool(requires_confirmation=True) with persistent DB record. |
| Approval Async | Async approval-backed HITL: @approval with async agent run. |
| Approval Team | Team-level approval: member agent tool with @approval. |
| Approval List And Resolve | Full approval lifecycle: pause, list, filter, resolve, delete. |
| Approval Post Hook | Resolve the database approval, continue by run ID, and inspect approval metadata in a post-hook. |
| Approval User Input | Approval + user input HITL: @approval + @tool(requires_user_input=True). |
| Approval External Execution | Approval + external execution HITL: @approval + @tool(external_execution=True). |
| Audit Approval Confirmation | Audit approval with confirmation: @approval(type="audit") + @tool(requires_confirmation=True). |
| Audit Approval User Input | Audit approval with user input: @approval(type="audit") + @tool(requires_user_input=True). |
| Audit Approval External | Audit approval with external execution: @approval(type="audit") + @tool(external_execution=True). |
| Audit Approval Async | Async audit approval: @approval(type="audit") + @tool(requires_confirmation=True) with async. |
| Audit Approval Overview | Overview: @approval vs @approval(type="audit") in the same agent. |