@devries-cameron20 / composio Mirror · read-only
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, 06:00 UTC

next
md 87 lines 5.49 KB
Rendered Raw
1 # Session approvals
2
3 Ask before running a tool, then resume the same call with your answer. These examples use read-only Hacker News lookups so you can try every choice without a connected account or model API key.
4
5 From the repository root, install dependencies and build the SDK:
6
7 ```bash
8 pnpm install
9 pnpm exec turbo build --filter=@composio/core
10 export COMPOSIO_API_KEY=your_project_key
11 pnpm --filter approvals-example start
12 ```
13
14 To use staging, also set `COMPOSIO_BASE_URL=https://staging-backend.composio.dev`. Otherwise the SDK uses production.
15
16 ## Choose an answer
17
18 The terminal prints the tool call and reads the decision choices from the returned schema. Enter `approve`, `always_approve`, or `deny` when offered. You can also enter `decline` or `cancel` to return those MCP elicitation actions without form content. An invalid choice asks again.
19
20 `deny` is a submitted form decision (`action: 'accept'`, `content: { decision: 'deny' }`). `decline` and `cancel` are protocol actions. All three are forwarded unchanged, and Composio decides the execution result. `always_approve` applies to that tool and connected account for the rest of the Session.
21
22 [`approval.ts`](src/approval.ts) waits for every answer before repeating the original call with `inputResponses` and the opaque `requestState`. It handles another input request if needed and propagates other execution errors. This terminal UI supports approval decision forms. Build a complete schema renderer for other elicitation forms.
23
24 ## Run the Python version
25
26 ```bash
27 uv sync --project python --frozen
28 uv run --project python python python/examples/approvals.py
29 ```
30
31 The [Python example](../../../python/examples/approvals.py) uses the same flow with `input_responses` and `request_state`. Closing its terminal prompt returns `cancel`.
32
33 ## Answer several questions
34
35 ```bash
36 pnpm --filter approvals-example start:multi
37 uv run --project python python python/examples/approvals.py --multi
38 ```
39
40 These calls use `session.executeMeta()` / `session.execute_meta()` with `COMPOSIO_MULTI_EXECUTE_TOOL` to look up a Hacker News user and the latest item ID. Try approving one and denying the other. The helpers collect every returned question by ID before resuming the batch. Inspect each tool's result; a completed meta-tool response can contain denied or failed app-tool calls.
41
42 ## Connect an MCP client
43
44 ```bash
45 pnpm --filter approvals-example start:mcp
46 ```
47
48 [`mcp.ts`](src/mcp.ts) creates a Session with `mcp: true`, connects with `session.mcp.url` and `session.mcp.headers`, advertises form elicitation, and registers an `elicitation/create` handler. The handler uses the same terminal prompt. The client calls `COMPOSIO_MULTI_EXECUTE_TOOL` and Composio asks for input over MCP; your application doesn't resubmit an SDK call.
49
50 To try a client without elicitation support:
51
52 ```bash
53 pnpm --filter approvals-example exec bun src/mcp.ts --no-elicitation
54 ```
55
56 The example explicitly sets `noElicitationSupportFallback: 'deny'`. The calls are denied without a prompt. Keep this fallback when approval is required. Clients such as Claude Code supply their own elicitation UI; this example shows how to implement that part in your own client.
57
58 ## CI coverage
59
60 Pull requests run the terminal and continuation tests in `.github/workflows/ts.examples.yml` and `.github/workflows/py.test.yml`. The TypeScript tests also connect the actual example MCP client to an in-memory MCP server and check answer forwarding and capability negotiation. These tests need no credentials.
61
62 Run them locally:
63
64 ```bash
65 pnpm --filter approvals-example test
66 uv run --project python pytest python/tests/test_approval_examples.py
67 ```
68
69 The existing staging manifest sweep runs three unattended entries nightly and on demand:
70
71 | Manifest entry | Backend assertions |
72 | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
73 | `ts/approvals/verify` | Approval is requested; approve succeeds; deny, decline, and cancel fail for approval reasons; Always approve suppresses the next prompt; a mixed batch has one success and one denial. |
74 | `py/approvals/verify` | The same assertions through the Python SDK. |
75 | `ts/approvals/verify-mcp` | An elicitation-capable client receives questions and runs the tools; a client without elicitation is denied. |
76
77 Run just those entries against a disposable staging project:
78
79 ```bash
80 COMPOSIO_BASE_URL=https://staging-backend.composio.dev \
81 node harness/run.mjs sweep --llm mock \
82 --ids ts/approvals/verify,py/approvals/verify,ts/approvals/verify-mcp
83 ```
84
85 The verification scripts supply fixed answers only for the explicitly gated read-only tools in this example. Keep human input in application flows. Each script creates fresh Sessions, fails if approval was skipped, and deletes its Sessions in `finally`. The interactive entrypoints are excluded from unattended sweeps so CI never waits for terminal input. Missing credentials fail verification; they don't count as passing coverage.
86
87 See the [approvals guide](https://docs.composio.dev/docs/approvals) for configuration and current limitations.