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 a real toolkit override in approvals
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 18:19 UTC
88a7bfa39b4863de7255355c37a5b86420eba63e
1 file changed
+13
-17
docs/content/docs/approvals.mdx
+13
-17
@@ -15,14 +15,14 @@ Approvals are experimental. They need `composio` newer than 0.27.0 or `@composio
15
16
## Choosing which tools need approval
17
18
-You choose which tools require approval when you create or update a session. To require approval for every tool with a [tag](/docs/tool-tags), in every toolkit:
18
+You choose which tools need approval with their [tags](/docs/tool-tags) when you create a session. For example, this session asks the user before any tool that creates, updates or deletes something:
19
20
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
21
<Tab value="Python">
22
```python
23
session = composio.create(
24
user_id="user_123",
25
- # Every tool that creates, updates or deletes something
25
+ # Everywhere: ask before tools that create, update or delete
26
tags={"require_approval": ["createHint", "updateHint", "destructiveHint"]},
27
)
28
```
@@ -34,27 +34,25 @@ import { Composio } from '@composio/core';
34
const composio = new Composio({ apiKey: 'your_api_key' });
35
// ---cut---
36
const session = await composio.create('user_123', {
37
- // Every tool that creates, updates or deletes something
37
+ // Everywhere: ask before tools that create, update or delete
38
tags: { requireApproval: ['createHint', 'updateHint', 'destructiveHint'] },
39
});
40
```
41
</Tab>
42
</Tabs>
43
44
-To handle one toolkit differently, override `tags` for it under `tools.<toolkit>`:
44
+To handle a toolkit differently, override the session-wide `tags` in `tools.<toolkit>.tags`. This session asks before the same tools everywhere, except GitHub, where it only asks before tools that delete:
45
46
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
47
<Tab value="Python">
48
```python
49
session = composio.create(
50
user_id="user_123",
51
+ # Everywhere: ask before tools that create, update or delete
52
+ tags={"require_approval": ["createHint", "updateHint", "destructiveHint"]},
53
tools={
52
- "gmail": {
53
- # The Gmail tools the agent can use
54
- "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
55
- # The ones that need approval. Set this even if it's empty.
56
- "require_approval": ["GMAIL_SEND_EMAIL"],
57
- },
54
+ # GitHub: ask only before tools that delete
55
+ "github": {"tags": {"require_approval": ["destructiveHint"]}},
56
},
57
)
58
```
@@ -66,20 +64,18 @@ import { Composio } from '@composio/core';
64
const composio = new Composio({ apiKey: 'your_api_key' });
65
// ---cut---
66
const session = await composio.create('user_123', {
67
+ // Everywhere: ask before tools that create, update or delete
68
+ tags: { requireApproval: ['createHint', 'updateHint', 'destructiveHint'] },
69
tools: {
70
- gmail: {
71
- // The Gmail tools the agent can use
72
- enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
73
- // The ones that need approval. Set this even if it's empty.
74
- requireApproval: ['GMAIL_SEND_EMAIL'],
75
- },
70
+ // GitHub: ask only before tools that delete
71
+ github: { tags: { requireApproval: ['destructiveHint'] } },
72
},
73
});
74
```
75
</Tab>
76
</Tabs>
77
82
-Tools that need approval stay visible to the agent, which can find and call them as usual.
78
+The override replaces the session-wide `tags` for that toolkit, including any tags you block, so list everything you still want for it.
79
80
## Asking the user
81