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: show session-wide and per-toolkit approval as two examples
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 17:53 UTC
eea2cc4d7dab3f83c234422a6552ed3dc503407a
1 file changed
+26
-13
docs/content/docs/approval-mode.mdx
+26
-13
@@ -14,24 +14,41 @@ Approval mode is experimental, and its SDK options may change. Answering questio
14
15
## Requiring approval
16
17
-Set approval rules when you create or update a session:
17
+Require approval for every tool with a [tag](/docs/tool-tags):
18
19
-- **`tags.require_approval`** requires approval for every tool with one of these [tags](/docs/tool-tags).
20
-- **`tools.<toolkit>`** overrides the session-wide `tags` for one toolkit. Set `tags.require_approval` inside it, or list the toolkit's tools in `enable` and the ones that need approval in `require_approval`. When you list tools, always set `require_approval`, even to `[]`.
19
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
20
+<Tab value="Python">
21
+```python
22
+session = composio.create(
23
+ user_id="user_123",
24
+ tags={"require_approval": ["createHint", "updateHint", "destructiveHint"]},
25
+)
26
+```
27
+</Tab>
28
+<Tab value="TypeScript">
29
+```typescript
30
+// @noErrors
31
+import { Composio } from '@composio/core';
32
+const composio = new Composio({ apiKey: 'your_api_key' });
33
+// ---cut---
34
+const session = await composio.create('user_123', {
35
+ tags: { requireApproval: ['createHint', 'updateHint', 'destructiveHint'] },
36
+});
37
+```
38
+</Tab>
39
+</Tabs>
40
22
-For example:
41
+Or set it per toolkit, which overrides `tags` for that toolkit:
42
43
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
44
<Tab value="Python">
45
```python
46
session = composio.create(
47
user_id="user_123",
29
- toolkits={"enable": ["gmail", "github"]},
30
- tags={"require_approval": ["createHint", "updateHint", "destructiveHint"]},
48
tools={
49
"gmail": {
50
"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
34
- "require_approval": ["GMAIL_SEND_EMAIL"],
51
+ "require_approval": ["GMAIL_SEND_EMAIL"], # set even if empty
52
},
53
},
54
)
@@ -44,12 +61,10 @@ import { Composio } from '@composio/core';
61
const composio = new Composio({ apiKey: 'your_api_key' });
62
// ---cut---
63
const session = await composio.create('user_123', {
47
- toolkits: { enable: ['gmail', 'github'] },
48
- tags: { requireApproval: ['createHint', 'updateHint', 'destructiveHint'] },
64
tools: {
65
gmail: {
66
enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
52
- requireApproval: ['GMAIL_SEND_EMAIL'],
67
+ requireApproval: ['GMAIL_SEND_EMAIL'], // set even if empty
68
},
69
},
70
});
@@ -57,13 +72,11 @@ const session = await composio.create('user_123', {
72
</Tab>
73
</Tabs>
74
60
-In this session, GitHub tools that create, update or delete need approval. Gmail is limited to fetching and sending emails, and sending needs approval.
61
-
75
Tools that need approval stay visible to the agent. It can find and call them, and each call waits for the user's approval. This includes calls the agent makes through `COMPOSIO_MULTI_EXECUTE_TOOL`: a batch with two calls that need approval returns two questions.
76
77
## Asking the user
78
66
-Say the agent in the 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:
79
+Say the agent in the Gmail 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:
80
81
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
82
<Tab value="Python">