@devries-cameron20 / composio Mirror · read-only / commits / 7f5bb7461
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 22, 07:00 UTC

docs: improve core concepts page structure and cross-linking

Restructure the 6 core concept pages to create a clear reading path and reduce content duplication with the hub page. - how-composio-works: add learning path overview, tighten meta tools section (remove duplicate table), remove thin Tool discovery/execution sections, add "What to read next" cards - users-and-sessions: add quickstart callout, add Authentication as next concept in reading path - authentication: add decision tree for in-chat vs manual auth, restructure bottom links into "What to read next" + "Related guides" - tools-and-toolkits: add Workbench and Direct execution links - workbench: add Triggers as next concept - triggers: add auth prerequisite callout Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Feb 23, 2026 at 19:43 UTC 7f5bb7461921e57c99d03eab2b6b2ff0f59be207
6 files changed +74 -114
docs/content/docs/authentication.mdx
+32 -27
@@ -4,15 +4,20 @@ description: Understand how Composio handles user authentication to toolkits
4 keywords: [connect link, oauth, auth config]
5 ---
6
7 -Composio simplifies authentication with Connect Links: hosted pages where users securely connect their accounts.
7 +Composio simplifies authentication with Connect Links: hosted pages where users securely connect their accounts. There are two approaches. Choose based on where in your app users should authenticate.
8
9 <Video src="/images/connect-link-auth-flow-recording.mp4" autoPlay />
10
11 -## In-chat authentication
11 +## Which approach should I use?
12 +
13 +- **Users chat with your agent?** Use [in-chat authentication](#in-chat-authentication). The agent handles connection prompts automatically, no setup needed.
14 +- **Want users connected before they chat?** Use [manual authentication](#manual-authentication). Your app calls `session.authorize()` during onboarding or from a settings page.
15
13 -By default, when a tool requires authentication, the agent prompts the user with a Connect Link. The user authenticates and confirms in chat. The agent handles OAuth flows, token refresh, and credential management automatically.
16 +Not sure? Start with in-chat. You can add manual auth later.
17
15 -Here's what this looks like in a conversation:
18 +## In-chat authentication
19 +
20 +By default, when a tool requires authentication, the agent prompts the user with a Connect Link. The user authenticates and confirms in chat. No setup needed. Just create a session and the agent handles OAuth flows, token refresh, and credential management automatically.
21
22 > **You:** Summarize my emails from today
23 >
@@ -22,18 +27,20 @@ Here's what this looks like in a conversation:
27 >
28 > **Agent:** Here's a summary of your emails from today...
29
25 -This flow works well for chat applications where users interact directly with the agent.
26 -
27 -<Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication">
28 - Let the agent handle authentication prompts automatically during conversation
30 +<Card icon={<MessageCircle />} title="In-chat authentication guide" href="/docs/authenticating-users/in-chat-authentication">
31 + Configuration, callback URLs, and full examples
32 </Card>
33
34 ## Manual authentication
35
33 -For apps that manage auth outside of chat, use `session.authorize()` to generate Connect Links programmatically. This is useful when you want users to connect accounts during onboarding, or when building a custom connections page.
36 +Use `session.authorize()` to generate Connect Links programmatically when you want to control when and where users authenticate. Common use cases:
37
35 -<Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
36 - Control when and how users connect their accounts
38 +- **Onboarding**: connect accounts during signup before the user ever chats with the agent
39 +- **Settings page**: let users manage their connections from a dedicated UI
40 +- **Pre-flight checks**: verify all required connections are active before starting a task
41 +
42 +<Card icon={<ShieldCheck />} title="Manual authentication guide" href="/docs/authenticating-users/manually-authenticating">
43 + `session.authorize()` API, callback URLs, and connection status checks
44 </Card>
45
46 ## How Composio manages authentication
@@ -42,9 +49,9 @@ Behind the scenes, Composio uses **auth configs** to manage authentication.
49
50 An **auth config** is a blueprint that defines how authentication works for a toolkit across all your users. It specifies:
51
45 -- **Authentication method** — OAuth2, Bearer token, API key, or Basic Auth
46 -- **Scopes** — what actions your tools can perform
47 -- **Credentials** — your own app credentials or Composio's managed auth
52 +- **Authentication method**: OAuth2, Bearer token, API key, or Basic Auth
53 +- **Scopes**: what actions your tools can perform
54 +- **Credentials**: your own app credentials or Composio's managed auth
55
56 Composio creates one auth config per toolkit, and it applies to every user who connects that toolkit. When a user authenticates, Composio creates a **connected account** that stores their credentials (OAuth tokens or API keys) and links them to your user ID. When you need to use your own OAuth credentials or customize scopes, you can create [custom auth configs](/docs/using-custom-auth-configuration).
57
@@ -91,19 +98,17 @@ You only need to create a custom auth config when:
98
99 To bring your own OAuth apps or customize scopes, see [custom auth configs](/docs/using-custom-auth-configuration).
100
94 -## Useful links
101 +## What to read next
102 +
103 +<Cards>
104 + <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools" />
105 + <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication" description="Let the agent prompt users to authenticate during conversation" />
106 + <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating" description="Generate Connect Links programmatically in your app" />
107 +</Cards>
108 +
109 +### Related guides
110
111 <Cards>
97 - <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication">
98 - Let the agent prompt users to authenticate during conversation
99 - </Card>
100 - <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
101 - Generate Connect Links programmatically in your app
102 - </Card>
103 - <Card icon={<Palette />} title="White-labeling" href="/docs/white-labeling-authentication">
104 - Customize OAuth screens with your branding
105 - </Card>
106 - <Card icon={<Key />} title="Custom auth configs" href="/docs/using-custom-auth-configuration">
107 - Use your own OAuth apps
108 - </Card>
112 + <Card icon={<Palette />} title="White-labeling" href="/docs/white-labeling-authentication" description="Customize OAuth screens with your branding" />
113 + <Card icon={<Key />} title="Custom auth configs" href="/docs/using-custom-auth-configuration" description="Use your own OAuth apps" />
114 </Cards>
docs/content/docs/how-composio-works.mdx
+22 -73
@@ -6,7 +6,15 @@ keywords: [architecture, how it works, sessions, meta tools, execution]
6
7 Composio connects AI agents to external services like GitHub, Gmail, and Slack. Your agent gets a small set of meta tools that can discover, authenticate, and execute tools across hundreds of apps at runtime.
8
9 -This page covers sessions, the meta tool pattern, authentication, and how tools execute. For setup, see the [quickstart](/docs/quickstart). For detailed concepts, see [Users & Sessions](/docs/users-and-sessions) and [Tools and toolkits](/docs/tools-and-toolkits).
9 +This page is a high-level overview. Each concept has a dedicated page with full details:
10 +
11 +1. [Users & Sessions](/docs/users-and-sessions): how users and sessions scope tools and connections
12 +2. [Authentication](/docs/authentication): Connect Links, OAuth, API keys, and auth configs
13 +3. [Tools and toolkits](/docs/tools-and-toolkits): meta tools, discovery, and execution
14 +4. [Workbench](/docs/workbench): persistent Python sandbox for bulk operations
15 +5. [Triggers](/docs/triggers): event-driven payloads from connected apps
16 +
17 +For hands-on setup, see the [quickstart](/docs/quickstart).
18
19 ## Sessions
20
@@ -57,45 +65,11 @@ graph LR
65 classDef annotation stroke-dasharray: 5 5
66 ```
67
60 -| Meta tool | What it does |
61 -|-----------|-------------|
62 -| `COMPOSIO_SEARCH_TOOLS` | Finds relevant tools by use case, returns input schemas, connection status, execution plan, and related tools |
63 -| `COMPOSIO_MANAGE_CONNECTIONS` | Generates Connect Links for OAuth and API key authentication |
64 -| `COMPOSIO_MULTI_EXECUTE_TOOL` | Executes up to 20 tools in parallel with the user's credentials |
65 -| `COMPOSIO_REMOTE_WORKBENCH` | Runs Python code in a [persistent sandbox](/docs/workbench) |
66 -| `COMPOSIO_REMOTE_BASH_TOOL` | Runs bash commands in the same sandbox for file operations and data processing |
67 -
68 -Meta tool calls within a session share context through a `session_id`. The agent can search for a tool in one call and execute it in the next without losing state. Tools can also store information (IDs, relationships) in memory for subsequent calls.
69 -
70 -### How they work together
68 +The agent searches for relevant tools, authenticates if needed, and executes them, all through these 5 meta tools. For large responses or bulk operations, the agent offloads work to the workbench sandbox. Meta tool calls share context through a `session_id`, so the agent can search in one call and execute in the next without losing state.
69
72 -The meta tools are how the agent reaches the actual toolkit tools:
70 +Composio also surfaces **learned plans** from past executions: step-by-step workflows that have worked before for similar tasks, guiding the agent without starting from scratch.
71
74 -```mermaid
75 -graph TD
76 - A["Agent: 'Create a GitHub issue for this bug'"] --> B["COMPOSIO_SEARCH_TOOLS"]
77 - B --> C["GITHUB_CREATE_ISSUE"]
78 - B --> C2["GITHUB_LIST_ISSUES"]
79 - B --> C3["GITHUB_GET_REPO"]
80 - B -.- B1["Returns matching tools with schemas"]:::annotation
81 - C --> D["COMPOSIO_MULTI_EXECUTE_TOOL"]
82 - D --> E["GitHub API"]
83 - D -.- D1["Injects user's OAuth token, makes the call"]:::annotation
84 -
85 - classDef annotation stroke-dasharray: 5 5
86 -```
87 -
88 -`COMPOSIO_SEARCH_TOOLS` discovers the right toolkit tools for the task. `COMPOSIO_MULTI_EXECUTE_TOOL` runs them against the external API with the user's credentials. If the user isn't authenticated yet, `COMPOSIO_MANAGE_CONNECTIONS` handles that in between.
89 -
90 -For large responses or bulk operations (labeling hundreds of emails, processing CSVs), the agent uses `COMPOSIO_REMOTE_WORKBENCH` to run Python with helper functions like `invoke_llm` and `run_composio_tool`.
91 -
92 -<Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, context management, and execution" />
93 -
94 -## Tool discovery
95 -
96 -When the agent calls `COMPOSIO_SEARCH_TOOLS`, Composio runs a Vector + BM25 hybrid search across all available toolkits to find the right tools for a given use-case query. The search returns matching tool schemas, connection statuses, and related tools in a single call.
97 -
98 -Composio also surfaces **learned plans** from past executions. These are step-by-step workflows that have worked before for similar tasks, guiding the LLM to better perform an operation without starting from scratch.
72 +<Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Full details on meta tools, discovery, and execution" />
73
74 ## Authentication
75
@@ -111,22 +85,9 @@ In a conversation, this looks like:
85 >
86 > **Agent:** Created issue #42 on your-org/your-repo.
87
114 -Composio manages the OAuth flow end to end: redirects, authorization codes, token exchange, and automatic token refresh before expiration. Credentials are encrypted and scoped to user IDs.
115 -
116 -Connections persist across sessions. A user who connects GitHub once can use it in every future session without re-authenticating. Users can also connect multiple accounts for the same service (work and personal Gmail, for example).
88 +Composio manages the OAuth flow end to end: redirects, token exchange, and automatic refresh. Connections persist across sessions. A user who connects GitHub once can use it in every future session without re-authenticating.
89
118 -For apps that manage auth outside of chat, like during onboarding or on a settings page, use `session.authorize()` to generate Connect Links programmatically and wait for the user to complete the flow.
119 -
120 -<Cards>
121 - <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and custom auth configs" />
122 - <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating" description="Authenticate users outside of chat with session.authorize()" />
123 -</Cards>
124 -
125 -## Tool execution
126 -
127 -When the agent calls `COMPOSIO_MULTI_EXECUTE_TOOL`, Composio resolves the session to look up the user and their connections, validates the input against the tool's schema, injects the user's OAuth token or API key, calls the external API, and returns a structured result.
128 -
129 -Your agent doesn't touch API credentials or handle token refresh. Composio resolves credentials from the session and connected account, makes the authenticated call, and returns the result.
90 +<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and custom auth configs" />
91
92 ## Remote workbench
93
@@ -141,25 +102,13 @@ This keeps the agent's context window lean while still letting it handle operati
102
103 <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for large-context operations" />
104
144 -## Direct tool execution
105 +## What to read next
106
146 -If you know exactly which tools you need, you can skip the meta tool pattern and execute tools directly:
107 +Start with the concepts in order, or jump to the quickstart if you want to build right away:
108
148 -```python
149 -composio = Composio()
150 -
151 -tools = composio.tools.get(
152 - user_id="user_123",
153 - toolkits=["github"]
154 -)
155 -
156 -result = composio.tools.execute(
157 - "GITHUB_STAR_REPOSITORY",
158 - user_id="user_123",
159 - arguments={"owner": "composiohq", "repo": "composio"}
160 -)
161 -```
162 -
163 -This is useful for deterministic workflows where the agent doesn't need to discover tools at runtime.
164 -
165 -<Card icon={<Zap />} title="Direct tool execution" href="/docs/tools-direct/executing-tools" description="Fetch, authenticate, and execute tools without meta tools" />
109 +<Cards>
110 + <Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
111 + <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
112 + <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, discovery, and execution" />
113 + <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent in 5 minutes" />
114 +</Cards>
docs/content/docs/tools-and-toolkits.mdx
+5 -7
@@ -78,13 +78,11 @@ If a tool requires authentication and the user hasn't connected yet, the agent c
78 Learn how Composio handles user authentication
79 </Card>
80
81 -## Useful links
81 +## What to read next
82
83 <Cards>
84 - <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits">
85 - Explore all available toolkits
86 - </Card>
87 - <Card icon={<Wrench />} title="Fetching tools" href="/docs/toolkits/fetching-tools-and-toolkits">
88 - Browse the catalog and fetch tools for sessions
89 - </Card>
84 + <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for bulk operations and data processing" />
85 + <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits" description="Explore all available toolkits" />
86 + <Card icon={<Wrench />} title="Fetching tools" href="/docs/toolkits/fetching-tools-and-toolkits" description="Browse the catalog and fetch tools for sessions" />
87 + <Card icon={<Zap />} title="Direct tool execution" href="/docs/tools-direct/executing-tools" description="Execute tools without meta tools for deterministic workflows" />
88 </Cards>
docs/content/docs/triggers.mdx
+4
@@ -30,6 +30,10 @@ When you create a trigger from a type, it's scoped to a specific user and connec
30 </Accordion>
31 </Accordions>
32
33 +<Callout>
34 +Triggers are scoped to a connected account. If you haven't set up authentication yet, see [Authentication](/docs/authentication).
35 +</Callout>
36 +
37 ## Next steps
38
39 <Cards>
docs/content/docs/users-and-sessions.mdx
+7
@@ -6,6 +6,10 @@ keywords: [session, user id, concepts]
6
7 When building AI agents for multiple users, each user needs their own connections and context. This is represented through **users** and **sessions**.
8
9 +<Callout>
10 +For a hands-on walkthrough, see the [quickstart](/docs/quickstart).
11 +</Callout>
12 +
13 ## Users
14
15 A user is an identifier from your app. When someone connects their Gmail or GitHub, that connection is stored under their user ID, so tools always run with the right authentication. Every tool execution and authorization uses the user ID to identify the context. Connections are fully isolated between user IDs.
@@ -119,7 +123,10 @@ Create a new session when the config changes: different toolkits, different auth
123 </Accordion>
124 </Accordions>
125
126 +## What to read next
127 +
128 <Cards>
129 + <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
130 <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />
131 <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Write and run code in a persistent sandbox" />
132 </Cards>
docs/content/docs/workbench.mdx
+4 -7
@@ -69,13 +69,10 @@ The agent can chain tools inside the sandbox. Fetch GitHub activity, aggregate w
69
70 The sandbox preserves variables and files across calls. The agent can paginate through records, transform them, and write to a destination over multiple calls.
71
72 -## Related
72 +## What to read next
73
74 <Cards>
75 - <Card icon={<Blocks />} title="Tools and toolkits" href="/docs/tools-and-toolkits">
76 - How meta tools discover, authenticate, and execute tools at runtime
77 - </Card>
78 - <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits">
79 - Explore all available toolkits
80 - </Card>
75 + <Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Event-driven payloads from connected apps" />
76 + <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools at runtime" />
77 + <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits" description="Explore all available toolkits" />
78 </Cards>