Skip to content

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: add composio.use() hints to all quickstart framework tabs

Abir Taheer6114ec290857
diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdx
index 265dd3713..300a245df 100644
--- a/docs/content/docs/quickstart.mdx
+++ b/docs/content/docs/quickstart.mdx
@@ -24,7 +24,7 @@ Give your OpenAI Agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.
**Key concepts**
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
- **Provider**: Translates Composio tools into the framework's tool format. For OpenAI Agents, use `OpenAIAgentsProvider`.
- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
@@ -123,6 +123,10 @@ user_id = "user_123"
session = composio.create(user_id=user_id)
tools = session.tools()
+# For multi-turn, store the session ID and reuse instead of calling create() again:
+# session_id = session.session_id
+# session = composio.use(session_id)
+
agent = Agent(
name="Personal Assistant",
instructions="You are a helpful personal assistant. Use Composio tools to take action.",
@@ -168,6 +172,10 @@ const userId = "user_123";
const session = await composio.create(userId);
const tools = await session.tools();
+// For multi-turn, store the session ID and reuse instead of calling create() again:
+// const sessionId = session.sessionId;
+// const session = await composio.use(sessionId);
+
const agent = new Agent({
name: "Personal Assistant",
instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
@@ -212,7 +220,7 @@ Give your OpenAI Agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.
**Key concepts**
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers`. No `@composio/openai-agents` package needed.
- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
@@ -423,7 +431,7 @@ Give your Claude agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.
**Key concepts**
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
- **Provider**: Translates Composio tools into the framework's tool format. For Claude Agent SDK, use `ClaudeAgentSDKProvider`.
- **SDK MCP server**: Tools must be wrapped in an SDK MCP server via `create_sdk_mcp_server` / `createSdkMcpServer` before passing to `ClaudeAgentOptions.mcp_servers`. Do NOT pass tools directly.
- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
@@ -530,6 +538,10 @@ user_id = "user_123"
session = composio.create(user_id=user_id)
tools = session.tools()
+# For multi-turn, store the session ID and reuse instead of calling create() again:
+# session_id = session.session_id
+# session = composio.use(session_id)
+
custom_server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)
async def main():
@@ -582,6 +594,10 @@ const userId = "user_123";
const session = await composio.create(userId);
const tools = await session.tools();
+// For multi-turn, store the session ID and reuse instead of calling create() again:
+// const sessionId = session.sessionId;
+// const session = await composio.use(sessionId);
+
const customServer = createSdkMcpServer({
name: "composio",
version: "1.0.0",
@@ -642,7 +658,7 @@ Give your Claude agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, etc.
**Key concepts**
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers`. No `@composio/claude-agent-sdk` package needed.
- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
@@ -878,7 +894,7 @@ Give your Vercel AI agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, e
**Key concepts**
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
- **Provider**: Translates Composio tools into the framework's tool format. For Vercel AI, use `VercelProvider`.
- **streamText vs generateText**: Use `streamText` for streaming responses, `generateText` for single responses. Both accept Composio tools via the `tools` parameter.
- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
@@ -962,6 +978,10 @@ const userId = "user_123";
const session = await composio.create(userId);
const tools = await session.tools();
+// For multi-turn, store the session ID and reuse instead of calling create() again:
+// const sessionId = session.sessionId;
+// const session = await composio.use(sessionId);
+
const readline = createInterface({ input: process.stdin, output: process.stdout });
console.log(`
@@ -1018,7 +1038,7 @@ Give your Vercel AI agent access to 1000+ tools (Gmail, GitHub, Slack, Notion, e
**Key concepts**
-- **Session**: Scoped environment for a user. Created with `composio.create(userId)`. Sessions have access to all toolkits by default — the agent discovers which tools to use via `COMPOSIO_SEARCH_TOOLS`.
+- **Session**: Scoped environment for a user. Created with `composio.create(userId)`, reused with `composio.use(sessionId)`. Each `create()` returns a new session ID — store it and reuse for multi-turn conversations. Sessions have access to all toolkits by default.
- **MCP mode**: Instead of using a provider package, you connect to Composio's hosted MCP server using `session.mcp.url` and `session.mcp.headers` via `@ai-sdk/mcp`. No `@composio/vercel` package needed.
- **Client lifecycle**: Always close the MCP client with `await client.close()` when done.
- **Authentication**: When a tool requires auth (e.g., GitHub OAuth), Composio returns an auth URL. The user authenticates once; Composio manages tokens.
@@ -1103,7 +1123,12 @@ const composio = new Composio();
// Create a session for your user
const userId = "user_123";
-const { mcp } = await composio.create(userId);
+const composioSession = await composio.create(userId);
+const { mcp } = composioSession;
+
+// For multi-turn, store the session ID and reuse instead of calling create() again:
+// const sessionId = composioSession.sessionId;
+// const composioSession = await composio.use(sessionId);
// Create an MCP client to connect to Composio
const client = await createMCPClient({
@@ -1173,6 +1198,10 @@ readline.close();
By default, sessions have access to **all available toolkits** in the Composio catalog. Your agent can discover and use any of them through `COMPOSIO_SEARCH_TOOLS`. To restrict which toolkits are available, see [Enable and disable toolkits](/docs/toolkits/enable-and-disable-toolkits).
</Callout>
+<Callout>
+Every `composio.create()` call returns a new session ID. For multi-turn conversations or web apps, store the session ID and call `composio.use(sessionId)` on subsequent requests instead of creating a new session each time. See [Reusing a session](/docs/users-and-sessions#reusing-a-session).
+</Callout>
+
## Next steps
<Cards>