Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: update documentation for new changelog entries (#3816)
Alberto Schiabelf9c2dc5d007d
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdxindex 491edd7e5..878dc5d89 100644--- a/docs/content/docs/configuring-sessions.mdx+++ b/docs/content/docs/configuring-sessions.mdx@@ -9,7 +9,7 @@ keywords: [session, toolkits, auth configs, connected accounts]<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(user_id="user_123")+session = composio.sessions.create(user_id="user_123")```</Tab><Tab value="TypeScript">@@ -34,13 +34,13 @@ To limit a session to specific toolkits, pass an array of toolkit slugs. The age<Tab value="Python">```python# Using array format-session = composio.create(+session = composio.sessions.create(user_id="user_123",toolkits=["github", "gmail", "slack"])# Using object format with enable key-session = composio.create(+session = composio.sessions.create(user_id="user_123",toolkits={"enable": ["github", "gmail", "slack"]})@@ -71,7 +71,7 @@ To keep every toolkit discoverable except a few, use the `disable` syntax. This<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",toolkits={"disable": ["exa", "firecrawl"]})@@ -106,7 +106,7 @@ composio = Composio(provider=OpenAIAgentsProvider(),)-session = composio.create(+session = composio.sessions.create(user_id="user_123",toolkits=["gmail"],tools={@@ -169,7 +169,7 @@ composio = Composio(provider=OpenAIAgentsProvider(),)-session = composio.create(+session = composio.sessions.create(user_id="user_123",toolkits=["gmail"],tools={@@ -245,7 +245,7 @@ To enable only specific tools, pass an `enable` list per toolkit:<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",tools={# Only these Gmail tools will be available@@ -278,7 +278,7 @@ The shorthand array syntax is equivalent to `enable`:<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",tools={"gmail": ["GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS"],@@ -307,7 +307,7 @@ To keep every tool in a toolkit except a few, use `disable`:<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",tools={# All Slack tools except delete@@ -352,13 +352,13 @@ To apply tag filters across all toolkits, pass `tags` at the session level:<Tab value="Python">```python# Only include read-only and idempotent tools-session = composio.create(+session = composio.sessions.create(user_id="user_123",tags=["readOnlyHint", "idempotentHint"])# Enable some tags, disable others-session = composio.create(+session = composio.sessions.create(user_id="user_123",tags={"enable": ["readOnlyHint"],@@ -393,7 +393,7 @@ To override the global tags for a specific toolkit, set `tags` inside that toolk<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",# Global: only read-only toolstags=["readOnlyHint"],@@ -455,7 +455,7 @@ composio = Composio(provider=OpenAIAgentsProvider(),)-session = composio.create(+session = composio.sessions.create(user_id="user_123",toolkits=["gmail"],preload={@@ -512,7 +512,7 @@ Use your own OAuth credentials instead of Composio's defaults. Pass an auth conf<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",auth_configs={"github": "ac_your_github_config",@@ -545,7 +545,7 @@ When a user has multiple connected accounts for the same toolkit, specify which<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",connected_accounts={"gmail": ["ca_work_gmail"],@@ -592,7 +592,7 @@ By default, sessions include the [sandbox](/docs/sandbox/remote), a persistent e<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",sandbox={"enable": False@@ -645,7 +645,7 @@ Defaults to `standard` when omitted.<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",sandbox={"sandbox_size": "large",diff --git a/docs/content/docs/how-composio-works.mdx b/docs/content/docs/how-composio-works.mdxindex 22c8523e0..90cfbba10 100644--- a/docs/content/docs/how-composio-works.mdx+++ b/docs/content/docs/how-composio-works.mdx@@ -4,7 +4,7 @@ description: What Composio sessions do, and how they scope users, tools, toolkitkeywords: [session, userID, tools, toolkits, meta tools, mcp, workbench]----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. In TypeScript, you create it with `composio.sessions.create(userId)`; Python uses `composio.create(user_id)`. 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.+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. Create one with `composio.sessions.create(...)` in either SDK. 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@@ -13,7 +13,7 @@ Create a session for a user, then read its tools formatted for your framework. T<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(user_id="user_123")+session = composio.sessions.create(user_id="user_123")tools = session.tools()```diff --git a/docs/content/docs/programmatic-auth-configs.mdx b/docs/content/docs/programmatic-auth-configs.mdxindex eecd8a7c0..ab3063480 100644--- a/docs/content/docs/programmatic-auth-configs.mdx+++ b/docs/content/docs/programmatic-auth-configs.mdx@@ -139,7 +139,7 @@ Creating an auth config does not change which credentials a session uses. Pass t<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python-session = composio.create(+session = composio.sessions.create(user_id="user_123",auth_configs={"notion": auth_config.id},)@@ -160,6 +160,25 @@ const session = await composio.sessions.create('user_123', {See [Configuring sessions](/docs/configuring-sessions#custom-auth-configs) for how `authConfigs` interacts with account selection and precedence.+## Find auth configs++In TypeScript, filter `authConfigs.list()` by name or ID with `search`. Disabled configs are excluded by default; set `showDisabled` to include them. Auth config responses use `id` as their canonical identifier.++```typescript+import { Composio } from '@composio/core';++const composio = new Composio();+// ---cut---+const configs = await composio.authConfigs.list({+ search: 'github',+ showDisabled: true,+});++for (const config of configs.items) {+ console.log(config.id);+}+```+## Discover the required fieldsDifferent schemes need different credential fields. To build the `credentials` object dynamically, ask the toolkit which fields it requires for a given scheme before you create the config.diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdxindex 5079049af..5efc13e9b 100644--- a/docs/content/docs/quickstart.mdx+++ b/docs/content/docs/quickstart.mdx@@ -6,6 +6,10 @@ keywords: [tutorial, setup, first agent]Build your first AI agent with Composio Tools. You'll create a [session](/docs/how-composio-works) for a user, give your agent access to [tools](/docs/how-composio-works), and let it take action across 1000+ apps.+<Callout type="info">+The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` syntax rather than CommonJS `require()`.+</Callout>+<QuickstartFlow><FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">@@ -62,10 +66,10 @@ composio = Composio(provider=OpenAIAgentsProvider())# Create a session for your useruser_id = "user_123"-session = composio.create(user_id=user_id)+session = composio.sessions.create(user_id=user_id)tools = session.tools()-# For multi-turn, store the session ID in your db and reuse instead of calling create() again:+# For multi-turn, store the session ID in your db and reuse instead of creating another session:# session_id = session.session_id# session = composio.use(session_id)@@ -209,10 +213,10 @@ composio = Composio(provider=ClaudeAgentSDKProvider())# Create a session for your useruser_id = "user_123"-session = composio.create(user_id=user_id)+session = composio.sessions.create(user_id=user_id)tools = session.tools()-# For multi-turn, store the session ID in your db and reuse instead of calling create() again:+# For multi-turn, store the session ID in your db and reuse instead of creating another session:# session_id = session.session_id# session = composio.use(session_id)@@ -426,7 +430,7 @@ readline.close();</QuickstartFlow>-By default, each `composio.create()` call returns a new session with access to all toolkits. Sessions are highly configurable beyond that: [Reusing a session](/docs/how-composio-works#how-sessions-behave) covers storing a session ID and calling `composio.use()` across multi-turn requests, while [Configuring Sessions](/docs/configuring-sessions) covers restricting toolkits, auth configs, and connected accounts.+By default, each `composio.sessions.create()` call returns a new session with access to all toolkits. Sessions are highly configurable beyond that: [Reusing a session](/docs/how-composio-works#how-sessions-behave) covers storing a session ID and calling `composio.use()` across multi-turn requests, while [Configuring Sessions](/docs/configuring-sessions) covers restricting toolkits, auth configs, and connected accounts.Prefer to connect over the Model Context Protocol instead? Every session also exposes an MCP endpoint. See [Using sessions via MCP](/docs/sessions-via-mcp).diff --git a/docs/content/docs/sessions-via-mcp.mdx b/docs/content/docs/sessions-via-mcp.mdxindex 074f81c13..c35a433d6 100644--- a/docs/content/docs/sessions-via-mcp.mdx+++ b/docs/content/docs/sessions-via-mcp.mdx@@ -18,7 +18,7 @@ Opt into MCP by passing `mcp: true` when you create the session. The session thefrom composio import Composiocomposio = Composio()-session = composio.create(user_id="user_123", mcp=True)+session = composio.sessions.create(user_id="user_123", mcp=True)mcp_url = session.mcp.urlmcp_headers = session.mcp.headers@@ -59,7 +59,7 @@ from composio import Composio, SESSION_PRESET_DIRECT_TOOLScomposio = Composio()-session = composio.create(+session = composio.sessions.create(user_id="user_123",toolkits=["gmail"],tools={"gmail": {"enable": ["GMAIL_FETCH_EMAILS", "GMAIL_CREATE_EMAIL_DRAFT"]}},@@ -161,7 +161,7 @@ MCP is the more portable option. Any MCP-compatible client connects with just aThe trade-off is that the MCP client talks to Composio's server directly, so anything the SDK does *around* tool execution doesn't apply:- **Tool-call modifiers don't run.** `beforeExecute` / `afterExecute` hooks and `modifySchema` transforms live in the SDK's execution path. Over MCP the client executes tools against the server and bypasses them, so you can't intercept, reshape, log, or gate calls the way you can with tools your agent calls directly.-- **Session-bound custom tools and toolkits don't work.** Tools created with `createCustomTool` / `createCustomToolkit` run in your process. The MCP server only exposes Composio's hosted tools, so your local custom tools aren't available over the endpoint.+- **Session-bound custom tools and toolkits don't work.** Tools created with `experimental_createTool` / `experimental_createToolkit` in TypeScript, or `composio.experimental.tool` / `composio.experimental.Toolkit` in Python, run in your process. The MCP server only exposes Composio's hosted tools, so your local custom tools aren't available over the endpoint.If you need any of those, call tools directly through a [provider](/docs/providers) instead of over MCP.diff --git a/docs/content/docs/shared-connections.mdx b/docs/content/docs/shared-connections.mdxindex 27639864a..6d27b3400 100644--- a/docs/content/docs/shared-connections.mdx+++ b/docs/content/docs/shared-connections.mdx@@ -102,7 +102,7 @@ The session config itself is **not** experimental. You pin the connection by ID# user_alice starts a session that pins the shared Gmail connection.# Gmail tools loaded from this session will resolve to that connection# even though user_alice did not create it.-session = composio.create(+session = composio.sessions.create(user_id="user_alice",connected_accounts={"gmail": ["ca_gmail_shared"],diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdxindex 1727afc74..403cc9db1 100644--- a/docs/content/docs/tools-direct/executing-tools.mdx+++ b/docs/content/docs/tools-direct/executing-tools.mdx@@ -14,6 +14,26 @@ LLMs on their own can only do generation. Tool calling changes that by letting tIn Composio, every **tool** is a single API action—fully described with schema, parameters, and return type. Tools live inside **toolkits** like Gmail, Slack, or GitHub, and Composio handles authentication and user scoping.+## Canceling TypeScript requests++TypeScript SDK methods accept an `AbortSignal` in their trailing request options. Aborted requests throw `ComposioRequestCancelledError`, so cancellation can be handled separately from execution failures:++```typescript+import { Composio, ComposioRequestCancelledError } from '@composio/core';++const composio = new Composio({ apiKey: 'your_composio_api_key' });++try {+ await composio.toolkits.get({}, { signal: AbortSignal.timeout(5_000) });+} catch (error) {+ if (error instanceof ComposioRequestCancelledError) {+ console.log('Request canceled');+ }+}+```++Use an `AbortController` when application code decides when to cancel. Custom tools receive the same signal as `ctx.signal` and should pass it to cancellable work.+<Callout type="info">**User Scoping**: All tools are scoped to a specific user - that's why every example includes a `user_id`. Learn how to structure User IDs in [User scoping](/docs/how-composio-works). Each user must authenticate with their respective services (Gmail, Calendar, etc.) - see [Authentication](/docs/tools-direct/authenticating-tools).</Callout>