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

Update to quickstart and sessions

Brendan O'Leary committed Sep 21, 2026 at 16:35 UTC 73c2c638a49869c6c68d762fca0ea1d4dcf3b59a
7 files changed +79 -39
docs/bun.lock
+3
@@ -7,6 +7,7 @@
7 "dependencies": {
8 "@ai-sdk/openai": "^4.0.60",
9 "@fuma-translate/react": "^1.0.2",
10 + "@iconify-json/lucide": "^1.2.135",
11 "@pierre/diffs": "^1.4.1",
12 "@pierre/trees": "^1.0.0-beta.6",
13 "@radix-ui/react-tabs": "^1.1.21",
@@ -305,6 +306,8 @@
306
307 "@hono/node-server": ["@hono/node-server@1.19.17", "", { "peerDependencies": { "hono": "^4" } }, "sha512-dSneS5qhiauZWGDCeK4o695Xd9nUNjviSZCMQrj10eetr8Uln1ucn6bbphOM6UynAMMtNIzZNSpL9vnASJwrPQ=="],
308
309 + "@iconify-json/lucide": ["@iconify-json/lucide@1.2.135", "", { "dependencies": { "@iconify/types": "*" } }, "sha512-M2RbCJMe/ZwRzGBxNGbqP3kEQ74iJjQyJsw5FgVQw+Kp8eJPQF1S19fiGJChG4yYLg73c8Z/fMnm07GTXUxmQA=="],
310 +
311 "@iconify/types": ["@iconify/types@2.0.0", "", {}, "sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg=="],
312
313 "@iconify/utils": ["@iconify/utils@3.1.7", "", { "dependencies": { "@antfu/install-pkg": "^2.0.1", "@iconify/types": "^2.0.0", "import-meta-resolve": "^4.2.0" } }, "sha512-JZHlwdID+dy+lTgbYC8NEC4zeugqeYsc6jewvzb4c58kHauJn+X7rNwQjxz5p2qSjqaEeQoLkCIQ9v/H4PK0/w=="],
docs/components/mermaid.tsx
+7
@@ -5,6 +5,13 @@ import mermaid from 'mermaid';
5 import Zoom from 'react-medium-image-zoom';
6 import 'react-medium-image-zoom/dist/styles.css';
7
8 +mermaid.registerIconPacks([
9 + {
10 + name: 'lucide',
11 + loader: () => import('@iconify-json/lucide').then((module) => module.icons),
12 + },
13 +]);
14 +
15 const MOBILE_BREAKPOINT = 768;
16
17 function useIsMobile() {
docs/components/quickstart/quickstart-flow.tsx
+1 -1
@@ -161,7 +161,7 @@ export function QuickstartFlow({ children }: QuickstartFlowProps) {
161 {/* Framework + integration type selector */}
162 {frameworks.length > 0 && (
163 <div className="not-prose mb-6 rounded-lg border border-fd-border bg-fd-card/50 p-4">
164 - <p className="mb-3 text-sm font-medium text-fd-muted-foreground">Choose your framework</p>
164 + <p className="mb-3 text-sm font-medium text-fd-muted-foreground">Choose your agent framework</p>
165 <div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
166 {frameworks.map((framework) => (
167 <FrameworkCard
docs/content/docs/how-composio-works.mdx
+40 -15
@@ -37,13 +37,30 @@ A session scopes four things:
37 - **Authentication**: managed auth, custom auth configs, and connected-account selection.
38 - **Execution state**: logs, tool memory, MCP state, and workbench files for the task.
39
40 -## Tools and toolkits
40
42 -A **toolkit** is a collection of related tools for a service. The `github` toolkit, for example, contains tools for creating issues, managing pull requests, and starring repositories.
41 +## What comes in a session
42 +Every session is designed to come with all of the things you will need for an agentic run for your user. By default, the session will come with all of the [tools and toolkits](#tools-and-toolkits), [authentication](#authentication) (for the given user) and skills needed to execute. Every session also comes with an agent [sandbox](#sandbox) so the agent can handle and manipulate large response, files, etc. outside of the context window for longer responses.
43
44 -A **tool** is an individual action your agent can execute. Each tool has an input schema (its parameters) and an output schema (what it returns), and follows a `{TOOLKIT}_{ACTION}` naming pattern, like `GITHUB_CREATE_ISSUE`.
44 +Later we'll discuss [configuring sessions](/docs/configuring-sessions) for specialized use cases. But for now you can think of the Composio session as the basic building block for your agent.
45
46 -Every toolkit in the catalog is discoverable by default. Create a session without a `toolkits` parameter and the agent can find any of them at runtime. To restrict the set, pass `toolkits` when you create the session. See [Enable and disable toolkits](/docs/configuring-sessions). You can also bind local, in-process tools to a session with the experimental [custom tools and toolkits](/docs/extending-sessions/custom-tools-and-toolkits) API.
46 +```mermaid
47 +architecture-beta
48 + group session(lucide:box)[Composio Session]
49 +
50 + service toolsearch(lucide:book-search)[Tool Search] in session
51 + service toolkits(lucide:toolbox)[Toolkits] in session
52 + service tools(lucide:wrench)[Tools] in session
53 + service sandbox(lucide:scan-box)[Sandbox] in session
54 +
55 + service user(lucide:user)[User Context] in session
56 + service auth(lucide:lock)[Authentication] in session
57 +
58 + user:R -- L:auth
59 + toolsearch:R -- L:toolkits
60 + toolkits:B -- T:tools
61 +```
62 +
63 +Bellow we're going to explain each of the concepts that come with a session.
64
65 ## Users
66
@@ -60,7 +77,23 @@ A user is an identifier from your app. Composio stores connections under that ID
77
78 A user can connect multiple accounts for the same toolkit, like work and personal Gmail. Use the same userID, then select the connected account when a session needs a specific one. See [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts).
79
63 -## Meta tools
80 +## Authentication
81 +
82 +When a tool needs a connection, the session generates a Connect Link with `session.authorize()`, or the agent handles the flow through `COMPOSIO_MANAGE_CONNECTIONS`.
83 +
84 +In chat, the agent can pause, ask the user to connect an app, then retry the tool once auth completes. Composio manages the OAuth redirects, token exchange, and refresh. Once a user connects a toolkit, the connected account persists and future sessions reuse it without re-authentication.
85 +
86 +For OAuth toolkits, Composio uses [managed apps](/docs/authentication/custom-app-vs-managed-app) by default. Bring your own app when you need your own branding, scopes, or consent screen.
87 +
88 +## Tools and Toolkits
89 +
90 +A **toolkit** is a collection of related tools for a service. The `github` toolkit, for example, contains tools for creating issues, managing pull requests, and starring repositories.
91 +
92 +A **tool** is an individual action your agent can execute. Each tool has an input schema (its parameters) and an output schema (what it returns), and follows a `{TOOLKIT}_{ACTION}` naming pattern, like `GITHUB_CREATE_ISSUE`.
93 +
94 +Every toolkit in the catalog is discoverable by default. Create a session without a `toolkits` parameter and the agent can find any of them at runtime. To restrict the set, pass `toolkits` when you create the session. See [Enable and disable toolkits](/docs/configuring-sessions). You can also bind local, in-process tools to a session with the experimental [custom tools and toolkits](/docs/extending-sessions/custom-tools-and-toolkits) API.
95 +
96 +### Meta tools
97
98 A session gives your agent meta tools, a small fixed set that discover, authenticate, and execute tools at runtime, so you never load hundreds of tool definitions into context:
99
@@ -70,7 +103,7 @@ The agent searches for relevant tools, authenticates if needed, and executes the
103
104 Know the exact tools upfront? The [direct tools preset](/docs/configuring-sessions#direct-tools-preset) returns them directly from `session.tools()` with no search step, while keeping session auth, connected accounts, and the workbench.
105
73 -## Executing session tools
106 +### Executing session tools
107
108 When your model asks to call a session tool, execute it with `session.execute()`. It routes the call through the session's tool router, which is the only place session meta-tools run:
109
@@ -93,19 +126,11 @@ const result = await session.execute("COMPOSIO_SEARCH_TOOLS", { queries: [{ use_
126
127 Do not execute session tools with `tools.execute()`, or by passing a user ID to a provider's `handle_tool_calls` helper — both take the direct execution path, which does not carry your session, and meta-tools fail there with `"can only be called inside a tool-router session"`. The [OpenAI](/docs/providers/openai) and [Anthropic](/docs/providers/anthropic) helpers also accept the session itself (`handle_tool_calls(response=response, session=session)` in Python, `handleToolCalls(session, response)` in TypeScript), which routes through the session while keeping provider argument normalization.
128
96 -## Authentication
97 -
98 -When a tool needs a connection, the session generates a Connect Link with `session.authorize()`, or the agent handles the flow through `COMPOSIO_MANAGE_CONNECTIONS`.
99 -
100 -In chat, the agent can pause, ask the user to connect an app, then retry the tool once auth completes. Composio manages the OAuth redirects, token exchange, and refresh. Once a user connects a toolkit, the connected account persists and future sessions reuse it without re-authentication.
101 -
102 -For OAuth toolkits, Composio uses [managed apps](/docs/authentication/custom-app-vs-managed-app) by default. Bring your own app when you need your own branding, scopes, or consent screen.
103 -
129 ## Sandbox
130
131 Handle large responses and bulk operations in the remote sandbox. Instead of stuffing long tool responses into the model context, the agent reads files, searches outputs, writes Python, transforms data, and calls Composio tools in bulk.
132
108 -The sandbox is scoped to the session, so files, variables, helper functions, and intermediate results stay available while the agent works through a task.
133 +The sandbox is scoped to the session, so files, variables, helper functions, and intermediate results stay available while the agent works through a task. Learn more about [sandboxes here](/docs/sandbox/remote).
134
135 ## How sessions behave
136
docs/content/docs/quickstart.mdx
+12 -11
@@ -6,17 +6,18 @@ keywords: [tutorial, setup, first agent, sessions, tool router]
6
7 Build an agent that chooses Composio tools at runtime. Type a task, connect an app if needed, and continue in the same conversation.
8
9 -Pick your framework below. A Composio [session](/docs/how-composio-works) gives your agent tool discovery, account connections, and execution across [1000+ apps](/toolkits). It exposes only a small set of meta tools, so app schemas are loaded when the agent needs them.
9
11 -<AgentSetupActions className="not-prose my-6" />
12 -
13 -<Callout type="info" title="Running as an unattended coding agent?">
14 -If no human is available to log in, use `composio login --agent` to obtain a Composio credential. Follow [Authenticate an unattended agent](/docs/agent-setup/unattended-authentication) to configure `COMPOSIO_API_KEY` and verify a live tool call.
15 -</Callout>
16 -
17 -<Callout type="info">
18 -The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` syntax rather than CommonJS `require()`.
19 -</Callout>
10 +<div className="not-prose my-6 grid grid-cols-1 items-start gap-4 md:grid-cols-2">
11 + <div>
12 + <p className="mb-6">
13 + Pick your framework below. A Composio [session](/docs/how-composio-works) gives your agent tool discovery, account connections, and execution across [1000+ apps](/toolkits). It exposes only a small set of meta tools, so app schemas are loaded when the agent needs them.
14 + </p>
15 + <AgentSetupActions />
16 + </div>
17 + <Callout className="my-0" type="info" title="Running as an unattended coding agent?">
18 + If no human is available to log in, use `composio login --agent` to obtain a Composio credential. Follow [Authenticate an unattended agent](/docs/agent-setup/unattended-authentication) to configure `COMPOSIO_API_KEY` and verify a live tool call.
19 + </Callout>
20 +</div>
21
22 <QuickstartFlow>
23
@@ -471,7 +472,7 @@ Ask for any task that needs an app tool: `Summarize my unread emails from today`
472 ## What just happened?
473
474 - The provider you picked formats Composio tools for your framework and wires in execution.
474 -- `composio.sessions.create()` creates a Composio session for `user_123`. The session scopes connections and tool calls to that ID.
475 +- `composio.sessions.create()` creates a [Composio session](/docs/how-composio-works) for `user_123`. The session scopes connections and tool calls to that ID.
476 - Composio sessions persist. In an application, store the session ID (`session.session_id` in Python, `session.sessionId` in TypeScript) and restore it with `composio.use(session_id)` instead of creating a new session for every turn. See [Reusing a session](/docs/how-composio-works#how-sessions-behave).
477 - `session.tools()` gives the agent a small set of meta tools for finding, connecting, and running app tools. It does not load thousands of tool schemas into the model context.
478
docs/lib/home-navigation.ts
+15 -12
@@ -1,8 +1,7 @@
1 export type DocsProduct = 'for-you' | 'platform';
2
3 export type ProductSidebarItem =
4 - | { type: 'page'; url: string; label?: string }
5 - | { type: 'folder'; path: string; label?: string };
4 + { type: 'page'; url: string; label?: string } | { type: 'folder'; path: string; label?: string };
5
6 export interface ProductSidebarGroup {
7 label: string;
@@ -42,7 +41,7 @@ const SHARED_SIDEBAR_ITEMS: readonly ProductSidebarItem[] = [
41 ];
42
43 const SHARED_ROUTE_PREFIXES = SHARED_SIDEBAR_ITEMS.map(item =>
45 - item.type === 'page' ? item.url : `/docs/${item.path}`,
44 + item.type === 'page' ? item.url : `/docs/${item.path}`
45 );
46
47 /**
@@ -150,7 +149,7 @@ export const DOCS_PRODUCTS = {
149 { type: 'page', url: '/docs/how-composio-works', label: 'Sessions' },
150 { type: 'page', url: '/docs/configuring-sessions' },
151 { type: 'folder', path: 'authentication' },
153 - { type: 'page', url: '/docs/skills', label: 'Tools and skills' },
152 + { type: 'page', url: '/docs/skills', label: 'Skills' },
153 { type: 'page', url: '/docs/triggers' },
154 ],
155 },
@@ -235,23 +234,24 @@ export function classifyDocsProduct(pathname: string): DocsProduct | null {
234
235 export function resolveDocsProduct(
236 pathname: string,
238 - persistedProduct?: string | null,
237 + persistedProduct?: string | null
238 ): DocsProduct {
239 return (
241 - classifyDocsProduct(pathname) ??
242 - parseDocsProduct(persistedProduct) ??
243 - DEFAULT_DOCS_PRODUCT
240 + classifyDocsProduct(pathname) ?? parseDocsProduct(persistedProduct) ?? DEFAULT_DOCS_PRODUCT
241 );
242 }
243
244 export function docsProductDestination(pathname: string, target: DocsProduct): string {
245 const sourceProduct = target === 'platform' ? 'for-you' : 'platform';
249 - const counterpart = PRODUCT_COUNTERPARTS.find(pair => matchesRoute(pathname, pair[sourceProduct]));
246 + const counterpart = PRODUCT_COUNTERPARTS.find(pair =>
247 + matchesRoute(pathname, pair[sourceProduct])
248 + );
249 if (counterpart) return counterpart[target];
250 if (
251 classifyDocsProduct(pathname) !== sourceProduct &&
252 SHARED_ROUTE_PREFIXES.some(prefix => matchesRoute(pathname, prefix))
254 - ) return pathname;
253 + )
254 + return pathname;
255 return DOCS_PRODUCTS[target].landingRoute;
256 }
257
@@ -261,7 +261,7 @@ export function serializeDocsProductCookie(product: DocsProduct): string {
261
262 export function shouldAnimateDocsProductSwitch(
263 supportsViewTransitions: boolean,
264 - prefersReducedMotion: boolean,
264 + prefersReducedMotion: boolean
265 ): boolean {
266 return supportsViewTransitions && !prefersReducedMotion;
267 }
@@ -271,7 +271,10 @@ export function shouldAnimateDocsProductSwitch(
271 * `intent.product`, so the ids are `#platform` / `#for-you`.
272 */
273 export function homeIntentAnchor(label: string): string {
274 - return label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
274 + return label
275 + .toLowerCase()
276 + .replace(/[^a-z0-9]+/g, '-')
277 + .replace(/(^-|-$)/g, '');
278 }
279
280 export function homeIntentsToMarkdown(): string {
docs/package.json
+1
@@ -39,6 +39,7 @@
39 "dependencies": {
40 "@ai-sdk/openai": "^4.0.60",
41 "@fuma-translate/react": "^1.0.2",
42 + "@iconify-json/lucide": "^1.2.135",
43 "@pierre/diffs": "^1.4.1",
44 "@pierre/trees": "^1.0.0-beta.6",
45 "@radix-ui/react-tabs": "^1.1.21",