@devries-cameron20 / composio Mirror · read-only / commits / 19a6219d9
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, 13:30 UTC

Add first draft of harness integration example

Brendan O'Leary committed Aug 28, 2026 at 10:58 UTC 19a6219d9b2f41c92fba443bc1a3f43f0bea9e4b
1 file changed +370
docs/content/examples/harness-integration.mdx new
+370
@@ -0,0 +1,370 @@
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: [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) do the finding, the authenticating, and the running. That is the right default, and it is the wrong shape if you already shipped a harness. You have a planner. You have a retrieval index over your tools. You have a dispatcher, a permission layer, and traces you already know how to read. You don't want another agent inside your agent; you want the 1000+ apps and none of the opinions.
14 +
15 +So use Composio as the layer under your harness. It comes down to four calls:
16 +
17 +1. **List toolkits.** [`session.toolkits()`](/docs/configuring-sessions#toolkits) returns the catalog with each toolkit's live connection state for this user. That's your integrations directory.
18 +2. **Connect what the user picks.** [`session.authorize(slug)`](/docs/authentication) returns a redirect URL. Composio owns the OAuth dance, the token storage, and the refresh.
19 +3. **Load raw tool schemas.** [`composio.tools.getRawComposioTools({ toolkits })`](/docs/configuring-sessions#browsing-the-catalog) returns plain JSON Schema. Feed it to whatever index your planner already searches.
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 + dispatch[Dispatcher]
29 + end
30 + subgraph composio["Composio"]
31 + toolkits["session.toolkits()"]
32 + authorize["session.authorize()"]
33 + schemas["tools.getRawComposioTools()"]
34 + execute["session.execute()"]
35 + end
36 + ui([Your settings UI]) --> toolkits
37 + toolkits --> authorize
38 + authorize --> schemas
39 + schemas --> index
40 + index --> planner
41 + planner --> dispatch
42 + dispatch --> execute
43 + execute --> planner
44 +`} />
45 +
46 +<Callout type="info" title="Is this the right example for you?">
47 +
48 +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.
49 +
50 +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.
51 +</Callout>
52 +
53 +## Setup
54 +
55 +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) and a user id from your own database. There's no model provider in this example: your harness already has one.
56 +
57 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
58 +<Tab value="Python">
59 +<PackageInstall packages="composio" ecosystem="python" />
60 +</Tab>
61 +<Tab value="TypeScript">
62 +<PackageInstall packages="@composio/core" />
63 +</Tab>
64 +</Tabs>
65 +
66 +## Create a session your code drives
67 +
68 +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.
69 +
70 +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 see the whole catalog, which is what step one needs.
71 +
72 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
73 +<Tab value="Python">
74 +```python
75 +from composio import Composio
76 +
77 +composio = Composio()
78 +
79 +# user_id is your own identifier, stable for the life of the account
80 +session = composio.sessions.create(
81 + user_id="user_123",
82 + manage_connections=False,
83 + sandbox={"enable": False},
84 +)
85 +```
86 +</Tab>
87 +<Tab value="TypeScript">
88 +```typescript
89 +import { Composio } from '@composio/core';
90 +
91 +const composio = new Composio();
92 +
93 +// userId is your own identifier, stable for the life of the account
94 +const session = await composio.create('user_123', {
95 + manageConnections: false,
96 + sandbox: { enable: false },
97 +});
98 +```
99 +</Tab>
100 +</Tabs>
101 +
102 +One session per user, created once and reused. 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.
103 +
104 +## 1. List the toolkits
105 +
106 +`session.toolkits()` is the catalog *and* the connection state, in one paginated call. Each item carries the toolkit's slug and name, whether it needs auth at all, and whether this user has a live connection. That's everything an integrations page needs to render.
107 +
108 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
109 +<Tab value="Python">
110 +```python
111 +page = session.toolkits(limit=50)
112 +
113 +for toolkit in page.items:
114 + connected = toolkit.is_no_auth or bool(
115 + toolkit.connection and toolkit.connection.is_active
116 + )
117 + print(f"{'connected' if connected else 'available':<10} {toolkit.slug:<20} {toolkit.name}")
118 +
119 +# page.next_cursor -> pass back as next_cursor= for the next page
120 +```
121 +</Tab>
122 +<Tab value="TypeScript">
123 +```typescript
124 +import { Composio } from '@composio/core';
125 +const composio = new Composio();
126 +const session = await composio.create('user_123');
127 +// ---cut---
128 +const page = await session.toolkits({ limit: 50 });
129 +
130 +for (const toolkit of page.items) {
131 + const connected = toolkit.isNoAuth || toolkit.connection?.isActive === true;
132 + console.log(
133 + `${connected ? 'connected' : 'available'} ${toolkit.slug.padEnd(20)} ${toolkit.name}`
134 + );
135 +}
136 +
137 +// page.cursor -> pass back as { cursor } for the next page
138 +```
139 +</Tab>
140 +</Tabs>
141 +
142 +Two filters matter for a real UI. `search` does the searching for you, so a user typing "issue tracker" gets Linear and Jira without you shipping a fuzzy match over 1000+ slugs. `isConnected` narrows to accounts that are actually live, which is the list step three works from.
143 +
144 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
145 +<Tab value="Python">
146 +```python
147 +matches = session.toolkits(search="issue tracker", limit=10)
148 +connected = session.toolkits(is_connected=True, limit=100)
149 +```
150 +</Tab>
151 +<Tab value="TypeScript">
152 +```typescript
153 +import { Composio } from '@composio/core';
154 +const composio = new Composio();
155 +const session = await composio.create('user_123');
156 +// ---cut---
157 +const matches = await session.toolkits({ search: 'issue tracker', limit: 10 });
158 +const connected = await session.toolkits({ isConnected: true, limit: 100 });
159 +```
160 +</Tab>
161 +</Tabs>
162 +
163 +<Callout type="info" title="Toolkits with no auth">
164 +Toolkits where `isNoAuth` is true (search, scrapers, and similar) come back with no `connection` object at all, because there's nothing to connect. Treat them as always available or your list will show a permanently disconnected Exa.
165 +</Callout>
166 +
167 +## 2. Connect what the user picks
168 +
169 +`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.
170 +
171 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
172 +<Tab value="Python">
173 +```python
174 +request = session.authorize(
175 + "github",
176 + callback_url="https://your-app.com/composio/callback",
177 +)
178 +
179 +# Redirect the user here
180 +print(request.redirect_url)
181 +
182 +# Scripts and CLIs can block; a web server should not
183 +account = request.wait_for_connection()
184 +print(f"Connected account: {account.id}")
185 +```
186 +</Tab>
187 +<Tab value="TypeScript">
188 +```typescript
189 +import { Composio } from '@composio/core';
190 +const composio = new Composio();
191 +const session = await composio.create('user_123');
192 +// ---cut---
193 +const request = await session.authorize('github', {
194 + callbackUrl: 'https://your-app.com/composio/callback',
195 +});
196 +
197 +// Redirect the user here
198 +console.log(request.redirectUrl);
199 +
200 +// Scripts and CLIs can block; a web server should not
201 +const account = await request.waitForConnection();
202 +console.log(`Connected account: ${account.id}`);
203 +```
204 +</Tab>
205 +</Tabs>
206 +
207 +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.
208 +
209 +## 3. Load raw tool schemas for what's connected
210 +
211 +This is the step that plugs into your index. `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 connected toolkits from step one, pull their tools, and write them into whatever corpus your planner already searches.
212 +
213 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
214 +<Tab value="Python">
215 +```python
216 +connected = session.toolkits(is_connected=True, limit=100)
217 +slugs = [toolkit.slug for toolkit in connected.items]
218 +
219 +tools = composio.tools.get_raw_composio_tools(toolkits=slugs)
220 +
221 +for tool in tools:
222 + index.add(
223 + name=tool.slug, # "GITHUB_CREATE_AN_ISSUE"
224 + description=tool.description,
225 + parameters=tool.input_parameters, # JSON Schema
226 + )
227 +```
228 +</Tab>
229 +<Tab value="TypeScript">
230 +```typescript
231 +import { Composio } from '@composio/core';
232 +const composio = new Composio();
233 +const session = await composio.create('user_123');
234 +declare const index: {
235 + add(entry: { name: string; description?: string; parameters?: unknown }): void;
236 +};
237 +// ---cut---
238 +const connected = await session.toolkits({ isConnected: true, limit: 100 });
239 +const slugs = connected.items.map(toolkit => toolkit.slug);
240 +
241 +const tools = await composio.tools.getRawComposioTools({
242 + toolkits: slugs,
243 + important: false,
244 +});
245 +
246 +for (const tool of tools) {
247 + index.add({
248 + name: tool.slug, // "GITHUB_CREATE_AN_ISSUE"
249 + description: tool.description,
250 + parameters: tool.inputParameters, // JSON Schema
251 + });
252 +}
253 +```
254 +</Tab>
255 +</Tabs>
256 +
257 +<Callout type="warn" title="`important: false`, or you get a curated subset">
258 +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.
259 +
260 +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.
261 +</Callout>
262 +
263 +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.
264 +
265 +<Accordions>
266 + <Accordion title="Alternative: let the session decide which tools exist">
267 + `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.
268 +
269 + 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.
270 + </Accordion>
271 +</Accordions>
272 +
273 +### Keep the session in step with what you indexed
274 +
275 +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.
276 +
277 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
278 +<Tab value="Python">
279 +```python
280 +session.update(toolkits={"enable": [*slugs, "linear"]})
281 +```
282 +</Tab>
283 +<Tab value="TypeScript">
284 +```typescript
285 +import { Composio } from '@composio/core';
286 +const composio = new Composio();
287 +const session = await composio.create('user_123');
288 +declare const slugs: string[];
289 +// ---cut---
290 +await session.update({ toolkits: { enable: [...slugs, 'linear'] } });
291 +```
292 +</Tab>
293 +</Tabs>
294 +
295 +A session created with no toolkit filter, as in the setup above, already allows everything and needs no update.
296 +
297 +## 4. Execute by slug
298 +
299 +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.
300 +
301 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
302 +<Tab value="Python">
303 +```python
304 +result = session.execute(
305 + "GITHUB_CREATE_AN_ISSUE",
306 + arguments={
307 + "owner": "ComposioHQ",
308 + "repo": "composio",
309 + "title": "Tool schemas drift between staging and prod",
310 + "body": "Filed by the harness.",
311 + },
312 +)
313 +
314 +if result.error:
315 + raise RuntimeError(result.error)
316 +
317 +print(result.data)
318 +print(result.log_id) # look this up in the dashboard
319 +```
320 +</Tab>
321 +<Tab value="TypeScript">
322 +```typescript
323 +import { Composio } from '@composio/core';
324 +const composio = new Composio();
325 +const session = await composio.create('user_123');
326 +// ---cut---
327 +const result = await session.execute('GITHUB_CREATE_AN_ISSUE', {
328 + owner: 'ComposioHQ',
329 + repo: 'composio',
330 + title: 'Tool schemas drift between staging and prod',
331 + body: 'Filed by the harness.',
332 +});
333 +
334 +if (result.error) {
335 + throw new Error(result.error);
336 +}
337 +
338 +console.log(result.data);
339 +console.log(result.logId); // look this up in the dashboard
340 +```
341 +</Tab>
342 +</Tabs>
343 +
344 +Arguments go through untouched: neither SDK validates them locally, so a wrong field reaches the upstream API and comes back as a populated `error` your planner can read and correct on the next turn, not as an exception. Exceptions are for transport failures and cancellation. `logId` ties the call to its entry in the dashboard, which is the fastest way to see what Composio actually sent upstream when a response surprises you.
345 +
346 +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.
347 +
348 +## What maps to what
349 +
350 +| Your harness | Composio |
351 +| --- | --- |
352 +| Integrations directory | `session.toolkits()` |
353 +| "Connect" button | `session.authorize(slug)` |
354 +| Tool index or retrieval corpus | `composio.tools.getRawComposioTools({ toolkits, important: false })` |
355 +| Tool dispatch | `session.execute(slug, args)` |
356 +| Per-user isolation | one session per user id |
357 +| Audit trail | `result.logId` |
358 +
359 +Your planner, your context window, your approval gate, and your traces stay where they are. What moves to Composio is the OAuth app registration for every service you'd otherwise have registered yourself, the token refresh, the schema maintenance as those APIs change, and one execute call in place of a client per vendor.
360 +
361 +<Callout type="info" title="If the tool set is fixed">
362 +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.
363 +</Callout>
364 +
365 +<Cards>
366 + <Card title="Configuring sessions" href="/docs/configuring-sessions" description="Every filter a session takes: toolkits, tools, tags, auth configs, connected accounts" />
367 + <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" />
368 + <Card title="Authentication" href="/docs/authentication" description="Managed auth, your own OAuth credentials, and pre-connecting accounts" />
369 + <Card title="Proxy execute" href="/docs/extending-sessions/proxy-execute" description="Call an API endpoint Composio doesn't wrap, as the connected account" />
370 +</Cards>
\ No newline at end of file