Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 193 lines 5.4 KB
Rendered Raw
1 ## Filter a broad read-only session with behavior tags
2
3 Use session-level behavior tags when the agent may discover tools across
4 multiple toolkits but should only receive tools marked as read-only. The same
5 filters are enforced when the session executes tools.
6
7 ### Python
8
9 ```python
10 session = composio.sessions.create(
11 user_id="user_123",
12 tags={
13 "enable": ["readOnlyHint"],
14 "disable": ["destructiveHint"],
15 },
16 )
17 ```
18
19 ### TypeScript
20
21 ```typescript
22 import { Composio } from "@composio/core";
23
24 const composio = new Composio();
25 const session = await composio.create("user_123", {
26 tags: {
27 enable: ["readOnlyHint"],
28 disable: ["destructiveHint"],
29 },
30 });
31 ```
32
33 ### API
34
35 ```bash
36 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
37 -H "x-api-key: $COMPOSIO_API_KEY" \
38 -H "Content-Type: application/json" \
39 -d '{"user_id":"user_123","tags":{"enable":["readOnlyHint"],"disable":["destructiveHint"]}}'
40 ```
41
42 <!-- end-languages -->
43
44 Behavior tags describe tool behavior. Inspect the tools the session exposes
45 before rollout, especially when a workflow handles sensitive data.
46
47 - [Filter tools by tags](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
48
49 ## Use exact tool allowlists for the narrowest policy
50
51 For a workflow with a known set of operations, allow only the exact tool slugs
52 it requires. An allowlist avoids admitting a newly added tool merely because it
53 shares a toolkit or behavior tag.
54
55 ### Python
56
57 ```python
58 session = composio.sessions.create(
59 user_id="user_123",
60 tools={
61 "gmail": {"enable": ["GMAIL_FETCH_EMAILS"]},
62 "github": {"enable": ["GITHUB_GET_AN_ISSUE"]},
63 },
64 )
65 ```
66
67 ### TypeScript
68
69 ```typescript
70 import { Composio } from "@composio/core";
71
72 const composio = new Composio();
73 const session = await composio.create("user_123", {
74 tools: {
75 gmail: { enable: ["GMAIL_FETCH_EMAILS"] },
76 github: { enable: ["GITHUB_GET_AN_ISSUE"] },
77 },
78 });
79 ```
80
81 ### API
82
83 ```bash
84 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
85 -H "x-api-key: $COMPOSIO_API_KEY" \
86 -H "Content-Type: application/json" \
87 -d '{"user_id":"user_123","tools":{"gmail":{"enable":["GMAIL_FETCH_EMAILS"]},"github":{"enable":["GITHUB_GET_AN_ISSUE"]}}}'
88 ```
89
90 <!-- end-languages -->
91
92 - [Enable and disable specific tools](https://docs.composio.dev/docs/configuring-sessions#enabling-or-disabling-specific-tools)
93
94 ## Combine provider scopes with session tool restrictions
95
96 OAuth scopes control what the provider grants to a connected account. Session
97 filters control which Composio tools the agent can discover and execute. Use
98 both layers for least privilege: request only the provider scopes the use case
99 needs, then restrict the session to the intended tools.
100
101 Changing an auth config's scopes affects new connections only. Existing users
102 keep their prior grants until they reconnect. Pass the intended auth config ID
103 to the session, keyed by toolkit, or the session will not request those scopes.
104
105 - [Control OAuth scopes](https://docs.composio.dev/docs/authentication/controlling-scopes)
106 - [Select an auth config in a session](https://docs.composio.dev/docs/authentication/custom-app-vs-managed-app#create-a-custom-auth-config)
107
108 ## Apply toolkit-specific exceptions without widening every toolkit
109
110 Set a global tag policy and override it only for a named toolkit. This is safer
111 than relaxing the global policy for the entire session.
112
113 ### Python
114
115 ```python
116 session = composio.sessions.create(
117 user_id="user_123",
118 tags=["readOnlyHint"],
119 tools={
120 "github": {"tags": {"disable": ["destructiveHint"]}},
121 "gmail": {"tags": ["readOnlyHint"]},
122 },
123 )
124 ```
125
126 ### TypeScript
127
128 ```typescript
129 import { Composio } from "@composio/core";
130
131 const composio = new Composio();
132 const session = await composio.create("user_123", {
133 tags: ["readOnlyHint"],
134 tools: {
135 github: { tags: { disable: ["destructiveHint"] } },
136 gmail: { tags: ["readOnlyHint"] },
137 },
138 });
139 ```
140
141 ### API
142
143 ```bash
144 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
145 -H "x-api-key: $COMPOSIO_API_KEY" \
146 -H "Content-Type: application/json" \
147 -d '{"user_id":"user_123","tags":["readOnlyHint"],"tools":{"github":{"tags":{"disable":["destructiveHint"]}},"gmail":{"tags":["readOnlyHint"]}}}'
148 ```
149
150 <!-- end-languages -->
151
152 - [Toolkit-specific tag filters](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
153
154 ## Disable the session sandbox when the workflow does not need code execution
155
156 Session tool filters govern app tools. Sessions also include remote sandbox
157 tools by default. Disable the sandbox for a tightly constrained workflow that
158 does not need Python, shell, file processing, or remote workbench execution.
159
160 ### Python
161
162 ```python
163 session = composio.sessions.create(
164 user_id="user_123",
165 tags=["readOnlyHint"],
166 sandbox={"enable": False},
167 )
168 ```
169
170 ### TypeScript
171
172 ```typescript
173 import { Composio } from "@composio/core";
174
175 const composio = new Composio();
176 const session = await composio.create("user_123", {
177 tags: ["readOnlyHint"],
178 sandbox: { enable: false },
179 });
180 ```
181
182 ### API
183
184 ```bash
185 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
186 -H "x-api-key: $COMPOSIO_API_KEY" \
187 -H "Content-Type: application/json" \
188 -d '{"user_id":"user_123","tags":["readOnlyHint"],"workbench":{"enable":false}}'
189 ```
190
191 <!-- end-languages -->
192
193 - [Disable the session sandbox](https://docs.composio.dev/docs/configuring-sessions#disabling-the-sandbox)