@devries-cameron20 / composio-1 / commits / eea2cc4d7
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.

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">