Why Approval Gates?
Some tools — sending emails, making payments, deleting records — should not auto-execute without human review. The SDK provides two mechanisms to control this:requireApproval— pause execution when the model calls sensitive tools, giving users a chance to approve or reject each callStateAccessor— persist conversation state betweencallModelinvocations so approval decisions, message history, and tool results survive across runs
Tool-Level Approval
AddrequireApproval directly on a tool definition. It accepts a boolean or a function:
Always Require Approval
Conditional Approval
Pass a function to require approval only in certain cases:TurnContext, and can return a boolean or Promise<boolean>. Decide from data you control, such as the record’s environment looked up by ID, not from an argument the model supplies.
Call-Level Approval
Override tool-level settings with arequireApproval callback on callModel itself:
requireApproval settings when both are present, so write it to require approval unless a tool is known to be safe. A callback that lists the tools needing review silently skips review for every tool it does not name.
How the Approval Flow Works
When tools with approval gates are called by the model, the SDK follows this flow:- Model generates tool calls — the model decides which tools to invoke
- SDK partitions tool calls — each call is checked against
requireApprovaland split into two groups: those requiring approval and those that can auto-execute - Auto-execute tools run immediately — tools that don’t need approval execute in parallel as normal
- State saves with pending approvals — the conversation state updates to
status: 'awaiting_approval'with the pending tool calls stored - Control returns to the caller — check
result.requiresApproval()and inspect pending calls withresult.getPendingToolCalls() - Resume with decisions — call
callModelagain with the samestate, passingapproveToolCallsand/orrejectToolCallsarrays of tool call IDs - Approved tools execute — the SDK runs approved tools and sends results to the model. Rejected tools send an error message to the model explaining the rejection
- Conversation continues — the model processes tool results and generates the next response
StateAccessor Interface
TheStateAccessor interface enables any storage backend:
In-Memory Implementation
StateAccessor with a persistent backend like Redis, a database, or file storage to survive process restarts.
ConversationState
The state object tracks everything needed to resume a conversation:Status Values
Serialization & Versioning
ConversationState carries an optional version field that identifies the serialization contract of the blob. createInitialState stamps version: 1; older states without the field are treated as version 1.
StateAccessor.load / save themselves are unchanged. Most callers still round-trip through JSON.stringify / JSON.parse. Use the opt-in helpers when you want typed errors and a migration hook for future serialization changes:
- Treat the serialized JSON as opaque. Do not introspect item shapes across releases.
- Additive field changes are allowed within a major version.
- On version bumps, any migration work runs inside
deserializeConversationState. Consumers using the helpers get forward-compat automatically.
UnsupportedStateVersionError: the blob’sversionisn’t in this SDK build’s supported set. Exposes{ found, supported }for logging or migration routing.InvalidStateError: the payload is malformed JSON or missing required fields (id,messages,status,createdAt,updatedAt).
Complete Example
Here is an end-to-end example showing approval gates with state persistence:Output
Resumption Patterns
Resuming from Approval
When the state hasstatus: 'awaiting_approval', pass approveToolCalls and/or rejectToolCalls to resume:
Resuming from Interruption
If a conversation was interrupted (status: 'interrupted'), calling callModel with the same state resumes automatically. The SDK clears the interruption flag and continues where it left off:
Multi-Run Conversations
Messages accumulate automatically acrosscallModel runs that share the same StateAccessor. Each run appends its input and response to the state’s message history:
Next Steps
- Tools - Tool definitions and the
tool()helper - Stop Conditions - Control when tool execution loops terminate
- Dynamic Parameters - Adjust parameters between turns
- Examples - Complete tool implementations
- Gate Agent Tool Calls with Jev - Decide
approve,block, orreviewper call with a decision model instead of a staticrequireApprovalflag