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, 08:15 UTC
docs: add "How Composio works" architecture page
Covers sessions, meta tools, authentication, tool execution, and direct tool execution. Linked from Core Concepts nav and Welcome page. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmithamallesh committed
Feb 19, 2026 at 12:19 UTC
2c39f8969af45298d4e16e73caf6142c7dd0d495
3 files changed
+128
-3
docs/content/docs/how-composio-works.mdx
new
+124
@@ -0,0 +1,124 @@
1
+---
2
+title: How Composio works
3
+description: Sessions, meta tools, authentication, and tool execution
4
+keywords: [architecture, how it works, sessions, meta tools, execution]
5
+---
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).
10
+
11
+## Sessions
12
+
13
+When your app calls `composio.create()`, it creates a session scoped to a user.
14
+
15
+```python
16
+composio = Composio()
17
+session = composio.create(user_id="user_123")
18
+
19
+# Get tools formatted for your provider
20
+tools = session.tools()
21
+
22
+# Or get the MCP endpoint for MCP-compatible frameworks
23
+mcp_url = session.mcp.url
24
+mcp_headers = session.mcp.headers
25
+```
26
+
27
+A session ties together:
28
+
29
+- **A user**: whose credentials and connections to use
30
+- **Available toolkits**: all by default, or a specific set you configure
31
+- **Auth configuration**: which authentication method and connected accounts to use
32
+
33
+Sessions are immutable. Their configuration is fixed at creation. If the context changes (different toolkits, different connected account), create a new session. You don't need to cache or manage session IDs.
34
+
35
+<Card icon={<BookOpen />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
36
+
37
+## Meta tools
38
+
39
+Rather than loading hundreds of tool definitions into your agent's context, a session provides 5 meta tools:
40
+
41
+```mermaid
42
+graph LR
43
+ A["Your agent"] --> B["Session"]
44
+ B --> C["Meta tools"]
45
+ C --> D["SEARCH_TOOLS"]
46
+ C --> E["MANAGE_CONNECTIONS"]
47
+ C --> F["MULTI_EXECUTE"]
48
+ C --> G["WORKBENCH + BASH"]
49
+
50
+ D -.- D1["Discover tools by use case"]:::annotation
51
+ E -.- E1["Handle OAuth and API keys"]:::annotation
52
+ F -.- F1["Run tools with user credentials"]:::annotation
53
+ G -.- G1["Persistent Python sandbox"]:::annotation
54
+
55
+ classDef annotation stroke-dasharray: 5 5
56
+```
57
+
58
+| Meta tool | What it does |
59
+|-----------|-------------|
60
+| `COMPOSIO_SEARCH_TOOLS` | Finds relevant tools by use case, returns input schemas, connection status, execution plan, and related tools |
61
+| `COMPOSIO_MANAGE_CONNECTIONS` | Generates Connect Links for OAuth and API key authentication |
62
+| `COMPOSIO_MULTI_EXECUTE_TOOL` | Executes up to 20 tools in parallel with the user's credentials |
63
+| `COMPOSIO_REMOTE_WORKBENCH` | Runs Python code in a [persistent sandbox](/docs/workbench) |
64
+| `COMPOSIO_REMOTE_BASH_TOOL` | Runs bash commands in the same sandbox for file operations and data processing |
65
+
66
+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.
67
+
68
+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`.
69
+
70
+<Card icon={<BookOpen />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, context management, and execution" />
71
+
72
+## Authentication
73
+
74
+When a tool requires authentication and the user hasn't connected yet, the agent uses `COMPOSIO_MANAGE_CONNECTIONS` to generate a **Connect Link**, a hosted page where the user authorizes access.
75
+
76
+In a conversation, this looks like:
77
+
78
+> **You:** Create a GitHub issue for the login bug
79
+>
80
+> **Agent:** You'll need to connect your GitHub account. Please authorize here: \<Connect Link\>
81
+>
82
+> **You:** Done
83
+>
84
+> **Agent:** Created issue #42 on your-org/your-repo.
85
+
86
+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.
87
+
88
+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).
89
+
90
+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.
91
+
92
+<Cards>
93
+ <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and custom auth configs" />
94
+ <Card icon={<BookOpen />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating" description="Authenticate users outside of chat with session.authorize()" />
95
+</Cards>
96
+
97
+## Tool execution
98
+
99
+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.
100
+
101
+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.
102
+
103
+## Direct tool execution
104
+
105
+If you know exactly which tools you need, you can skip the meta tool pattern and execute tools directly:
106
+
107
+```python
108
+composio = Composio()
109
+
110
+tools = composio.tools.get(
111
+ user_id="user_123",
112
+ toolkits=["github"]
113
+)
114
+
115
+result = composio.tools.execute(
116
+ "GITHUB_STAR_REPOSITORY",
117
+ user_id="user_123",
118
+ arguments={"owner": "composiohq", "repo": "composio"}
119
+)
120
+```
121
+
122
+This is useful for deterministic workflows where the agent doesn't need to discover tools at runtime.
123
+
124
+<Card icon={<BookOpen />} title="Direct tool execution" href="/docs/tools-direct/executing-tools" description="Fetch, authenticate, and execute tools without meta tools" />
docs/content/docs/index.mdx
+3
-3
@@ -21,9 +21,9 @@ Composio powers 800+ toolkits, tool search, context management, authentication,
21
/>
22
<Card
23
icon={<BookOpen />}
24
- title="How tools work"
25
- href="/docs/tools-and-toolkits"
26
- description="Meta tools, context management, and execution"
24
+ title="How it works"
25
+ href="/docs/how-composio-works"
26
+ description="Sessions, meta tools, authentication, and execution"
27
/>
28
<Card
29
icon={<Wrench />}
docs/content/docs/meta.json
+1
@@ -5,6 +5,7 @@
5
"quickstart",
6
"providers",
7
"---Core Concepts---",
8
+ "how-composio-works",
9
"users-and-sessions",
10
"authentication",
11
"tools-and-toolkits",