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: answer the execution choice before its details
Brendan O'Leary committed
Nov 11, 2026 at 17:05 UTC
31f5c32abd19198d6f2510df7e192f25e893fc0e
1 file changed
+3
-5
docs/content/docs/sessions-vs-direct-execution.mdx
+3
-5
@@ -7,15 +7,13 @@ legacy: true
7
8
## Should I use sessions or direct execution?
9
10
+Use sessions for new integrations. If your agent needs a fixed set of app tools, use a session's [direct tools preset](/docs/configuring-sessions#direct-tools-preset) to keep session authentication and connected accounts without runtime tool discovery. Direct execution is a legacy interface that remains supported for existing integrations. If you maintain one, plan a [migration to sessions](/docs/migration-guide/direct-to-sessions).
11
+
12
A **session** is the runtime context Composio creates for one of your users with `composio.create(userId)`. It ties together the user, available toolkits, auth, and connected accounts. By default it gives your agent [meta tools](/docs/how-composio-works#meta-tools) so the agent discovers which app tools to use, authenticates users, and executes tools at runtime.
13
14
**Direct execution** skips the session. Your code fetches specific tool schemas, manages auth itself, and calls `tools.execute()` directly.
15
14
-<Callout type="info" title="Use sessions for new integrations">
15
-Direct execution is a legacy interface that remains supported for existing integrations. We recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). Sessions handle runtime tool discovery, authentication, and execution.
16
-</Callout>
17
-
18
-If your application needs a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. If you need approval before execution, use [approvals](/docs/governance/approvals): the session asks the user before it runs the tools you choose, including calls inside meta tools that execute multiple app tools. The comparison below describes the tradeoffs when maintaining a direct-execution integration.
16
+If you need approval before execution, use [approvals](/docs/governance/approvals): the session asks the user before it runs the tools you choose, including calls inside meta tools that execute multiple app tools. The comparison below describes the tradeoffs when maintaining a direct-execution integration.
17
18
| | Sessions | Direct execution |
19
|---|---|---|