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
Docs navigation reorganization
Brendan O'Leary committed
Sep 22, 2026 at 09:43 UTC
139f6ec41596814a7c53e56cac0421489824f2e0
6 files changed
+202
-21
docs/content/docs/how-composio-works.mdx
+2
@@ -91,6 +91,8 @@ A **toolkit** is a collection of related tools for a service. The `github` toolk
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
+See [Toolkits](/docs/toolkits) for how tools are grouped, discovered, and used with connected accounts.
95
+
96
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.
97
98
### Meta tools
docs/content/docs/meta.json
+1
@@ -12,6 +12,7 @@
12
"---Core concepts---",
13
"how-composio-works",
14
"configuring-sessions",
15
+ "toolkits",
16
"authentication",
17
"triggers",
18
"skills",
docs/content/docs/toolkits.mdx
new
+91
@@ -0,0 +1,91 @@
1
+---
2
+title: Toolkits
3
+description: How toolkits group app tools, and how your agent discovers, authenticates, and uses them in a session
4
+keywords: [toolkits, tools, toolkit slug, tool slug, sessions, connected accounts]
5
+---
6
+
7
+A **toolkit** is a collection of related tools for an app or service, such as GitHub, Gmail, or Slack. A **tool** is one action your agent can execute, such as creating a GitHub issue or fetching emails from Gmail.
8
+
9
+You choose which toolkits a session can access. Your agent discovers the individual tools it needs for the task.
10
+
11
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
12
+<Tab value="Python">
13
+```python
14
+from composio import Composio
15
+
16
+composio = Composio(api_key="your_api_key")
17
+session = composio.sessions.create(
18
+ user_id="user_123",
19
+ toolkits=["github", "gmail"],
20
+)
21
+
22
+tools = session.tools()
23
+```
24
+</Tab>
25
+<Tab value="TypeScript">
26
+```typescript
27
+import { Composio } from '@composio/core';
28
+
29
+const composio = new Composio({ apiKey: 'your_api_key' });
30
+const session = await composio.create("user_123", {
31
+ toolkits: ["github", "gmail"],
32
+});
33
+
34
+const tools = await session.tools();
35
+```
36
+</Tab>
37
+</Tabs>
38
+
39
+This session can discover and use GitHub and Gmail tools. By default, `session.tools()` returns the session's meta tools for discovery, authentication, and execution, rather than every tool in those toolkits. If you omit `toolkits`, every toolkit in the catalog is discoverable.
40
+
41
+## Toolkits and tools
42
+
43
+Each toolkit has a **slug**, a short identifier you use in configuration. A toolkit can contain many tools, and each tool has its own slug that identifies the action to execute.
44
+
45
+| Toolkit | Toolkit slug | Example tool slug | Action |
46
+| --- | --- | --- | --- |
47
+| GitHub | `github` | `GITHUB_CREATE_AN_ISSUE` | Create an issue in a repository |
48
+| GitHub | `github` | `GITHUB_LIST_PULL_REQUESTS` | List pull requests in a repository |
49
+| GitHub | `github` | `GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER` | Star a repository |
50
+| Gmail | `gmail` | `GMAIL_FETCH_EMAILS` | Fetch emails from a mailbox |
51
+| Slack | `slack` | `SLACK_SEND_MESSAGE` | Send a message to a channel |
52
+
53
+Tool slugs follow the `{TOOLKIT}_{ACTION}` naming pattern. A tool defines an input schema for its parameters and an output schema for its result. For example, creating an issue takes repository details and issue content, then returns information about the created issue.
54
+
55
+Use toolkit slugs when choosing which apps your agent can work with. Use tool slugs when selecting or executing specific actions. Browse the [toolkit catalog](/toolkits) to find available tools and their schemas.
56
+
57
+## How your agent uses a toolkit
58
+
59
+In a default [session](/docs/how-composio-works), your agent works through meta tools:
60
+
61
+1. **Discover.** The agent describes its task to `COMPOSIO_SEARCH_TOOLS`, which finds relevant tools within the session's allowed toolkits and returns their schemas.
62
+2. **Connect.** If a tool needs an account that isn't connected, the agent uses `COMPOSIO_MANAGE_CONNECTIONS` to get a Connect Link for your user.
63
+3. **Execute.** The agent calls the discovered tools through `COMPOSIO_MULTI_EXECUTE_TOOL` with the required arguments.
64
+
65
+Meta tools coordinate this flow across apps. App tools, such as `GITHUB_CREATE_ISSUE`, perform the individual actions. See the [meta tools reference](/toolkits/meta-tools) for their schemas.
66
+
67
+If you know the exact tools your agent needs upfront, use the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) to load them into `session.tools()` without a search step.
68
+
69
+## Toolkits and connected accounts
70
+
71
+Enabling a toolkit makes its tools available to the session. It doesn't connect an account or grant access to an app's data.
72
+
73
+A **connected account** stores a specific user's authenticated connection to a toolkit. For example, `gmail` is the toolkit, while your user's work Gmail account is a connected account. Tools that require authentication execute using that account's credentials and permissions.
74
+
75
+Connections persist across sessions for the same user. A user can also connect multiple accounts for one toolkit, such as work and personal Gmail, and you can select which account a session uses.
76
+
77
+See [Authentication](/docs/authentication) for connection flows and [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts) for account selection.
78
+
79
+## Control which tools are available
80
+
81
+Toolkit filters choose the apps a session can access. Tool filters narrow that access to specific actions within an app. For example, you can enable Gmail but limit your agent to fetching emails and creating drafts.
82
+
83
+Use [session configuration](/docs/configuring-sessions) to enable or disable toolkits, select individual tools, or filter by tags such as read-only. The connected account's permissions still determine what those tools can do in the app.
84
+
85
+You can also attach your own local, in-process tools with the experimental [custom tools and toolkits](/docs/extending-sessions/custom-tools-and-toolkits) API.
86
+
87
+## Related concepts
88
+
89
+- [Sessions](/docs/how-composio-works) tie toolkits, connected accounts, and execution state to a user.
90
+- [Skills](/docs/skills) provide task-specific guidance about which tools to call and in what order. A skill can span multiple toolkits.
91
+- [Triggers](/docs/triggers) notify your app when an event happens in a connected service, so you can start an agent run in response.
docs/lib/home-navigation.ts
+77
-20
@@ -1,7 +1,15 @@
1
export type DocsProduct = 'for-you' | 'platform';
2
3
+export type ProductSidebarGroupLink =
4
+ | { type?: 'page'; url: string; label?: string }
5
+ | { type: 'folder'; path: string; label?: string }
6
+ | { type: 'link'; url: string; label: string; external?: boolean };
7
+
8
export type ProductSidebarItem =
4
- { type: 'page'; url: string; label?: string } | { type: 'folder'; path: string; label?: string };
9
+ | { type: 'page'; url: string; label?: string }
10
+ | { type: 'folder'; path: string; label?: string }
11
+ | { type: 'link'; url: string; label: string; external?: boolean }
12
+ | { type: 'group'; label: string; links: readonly ProductSidebarGroupLink[] };
13
14
export interface ProductSidebarGroup {
15
label: string;
@@ -40,8 +48,12 @@ const SHARED_SIDEBAR_ITEMS: readonly ProductSidebarItem[] = [
48
{ type: 'folder', path: 'security', label: 'Security and data' },
49
];
50
43
-const SHARED_ROUTE_PREFIXES = SHARED_SIDEBAR_ITEMS.map(item =>
44
- item.type === 'page' ? item.url : `/docs/${item.path}`
51
+const SHARED_ROUTE_PREFIXES = SHARED_SIDEBAR_ITEMS.flatMap(item =>
52
+ item.type === 'page' || item.type === 'link'
53
+ ? [item.url]
54
+ : item.type === 'folder'
55
+ ? [`/docs/${item.path}`]
56
+ : item.links.map(link => (link.type === 'folder' ? `/docs/${link.path}` : link.url))
57
);
58
59
/**
@@ -119,6 +131,7 @@ export const DOCS_PRODUCTS = {
131
'/docs/providers',
132
'/docs/how-composio-works',
133
'/docs/configuring-sessions',
134
+ '/docs/toolkits',
135
'/docs/authentication',
136
'/docs/triggers',
137
'/docs/skills',
@@ -144,35 +157,79 @@ export const DOCS_PRODUCTS = {
157
],
158
},
159
{
147
- label: 'Build with Composio',
160
+ label: 'Build',
161
items: [
149
- { type: 'page', url: '/docs/how-composio-works', label: 'Sessions' },
150
- { type: 'page', url: '/docs/configuring-sessions' },
151
- { type: 'folder', path: 'authentication' },
162
+ {
163
+ type: 'group',
164
+ label: 'Sessions',
165
+ links: [
166
+ { url: '/docs/how-composio-works', label: 'What is a Session?' },
167
+ { url: '/docs/configuring-sessions' },
168
+ { url: '/docs/sessions-via-mcp' },
169
+ ],
170
+ },
171
+ { type: 'page', url: '/docs/toolkits' },
172
+ {
173
+ type: 'group',
174
+ label: 'Authentication',
175
+ links: [
176
+ { url: '/docs/authentication', label: 'Authentication with Composio' },
177
+ {
178
+ url: '/docs/authentication/managing-multiple-connected-accounts',
179
+ label: 'Multiple connected accounts',
180
+ },
181
+ { url: '/docs/authentication/controlling-scopes' },
182
+ { url: '/docs/authentication/manually-authenticating' },
183
+ { url: '/docs/authentication/programmatic-auth-configs' },
184
+ { url: '/docs/authentication/importing-existing-connections' },
185
+ ],
186
+ },
187
{ type: 'page', url: '/docs/skills', label: 'Skills' },
153
- { type: 'page', url: '/docs/triggers' },
188
+ {
189
+ type: 'group',
190
+ label: 'Triggers',
191
+ links: [{ url: '/docs/triggers' }, { type: 'folder', path: 'setting-up-triggers' }],
192
+ },
193
],
194
},
195
{
157
- label: 'Guides',
196
+ label: 'Customize',
197
items: [
159
- { type: 'page', url: '/docs/consumer-agents' },
160
- { type: 'page', url: '/docs/b2b-agents' },
161
- { type: 'page', url: '/docs/production-readiness' },
162
- { type: 'page', url: '/docs/sessions-via-mcp' },
163
- { type: 'folder', path: 'sandbox' },
198
{ type: 'folder', path: 'extending-sessions' },
165
- { type: 'folder', path: 'setting-up-triggers' },
199
+ { type: 'folder', path: 'sandbox' },
200
+ {
201
+ type: 'group',
202
+ label: 'Guides & Examples',
203
+ links: [
204
+ { url: '/docs/consumer-agents' },
205
+ { url: '/docs/b2b-agents' },
206
+ { type: 'link', url: '/examples', label: 'Examples' },
207
+ ],
208
+ },
209
+ ],
210
+ },
211
+ {
212
+ label: 'Ship',
213
+ items: [
214
+ { type: 'page', url: '/docs/production-readiness' },
215
+ { type: 'page', url: '/docs/authentication/white-labeling-authentication' },
216
{ type: 'folder', path: 'poc-to-prod' },
217
],
218
},
219
{
170
- label: 'Migration and legacy',
220
+ label: 'Reference and Migration',
221
items: [
172
- { type: 'folder', path: 'migration-guide' },
173
- { type: 'page', url: '/docs/sessions-vs-direct-execution' },
174
- { type: 'folder', path: 'tools-direct' },
175
- { type: 'folder', path: 'auth-configuration' },
222
+ { type: 'link', url: '/reference', label: 'API reference' },
223
+ {
224
+ type: 'group',
225
+ label: 'Migration and legacy',
226
+ links: [
227
+ { type: 'page', url: '/docs/sessions-vs-direct-execution' },
228
+ { type: 'folder', path: 'migration-guide' },
229
+ { type: 'folder', path: 'tools-direct' },
230
+ { type: 'folder', path: 'auth-configuration' },
231
+ ],
232
+ },
233
],
234
},
235
{ label: 'Shared resources', items: SHARED_SIDEBAR_ITEMS },
docs/lib/product-page-tree.ts
+20
-1
@@ -28,6 +28,20 @@ function findFolder(nodes: Node[], path: string): Folder | null {
28
}
29
30
function resolveSidebarItem(tree: Root, item: ProductSidebarItem): Node {
31
+ if (item.type === 'link') {
32
+ return { type: 'page', name: item.label, url: item.url, external: item.external };
33
+ }
34
+
35
+ if (item.type === 'group') {
36
+ if (item.links.length === 0) throw new Error(`Product sidebar group is empty: ${item.label}`);
37
+ const children = item.links.map(link => resolveSidebarItem(tree, { type: 'page', ...link }));
38
+ const first = children[0];
39
+ if (first.type !== 'page') {
40
+ throw new Error(`Product sidebar group has no first page: ${item.label}`);
41
+ }
42
+ return { type: 'folder', name: item.label, index: first, children };
43
+ }
44
+
45
const sourceNode =
46
item.type === 'page'
47
? findPage(tree.children, item.url)
@@ -60,7 +74,12 @@ export function pageTreeUrls(tree: Root): string[] {
74
if (node.type === 'page') {
75
urls.push(node.url);
76
} else if (node.type === 'folder') {
63
- if (node.index) urls.push(node.index.url);
77
+ if (
78
+ node.index &&
79
+ !node.children.some(child => child.type === 'page' && child.url === node.index?.url)
80
+ ) {
81
+ urls.push(node.index.url);
82
+ }
83
visit(node.children);
84
}
85
}
docs/tests/static/product-navigation.test.ts
+11
@@ -136,6 +136,17 @@ describe('Docs product navigation', () => {
136
expect(platformUrls).not.toContain('/docs/agent-plugins');
137
expect(platformUrls).toContain('/docs/agent-setup');
138
139
+ const agentGuides = platformTree.children.find(
140
+ node => node.type === 'folder' && node.name === 'Agent guides',
141
+ );
142
+ expect(agentGuides?.type).toBe('folder');
143
+ if (agentGuides?.type !== 'folder') throw new Error('Agent guides group is missing');
144
+ expect(agentGuides.index?.url).toBe('/docs/consumer-agents');
145
+ expect(agentGuides.children.map(node => node.type === 'page' ? node.url : null)).toEqual(
146
+ ['/docs/consumer-agents', '/docs/b2b-agents'],
147
+ );
148
+ expect(platformUrls.filter(url => url === '/docs/consumer-agents')).toHaveLength(1);
149
+
150
const agentSetup = platformTree.children.find(
151
node => node.type === 'folder' && node.$ref?.folder === 'agent-setup',
152
);