What is a session?

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.

The basics

When you create a session, Composio gives your agent two ways to access tools:

• Native tools from session.tools() for frameworks with tool-calling support.
• A remote MCP URL from session.mcp.url for MCP-compatible clients.

Both point at the same session context.

session = composio.create(user_id="user_123")

tools = session.tools()
mcp_url = session.mcp.url

const session = await composio.create("user_123");

const tools = await session.tools();
const mcpUrl = session.mcp.url;

A session ties together:

• User ID: which user's connected accounts and tool executions are in scope.
• Tool access: all toolkits by default, or a filtered set of toolkits/tools/tags.
• Authentication: managed auth, custom auth configs, and connected account selection.
• Execution state: logs, tool memory, MCP state, and workbench files for the task.

Users

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.

User ID best practices:

• Recommended: Database UUID or primary key (user.id)
• Acceptable: Unique username (user.username)
• Avoid: Email addresses (they can change)
• Never: default in production (exposes other users' data)

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.

What sessions do

Discover and execute tools

Instead of loading hundreds of tool definitions into context, a session gives your agent meta tools that discover, authenticate, and execute tools at runtime:

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.

Handle authentication

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.

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.

Preserve workbench state

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.

The workbench is scoped to the session, so files, variables, helper functions, and intermediate results stay available while the agent works through a task.

How sessions behave

Every create() call returns a new session ID. Use this when you want a fresh task context.

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.

session = composio.use("session_id")
tools = session.tools()

const session = await composio.use("session_id");
const tools = await session.tools();

You can also update a session without creating a new one:

session.update(
    toolkits=["gmail", "slack"],
    auth_configs={"gmail": "ac_new_config"},
    connected_accounts={"slack": ["ca_work_slack"]},
)

await session.update({
  toolkits: ["gmail", "slack"],
  authConfigs: { gmail: "ac_new_config" },
  connectedAccounts: { slack: ["ca_work_slack"] },
});

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.

What to read next