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.
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:
- Python
- TypeScript
- API
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:- Python
- TypeScript
- API
Direct execution
Fetch tools by slug or toolkit. Pass them to your LLM or calltools.execute() without one.
- Python
- TypeScript
- API