@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, 03:37 UTC

next
mdx 619 lines 26 KB
Raw
1 ---
2 title: Integrate Composio into an existing harness
3 description: "You already have a planner and tool search. This wires Composio in underneath them: list toolkits, connect the ones a user picks, load raw schemas into your own index, and execute by slug. Four calls your code makes, with no agent inside your agent."
4 keywords: [agent harness, own planner, own tool search, raw tools, tool schemas, session toolkits, authorize, session execute, manage connections, direct tools, connected accounts]
5 full: true
6 gallery:
7 categories: [General agents, Coding agents]
8 logos: [github, slack]
9 featured: true
10 order: 4
11 ---
12
13 Most Composio examples hand the agent a session and let Composio's [meta tools](/docs/how-composio-works#meta-tools) find, authenticate, and run tools. That default works well until you already have your own planner, retrieval index, dispatcher, and permission layer. Then you need the %TOOLKIT_COUNT% apps and managed auth, not another agent inside yours.
14
15 Composio sits underneath your harness in four calls:
16
17 1. **List toolkits.** [`composio.toolkits.get()`](/reference/sdk-reference/typescript/toolkits) returns the catalog independent of any user. That's your integrations directory.
18 2. **Connect what the user picks.** [`session.authorize(slug)`](/docs/authentication) starts the OAuth flow for this user. Bring your own OAuth credentials via [auth configs](/docs/authentication/programmatic-auth-configs) for a white-label flow, or [import existing tokens](/docs/authentication/importing-existing-connections) to migrate from another store.
19 3. **Fetch tools.** Load raw JSON Schema with [`composio.tools.getRawComposioTools({ toolkits })`](/docs/configuring-sessions#browsing-the-catalog), or serve the same tools over [MCP](/docs/sessions-via-mcp) and let your harness call them through the protocol.
20 4. **Execute by slug.** [`session.execute(slug, args)`](/docs/how-composio-works#executing-session-tools) runs one tool as the connected user and hands back data.
21
22 Nothing here asks a model to make a decision. Every call is one your code makes, at a moment you choose, because your planner decided.
23
24 <Mermaid chart={`flowchart LR
25 subgraph yours["Your harness"]
26 planner[Planner]
27 index[Tool index]
28 mcpClient[MCP client]
29 dispatch[Dispatcher]
30 end
31 subgraph composio["Composio"]
32 toolkits["composio.toolkits.get()"]
33 authorize["session.authorize()"]
34 schemas["tools.getRawComposioTools()"]
35 mcp["session.mcp"]
36 execute["session.execute()"]
37 end
38 ui([Your settings UI]) --> toolkits
39 toolkits --> authorize
40 toolkits --> schemas
41 toolkits --> mcp
42 schemas --> index
43 index --> planner
44 mcp --> mcpClient
45 mcpClient --> planner
46 planner --> dispatch
47 dispatch --> execute
48 execute --> planner
49 `} />
50
51 <Callout type="info" title="Is this the right example for you?">
52
53 Read this one if you already own the loop: your own planner, your own tool search or retrieval, your own execution and approval path. You get the app catalog, managed auth, and a single execute call, and Composio stays out of the reasoning.
54
55 Read [What is a session?](/docs/how-composio-works) instead if you'd rather Composio did the discovery. Runtime search returns guidance and recommended steps alongside schemas, keeps a shared context across calls, and costs you far less context than loading hundreds of schemas upfront. That's a real advantage to give up knowingly.
56 </Callout>
57
58 ## Setup
59
60 You need a [Composio API key](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=examples-agent-harness) to list the catalog and drive sessions. Listing apps does not need a user id; creating a session and connecting accounts does. There's no model provider in this example: your harness already has one.
61
62 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
63 <Tab value="Python">
64 <PackageInstall packages="composio" ecosystem="python" />
65 </Tab>
66 <Tab value="TypeScript">
67 <PackageInstall packages="@composio/core" />
68 </Tab>
69 </Tabs>
70
71 ## Create a session your code drives
72
73 A [session](/docs/how-composio-works) is the per-user context: which toolkits are in play, which accounts are connected, what may run. You still want one. What changes is that nothing on it ever reaches a model. Your harness never calls `session.tools()`, so the search and execute meta tools sit on the session unused.
74
75 Two settings are still worth passing at creation. `manageConnections: false` drops the connection meta-tools, because your settings page is doing that job. [Disabling the sandbox](/docs/configuring-sessions#disabling-the-sandbox) drops the code-execution tools, because your harness runs its own code. Leave the toolkit filter open and the session can execute any tool your planner names.
76
77 If you want a white-label flow, pass `authConfigs` at creation to pin the session to your own OAuth app. `session.authorize()` then sends the user through your consent screen instead of Composio's managed app. You can update those configs later, so migrating from a default app to your own app is a session patch, not a rebuild.
78
79 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
80 <Tab value="Python">
81 ```python
82 from composio import Composio
83
84 composio = Composio()
85
86 # user_id is your own identifier, stable for the life of the account
87 session = composio.sessions.create(
88 user_id="user_123",
89 manage_connections=False,
90 sandbox={"enable": False},
91 )
92 ```
93 </Tab>
94 <Tab value="TypeScript">
95 ```typescript
96 import { Composio } from '@composio/core';
97
98 const composio = new Composio();
99
100 // userId is your own identifier, stable for the life of the account
101 const session = await composio.create('user_123', {
102 manageConnections: false,
103 sandbox: { enable: false },
104 });
105 ```
106 </Tab>
107 <Tab value="API">
108 ```bash
109 # user_id is your own identifier, stable for the life of the account
110 SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
111 -H "x-api-key: $COMPOSIO_API_KEY" \
112 -H "Content-Type: application/json" \
113 -d '{"user_id": "user_123", "manage_connections": {"enable": false}, "workbench": {"enable": false}}' \
114 | jq -r '.session_id')
115 ```
116 </Tab>
117 </Tabs>
118
119 Create one session per user and reuse it. Sessions persist on the server and don't expire, so store the session id on the user record and pick it back up with `composio.use(sessionId)` on later requests. Calling `create()` again just makes another session.
120
121 ## 1. List the toolkits
122
123 The catalog does not belong to a user. `composio.toolkits.list()` in Python or `composio.toolkits.get()` in TypeScript returns the app list independent of any session, so your integrations page can render before anyone signs in.
124
125 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
126 <Tab value="Python">
127 ```python
128 page = composio.toolkits.list(limit=50)
129
130 for toolkit in page.items:
131 print(f"{toolkit.slug:<20} {toolkit.name}")
132
133 # page.next_cursor -> pass back as next_cursor= for the next page
134 ```
135 </Tab>
136 <Tab value="TypeScript">
137 ```typescript
138 import { Composio } from '@composio/core';
139 const composio = new Composio();
140 // ---cut---
141 const toolkits = await composio.toolkits.get({ limit: 50 });
142
143 for (const toolkit of toolkits) {
144 console.log(`${toolkit.slug.padEnd(20)} ${toolkit.name}`);
145 }
146
147 // pass a cursor as { cursor } to request the next page
148 ```
149 </Tab>
150 <Tab value="API">
151 ```bash
152 curl -X GET "https://backend.composio.dev/api/v3.1/toolkits?limit=50" \
153 -H "x-api-key: $COMPOSIO_API_KEY"
154
155 # Pass the response's next_cursor back as cursor= for the next page
156 ```
157 </Tab>
158 </Tabs>
159
160 Filter by category or sort alphabetically. If you also need to know whether this user has a live connection, call `session.toolkits()` with the same toolkit list; it merges the global catalog with per-user connection state.
161
162 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
163 <Tab value="Python">
164 ```python
165 developer = composio.toolkits.list(category="developer-tools", limit=50)
166 connected = session.toolkits(is_connected=True, limit=100)
167 ```
168 </Tab>
169 <Tab value="TypeScript">
170 ```typescript
171 import { Composio } from '@composio/core';
172 const composio = new Composio();
173 const session = await composio.create('user_123');
174 // ---cut---
175 const developer = await composio.toolkits.get({ category: 'developer-tools', limit: 50 });
176 const connected = await session.toolkits({ isConnected: true, limit: 100 });
177 ```
178 </Tab>
179 <Tab value="API">
180 ```bash
181 curl -X GET "https://backend.composio.dev/api/v3.1/toolkits?category=developer-tools&limit=50" \
182 -H "x-api-key: $COMPOSIO_API_KEY"
183
184 curl -X GET "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?is_connected=true&limit=100" \
185 -H "x-api-key: $COMPOSIO_API_KEY"
186 ```
187 </Tab>
188 </Tabs>
189
190 <Callout type="info" title="Toolkits with no auth">
191 Toolkits where `isNoAuth` is true (search, scrapers, and similar) need no connection. They show up in the global catalog and, if you use `session.toolkits()`, come back with no `connection` object. Treat them as always available.
192 </Callout>
193
194 ## 2. Connect what the user picks
195
196 `session.authorize(slug)` starts the flow and returns a connection request with a redirect URL. Send the user there. Composio holds the credentials and refreshes them; no token ever lands in your code.
197
198 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
199 <Tab value="Python">
200 ```python
201 request = session.authorize(
202 "github",
203 callback_url="https://your-app.com/composio/callback",
204 )
205
206 # Redirect the user here
207 print(request.redirect_url)
208
209 # Scripts and CLIs can block; a web server should not
210 account = request.wait_for_connection()
211 print(f"Connected account: {account.id}")
212 ```
213 </Tab>
214 <Tab value="TypeScript">
215 ```typescript
216 import { Composio } from '@composio/core';
217 const composio = new Composio();
218 const session = await composio.create('user_123');
219 // ---cut---
220 const request = await session.authorize('github', {
221 callbackUrl: 'https://your-app.com/composio/callback',
222 });
223
224 // Redirect the user here
225 console.log(request.redirectUrl);
226
227 // Scripts and CLIs can block; a web server should not
228 const account = await request.waitForConnection();
229 console.log(`Connected account: ${account.id}`);
230 ```
231 </Tab>
232 <Tab value="API">
233 ```bash
234 # Redirect the user to the returned redirect_url
235 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
236 -H "x-api-key: $COMPOSIO_API_KEY" \
237 -H "Content-Type: application/json" \
238 -d '{"toolkit": "github", "callback_url": "https://your-app.com/composio/callback"}'
239 ```
240 </Tab>
241 </Tabs>
242
243 In a web app, don't hold a request open on `waitForConnection`. Point `callbackUrl` at your own route and, when the user lands back on it, confirm with `session.toolkits({ toolkits: ['github'], isConnected: true })`. That check is authoritative and costs one call.
244
245 <Callout type="info" title="White-label OAuth and migrating apps">
246 By default, `session.authorize()` uses Composio's managed OAuth app. To brand the consent screen or control the OAuth client, create an auth config with your own credentials and pass it at session creation.
247
248 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
249 <Tab value="Python">
250 ```python
251 import os
252 from typing import cast
253 from composio.client.types import auth_config_create_params as auth_types
254
255 auth_config = composio.auth_configs.create(
256 toolkit="github",
257 options={
258 "type": "use_custom_auth",
259 "auth_scheme": "OAUTH2",
260 "name": "My GitHub App",
261 # The generated credentials type omits OAuth client fields accepted by the API.
262 "credentials": cast(auth_types.AuthConfigUnionMember1Credentials, {
263 "client_id": os.environ["GITHUB_CLIENT_ID"],
264 "client_secret": os.environ["GITHUB_CLIENT_SECRET"],
265 "oauth_redirect_uri": "https://backend.composio.dev/api/v1/auth-apps/add",
266 }),
267 },
268 )
269
270 session = composio.sessions.create(
271 user_id="user_123",
272 toolkits=["github"],
273 auth_configs={"github": auth_config.id},
274 manage_connections=False,
275 sandbox={"enable": False},
276 )
277 ```
278 </Tab>
279 <Tab value="TypeScript">
280 ```typescript
281 import { Composio } from '@composio/core';
282 const composio = new Composio();
283 // ---cut---
284 const authConfig = await composio.authConfigs.create('github', {
285 type: 'use_custom_auth',
286 authScheme: 'OAUTH2',
287 name: 'My GitHub App',
288 credentials: {
289 client_id: process.env.GITHUB_CLIENT_ID!,
290 client_secret: process.env.GITHUB_CLIENT_SECRET!,
291 oauth_redirect_uri: 'https://backend.composio.dev/api/v1/auth-apps/add',
292 },
293 });
294
295 const session = await composio.sessions.create('user_123', {
296 toolkits: ['github'],
297 authConfigs: { github: authConfig.id },
298 manageConnections: false,
299 sandbox: { enable: false },
300 });
301 ```
302 </Tab>
303 <Tab value="API">
304 ```bash
305 AUTH_CONFIG_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/auth_configs \
306 -H "x-api-key: $COMPOSIO_API_KEY" \
307 -H "Content-Type: application/json" \
308 -d '{
309 "toolkit": {"slug": "github"},
310 "auth_config": {
311 "type": "use_custom_auth",
312 "authScheme": "OAUTH2",
313 "name": "My GitHub App",
314 "credentials": {
315 "client_id": "'"$GITHUB_CLIENT_ID"'",
316 "client_secret": "'"$GITHUB_CLIENT_SECRET"'",
317 "oauth_redirect_uri": "https://backend.composio.dev/api/v1/auth-apps/add"
318 }
319 }
320 }' | jq -r '.auth_config.id')
321
322 SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
323 -H "x-api-key: $COMPOSIO_API_KEY" \
324 -H "Content-Type: application/json" \
325 -d '{
326 "user_id": "user_123",
327 "toolkits": {"enable": ["github"]},
328 "auth_configs": {"github": "'"$AUTH_CONFIG_ID"'"},
329 "manage_connections": {"enable": false},
330 "workbench": {"enable": false}
331 }' | jq -r '.session_id')
332 ```
333 </Tab>
334 </Tabs>
335
336 To migrate users from an existing token store, create a connected account directly with `composio.connectedAccounts.initiate()` (TypeScript) or `composio.connected_accounts.initiate()` (Python). You can update `authConfigs` on the session later, so moving from the default app to your own app is a patch rather than a rebuild.
337 </Callout>
338
339 ## 3. Fetch tools
340
341 Your harness can consume tools in two shapes. Load raw JSON Schema and call them yourself, or expose them through an MCP server and let your harness call them over the protocol.
342
343 ### Option A: Raw JSON Schema
344
345 `getRawComposioTools` returns tool definitions with no user context and no provider wrapping: a slug, a name, a description, and input parameters as plain JSON Schema. Take the toolkits you want to expose, pull their tools, and write them into whatever corpus your planner already searches.
346
347 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
348 <Tab value="Python">
349 ```python
350 connected = session.toolkits(is_connected=True, limit=100)
351 slugs = [toolkit.slug for toolkit in connected.items]
352
353 tools = composio.tools.get_raw_composio_tools(toolkits=slugs)
354
355 for tool in tools:
356 index.add(
357 name=tool.slug, # "GITHUB_CREATE_AN_ISSUE"
358 description=tool.description,
359 parameters=tool.input_parameters, # JSON Schema
360 )
361 ```
362 </Tab>
363 <Tab value="TypeScript">
364 ```typescript
365 import { Composio } from '@composio/core';
366 const composio = new Composio();
367 const session = await composio.create('user_123');
368 declare const index: {
369 add(entry: { name: string; description?: string; parameters?: unknown }): void;
370 };
371 // ---cut---
372 const connected = await session.toolkits({ isConnected: true, limit: 100 });
373 const slugs = connected.items.map(toolkit => toolkit.slug);
374
375 const tools = await composio.tools.getRawComposioTools({
376 toolkits: slugs,
377 important: false,
378 });
379
380 for (const tool of tools) {
381 index.add({
382 name: tool.slug, // "GITHUB_CREATE_AN_ISSUE"
383 description: tool.description,
384 parameters: tool.inputParameters, // JSON Schema
385 });
386 }
387 ```
388 </Tab>
389 <Tab value="API">
390 ```bash
391 SLUGS=$(curl -s -X GET "https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits?is_connected=true&limit=100" \
392 -H "x-api-key: $COMPOSIO_API_KEY" \
393 | jq -r '[.items[].slug] | join(",")')
394
395 # Each item has slug, description, and input_parameters (JSON Schema)
396 curl -X GET "https://backend.composio.dev/api/v3.1/tools?toolkit_slug=$SLUGS" \
397 -H "x-api-key: $COMPOSIO_API_KEY"
398 ```
399 </Tab>
400 </Tabs>
401
402 <Callout type="warn" title="Pass `important: false` to fetch every tool, not a curated subset">
403 In TypeScript, `getRawComposioTools({ toolkits })` applies Composio's `important` flag on your behalf and returns a hand-picked subset of each toolkit rather than all of it. Nothing errors; the list is just shorter than the toolkit, which is a bad surprise to find in an index weeks later. The auto-apply is suppressed by `important: false` and by passing any of `tools`, `tags`, `search`, or `limit`, so a call that already sets a large `limit` is getting the full list. The Python method has no `important` parameter and always returns the unfiltered list.
404
405 Which you want depends on your index. Curated is a reasonable default for semantic search over a few toolkits. Full is what you want when your planner needs to name an exact tool.
406 </Callout>
407
408 Fetch per toolkit rather than in one shot once a user has a lot connected. Thirty toolkits at full breadth is several thousand schemas, and you almost certainly want them cached, keyed by toolkit and refreshed on your own schedule, rather than pulled on every turn.
409
410 ### Option B: MCP server
411
412 Create a session with `mcp: true` and hand `session.mcp.url` (and `session.mcp.headers` if required) to any MCP client. The server exposes the same tools and executes them under the session's connected accounts, so your harness talks the protocol instead of calling `session.execute()` directly.
413
414 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
415 <Tab value="Python">
416 ```python
417 from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
418
419 composio = Composio()
420
421 session = composio.sessions.create(
422 user_id="user_123",
423 toolkits=["gmail"],
424 tools={
425 "gmail": {
426 "enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"],
427 },
428 },
429 session_preset=SESSION_PRESET_DIRECT_TOOLS,
430 mcp=True,
431 )
432
433 print(session.mcp.url)
434 print(session.mcp.headers)
435 ```
436 </Tab>
437 <Tab value="TypeScript">
438 ```typescript
439 import { Composio, SessionPreset } from '@composio/core';
440
441 const composio = new Composio();
442
443 const session = await composio.sessions.create('user_123', {
444 toolkits: ['gmail'],
445 tools: {
446 gmail: {
447 enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_CREATE_EMAIL_DRAFT'],
448 },
449 },
450 sessionPreset: SessionPreset.DIRECT_TOOLS,
451 mcp: true,
452 });
453
454 console.log(session.mcp.url);
455 console.log(session.mcp.headers);
456 ```
457 </Tab>
458 <Tab value="API">
459 ```bash
460 # The direct-tools preset is these settings: no connection manager, sandbox,
461 # search, or multi-execute, and every allowed tool preloaded
462 curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
463 -H "x-api-key: $COMPOSIO_API_KEY" \
464 -H "Content-Type: application/json" \
465 -d '{
466 "user_id": "user_123",
467 "toolkits": {"enable": ["gmail"]},
468 "tools": {"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}},
469 "manage_connections": {"enable": false},
470 "workbench": {"enable": false},
471 "preload": {"tools": "all"},
472 "search": {"enable": false},
473 "execute": {"enable_multi_execute": false}
474 }' | jq -r '.mcp.url'
475
476 # MCP clients authenticate to that URL with the same x-api-key header
477 ```
478 </Tab>
479 </Tabs>
480
481 Wire the URL into any MCP client. Examples for OpenAI Agents, Claude Agent SDK, and Vercel AI SDK are in the [sessions via MCP guide](/docs/sessions-via-mcp).
482
483 <Accordions>
484 <Accordion title="Alternative: let the session decide which tools exist">
485 `getRawComposioTools` reads the catalog and ignores your session's filters. If you'd rather have one source of truth, scope the session and read its tool list back instead: set `preload: { tools: 'all' }` alongside a toolkit filter, then fetch with `composio.tools.getRawToolRouterSessionTools(session.sessionId)` in TypeScript or `composio.tools.get_raw_tool_router_meta_tools(session.session_id)` in Python. You get exactly the tools the session allows, so the set you index and the set that can execute can't drift apart.
486
487 The trade-off is that every change to the exposed set becomes a session update rather than a local filter, and the returned list includes any meta tools the session still has enabled.
488 </Accordion>
489 </Accordions>
490
491 ### Keep the session in step with what you indexed
492
493 If you scoped the session to specific toolkits, that filter is what gates execution later. When a user connects something new, widen the session rather than creating another one. `session.update()` is a patch: fields you omit are left alone.
494
495 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
496 <Tab value="Python">
497 ```python
498 session.update(toolkits={"enable": [*slugs, "linear"]})
499 ```
500 </Tab>
501 <Tab value="TypeScript">
502 ```typescript
503 import { Composio } from '@composio/core';
504 const composio = new Composio();
505 const session = await composio.create('user_123');
506 declare const slugs: string[];
507 // ---cut---
508 await session.update({ toolkits: { enable: [...slugs, 'linear'] } });
509 ```
510 </Tab>
511 <Tab value="API">
512 ```bash
513 # List the toolkits already in your index, plus the new one
514 curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
515 -H "x-api-key: $COMPOSIO_API_KEY" \
516 -H "Content-Type: application/json" \
517 -d '{"toolkits": {"enable": ["github", "linear"]}}'
518 ```
519 </Tab>
520 </Tabs>
521
522 A session created with no toolkit filter, as in the setup above, already allows everything and needs no update.
523
524 ## 4. Execute by slug
525
526 Your planner picked a tool and produced arguments. `session.execute` runs it as this user's connected account and returns the result. No model, no retry loop, no interpretation.
527
528 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
529 <Tab value="Python">
530 ```python
531 result = session.execute(
532 "GITHUB_CREATE_AN_ISSUE",
533 arguments={
534 "owner": "ComposioHQ",
535 "repo": "composio",
536 "title": "Tool schemas drift between staging and prod",
537 "body": "Filed by the harness.",
538 },
539 )
540
541 if result.result_type == "failed":
542 raise RuntimeError(result.error or f"Tool execution failed (log ID: {result.log_id})")
543
544 print(result.data)
545 print(result.log_id) # look this up in the dashboard
546 ```
547 </Tab>
548 <Tab value="TypeScript">
549 ```typescript
550 import { Composio } from '@composio/core';
551 const composio = new Composio();
552 const session = await composio.create('user_123');
553 // ---cut---
554 const result = await session.execute('GITHUB_CREATE_AN_ISSUE', {
555 owner: 'ComposioHQ',
556 repo: 'composio',
557 title: 'Tool schemas drift between staging and prod',
558 body: 'Filed by the harness.',
559 });
560
561 if (result.resultType === 'failed') {
562 throw new Error(result.error || `Tool execution failed (log ID: ${result.logId})`);
563 }
564
565 console.log(result.data);
566 console.log(result.logId); // look this up in the dashboard
567 ```
568 </Tab>
569 <Tab value="API">
570 ```bash
571 # The response carries result_type, data, error, and log_id
572 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute \
573 -H "x-api-key: $COMPOSIO_API_KEY" \
574 -H "Content-Type: application/json" \
575 -d '{
576 "tool_slug": "GITHUB_CREATE_AN_ISSUE",
577 "arguments": {
578 "owner": "ComposioHQ",
579 "repo": "composio",
580 "title": "Tool schemas drift between staging and prod",
581 "body": "Filed by the harness."
582 }
583 }'
584 ```
585 </Tab>
586 </Tabs>
587
588 Check `resultType` (`result_type` in Python), not `error`, to tell whether execution succeeded. A failed execution can have null or empty error text. The tool-specific `data` payload has no guaranteed `successful` field. See [Reading execution results](/docs/how-composio-works#reading-execution-results) for the result envelope.
589
590 Transport failures, cancellation, and [requests for user input](/docs/how-composio-works#handling-requests-for-user-input) can raise exceptions instead of returning a result. `logId` (`log_id` in Python) ties the call to its entry in the dashboard so you can inspect what Composio sent upstream.
591
592 When the thing you need isn't wrapped as a tool, [`session.proxyExecute()`](/docs/extending-sessions/proxy-execute) calls the raw API endpoint under the same connected account.
593
594 ## What maps to what
595
596 | Your harness | Composio |
597 | --- | --- |
598 | Integrations directory | `composio.toolkits.get()` / `composio.toolkits.list()` |
599 | Per-user connection state | `session.toolkits()` |
600 | "Connect" button | `session.authorize(slug)` |
601 | White-label OAuth app | `authConfigs` at session creation |
602 | Tool index or retrieval corpus | `composio.tools.getRawComposioTools({ toolkits, important: false })` |
603 | MCP tool server | `session.mcp` |
604 | Tool dispatch | `session.execute(slug, args)` |
605 | Per-user isolation | one session per user id |
606 | Audit trail | `result.logId` |
607
608 Your planner, context window, approval gate, and traces stay the same. Composio takes over the global app catalog, OAuth registration, token refresh, schema maintenance, and the execute path, whether you call `session.execute()` directly or through the MCP server.
609
610 <Callout type="info" title="If the tool set is fixed">
611 A harness with a known, small tool set doesn't need step three at all. Create the session with the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) and an explicit `tools` filter, and `session.tools()` hands back exactly those tools with search, multi-execute, connection management, and the sandbox all off. That's `sessionPreset: SessionPreset.DIRECT_TOOLS` in TypeScript and `session_preset=SESSION_PRESET_DIRECT_TOOLS` in Python. Worth it when the list is short and stable; the four calls above are for when the list is whatever the user connected this morning.
612 </Callout>
613
614 <Cards>
615 <Card title="Configuring sessions" href="/docs/configuring-sessions" description="Every filter a session takes: toolkits, tools, tags, auth configs, connected accounts" />
616 <Card title="What is a session?" href="/docs/how-composio-works" description="The runtime context behind all four calls, and what the meta tools do when you leave them on" />
617 <Card title="Authentication" href="/docs/authentication" description="Managed auth, your own OAuth credentials, and pre-connecting accounts" />
618 <Card title="Proxy execute" href="/docs/extending-sessions/proxy-execute" description="Call an API endpoint Composio doesn't wrap, as the connected account" />
619 </Cards>