@devries-cameron20 / composio Mirror · read-only / commits / eb54e54df
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 08:30 UTC

docs: make the approval rules section concise

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Mukund committed Oct 15, 2026 at 17:48 UTC eb54e54df9fd094ec945d42e50913ea349443f5b
1 file changed +7 -69
docs/content/docs/approval-mode.mdx
+7 -69
@@ -14,58 +14,12 @@ Approval mode is experimental, and its SDK options may change. Answering questio
14
15 ## Requiring approval
16
17 -You choose which tools need approval when you create or update a session.
17 +Set approval rules when you create or update a session:
18
19 -### By type of tool
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 `[]`.
21
21 -Every tool has a [tag](/docs/tool-tags) for the type of action it takes:
22 -
23 -| Tag | Action |
24 -|---|---|
25 -| `readOnlyHint` | Read |
26 -| `createHint` | Create |
27 -| `updateHint` | Update |
28 -| `destructiveHint` | Destructive |
29 -
30 -To require approval for every tool of a type, add its tag to `tags.require_approval`. Tools whose tags you leave out run without approval, and tools whose tags are in `tags.disable` are [blocked](/docs/configuring-sessions#filtering-tools-by-tags). For example, to require approval for tools that create or update, and block tools that delete:
31 -
32 -```python
33 -tags={
34 - "require_approval": ["createHint", "updateHint"],
35 - "disable": ["destructiveHint"],
36 -}
37 -```
38 -
39 -### Overriding for a toolkit
40 -
41 -The session-wide `tags` apply to the tools of every toolkit. To handle a toolkit's tools differently, override them under `tools.<toolkit>`. The override replaces the session-wide `tags` for that toolkit, so it has to cover all of its tools. You can override by type or tool by tool.
42 -
43 -**By type.** Set `tools.<toolkit>.tags` the same way as the session-wide `tags`, and repeat anything from them you still want for the toolkit. For example, this override makes GitHub's tools that delete need approval instead of being blocked. Tools that create or update are listed again so they still need approval:
44 -
45 -```python
46 -tools={
47 - "github": {
48 - "tags": {"require_approval": ["createHint", "updateHint", "destructiveHint"]}
49 - }
50 -}
51 -```
52 -
53 -**Tool by tool.** List the tools the agent can use in `tools.<toolkit>.enable`, and the ones that need approval in `tools.<toolkit>.require_approval`. Tools you leave out are blocked, including tools added to the toolkit later. For example, this override lets the agent fetch and send Gmail, and requires approval to send:
54 -
55 -```python
56 -tools={
57 - "gmail": {
58 - "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
59 - "require_approval": ["GMAIL_SEND_EMAIL"],
60 - }
61 -}
62 -```
63 -
64 -Always set `require_approval` in a tool-by-tool override, even to `[]`. Without it, the session-wide `tags.require_approval` still applies to the tools you list.
65 -
66 -Use one or the other for a toolkit, not both.
67 -
68 -### Example
22 +For example:
23
24 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
25 <Tab value="Python">
@@ -73,18 +27,12 @@ Use one or the other for a toolkit, not both.
27 session = composio.create(
28 user_id="user_123",
29 toolkits={"enable": ["gmail", "github"]},
76 - tags={
77 - "require_approval": ["createHint", "updateHint"],
78 - "disable": ["destructiveHint"],
79 - },
30 + tags={"require_approval": ["createHint", "updateHint", "destructiveHint"]},
31 tools={
32 "gmail": {
33 "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
34 "require_approval": ["GMAIL_SEND_EMAIL"],
35 },
85 - "github": {
86 - "tags": {"require_approval": ["createHint", "updateHint", "destructiveHint"]}
87 - },
36 },
37 )
38 ```
@@ -97,29 +45,19 @@ const composio = new Composio({ apiKey: 'your_api_key' });
45 // ---cut---
46 const session = await composio.create('user_123', {
47 toolkits: { enable: ['gmail', 'github'] },
100 - tags: {
101 - requireApproval: ['createHint', 'updateHint'],
102 - disable: ['destructiveHint'],
103 - },
48 + tags: { requireApproval: ['createHint', 'updateHint', 'destructiveHint'] },
49 tools: {
50 gmail: {
51 enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
52 requireApproval: ['GMAIL_SEND_EMAIL'],
53 },
109 - github: {
110 - tags: { requireApproval: ['createHint', 'updateHint', 'destructiveHint'] },
111 - },
54 },
55 });
56 ```
57 </Tab>
58 </Tabs>
59
118 -With this session:
119 -
120 -- **GitHub** is overridden by type. Tools that read run without approval, and tools that create, update or delete need approval.
121 -- **Gmail** is overridden tool by tool. Fetching emails runs without approval, sending needs approval, and no other Gmail tools are available.
122 -- **Any other toolkit** isn't enabled. If you enabled one without an override, the session-wide `tags` would apply to its tools: tools that read run without approval, tools that create or update need approval, and tools that delete are blocked.
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
62 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.
63