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 approval rules in code instead of describing them
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 18:08 UTC
855d3c40010f12ea9da805f76493abdf2e238b1c
1 file changed
+8
-7
docs/content/docs/approvals.mdx
+8
-7
@@ -15,18 +15,14 @@ Approvals are experimental. They need `composio` newer than 0.27.0 or `@composio
15
16
## Requiring approval
17
18
-You configure which tools require approval when you create or update a session. There are two ways to choose them:
19
-
20
-- **By tag.** Every tool has a [tag](/docs/tool-tags) for the type of action it takes, such as `createHint` for tools that create something or `destructiveHint` for tools that delete something. Add tags to `tags.require_approval` to require approval for every tool with those tags, in every toolkit.
21
-- **Per toolkit.** Set approval for one toolkit's tools under `tools.<toolkit>`. This overrides the session-wide `tags` for that toolkit, so you can treat it differently from the rest of the session.
22
-
23
-This session requires approval for every tool that creates, updates or deletes something:
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:
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
26
tags={"require_approval": ["createHint", "updateHint", "destructiveHint"]},
27
)
28
```
@@ -38,13 +34,14 @@ 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
38
tags: { requireApproval: ['createHint', 'updateHint', 'destructiveHint'] },
39
});
40
```
41
</Tab>
42
</Tabs>
43
47
-This session limits Gmail to two tools, and requires approval before sending an email. List the tools the agent can use in `enable` and the ones that need approval in `require_approval`. Always set `require_approval` when you list tools, even to `[]`. Otherwise the session-wide `tags.require_approval` still applies to them:
44
+To handle one toolkit differently, override `tags` for it under `tools.<toolkit>`:
45
46
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
47
<Tab value="Python">
@@ -53,7 +50,9 @@ session = composio.create(
50
user_id="user_123",
51
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
},
58
},
@@ -69,7 +68,9 @@ const composio = new Composio({ apiKey: 'your_api_key' });
68
const session = await composio.create('user_123', {
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
},
76
},