@devries-cameron20 / composio-1 / commits / 1c470b8f4
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add approval mode page

Explains require_approval lists, answering input requests with session.execute(), an Anthropic agent loop that asks the user, answering later in web apps, the MCP fallback and current limitations. Links it from configuring sessions, production readiness and sessions vs direct execution. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Mukund committed Oct 15, 2026 at 14:13 UTC 1c470b8f496aaf66a2203868c6a3181eb19876f5
6 files changed +463 -3
docs/content/docs/approval-mode.mdx new
+455
@@ -0,0 +1,455 @@
1 +---
2 +title: Approval mode
3 +description: Ask the user before your agent runs tools that send, post or delete things on their behalf
4 +keywords: [approval, human in the loop, elicitation, require_approval, input_required, confirmation]
5 +---
6 +
7 +By default, your agent can run any tool in a session as soon as it decides to. For tools that send, post or delete things on your users' behalf, you can configure the session to require the user's approval first.
8 +
9 +When your agent calls a tool that requires approval, Composio doesn't run it. It returns a question for the user instead, and runs the tool once your app sends back their approval.
10 +
11 +<Callout type="warn" title="Experimental">
12 +Approval mode is experimental, and its SDK options may change. Answering questions needs `composio` newer than 0.26.0 (Python) or `@composio/core` newer than 0.23.0 (TypeScript).
13 +</Callout>
14 +
15 +## Requiring approval
16 +
17 +You can configure a session to require the user's approval for certain tools when you create or update it. Add a `require_approval` list to `toolkits`, `tools.<toolkit>` or `tags` (`requireApproval` in TypeScript). For example, this session lets the agent read Gmail freely, but needs approval before it sends anything:
18 +
19 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
20 +<Tab value="Python">
21 +```python
22 +session = composio.create(
23 + user_id="user_123",
24 + toolkits=["gmail"],
25 + tools={"gmail": {"require_approval": ["GMAIL_SEND_EMAIL"]}},
26 +)
27 +```
28 +</Tab>
29 +<Tab value="TypeScript">
30 +```typescript
31 +// @noErrors
32 +import { Composio } from '@composio/core';
33 +const composio = new Composio({ apiKey: 'your_api_key' });
34 +// ---cut---
35 +const session = await composio.create('user_123', {
36 + toolkits: ['gmail'],
37 + tools: { gmail: { requireApproval: ['GMAIL_SEND_EMAIL'] } },
38 +});
39 +```
40 +</Tab>
41 +</Tabs>
42 +
43 +This one needs approval for every Slack tool:
44 +
45 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
46 +<Tab value="Python">
47 +```python
48 +session = composio.create(
49 + user_id="user_123",
50 + toolkits={"enable": ["slack"], "require_approval": ["slack"]},
51 +)
52 +```
53 +</Tab>
54 +<Tab value="TypeScript">
55 +```typescript
56 +// @noErrors
57 +import { Composio } from '@composio/core';
58 +const composio = new Composio({ apiKey: 'your_api_key' });
59 +// ---cut---
60 +const session = await composio.create('user_123', {
61 + toolkits: { enable: ['slack'], requireApproval: ['slack'] },
62 +});
63 +```
64 +</Tab>
65 +</Tabs>
66 +
67 +And this one needs approval for any tool that can delete data, in any toolkit:
68 +
69 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
70 +<Tab value="Python">
71 +```python
72 +session = composio.create(
73 + user_id="user_123",
74 + tags={"require_approval": ["destructiveHint"]},
75 +)
76 +```
77 +</Tab>
78 +<Tab value="TypeScript">
79 +```typescript
80 +// @noErrors
81 +import { Composio } from '@composio/core';
82 +const composio = new Composio({ apiKey: 'your_api_key' });
83 +// ---cut---
84 +const session = await composio.create('user_123', {
85 + tags: { requireApproval: ['destructiveHint'] },
86 +});
87 +```
88 +</Tab>
89 +</Tabs>
90 +
91 +A tool needs approval if any `require_approval` list matches it, whether it's set on the tool's toolkit, the tool itself or one of its [tags](/docs/configuring-sessions#filtering-tools-by-tags). `require_approval` doesn't hide any tools from the agent. It can still find and call them, and the call waits for the user's approval.
92 +
93 +This also applies to each tool call inside `COMPOSIO_MULTI_EXECUTE_TOOL`, the meta tool agents use to run app tools. A batch with two calls that need approval comes back with two questions.
94 +
95 +## Asking the user
96 +
97 +Say the agent in the first session above asks to call `GMAIL_SEND_EMAIL`. Because it needs approval, the email isn't sent. Instead, `session.execute()` raises `ToolInputRequiredError` in Python and `ComposioToolInputRequiredError` in TypeScript:
98 +
99 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
100 +<Tab value="Python">
101 +```python
102 +from composio.exceptions import ToolInputRequiredError
103 +
104 +arguments = {"recipient_email": "priya@acme.com", "subject": "Q3 numbers"}
105 +
106 +try:
107 + session.execute("GMAIL_SEND_EMAIL", arguments=arguments)
108 +except ToolInputRequiredError as error:
109 + questions = error.input_requests
110 + request_state = error.request_state
111 +```
112 +</Tab>
113 +<Tab value="TypeScript">
114 +```typescript
115 +// @noErrors
116 +import { Composio, ComposioToolInputRequiredError, type ToolRouterInputRequest } from '@composio/core';
117 +const composio = new Composio({ apiKey: 'your_api_key' });
118 +const session = await composio.create('user_123');
119 +// ---cut---
120 +const args = { recipient_email: 'priya@acme.com', subject: 'Q3 numbers' };
121 +let questions: Record<string, ToolRouterInputRequest> = {};
122 +let requestState: string | undefined;
123 +
124 +try {
125 + await session.execute('GMAIL_SEND_EMAIL', args);
126 +} catch (error) {
127 + if (error instanceof ComposioToolInputRequiredError) {
128 + questions = error.inputRequests;
129 + requestState = error.requestState;
130 + }
131 +}
132 +```
133 +</Tab>
134 +</Tabs>
135 +
136 +`input_requests` (`inputRequests` in TypeScript) holds the questions for the user, keyed by an ID you'll answer them under:
137 +
138 +```json
139 +{
140 + "elicit_0f2f8872eea523ed": {
141 + "type": "elicitation",
142 + "mode": "form",
143 + "message": "Your agent wants to run the following tool:\n\nGMAIL_SEND_EMAIL({\"recipient_email\": \"priya@acme.com\", \"subject\": \"Q3 numbers\"})",
144 + "requested_schema": {
145 + "type": "object",
146 + "properties": {
147 + "decision": {
148 + "type": "string",
149 + "title": "Decision",
150 + "oneOf": [
151 + { "const": "approve", "title": "Approve" },
152 + { "const": "always_approve", "title": "Always approve" },
153 + { "const": "deny", "title": "Deny" }
154 + ]
155 + }
156 + },
157 + "required": ["decision"]
158 + }
159 + }
160 +}
161 +```
162 +
163 +Each question is an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Your app can show the `message` to the user, along with a form built from `requested_schema` (`requestedSchema` in TypeScript). This is a JSON Schema for the answer. As in MCP form mode, it's a flat object whose fields are strings, numbers, booleans, or single- or multi-select enums. Build the form from the schema rather than hard-coding the choices, because different questions offer different ones.
164 +
165 +`request_state` (`requestState` in TypeScript) is state you send back with the answer. The SDK keeps it out of the error's message, logs and serialized output, so read it from the attribute.
166 +
167 +## Sending the answer
168 +
169 +Once the user answers, send the same call again, with the answer in `input_responses` under the question's ID, and `request_state`:
170 +
171 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
172 +<Tab value="Python">
173 +```python
174 +result = session.execute(
175 + "GMAIL_SEND_EMAIL",
176 + arguments=arguments,
177 + input_responses={
178 + "elicit_0f2f8872eea523ed": {
179 + "action": "accept",
180 + "content": {"decision": "approve"},
181 + }
182 + },
183 + request_state=request_state,
184 +)
185 +```
186 +</Tab>
187 +<Tab value="TypeScript">
188 +```typescript
189 +// @noErrors
190 +import { Composio } from '@composio/core';
191 +const composio = new Composio({ apiKey: 'your_api_key' });
192 +const session = await composio.create('user_123');
193 +const args = { recipient_email: 'priya@acme.com', subject: 'Q3 numbers' };
194 +declare const requestState: string | undefined;
195 +// ---cut---
196 +const result = await session.execute('GMAIL_SEND_EMAIL', args, {
197 + inputResponses: {
198 + elicit_0f2f8872eea523ed: {
199 + action: 'accept',
200 + content: { decision: 'approve' },
201 + },
202 + },
203 + requestState,
204 +});
205 +```
206 +</Tab>
207 +</Tabs>
208 +
209 +Send the same tool and arguments. The question's ID comes from the call, so a call with different arguments is a new question.
210 +
211 +If the user approves, the tool runs and `result_type` is `completed`. If they deny it, or the answer's `action` is `decline` or `cancel`, the tool doesn't run and `result_type` is `failed`, with an error you can pass back to the agent.
212 +
213 +If the user picks **Always approve**, the tool runs, and later calls to the same tool on the same connected account run without asking for the rest of the session.
214 +
215 +## Adding approval to an agent loop
216 +
217 +This agent sends an email over Gmail with Claude. Each tool call goes through `run_tool`, which runs it with `session.execute()`. When Composio needs the user's approval, `run_tool` asks in the terminal, then sends the call again with the answers.
218 +
219 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
220 +<Tab value="Python">
221 +```python
222 +import json
223 +
224 +import anthropic
225 +from composio import Composio
226 +from composio.exceptions import ToolInputRequiredError
227 +from composio_anthropic import AnthropicProvider
228 +
229 +composio = Composio(provider=AnthropicProvider())
230 +client = anthropic.Anthropic()
231 +
232 +session = composio.create(
233 + user_id="user_123",
234 + toolkits=["gmail"],
235 + tools={"gmail": {"require_approval": ["GMAIL_SEND_EMAIL"]}},
236 +)
237 +tools = session.tools()
238 +
239 +
240 +def ask_user(question):
241 + """Show one question in the terminal and return the user's answer."""
242 + print(question["message"])
243 + content = {}
244 + for name, field in question["requested_schema"]["properties"].items():
245 + choices = [choice["const"] for choice in field.get("oneOf", [])]
246 + content[name] = input(f"{field.get('title', name)} ({'/'.join(choices)}): ")
247 + return {"action": "accept", "content": content}
248 +
249 +
250 +def run_tool(block):
251 + """Run one tool call, asking the user whenever Composio needs their input."""
252 + input_responses, request_state = None, None
253 + while True:
254 + try:
255 + result = session.execute(
256 + block.name,
257 + arguments=block.input,
258 + input_responses=input_responses,
259 + request_state=request_state,
260 + )
261 + break
262 + except ToolInputRequiredError as error:
263 + input_responses = {
264 + question_id: ask_user(question)
265 + for question_id, question in error.input_requests.items()
266 + }
267 + request_state = error.request_state
268 +
269 + return {
270 + "type": "tool_result",
271 + "tool_use_id": block.id,
272 + "content": json.dumps({"data": result.data, "error": result.error}),
273 + }
274 +
275 +
276 +messages = [
277 + {"role": "user", "content": "Email priya@acme.com with the subject 'Q3 numbers' and say the report is ready."}
278 +]
279 +response = client.messages.create(
280 + model="claude-opus-4-6", max_tokens=4096, tools=tools, messages=messages
281 +)
282 +
283 +while response.stop_reason == "tool_use":
284 + messages.append({"role": "assistant", "content": response.content})
285 + messages.append({
286 + "role": "user",
287 + "content": [run_tool(block) for block in response.content if block.type == "tool_use"],
288 + })
289 + response = client.messages.create(
290 + model="claude-opus-4-6", max_tokens=4096, tools=tools, messages=messages
291 + )
292 +
293 +for block in response.content:
294 + if block.type == "text":
295 + print(block.text)
296 +```
297 +</Tab>
298 +<Tab value="TypeScript">
299 +```typescript
300 +// @noErrors
301 +import Anthropic from '@anthropic-ai/sdk';
302 +import { AnthropicProvider } from '@composio/anthropic';
303 +import {
304 + Composio,
305 + ComposioToolInputRequiredError,
306 + type ToolRouterInputRequest,
307 + type ToolRouterSessionExecuteOptions,
308 +} from '@composio/core';
309 +import * as readline from 'node:readline/promises';
310 +
311 +const composio = new Composio({ provider: new AnthropicProvider() });
312 +const client = new Anthropic();
313 +const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
314 +
315 +const session = await composio.create('user_123', {
316 + toolkits: ['gmail'],
317 + tools: { gmail: { requireApproval: ['GMAIL_SEND_EMAIL'] } },
318 +});
319 +const tools = await session.tools();
320 +
321 +// Show one question in the terminal and return the user's answer
322 +async function askUser(question: ToolRouterInputRequest) {
323 + console.log(question.message);
324 + const { properties } = question.requestedSchema as {
325 + properties: Record<string, { title?: string; oneOf?: { const: string }[] }>;
326 + };
327 + const content: Record<string, string> = {};
328 + for (const [name, field] of Object.entries(properties)) {
329 + const choices = field.oneOf?.map((choice) => choice.const) ?? [];
330 + content[name] = await terminal.question(`${field.title ?? name} (${choices.join('/')}): `);
331 + }
332 + return { action: 'accept' as const, content };
333 +}
334 +
335 +// Run one tool call, asking the user whenever Composio needs their input
336 +async function runTool(block: Anthropic.ToolUseBlock): Promise<Anthropic.ToolResultBlockParam> {
337 + let answers: ToolRouterSessionExecuteOptions = {};
338 + while (true) {
339 + try {
340 + const result = await session.execute(block.name, block.input as Record<string, unknown>, answers);
341 + return {
342 + type: 'tool_result',
343 + tool_use_id: block.id,
344 + content: JSON.stringify({ data: result.data, error: result.error }),
345 + };
346 + } catch (error) {
347 + if (!(error instanceof ComposioToolInputRequiredError)) throw error;
348 + const inputResponses: NonNullable<ToolRouterSessionExecuteOptions['inputResponses']> = {};
349 + for (const [questionId, question] of Object.entries(error.inputRequests)) {
350 + inputResponses[questionId] = await askUser(question);
351 + }
352 + answers = { inputResponses, requestState: error.requestState };
353 + }
354 + }
355 +}
356 +
357 +const messages: Anthropic.MessageParam[] = [
358 + { role: 'user', content: "Email priya@acme.com with the subject 'Q3 numbers' and say the report is ready." },
359 +];
360 +let response = await client.messages.create({
361 + model: 'claude-opus-4-6',
362 + max_tokens: 4096,
363 + tools,
364 + messages,
365 +});
366 +
367 +while (response.stop_reason === 'tool_use') {
368 + messages.push({ role: 'assistant', content: response.content });
369 + const results: Anthropic.ToolResultBlockParam[] = [];
370 + for (const block of response.content) {
371 + if (block.type === 'tool_use') results.push(await runTool(block));
372 + }
373 + messages.push({ role: 'user', content: results });
374 + response = await client.messages.create({
375 + model: 'claude-opus-4-6',
376 + max_tokens: 4096,
377 + tools,
378 + messages,
379 + });
380 +}
381 +
382 +for (const block of response.content) {
383 + if (block.type === 'text') console.log(block.text);
384 +}
385 +terminal.close();
386 +```
387 +</Tab>
388 +</Tabs>
389 +
390 +Running it, the agent searches for the Gmail tool, then asks to send the email through `COMPOSIO_MULTI_EXECUTE_TOOL`. Before anything is sent, you see:
391 +
392 +```txt
393 +Your agent wants to run the following tool:
394 +
395 +GMAIL_SEND_EMAIL({"recipient_email": "priya@acme.com", "subject": "Q3 numbers", ...})
396 +Decision (approve/always_approve/deny):
397 +```
398 +
399 +If you deny it, Claude gets the denial as the tool's error and can tell the user it didn't send the email.
400 +
401 +### Answering later
402 +
403 +In a web app, the user answers in your UI, perhaps minutes later, so you can't wait in a loop for their answer. When `session.execute()` raises, save these with the conversation:
404 +
405 +- the tool call: its ID, tool name and arguments
406 +- the error's `input_requests` and `request_state`
407 +
408 +Then send the questions to your frontend and end the request. When the user answers, call `session.execute()` again with the saved tool name and arguments, their answers in `input_responses`, and the saved `request_state`. Add the result to the conversation as that tool call's result, and continue the agent loop.
409 +
410 +Keep `request_state` on your server. It's only meaningful to Composio, so don't send it to the browser.
411 +
412 +## Using MCP
413 +
414 +If your agent connects to the session [over MCP](/docs/sessions-via-mcp), clients that support elicitation, like Claude Code, ask the user for you. Clients that don't support it can't ask, so calls that need approval are denied by default. You can set `no_elicitation_support_fallback` to `"allow"` to run them without asking instead:
415 +
416 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
417 +<Tab value="Python">
418 +```python
419 +session = composio.create(
420 + user_id="user_123",
421 + tools={"gmail": {"require_approval": ["GMAIL_SEND_EMAIL"]}},
422 + experimental={"no_elicitation_support_fallback": "allow"},
423 +)
424 +```
425 +</Tab>
426 +<Tab value="TypeScript">
427 +```typescript
428 +// @noErrors
429 +import { Composio } from '@composio/core';
430 +const composio = new Composio({ apiKey: 'your_api_key' });
431 +// ---cut---
432 +const session = await composio.create('user_123', {
433 + tools: { gmail: { requireApproval: ['GMAIL_SEND_EMAIL'] } },
434 + experimental: { noElicitationSupportFallback: 'allow' },
435 +});
436 +```
437 +</Tab>
438 +</Tabs>
439 +
440 +## Limitations
441 +
442 +While approval mode is experimental, only `session.execute()` and `session.execute_meta()` (`executeMeta()` in TypeScript) accept answers.
443 +
444 +- **Providers.** `handle_tool_calls` (`handleToolCalls` in TypeScript) and the tools that framework providers wrap don't ask the user. Depending on the provider, a call that needs approval either raises the error or returns it to the agent as a tool error. Run tool calls with `session.execute()`, as in the example above.
445 +- **Custom tools.** If a [custom tool](/docs/extending-sessions/custom-tools-and-toolkits) runs a tool that needs approval through `ctx.execute()`, it raises the error, and there's no way to pass the answer back through the custom tool yet.
446 +- **Proxy execute.** `session.proxy_execute()` (`proxyExecute()` in TypeScript) raises the error when a call needs approval, but can't send an answer.
447 +
448 +## Next
449 +
450 +<Card
451 + icon={<Wrench />}
452 + title="Configuring sessions"
453 + href="/docs/configuring-sessions"
454 + description="Enable toolkits and tools, filter by tags, and update a session's configuration."
455 +/>
docs/content/docs/configuring-sessions.mdx
+2
@@ -499,6 +499,8 @@ const session = await composio.create("user_123", {
499 </Tab>
500 </Tabs>
501
502 +To keep a tool available but have the session ask the user before it runs, see [Approval mode](/docs/approval-mode).
503 +
504 ## Preloading tools
505
506 Return a known set of tools directly from `session.tools()` and the session MCP tool list, without the agent searching for them first.
docs/content/docs/meta.json
+1
@@ -13,6 +13,7 @@
13 "how-composio-works",
14 "configuring-sessions",
15 "session-configs",
16 + "approval-mode",
17 "instant-tools",
18 "toolkits",
19 "authentication",
docs/content/docs/production-readiness.mdx
+1 -1
@@ -62,7 +62,7 @@ Configure sessions with only the toolkits and tools required by the feature. Nar
62
63 Require explicit user confirmation before destructive or externally visible actions, such as sending a message, creating a purchase, or deleting data. Enforce product authorization before creating or restoring the session, especially for workspace-owned connections.
64
65 -See [Configuring sessions](/docs/configuring-sessions) for toolkit and tool filters.
65 +See [Configuring sessions](/docs/configuring-sessions) for toolkit and tool filters, and [Approval mode](/docs/approval-mode) to have a session ask the user before it runs the tools you choose.
66
67 ## 5. Persist the right state
68
docs/content/docs/sessions-vs-direct-execution.mdx
+2 -2
@@ -13,7 +13,7 @@ A **session** is the runtime context Composio creates for one of your users with
13 Direct execution is a legacy interface that remains supported for existing integrations. We recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). Sessions handle runtime tool discovery, authentication, and execution.
14 </Callout>
15
16 -If your application needs a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. If you need approval before execution, evaluate how your integration intercepts session tool calls, including meta tools that can execute multiple app-tool calls. The comparison below describes the tradeoffs when maintaining a direct-execution integration.
16 +If your application needs a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. If you need approval before execution, use [approval mode](/docs/approval-mode): the session asks the user before it runs the tools you choose, including calls inside meta tools that execute multiple app tools. The comparison below describes the tradeoffs when maintaining a direct-execution integration.
17
18 | | Sessions | Direct execution |
19 |---|---|---|
@@ -23,7 +23,7 @@ If your application needs a fixed tool set, consider the [direct tools preset](/
23 | **Memory** | Meta tools share context across calls, storing discovered IDs and relationships | You manage state between calls |
24 | **Auth** | [In-chat](/docs/authentication#in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authentication/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
25 | **[Sandbox](/docs/sandbox/remote)** | Built in, large responses offloaded automatically | Not available |
26 -| **Human approval** | Your integration must account for meta tools that can execute multiple app-tool calls. See the direct-tools option below | You intercept before each call in your code |
26 +| **Human approval** | [Approval mode](/docs/approval-mode) asks the user before the tools you choose run, including inside meta tools | You intercept before each call in your code |
27 | **Latency** | Multiple LLM turns (search, then execute) | Single call |
28
29 Sessions are configurable. [Restrict toolkits](/docs/configuring-sessions), set [auth configs](/docs/auth-configuration/custom-auth-configs) for white-labeled OAuth, and pin [connected accounts](/docs/configuring-sessions#account-selection). See [Configuring Sessions](/docs/configuring-sessions) for the full list.
docs/lib/home-navigation.ts
+2
@@ -130,6 +130,7 @@ export const DOCS_PRODUCTS = {
130 '/docs/how-composio-works',
131 '/docs/configuring-sessions',
132 '/docs/session-configs',
133 + '/docs/approval-mode',
134 '/docs/instant-tools',
135 '/docs/toolkits',
136 '/docs/authentication',
@@ -166,6 +167,7 @@ export const DOCS_PRODUCTS = {
167 { url: '/docs/how-composio-works', label: 'What is a Session?' },
168 { url: '/docs/configuring-sessions' },
169 { url: '/docs/session-configs' },
170 + { url: '/docs/approval-mode' },
171 { url: '/docs/sessions-via-mcp' },
172 ],
173 },