Skip to main content
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 so the agent discovers which app tools to use, authenticates users, and executes tools at runtime. Direct execution skips the session. Your code fetches specific tool schemas, manages auth itself, and calls tools.execute() directly.
Use sessions for new integrationsDirect 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. Sessions handle runtime tool discovery, authentication, and execution.
If your application needs a fixed tool set, consider the direct tools preset within a session. If you need approval before execution, use 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. Sessions are configurable. Restrict toolkits, set auth configs for white-labeled OAuth, and pin connected accounts. See Configuring Sessions for the full list. Sessions aren’t all-or-nothing. With the direct tools preset, a session returns a fixed set of tools directly from session.tools() with no search or meta tools, so the agent sees exactly the tools you list while you keep session auth, connected accounts, and the sandbox. It’s the middle ground between runtime discovery and direct execution.

Sessions

composio.create() returns meta tools:
The agent discovers app tools through COMPOSIO_SEARCH_TOOLS:
session.tools() returns meta tools (COMPOSIO_SEARCH_TOOLS, etc.), not app tools (GMAIL_SEND_EMAIL, etc.). The agent discovers app tools at runtime through search. To work with app tools directly, use direct execution.

Configuration

Restrict toolkits, set auth configs, pin connected accounts:
See Configuring Sessions for details.

Direct execution

Fetch tools by slug or toolkit. Pass them to your LLM or call tools.execute() without one.
tools.get() returns up to 20 tools by default. A limit caps the result count; it does not select tools by task relevance. When fetching from multiple toolkits (e.g., toolkits=["gmail", "github", "tavily"]), the limit may cut off tools from later toolkits. For a fixed workflow, fetch explicit tool names. See tool filtering and the TypeScript important filter.
With direct execution, you manage auth configs, connect links, and toolkit versioning yourself.

Migrating

See the migration guide. Auth configs and connected accounts carry over.

Next

Configuring Sessions