What is a session?

A session is the runtime context for an agentic run: the scoped environment an AI agent works in while it acts for one of your users. You create it with composio.create(userId), and it ties together the user, the toolkits available, authentication, and connected accounts. By default it gives the agent meta tools to discover, authenticate, and execute app tools at runtime, instead of loading hundreds of tool definitions into context.

The basics

Create a session for a user, then read its tools formatted for your framework. To connect over MCP instead, see Using sessions via MCP.

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

tools = session.tools()

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

const tools = await session.tools();

A session scopes four things:

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

Tools and toolkits

A toolkit is a collection of related tools for a service. The github toolkit, for example, contains tools for creating issues, managing pull requests, and starring repositories.

A tool is an individual action your agent can execute. Each tool has an input schema (its parameters) and an output schema (what it returns), and follows a {TOOLKIT}_{ACTION} naming pattern, like GITHUB_CREATE_ISSUE.

Every toolkit in the catalog is discoverable by default. Create a session without a toolkits parameter and the agent can find any of them at runtime. To restrict the set, pass toolkits when you create the session. See Enable and disable toolkits. You can also bind local, in-process tools to a session with the experimental custom tools and toolkits API.

Users

A user is an identifier from your app. Composio stores connections under that ID, so tools run with the right account and stay isolated from other users. Use a stable identifier like your database ID, never one that can change.

A user can connect multiple accounts for the same toolkit, like work and personal Gmail. Use the same userID, then select the connected account when a session needs a specific one. See Managing multiple connected accounts.

Meta tools

A session gives your agent meta tools, a small fixed set that discover, authenticate, and execute tools at runtime, so you never load hundreds of tool definitions into context:

The agent searches for relevant tools, authenticates if needed, and executes them through the same session. Meta-tool calls share context, so the agent searches in one call and executes in the next without losing state. See the Meta Tools reference for each tool's input and output schema.

Know the exact tools upfront? The direct tools preset returns them directly from session.tools() with no search step, while keeping session auth, connected accounts, and the workbench.

Authentication

When a tool needs a connection, the session generates a Connect Link with session.authorize(), or the agent handles the flow through COMPOSIO_MANAGE_CONNECTIONS.

In chat, the agent can pause, ask the user to connect an app, then retry the tool once auth completes. Composio manages the OAuth redirects, token exchange, and refresh. Once a user connects a toolkit, the connected account persists and future sessions reuse it without re-authentication.

For OAuth toolkits, Composio uses managed apps by default. Bring your own app when you need your own branding, scopes, or consent screen.

Sandbox

Handle large responses and bulk operations in the remote sandbox. Instead of stuffing long tool responses into the model context, the agent reads files, searches outputs, writes Python, transforms data, and calls Composio tools in bulk.

The sandbox 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 it for a fresh task context.

Sessions persist on the server and don't expire. For multi-turn conversations, store the session ID and reuse it with composio.use() instead of 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 in place instead of 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 a fundamentally different task setup. Reuse or update a session when the same conversation should keep its tool, auth, and workbench context.

Next