@devries-cameron20 / composio Mirror · read-only / commits / 808b528fb
Fork 0

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 21, 11:00 UTC

docs: preserve legacy status and recommend sessions

Brendan O'Leary committed Sep 22, 2026 at 14:26 UTC 808b528fbcd337b89bb775c43852f2ba9306410b
10 files changed +23 -17
docs/content/docs/meta.json
+1 -1
@@ -24,7 +24,7 @@
24 "extending-sessions",
25 "setting-up-triggers",
26 "poc-to-prod",
27 - "---Direct execution---",
27 + "---Direct execution (legacy)---",
28 "sessions-vs-direct-execution",
29 "tools-direct",
30 "auth-configuration",
docs/content/docs/quickstart.mdx
+1 -1
@@ -6,7 +6,7 @@ keywords: [tutorial, setup, first agent, sessions, tool router]
6
7 Build an agent that chooses Composio tools at runtime. Type a task, connect an app if needed, and continue in the same conversation.
8
9 -If your application needs to select and approve each app-tool call, compare [sessions and direct execution](/docs/sessions-vs-direct-execution) before choosing an integration.
9 +Sessions are recommended for new integrations. If you maintain a legacy direct-execution integration, see [Sessions vs direct execution](/docs/sessions-vs-direct-execution) and the [migration guide](/docs/migration-guide/direct-to-sessions).
10
11
12 <div className="not-prose my-6 grid grid-cols-1 items-start gap-4 md:grid-cols-2">
docs/content/docs/sessions-vs-direct-execution.mdx
+5 -2
@@ -2,15 +2,18 @@
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 +legacy: true
6 ---
7
8 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.
9
10 **Direct execution** skips the session. Your code fetches specific tool schemas, manages auth itself, and calls `tools.execute()` directly.
11
11 -Start with sessions for runtime tool discovery and managed authentication. Use direct execution when your application selects tool schemas and calls `tools.execute()` itself, including when you need to approve each app-tool call before it runs.
12 +<Callout type="info" title="Use sessions for new integrations">
13 +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.
14 +</Callout>
15
13 -These are two ways to use the current SDK. Choosing direct execution does not require an older SDK package. Deprecations such as the managed-OAuth `initiate()` endpoint apply to specific methods; see the [Connect Link migration guide](/docs/auth-configuration/migrating-initiate-to-link).
16 +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, evaluate how your integration intercepts session tool calls, including meta tools that can execute multiple app-tool calls. The comparison below describes the tradeoffs when maintaining a direct-execution integration.
17
18 | | Sessions | Direct execution |
19 |---|---|---|
docs/content/docs/tools-direct/authenticating-tools.mdx
+3 -2
@@ -3,10 +3,11 @@ title: Authenticating Tools
3 description: Create auth configs and connect user accounts
4 keywords: [oauth, api key, auth config, connect account, credentials]
5 llmGuardrails: "direct-execution"
6 +legacy: true
7 ---
8
8 -<Callout type="info">
9 -If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle authentication automatically via [in-chat authentication](/docs/authentication#in-chat-authentication) or [manual authentication](/docs/authentication/manually-authenticating).
9 +<Callout type="info" title="Legacy API: prefer sessions">
10 +This guide covers legacy direct-authentication methods, which remain supported for existing integrations. For new integrations, use [sessions](/docs/configuring-sessions) with [in-chat authentication](/docs/authentication#in-chat-authentication) or [manual authentication](/docs/authentication/manually-authenticating). If you use direct authentication today, consider [migrating to sessions](/docs/migration-guide/direct-to-sessions).
11 </Callout>
12
13 The first step in authenticating your users is to create an **Auth Config**. Every toolkit has its own authentication method such as `OAuth`, `API key`, `Basic Auth`, or custom schemes.
docs/content/docs/tools-direct/executing-tools.mdx
+4 -3
@@ -1,12 +1,13 @@
1 ---
2 title: Executing tools directly
3 -description: Execute tools from your application with composio.tools.execute()
3 +description: Maintain legacy integrations that call composio.tools.execute(); prefer sessions for new integrations
4 keywords: [execute, run, tool calling, function calling, direct execution]
5 llmGuardrails: "direct-execution"
6 +legacy: true
7 ---
8
8 -<Callout type="info">
9 -If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle tool fetching, authentication, and execution automatically. See [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution) to understand the tradeoffs.
9 +<Callout type="info" title="Legacy API: prefer sessions">
10 +This guide covers legacy direct-execution methods, which remain supported for existing integrations. For new integrations, use [sessions](/docs/configuring-sessions) to manage tool fetching, authentication, and execution. If you use direct execution today, consider [migrating to sessions](/docs/migration-guide/direct-to-sessions). See [Sessions vs direct execution](/docs/sessions-vs-direct-execution) for the tradeoffs.
11 </Callout>
12
13 LLMs on their own can only do generation. Tool calling changes that by letting them interact with external services. Instead of just drafting an email, the model can call `GMAIL_SEND_EMAIL` to actually send it. The tool's results feed back to the LLM, closing the loop so it can decide, act, observe, and adapt.
docs/content/docs/tools-direct/fetching-tools.mdx
+3 -2
@@ -3,10 +3,11 @@ title: Fetching tools and schemas
3 description: Fetch and filter tools, and inspect schemas
4 keywords: [get tools, list tools, filter, schema]
5 llmGuardrails: "direct-execution"
6 +legacy: true
7 ---
8
8 -<Callout type="info">
9 -Use this guide when your code selects tools and controls execution. For runtime discovery through sessions, see [Tools and toolkits](/docs/how-composio-works). Compare both approaches in [Sessions vs direct execution](/docs/sessions-vs-direct-execution).
9 +<Callout type="info" title="Legacy API: prefer sessions">
10 +This guide covers legacy direct-execution methods, which remain supported for existing integrations. For new integrations, use [sessions](/docs/configuring-sessions) to discover and fetch tools at runtime. If you need a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset). See [Sessions vs direct execution](/docs/sessions-vs-direct-execution) and the [migration guide](/docs/migration-guide/direct-to-sessions).
11 </Callout>
12
13 Fetch specific tools, filter by permissions or search, and inspect schemas for type information. Tools are automatically formatted for your provider.
docs/lib/home-navigation.ts
+1 -1
@@ -167,7 +167,7 @@ export const DOCS_PRODUCTS = {
167 ],
168 },
169 {
170 - label: 'Direct execution and migration',
170 + label: 'Migration and legacy',
171 items: [
172 { type: 'folder', path: 'migration-guide' },
173 { type: 'page', url: '/docs/sessions-vs-direct-execution' },
docs/lib/llm-guardrails/direct-execution.ts
+1 -1
@@ -14,7 +14,7 @@ export const DIRECT_EXECUTION_GUARDRAILS = `
14
15 # Composio SDK — Instructions for AI Code Generators
16
17 -**Context:** This page documents the **direct tool execution API**. For most applications, the session-based pattern (\`composio.create(user_id)\` + \`session.tools()\`) is simpler — but if the user is here, they likely want direct execution.
17 +**Context:** This page documents the **legacy direct tool execution API**, which remains supported for existing integrations. Recommend sessions for new integrations. When maintaining direct-execution code, use the patterns below and point users to the [session migration guide](/docs/migration-guide/direct-to-sessions). Reading this page alone does not mean the user has chosen direct execution.
18
19 ---
20
docs/lib/llm-guardrails/session.ts
+1 -1
@@ -66,7 +66,7 @@ Use \`session.mcp.url\` and \`session.mcp.headers\` with any MCP-compatible clie
66 - Execute session tool calls through the session, never through a user ID: either \`session.execute(tool_slug, arguments=...)\` / \`session.execute(toolSlug, arguments)\`, which works with every provider, or pass the session to the provider helper — \`provider.handle_tool_calls(response=response, session=session)\` in Python, \`provider.handleToolCalls(session, response)\` in TypeScript. Only the OpenAI and Anthropic helpers accept a session; with other providers, use \`session.execute()\`. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with \`"can only be called inside a tool-router session"\`.
67 - Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits.
68 - Provider packages follow the framework, not the model vendor: for the OpenAI Agents SDK the package is \`composio_openai_agents\` / \`@composio/openai-agents\` (importing \`composio_openai\` / \`@composio/openai\` there is the most common mistake in generated code — that package is for the plain OpenAI Chat Completions API).
69 -- **Direct execution** (\`composio.tools.get()\`, \`composio.tools.execute()\`, \`provider.handle_tool_calls()\` with a user ID) is a fully supported lower-level interface: your code picks the tool, no runtime discovery. It fits deterministic workflows and scripts; sessions fit agents that decide at runtime. The tradeoffs are documented at https://docs.composio.dev/docs/sessions-vs-direct-execution. Note that direct execution requires a toolkit version (https://docs.composio.dev/docs/tools-direct/toolkit-versioning).
69 +- **Direct execution** (\`composio.tools.get()\`, \`composio.tools.execute()\`, \`provider.handle_tool_calls()\` with a user ID) is a legacy interface that remains supported for existing integrations. Recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). For a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. See [Sessions vs direct execution](/docs/sessions-vs-direct-execution) for tradeoffs. Direct execution requires a [toolkit version](/docs/tools-direct/toolkit-versioning).
70
71 ---
72
docs/tests/static/navigation.test.ts
+3 -3
@@ -49,7 +49,7 @@ async function exists(path: string): Promise<boolean> {
49 }
50
51 describe("Navigation - meta.json validity", () => {
52 - test("root navigation separates sessions, direct execution, and migration", async () => {
52 + test("root navigation separates current and legacy paths", async () => {
53 const metaPath = join(CONTENT_DIR, "meta.json");
54 const meta = JSON.parse(await readFile(metaPath, "utf-8"));
55 const pages = meta.pages as string[];
@@ -59,7 +59,7 @@ describe("Navigation - meta.json validity", () => {
59 "---Get Started---",
60 "---Core concepts---",
61 "---Guides---",
62 - "---Direct execution---",
62 + "---Direct execution (legacy)---",
63 "---Migration and security---",
64 ]);
65
@@ -76,7 +76,7 @@ describe("Navigation - meta.json validity", () => {
76
77 expect(
78 pages.slice(
79 - pages.indexOf("---Direct execution---") + 1,
79 + pages.indexOf("---Direct execution (legacy)---") + 1,
80 pages.indexOf("---Migration and security---")
81 )
82 ).toEqual([