1
+---
2
+title: Sessions vs Direct Execution
3
+description: When to use session-based meta tools vs direct tool fetching and execution
4
+keywords: [session, direct execution, tool router, meta tools, architecture, decision]
5
+---
6
+
7
+**Sessions** give your agent [meta tools](/docs/tools-and-toolkits#meta-tools). The agent discovers which app tools to use, authenticates users, and executes tools at runtime through these meta tools.
8
+
9
+**Direct execution** gives your code specific tool schemas. You decide which tools to fetch, manage auth yourself, and call `tools.execute()` directly.
10
+
11
+Use sessions unless you need full control over which tools are available and when they run.
12
+
13
+| | Sessions | Direct execution |
14
+|---|---|---|
15
+| **Discovery** | Agent finds tools at runtime and resolves dependencies automatically (e.g., if a tool needs an ID from another API, the agent finds that tool, runs it, and continues) | You select all tools upfront and need to account for any dependencies between them |
16
+| **Context cost** | Only meta tools in context, app tools loaded on demand | Every tool schema you select is loaded upfront |
17
+| **Guidance** | Search returns recommended steps and common pitfalls alongside schemas | You get tool schemas only |
18
+| **Memory** | Meta tools share context across calls, storing discovered IDs and relationships | You manage state between calls |
19
+| **Auth** | [In-chat](/docs/authenticating-users/in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authenticating-users/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
20
+| **[Workbench](/docs/workbench)** | Built in, large responses offloaded automatically | Not available |
21
+| **Human approval** | You configure approval rules on the session. Harder to intercept individual calls since tools are discovered dynamically | You intercept before each call in your code |
22
+| **Latency** | Multiple LLM turns (search, then execute) | Single call |
23
+
24
+Sessions are configurable. You can [enable or disable specific toolkits](/docs/toolkits/enable-and-disable-toolkits), set [auth configs](/docs/auth-configuration/custom-auth-configs) for white-labeled OAuth, and pin specific [connected accounts](/docs/configuring-sessions#account-selection). See [Configuring Sessions](/docs/configuring-sessions) for the full list.
25
+
26
+## Sessions
27
+
28
+`composio.create()` returns [meta tools](/docs/tools-and-toolkits#meta-tools):
29
+
30
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
31
+<Tab value="Python">
32
+```python
33
+from composio import Composio
34
+from composio_openai import OpenAIProvider
35
+
36
+composio = Composio(provider=OpenAIProvider())
37
+session = composio.create(user_id="user_123")
38
+tools = session.tools()
39
+# Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
40
+# COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
41
+```
42
+</Tab>
43
+<Tab value="TypeScript">
44
+```typescript
45
+import { Composio } from '@composio/core';
46
+import { OpenAIProvider } from '@composio/openai';
47
+
48
+const composio = new Composio({
49
+ apiKey: process.env.COMPOSIO_API_KEY,
50
+ provider: new OpenAIProvider(),
51
+});
52
+const session = await composio.create("user_123");
53
+const tools = await session.tools();
54
+// Returns meta tools like COMPOSIO_SEARCH_TOOLS, COMPOSIO_MANAGE_CONNECTIONS,
55
+// COMPOSIO_MULTI_EXECUTE_TOOL, COMPOSIO_REMOTE_WORKBENCH, etc.
56
+```
57
+</Tab>
58
+</Tabs>
59
+
60
+The agent discovers app tools through `COMPOSIO_SEARCH_TOOLS`:
61
+
62
+```
63
+User: "Create a GitHub issue for the login bug"
64
+
65
+> Agent calls COMPOSIO_SEARCH_TOOLS({ query: "create github issue" })
66
+ Returns: GITHUB_CREATE_ISSUE schema + connection status
67
+
68
+> Agent calls COMPOSIO_MANAGE_CONNECTIONS({ toolkits: ["github"] })
69
+ Returns: confirms connected (or auth link if not)
70
+
71
+> Agent calls COMPOSIO_MULTI_EXECUTE_TOOL({ tool: "GITHUB_CREATE_ISSUE", args: {...} })
72
+ Returns: issue details
73
+
74
+Agent: "Created issue #42 on your-org/your-repo"
75
+```
76
+
77
+<Callout>
78
+`session.tools()` returns **meta tools** (COMPOSIO_SEARCH_TOOLS, etc.), not app tools (GMAIL_SEND_EMAIL, etc.). The agent discovers app tools at runtime through search. For app tools directly, use direct execution.
79
+</Callout>
80
+
81
+### Configuration
82
+
83
+Restrict toolkits, set auth configs, pin connected accounts:
84
+
85
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
86
+<Tab value="Python">
87
+```python
88
+session = composio.create(
89
+ user_id="user_123",
90
+ toolkits=["github", "gmail"],
91
+ auth_configs={"github": "ac_my_config"},
92
+ connected_accounts={"gmail": "ca_work"},
93
+)
94
+```
95
+</Tab>
96
+<Tab value="TypeScript">
97
+```typescript
98
+import { Composio } from '@composio/core';
99
+const composio = new Composio({ apiKey: 'your_api_key' });
100
+// ---cut---
101
+const session = await composio.create("user_123", {
102
+ toolkits: ["github", "gmail"],
103
+ authConfigs: { github: "ac_my_config" },
104
+ connectedAccounts: { gmail: "ca_work" },
105
+});
106
+```
107
+</Tab>
108
+</Tabs>
109
+
110
+See [Configuring Sessions](/docs/configuring-sessions) for details.
111
+
112
+## Direct execution
113
+
114
+Fetch tools by slug or toolkit. Pass them to your LLM or call `tools.execute()` without one.
115
+
116
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
117
+<Tab value="Python">
118
+```python
119
+from composio import Composio
120
+from composio_openai import OpenAIProvider
121
+
122
+composio = Composio(provider=OpenAIProvider())
123
+
124
+# Fetch specific tools
125
+tools = composio.tools.get(
126
+ user_id="user_123",
127
+ tools=["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"]
128
+)
129
+
130
+# Or by toolkit
131
+tools = composio.tools.get(
132
+ user_id="user_123",
133
+ toolkits=["GITHUB"],
134
+ limit=50
135
+)
136
+
137
+# Execute without an LLM
138
+result = composio.tools.execute(
139
+ "GITHUB_CREATE_ISSUE",
140
+ user_id="user_123",
141
+ arguments={"owner": "my-org", "repo": "my-repo", "title": "Fix login bug"}
142
+)
143
+```
144
+</Tab>
145
+<Tab value="TypeScript">
146
+```typescript
147
+import { Composio } from '@composio/core';
148
+import { OpenAIProvider } from '@composio/openai';
149
+
150
+const composio = new Composio({
151
+ apiKey: process.env.COMPOSIO_API_KEY,
152
+ provider: new OpenAIProvider(),
153
+});
154
+
155
+// Fetch specific tools
156
+const tools = await composio.tools.get("user_123", {
157
+ tools: ["GITHUB_CREATE_ISSUE", "GITHUB_LIST_ISSUES"],
158
+});
159
+
160
+// Or by toolkit
161
+const allTools = await composio.tools.get("user_123", {
162
+ toolkits: ["GITHUB"],
163
+ limit: 50,
164
+});
165
+
166
+// Execute without an LLM
167
+const result = await composio.tools.execute("GITHUB_CREATE_ISSUE", {
168
+ userId: "user_123",
169
+ arguments: { owner: "my-org", repo: "my-repo", title: "Fix login bug" },
170
+});
171
+```
172
+</Tab>
173
+</Tabs>
174
+
175
+<Callout type="warn">
176
+`tools.get()` returns 20 tools by default. When fetching from multiple toolkits (e.g., `toolkits=["GMAIL", "GITHUB", "TAVILY"]`), the limit may cut off tools from later toolkits. Increase `limit` or fetch each toolkit separately.
177
+</Callout>
178
+
179
+With direct execution, you manage [auth configs](/docs/auth-configuration/custom-auth-configs), [connect links](/docs/tools-direct/authenticating-tools), and [toolkit versioning](/docs/tools-direct/toolkit-versioning) yourself.
180
+
181
+## Migrating
182
+
183
+See the [migration guide](/docs/migration-guide/direct-to-sessions). Auth configs and connected accounts carry over.
184
+
185
+## Next steps
186
+
187
+<Cards>
188
+ <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build an agent with sessions" />
189
+ <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Toolkits, auth configs, and connected accounts" />
190
+ <Card icon={<Wrench />} title="Direct Tool Execution" href="/docs/tools-direct/executing-tools" description="Fetch and execute specific tools" />
191
+</Cards>