Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: improve core concepts page structure and cross-linking

Sushmitha Mallesh7f5bb7461921
diff --git a/docs/content/docs/authentication.mdx b/docs/content/docs/authentication.mdx
index 9883b85cc..fed93367b 100644
--- a/docs/content/docs/authentication.mdx
+++ b/docs/content/docs/authentication.mdx
@@ -4,15 +4,20 @@ description: Understand how Composio handles user authentication to toolkits
keywords: [connect link, oauth, auth config]
---
-Composio simplifies authentication with Connect Links: hosted pages where users securely connect their accounts.
+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.
<Video src="/images/connect-link-auth-flow-recording.mp4" autoPlay />
-## In-chat authentication
+## Which approach should I use?
+
+- **Users chat with your agent?** Use [in-chat authentication](#in-chat-authentication). The agent handles connection prompts automatically, no setup needed.
+- **Want users connected before they chat?** Use [manual authentication](#manual-authentication). Your app calls `session.authorize()` during onboarding or from a settings page.
-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.
+Not sure? Start with in-chat. You can add manual auth later.
-Here's what this looks like in a conversation:
+## In-chat authentication
+
+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.
> **You:** Summarize my emails from today
>
@@ -22,18 +27,20 @@ Here's what this looks like in a conversation:
>
> **Agent:** Here's a summary of your emails from today...
-This flow works well for chat applications where users interact directly with the agent.
-
-<Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication">
- Let the agent handle authentication prompts automatically during conversation
+<Card icon={<MessageCircle />} title="In-chat authentication guide" href="/docs/authenticating-users/in-chat-authentication">
+ Configuration, callback URLs, and full examples
</Card>
## Manual authentication
-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.
+Use `session.authorize()` to generate Connect Links programmatically when you want to control when and where users authenticate. Common use cases:
-<Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
- Control when and how users connect their accounts
+- **Onboarding**: connect accounts during signup before the user ever chats with the agent
+- **Settings page**: let users manage their connections from a dedicated UI
+- **Pre-flight checks**: verify all required connections are active before starting a task
+
+<Card icon={<ShieldCheck />} title="Manual authentication guide" href="/docs/authenticating-users/manually-authenticating">
+ `session.authorize()` API, callback URLs, and connection status checks
</Card>
## How Composio manages authentication
@@ -42,9 +49,9 @@ Behind the scenes, Composio uses **auth configs** to manage authentication.
An **auth config** is a blueprint that defines how authentication works for a toolkit across all your users. It specifies:
-- **Authentication method** — OAuth2, Bearer token, API key, or Basic Auth
-- **Scopes** — what actions your tools can perform
-- **Credentials** — your own app credentials or Composio's managed auth
+- **Authentication method**: OAuth2, Bearer token, API key, or Basic Auth
+- **Scopes**: what actions your tools can perform
+- **Credentials**: your own app credentials or Composio's managed auth
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).
@@ -91,19 +98,17 @@ You only need to create a custom auth config when:
To bring your own OAuth apps or customize scopes, see [custom auth configs](/docs/using-custom-auth-configuration).
-## Useful links
+## What to read next
+
+<Cards>
+ <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools" />
+ <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication" description="Let the agent prompt users to authenticate during conversation" />
+ <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating" description="Generate Connect Links programmatically in your app" />
+</Cards>
+
+### Related guides
<Cards>
- <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication">
- Let the agent prompt users to authenticate during conversation
- </Card>
- <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
- Generate Connect Links programmatically in your app
- </Card>
- <Card icon={<Palette />} title="White-labeling" href="/docs/white-labeling-authentication">
- Customize OAuth screens with your branding
- </Card>
- <Card icon={<Key />} title="Custom auth configs" href="/docs/using-custom-auth-configuration">
- Use your own OAuth apps
- </Card>
+ <Card icon={<Palette />} title="White-labeling" href="/docs/white-labeling-authentication" description="Customize OAuth screens with your branding" />
+ <Card icon={<Key />} title="Custom auth configs" href="/docs/using-custom-auth-configuration" description="Use your own OAuth apps" />
</Cards>
diff --git a/docs/content/docs/how-composio-works.mdx b/docs/content/docs/how-composio-works.mdx
index 008b8aca8..851246b45 100644
--- a/docs/content/docs/how-composio-works.mdx
+++ b/docs/content/docs/how-composio-works.mdx
@@ -6,7 +6,15 @@ keywords: [architecture, how it works, sessions, meta tools, execution]
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.
-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).
+This page is a high-level overview. Each concept has a dedicated page with full details:
+
+1. [Users & Sessions](/docs/users-and-sessions): how users and sessions scope tools and connections
+2. [Authentication](/docs/authentication): Connect Links, OAuth, API keys, and auth configs
+3. [Tools and toolkits](/docs/tools-and-toolkits): meta tools, discovery, and execution
+4. [Workbench](/docs/workbench): persistent Python sandbox for bulk operations
+5. [Triggers](/docs/triggers): event-driven payloads from connected apps
+
+For hands-on setup, see the [quickstart](/docs/quickstart).
## Sessions
@@ -57,45 +65,11 @@ graph LR
classDef annotation stroke-dasharray: 5 5
```
-| Meta tool | What it does |
-|-----------|-------------|
-| `COMPOSIO_SEARCH_TOOLS` | Finds relevant tools by use case, returns input schemas, connection status, execution plan, and related tools |
-| `COMPOSIO_MANAGE_CONNECTIONS` | Generates Connect Links for OAuth and API key authentication |
-| `COMPOSIO_MULTI_EXECUTE_TOOL` | Executes up to 20 tools in parallel with the user's credentials |
-| `COMPOSIO_REMOTE_WORKBENCH` | Runs Python code in a [persistent sandbox](/docs/workbench) |
-| `COMPOSIO_REMOTE_BASH_TOOL` | Runs bash commands in the same sandbox for file operations and data processing |
-
-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.
-
-### How they work together
+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.
-The meta tools are how the agent reaches the actual toolkit tools:
+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.
-```mermaid
-graph TD
- A["Agent: 'Create a GitHub issue for this bug'"] --> B["COMPOSIO_SEARCH_TOOLS"]
- B --> C["GITHUB_CREATE_ISSUE"]
- B --> C2["GITHUB_LIST_ISSUES"]
- B --> C3["GITHUB_GET_REPO"]
- B -.- B1["Returns matching tools with schemas"]:::annotation
- C --> D["COMPOSIO_MULTI_EXECUTE_TOOL"]
- D --> E["GitHub API"]
- D -.- D1["Injects user's OAuth token, makes the call"]:::annotation
-
- classDef annotation stroke-dasharray: 5 5
-```
-
-`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.
-
-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`.
-
-<Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, context management, and execution" />
-
-## Tool discovery
-
-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.
-
-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.
+<Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Full details on meta tools, discovery, and execution" />
## Authentication
@@ -111,22 +85,9 @@ In a conversation, this looks like:
>
> **Agent:** Created issue #42 on your-org/your-repo.
-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.
-
-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).
+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.
-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.
-
-<Cards>
- <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and custom auth configs" />
- <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating" description="Authenticate users outside of chat with session.authorize()" />
-</Cards>
-
-## Tool execution
-
-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.
-
-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.
+<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and custom auth configs" />
## Remote workbench
@@ -141,25 +102,13 @@ This keeps the agent's context window lean while still letting it handle operati
<Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for large-context operations" />
-## Direct tool execution
+## What to read next
-If you know exactly which tools you need, you can skip the meta tool pattern and execute tools directly:
+Start with the concepts in order, or jump to the quickstart if you want to build right away:
-```python
-composio = Composio()
-
-tools = composio.tools.get(
- user_id="user_123",
- toolkits=["github"]
-)
-
-result = composio.tools.execute(
- "GITHUB_STAR_REPOSITORY",
- user_id="user_123",
- arguments={"owner": "composiohq", "repo": "composio"}
-)
-```
-
-This is useful for deterministic workflows where the agent doesn't need to discover tools at runtime.
-
-<Card icon={<Zap />} title="Direct tool execution" href="/docs/tools-direct/executing-tools" description="Fetch, authenticate, and execute tools without meta tools" />
+<Cards>
+ <Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
+ <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
+ <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, discovery, and execution" />
+ <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent in 5 minutes" />
+</Cards>
diff --git a/docs/content/docs/tools-and-toolkits.mdx b/docs/content/docs/tools-and-toolkits.mdx
index 681da20a0..05ef97119 100644
--- a/docs/content/docs/tools-and-toolkits.mdx
+++ b/docs/content/docs/tools-and-toolkits.mdx
@@ -78,13 +78,11 @@ If a tool requires authentication and the user hasn't connected yet, the agent c
Learn how Composio handles user authentication
</Card>
-## Useful links
+## What to read next
<Cards>
- <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits">
- Explore all available toolkits
- </Card>
- <Card icon={<Wrench />} title="Fetching tools" href="/docs/toolkits/fetching-tools-and-toolkits">
- Browse the catalog and fetch tools for sessions
- </Card>
+ <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for bulk operations and data processing" />
+ <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits" description="Explore all available toolkits" />
+ <Card icon={<Wrench />} title="Fetching tools" href="/docs/toolkits/fetching-tools-and-toolkits" description="Browse the catalog and fetch tools for sessions" />
+ <Card icon={<Zap />} title="Direct tool execution" href="/docs/tools-direct/executing-tools" description="Execute tools without meta tools for deterministic workflows" />
</Cards>
diff --git a/docs/content/docs/triggers.mdx b/docs/content/docs/triggers.mdx
index 839d32555..f69935987 100644
--- a/docs/content/docs/triggers.mdx
+++ b/docs/content/docs/triggers.mdx
@@ -30,6 +30,10 @@ When you create a trigger from a type, it's scoped to a specific user and connec
</Accordion>
</Accordions>
+<Callout>
+Triggers are scoped to a connected account. If you haven't set up authentication yet, see [Authentication](/docs/authentication).
+</Callout>
+
## Next steps
<Cards>
diff --git a/docs/content/docs/users-and-sessions.mdx b/docs/content/docs/users-and-sessions.mdx
index d65f8609a..b2ff996a5 100644
--- a/docs/content/docs/users-and-sessions.mdx
+++ b/docs/content/docs/users-and-sessions.mdx
@@ -6,6 +6,10 @@ keywords: [session, user id, concepts]
When building AI agents for multiple users, each user needs their own connections and context. This is represented through **users** and **sessions**.
+<Callout>
+For a hands-on walkthrough, see the [quickstart](/docs/quickstart).
+</Callout>
+
## Users
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
</Accordion>
</Accordions>
+## What to read next
+
<Cards>
+ <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
<Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />
<Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Write and run code in a persistent sandbox" />
</Cards>
diff --git a/docs/content/docs/workbench.mdx b/docs/content/docs/workbench.mdx
index b202ae189..b0849b113 100644
--- a/docs/content/docs/workbench.mdx
+++ b/docs/content/docs/workbench.mdx
@@ -69,13 +69,10 @@ The agent can chain tools inside the sandbox. Fetch GitHub activity, aggregate w
The sandbox preserves variables and files across calls. The agent can paginate through records, transform them, and write to a destination over multiple calls.
-## Related
+## What to read next
<Cards>
- <Card icon={<Blocks />} title="Tools and toolkits" href="/docs/tools-and-toolkits">
- How meta tools discover, authenticate, and execute tools at runtime
- </Card>
- <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits">
- Explore all available toolkits
- </Card>
+ <Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Event-driven payloads from connected apps" />
+ <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools at runtime" />
+ <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits" description="Explore all available toolkits" />
</Cards>