Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 08:30 UTC
docs: configure approvals the way the dashboard does
Presents session approvals as the dashboard's three steps: enable toolkits, choose allow / ask first / block per kind of action, then override a toolkit by kind or by tool. Examples use the same config shapes the dashboard writes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 15:00 UTC
eaf3d9d3fccf42bd9cf9e48e47ec98d0ede294ec
1 file changed
+115
-75
docs/content/docs/approval-mode.mdx
+115
-75
@@ -12,66 +12,92 @@ When your agent calls a tool that requires approval, Composio doesn't run it. It
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
15
+## Configuring approvals
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:
17
+You set approvals when you create or update a session, in three steps. They're the same steps as building a [Session config](/docs/configuring-sessions#using-a-saved-session-config) in the Composio Dashboard, and produce the same configuration. The snippets in each step are Python. In TypeScript, `require_approval` is `requireApproval`.
18
+
19
+### 1. Enable toolkits
20
+
21
+List the toolkits the agent can use in `toolkits.enable`:
22
19
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
20
-<Tab value="Python">
23
```python
22
-session = composio.create(
23
- user_id="user_123",
24
- toolkits=["gmail"],
25
- tools={"gmail": {"require_approval": ["GMAIL_SEND_EMAIL"]}},
26
-)
24
+toolkits={"enable": ["gmail", "github"]}
25
```
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
-});
26
+
27
+### 2. Choose what each kind of action does
28
+
29
+Every tool is tagged with the kind of action it takes:
30
+
31
+| Kind | Tag |
32
+|---|---|
33
+| Read | `readOnlyHint` |
34
+| Create | `createHint` |
35
+| Update | `updateHint` |
36
+| Destructive | `destructiveHint` |
37
+
38
+For each kind, choose one of:
39
+
40
+- **Allow:** leave the tag out.
41
+- **Ask first:** add the tag to `tags.require_approval`.
42
+- **Block:** add the tag to `tags.disable`. The agent can't see or call these tools.
43
+
44
+For example, to allow reads, ask before creates and updates, and block destructive actions:
45
+
46
+```python
47
+tags={
48
+ "require_approval": ["createHint", "updateHint"],
49
+ "disable": ["destructiveHint"],
50
+}
51
```
40
-</Tab>
41
-</Tabs>
52
43
-This one needs approval for every Slack tool:
53
+### 3. Override toolkits
54
+
55
+You can override step 2 for a toolkit, either by kind or by tool.
56
+
57
+**By kind.** Set `tools.<toolkit>.tags`, the same way as step 2. This replaces the session-wide `tags` for that toolkit rather than adding to them, so list every kind you want it to ask about or block. For example, this lets GitHub's destructive actions run after the user approves them, rather than blocking them:
58
45
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
46
-<Tab value="Python">
59
```python
48
-session = composio.create(
49
- user_id="user_123",
50
- toolkits={"enable": ["slack"], "require_approval": ["slack"]},
51
-)
60
+tools={
61
+ "github": {
62
+ "tags": {"require_approval": ["createHint", "updateHint", "destructiveHint"]}
63
+ }
64
+}
65
```
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
-});
66
+
67
+**By tool.** List the tools the agent can use in `tools.<toolkit>.enable`, and the ones to ask about first in `tools.<toolkit>.require_approval`. Tools you leave out are blocked, including tools added to the toolkit later. Always set `require_approval`, even to `[]`. Otherwise the session-wide `tags.require_approval` still applies to the listed tools. For example, this lets the agent read and send Gmail, and asks before sending:
68
+
69
+```python
70
+tools={
71
+ "gmail": {
72
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
73
+ "require_approval": ["GMAIL_SEND_EMAIL"],
74
+ }
75
+}
76
```
64
-</Tab>
65
-</Tabs>
77
67
-And this one needs approval for any tool that can delete data, in any toolkit:
78
+Use one or the other for a toolkit, not both.
79
+
80
+### Putting it together
81
82
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
83
<Tab value="Python">
84
```python
85
session = composio.create(
86
user_id="user_123",
74
- tags={"require_approval": ["destructiveHint"]},
87
+ toolkits={"enable": ["gmail", "github"]},
88
+ tags={
89
+ "require_approval": ["createHint", "updateHint"],
90
+ "disable": ["destructiveHint"],
91
+ },
92
+ tools={
93
+ "gmail": {
94
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
95
+ "require_approval": ["GMAIL_SEND_EMAIL"],
96
+ },
97
+ "github": {
98
+ "tags": {"require_approval": ["createHint", "updateHint", "destructiveHint"]}
99
+ },
100
+ },
101
)
102
```
103
</Tab>
@@ -82,42 +108,36 @@ import { Composio } from '@composio/core';
108
const composio = new Composio({ apiKey: 'your_api_key' });
109
// ---cut---
110
const session = await composio.create('user_123', {
85
- tags: { requireApproval: ['destructiveHint'] },
111
+ toolkits: { enable: ['gmail', 'github'] },
112
+ tags: {
113
+ requireApproval: ['createHint', 'updateHint'],
114
+ disable: ['destructiveHint'],
115
+ },
116
+ tools: {
117
+ gmail: {
118
+ enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
119
+ requireApproval: ['GMAIL_SEND_EMAIL'],
120
+ },
121
+ github: {
122
+ tags: { requireApproval: ['createHint', 'updateHint', 'destructiveHint'] },
123
+ },
124
+ },
125
});
126
```
127
</Tab>
128
</Tabs>
129
91
-A tool needs approval if:
92
-
93
-- its toolkit is in `toolkits.require_approval`,
94
-- its slug is in `tools.<toolkit>.require_approval`, or
95
-- one of its [tags](/docs/configuring-sessions#filtering-tools-by-tags) is in the tag list that applies to its toolkit.
96
-
97
-The session-wide `tags.require_approval` list applies to every toolkit that doesn't set approval rules of its own. Once a toolkit has its own `require_approval` under `tools.<toolkit>`, its own tag list (`tools.<toolkit>.tags.require_approval`) replaces the session-wide one, the same way its tag filter replaces the session-wide filter. If it has no tag list of its own, no tags apply to it. For example:
98
-
99
-```json
100
-{
101
- "tags": { "require_approval": ["destructiveHint"] },
102
- "tools": { "gmail": { "require_approval": ["GMAIL_SEND_EMAIL"] } }
103
-}
104
-```
105
-
106
-Here, Gmail only asks before `GMAIL_SEND_EMAIL`, and its destructive tools run without asking. Every other toolkit asks before its destructive tools. To keep asking before Gmail's destructive tools too, add `"tags": { "require_approval": ["destructiveHint"] }` to the `gmail` entry.
107
-
108
-A few more things follow from this:
130
+With this session, the agent can:
131
110
-- A toolkit in `toolkits.require_approval` always asks, whatever else is set.
111
-- To exempt a toolkit from the session-wide tag list, give it an empty list of its own, such as `"tools": { "github": { "require_approval": [] } }`.
112
-- Setting `tools.<toolkit>.tags`, even just for `require_approval`, also replaces the session-wide tag `enable` and `disable` filter for that toolkit. To change a toolkit's approvals without touching its filter, use `tools.<toolkit>.require_approval`.
132
+- read GitHub freely, and create, update or delete things in GitHub after the user approves
133
+- fetch Gmail emails freely, and send emails after the user approves
134
+- use no other Gmail tools, and no other toolkits
135
114
-`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.
115
-
116
-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.
136
+Asking first doesn't hide a tool from the agent. It can still find and call it, and the call waits for the user's approval. 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.
137
138
## Asking the user
139
120
-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:
140
+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:
141
142
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
143
<Tab value="Python">
@@ -254,8 +274,13 @@ client = anthropic.Anthropic()
274
275
session = composio.create(
276
user_id="user_123",
257
- toolkits=["gmail"],
258
- tools={"gmail": {"require_approval": ["GMAIL_SEND_EMAIL"]}},
277
+ toolkits={"enable": ["gmail"]},
278
+ tools={
279
+ "gmail": {
280
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
281
+ "require_approval": ["GMAIL_SEND_EMAIL"],
282
+ }
283
+ },
284
)
285
tools = session.tools()
286
@@ -336,8 +361,13 @@ const client = new Anthropic();
361
const terminal = readline.createInterface({ input: process.stdin, output: process.stdout });
362
363
const session = await composio.create('user_123', {
339
- toolkits: ['gmail'],
340
- tools: { gmail: { requireApproval: ['GMAIL_SEND_EMAIL'] } },
364
+ toolkits: { enable: ['gmail'] },
365
+ tools: {
366
+ gmail: {
367
+ enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
368
+ requireApproval: ['GMAIL_SEND_EMAIL'],
369
+ },
370
+ },
371
});
372
const tools = await session.tools();
373
@@ -441,7 +471,12 @@ If your agent connects to the session [over MCP](/docs/sessions-via-mcp), client
471
```python
472
session = composio.create(
473
user_id="user_123",
444
- tools={"gmail": {"require_approval": ["GMAIL_SEND_EMAIL"]}},
474
+ tools={
475
+ "gmail": {
476
+ "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
477
+ "require_approval": ["GMAIL_SEND_EMAIL"],
478
+ }
479
+ },
480
experimental={"no_elicitation_support_fallback": "allow"},
481
)
482
```
@@ -453,7 +488,12 @@ import { Composio } from '@composio/core';
488
const composio = new Composio({ apiKey: 'your_api_key' });
489
// ---cut---
490
const session = await composio.create('user_123', {
456
- tools: { gmail: { requireApproval: ['GMAIL_SEND_EMAIL'] } },
491
+ tools: {
492
+ gmail: {
493
+ enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
494
+ requireApproval: ['GMAIL_SEND_EMAIL'],
495
+ },
496
+ },
497
experimental: { noElicitationSupportFallback: 'allow' },
498
});
499
```