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]
2
+title: What is a session?
3
+description: What Composio sessions do and how they scope users, tools, auth, MCP, and workbench state
4
+keywords: [session, user id, concepts, meta tools, mcp, workbench]
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.
7
+A **session** is the runtime context your agent uses to work for one of your users. It tells Composio whose connected accounts to use, which tools are available, how authentication should happen, and where state should persist while the agent works.
8
9
-This page is a high-level overview. Each concept has a dedicated page with full details:
9
+## The basics
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
11
+When you create a session, Composio gives your agent two ways to access tools:
12
17
-For hands-on setup, see the [quickstart](/docs/quickstart).
13
+- **Native tools** from `session.tools()` for frameworks with tool-calling support.
14
+- **A remote MCP URL** from `session.mcp.url` for MCP-compatible clients.
15
19
-## Sessions
20
-
21
-When your app calls `composio.create()`, it creates a session scoped to a user.
16
+Both point at the same session context.
17
18
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19
+<Tab value="Python">
20
```python
24
-composio = Composio()
21
session = composio.create(user_id="user_123")
22
27
-# Get tools formatted for your provider
23
tools = session.tools()
29
-
30
-# Or get the MCP endpoint for MCP-compatible frameworks
24
mcp_url = session.mcp.url
32
-mcp_headers = session.mcp.headers
25
```
26
+</Tab>
27
+<Tab value="TypeScript">
28
+```typescript
29
+import { Composio } from '@composio/core';
30
+const composio = new Composio({ apiKey: 'your_api_key' });
31
+// ---cut---
32
+const session = await composio.create("user_123");
33
+
34
+const tools = await session.tools();
35
+const mcpUrl = session.mcp.url;
36
+```
37
+</Tab>
38
+</Tabs>
39
40
A session ties together:
41
37
-- **A user**: whose credentials and connections to use
38
-- **Available toolkits**: all by default, or a specific set you configure
39
-- **Auth configuration**: which authentication method and connected accounts to use
42
+- **User ID**: which user's connected accounts and tool executions are in scope.
43
+- **Tool access**: all toolkits by default, or a filtered set of toolkits/tools/tags.
44
+- **Authentication**: managed auth, custom auth configs, and connected account selection.
45
+- **Execution state**: logs, tool memory, MCP state, and workbench files for the task.
46
+
47
+## Users
48
+
49
+A user is an identifier from your app. Connections are stored under that ID, so tools run with the right account and stay isolated from other users.
50
41
-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.
51
+**User ID best practices:**
52
43
-<Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
53
+- **Recommended:** Database UUID or primary key (`user.id`)
54
+- **Acceptable:** Unique username (`user.username`)
55
+- **Avoid:** Email addresses (they can change)
56
+- **Never:** `default` in production (exposes other users' data)
57
45
-## Meta tools
58
+A user can connect multiple accounts for the same toolkit, such as work and personal Gmail. Use the same user ID, then select the connected account when a session needs a specific account. See [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts).
59
47
-Rather than loading hundreds of tool definitions into your agent's context, a session provides [meta tools](/docs/tools-and-toolkits#meta-tools):
60
+## What sessions do
61
+
62
+### Discover and execute tools
63
+
64
+Instead of loading hundreds of tool definitions into context, a session gives your agent meta tools that discover, authenticate, and execute tools at runtime:
65
66
```mermaid
67
graph LR
72
C --> F["COMPOSIO_MANAGE_CONNECTIONS"]
73
C --> G["COMPOSIO_MULTI_EXECUTE_TOOL"]
74
C --> H["COMPOSIO_REMOTE_WORKBENCH"]
58
- C --> I["COMPOSIO_REMOTE_BASH_TOOL"]
75
+```
76
60
- D -.- D1["Discover tools by use case"]:::annotation
61
- E -.- E1["Retrieve input schemas for tools"]:::annotation
62
- F -.- F1["Handle OAuth and API keys"]:::annotation
63
- G -.- G1["Run tools with user credentials"]:::annotation
64
- H -.- H1["Persistent Python sandbox"]:::annotation
65
- I -.- I1["File operations and data processing"]:::annotation
77
+The agent searches for relevant tools, authenticates if needed, and executes them through the same session. Meta tool calls share context through the session, so the agent can search in one call and execute in the next without losing state.
78
67
- classDef annotation stroke-dasharray: 5 5
68
-```
79
+### Handle authentication
80
70
-The agent searches for relevant tools, authenticates if needed, and executes them, all through these 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.
81
+When a tool needs a connection, the session can generate a Connect Link with `session.authorize()` or let the agent handle the flow through `COMPOSIO_MANAGE_CONNECTIONS`.
82
72
-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.
83
+In chat, this means the agent can pause, ask the user to connect an app, then retry the tool once auth is complete. Composio manages the OAuth redirects, token exchange, and refresh. Once a user connects a toolkit, the connected account persists for that user and can be reused by future sessions without re-authentication.
84
74
-<Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Full details on meta tools, discovery, and execution" />
85
+<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, in-chat auth, manual auth, and custom auth configs" />
86
76
-## Authentication
87
+### Preserve workbench state
88
78
-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.
89
+Large responses and bulk operations can be handled in the remote workbench. Instead of stuffing long tool responses into the model context, the agent can use the workbench to read files, search outputs, write Python, transform data, and call Composio tools in bulk.
90
80
-In a conversation, this looks like:
91
+The workbench is scoped to the session, so files, variables, helper functions, and intermediate results stay available while the agent works through a task.
92
82
-> **You:** Create a GitHub issue for the login bug
83
->
84
-> **Agent:** You'll need to connect your GitHub account. Please authorize here: \<Connect Link\>
85
->
86
-> **You:** Done
87
->
88
-> **Agent:** Created issue #42 on your-org/your-repo.
93
+<Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for large responses, bulk operations, and data processing" />
94
90
-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.
95
+## How sessions behave
96
92
-<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and custom auth configs" />
97
+Every `create()` call returns a new session ID. Use this when you want a fresh task context.
98
94
-## Remote workbench
99
+Sessions persist on the server and do not expire. For multi-turn conversations, store the session ID and reuse it with `composio.use()` rather than calling `create()` again.
100
96
-Large responses from `COMPOSIO_MULTI_EXECUTE_TOOL` are automatically synced to a secure remote workbench. Instead of stuffing thousands of lines into the context window, the agent can work with the data inside the workbench:
101
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
102
+<Tab value="Python">
103
+```python
104
+session = composio.use("session_id")
105
+tools = session.tools()
106
+```
107
+</Tab>
108
+<Tab value="TypeScript">
109
+```typescript
110
+import { Composio } from '@composio/core';
111
+const composio = new Composio({ apiKey: 'your_api_key' });
112
+// ---cut---
113
+const session = await composio.use("session_id");
114
+const tools = await session.tools();
115
+```
116
+</Tab>
117
+</Tabs>
118
98
-- **Reading** files and tool responses
99
-- **Searching** across large outputs
100
-- **Writing and executing** Python code to transform, filter, or aggregate data
101
-- **Calling Composio tools** via the `run_composio_tool` helper for bulk orchestration
119
+You can also update a session without creating a new one:
120
103
-This keeps the agent's context window lean while still letting it handle operations like labeling hundreds of emails, processing CSV exports, or summarizing long API responses.
121
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
122
+<Tab value="Python">
123
+```python
124
+session.update(
125
+ toolkits=["gmail", "slack"],
126
+ auth_configs={"gmail": "ac_new_config"},
127
+ connected_accounts={"slack": ["ca_work_slack"]},
128
+)
129
+```
130
+</Tab>
131
+<Tab value="TypeScript">
132
+```typescript
133
+import { Composio } from '@composio/core';
134
+const composio = new Composio({ apiKey: 'your_api_key' });
135
+const session = await composio.use("session_id");
136
+// ---cut---
137
+await session.update({
138
+ toolkits: ["gmail", "slack"],
139
+ authConfigs: { gmail: "ac_new_config" },
140
+ connectedAccounts: { slack: ["ca_work_slack"] },
141
+});
142
+```
143
+</Tab>
144
+</Tabs>
145
105
-<Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for large-context operations" />
146
+Create a new session for a different user or fundamentally different task setup. Reuse or update the session when the same conversation should keep its tool, auth, and workbench context.
147
148
## What to read next
149
109
-Start with the concepts in order, or jump to the quickstart to build right away:
110
-
150
<Cards>
112
- <Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
151
+ <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />
152
+ <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools" />
153
<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
114
- <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, discovery, and execution" />
115
- <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent" />
154
+ <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Write and run code in a persistent sandbox" />
155
</Cards>
117
-
118
-Deciding how to connect? See:
119
-- [Native Tools vs MCP](/docs/native-tools-vs-mcp) — SDK vs MCP servers
120
-- [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution) — meta tools vs fetching specific tools