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: comment the approvals full example
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mukund committed
Oct 15, 2026 at 18:27 UTC
f1c3a085edd8183ef4507a807acbd4fe6ef71941
1 file changed
+18
docs/content/docs/approvals.mdx
+18
@@ -262,7 +262,9 @@ session = composio.create(
262
toolkits={"enable": ["gmail"]},
263
tools={
264
"gmail": {
265
+ # The agent can fetch and send emails
266
"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"],
267
+ # but needs the user's approval to send one
268
"require_approval": ["GMAIL_SEND_EMAIL"],
269
}
270
},
@@ -272,7 +274,9 @@ tools = session.tools()
274
275
def ask_user(question):
276
"""Show one question in the terminal and return the user's answer."""
277
+ # Describes the tool call, like which email the agent wants to send
278
print(question["message"])
279
+ # Ask for each field in requested_schema, like the decision to approve or deny
280
content = {}
281
for name, field in question["requested_schema"]["properties"].items():
282
choices = [choice["const"] for choice in field.get("oneOf", [])]
@@ -282,6 +286,7 @@ def ask_user(question):
286
287
def run_tool(block):
288
"""Run one tool call, asking the user whenever Composio needs their input."""
289
+ # No answers yet on the first try
290
input_responses, request_state = None, None
291
while True:
292
try:
@@ -293,12 +298,15 @@ def run_tool(block):
298
)
299
break
300
except ToolInputRequiredError as error:
301
+ # The tool needs approval: ask the user every question, keyed by its ID
302
input_responses = {
303
question_id: ask_user(question)
304
for question_id, question in error.input_requests.items()
305
}
306
+ # Send this back with the answers when you retry the call
307
request_state = error.request_state
308
309
+ # Return the result to Claude
310
return {
311
"type": "tool_result",
312
"tool_use_id": block.id,
@@ -313,6 +321,7 @@ response = client.messages.create(
321
model="claude-opus-4-6", max_tokens=4096, tools=tools, messages=messages
322
)
323
324
+# Run the tools Claude calls until it has a final answer
325
while response.stop_reason == "tool_use":
326
messages.append({"role": "assistant", "content": response.content})
327
messages.append({
@@ -349,7 +358,9 @@ const session = await composio.create('user_123', {
358
toolkits: { enable: ['gmail'] },
359
tools: {
360
gmail: {
361
+ // The agent can fetch and send emails
362
enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
363
+ // but needs the user's approval to send one
364
requireApproval: ['GMAIL_SEND_EMAIL'],
365
},
366
},
@@ -358,7 +369,9 @@ const tools = await session.tools();
369
370
// Show one question in the terminal and return the user's answer
371
async function askUser(question: ToolRouterInputRequest) {
372
+ // Describes the tool call, like which email the agent wants to send
373
console.log(question.message);
374
+ // Ask for each field in requestedSchema, like the decision to approve or deny
375
const { properties } = question.requestedSchema as {
376
properties: Record<string, { title?: string; oneOf?: { const: string }[] }>;
377
};
@@ -372,10 +385,12 @@ async function askUser(question: ToolRouterInputRequest) {
385
386
// Run one tool call, asking the user whenever Composio needs their input
387
async function runTool(block: Anthropic.ToolUseBlock): Promise<Anthropic.ToolResultBlockParam> {
388
+ // No answers yet on the first try
389
let answers: ToolRouterSessionExecuteOptions = {};
390
while (true) {
391
try {
392
const result = await session.execute(block.name, block.input as Record<string, unknown>, answers);
393
+ // Return the result to Claude
394
return {
395
type: 'tool_result',
396
tool_use_id: block.id,
@@ -383,10 +398,12 @@ async function runTool(block: Anthropic.ToolUseBlock): Promise<Anthropic.ToolRes
398
};
399
} catch (error) {
400
if (!(error instanceof ComposioToolInputRequiredError)) throw error;
401
+ // The tool needs approval: ask the user every question, keyed by its ID
402
const inputResponses: NonNullable<ToolRouterSessionExecuteOptions['inputResponses']> = {};
403
for (const [questionId, question] of Object.entries(error.inputRequests)) {
404
inputResponses[questionId] = await askUser(question);
405
}
406
+ // Retry the call with the answers, and the request state if there is one
407
answers = { inputResponses, requestState: error.requestState };
408
}
409
}
@@ -402,6 +419,7 @@ let response = await client.messages.create({
419
messages,
420
});
421
422
+// Run the tools Claude calls until it has a final answer
423
while (response.stop_reason === 'tool_use') {
424
messages.push({ role: 'assistant', content: response.content });
425
const results: Anthropic.ToolResultBlockParam[] = [];