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
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
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
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>