Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 6.91 KB

@composio/core

The Composio SDK for TypeScript. Create a session for one of your users, hand its tools to your agent, and let the agent take action across 1000+ apps with authentication handled for you.

Full documentation lives at docs.composio.dev. This package intentionally ships its TypeScript source and SDK docs so the installed package is inspectable by coding agents; if you want a smaller install with the same API, use @composio/slim.

Installation

You need Node.js 22.22.3 or newer. The SDK is ESM-only: use import rather than CommonJS require(), and set "type": "module" in your project's package.json. See the SDK quickstart for framework setup.

npm install @composio/core

Quickstart

Grab a COMPOSIO_API_KEY from the dashboard, then create a session:

import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });

// Each session is scoped to one of your users
const session = await composio.create('user_123');
const tools = await session.tools();

By default a session gives your agent a small set of meta tools that discover, authenticate, and execute app tools at runtime, so you never load hundreds of tool definitions into context. Without a provider configured, session.tools() returns OpenAI function-calling format.

Sessions persist on the server. For multi-turn conversations, store session.sessionId and reuse it instead of calling create() again:

const session = await composio.use(sessionId);

See what a session is and configuring sessions for restricting toolkits, auth configs, and connected accounts.

Execution results

session.execute(toolSlug, arguments) returns a plain ToolRouterSessionExecuteResponse object:

const result = await session.execute('COMPOSIO_SEARCH_TOOLS', {
  queries: [{ use_case: 'find recent emails' }],
});
if (result.resultType === 'completed') {
  console.log(result.data);
} else { // 'failed' or 'blocked', even if error is empty
  console.error(result.resultType, result.error);
}

Read resultType, not successful, on a session result. It also includes data, error, and logId; serialize with JSON.stringify(result). A direct session call has no model tool-call ID, so keep that ID separately when constructing provider messages.

composio.tools.execute(toolSlug, { arguments, userId }) and afterExecute modifiers instead use ToolExecuteResponse objects with a successful boolean. Check result.successful there. Session provider adapters derive it from resultType === 'completed'. An afterExecute modifier receives { toolSlug, toolkitSlug, result } and returns the result. Calling session.execute directly doesn't run callbacks supplied to session.tools().

Transport/authentication errors and requests for user input can throw instead of returning a tool result. Handle authentication recovery separately from returned failures. A non-throwing call, empty error, or log ID isn't proof of a provider-side action. Check the explicit outcome and tool-specific data; retry and idempotency policy stays in your application.

Provider helpers serialize differently. The Anthropic executeToolCall returns a JSON string; handleToolCalls returns correlated user messages containing tool_result blocks. These payload projections aren't the session/modifier outcome contract. See the provider package's execution contract before using a helper result to make application decisions.

Providers

A provider formats session tools for your agent framework and wires up execution:

import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';

const composio = new Composio({ provider: new OpenAIAgentsProvider() });

const session = await composio.create('user_123');
const tools = await session.tools(); // ready to pass to the OpenAI Agents SDK

Adapters exist for OpenAI, OpenAI Agents, Anthropic, Claude Agent SDK, Vercel AI SDK, Google GenAI, LangChain, LlamaIndex, Mastra, and Cloudflare Workers AI. See the provider table and the framework quickstarts.

MCP

Every session also exposes a hosted MCP endpoint. Pass mcp: true to surface it in the type, then point Claude, Cursor, or any MCP client at it:

const session = await composio.create('user_123', { mcp: true });

console.log(session.mcp.url);
console.log(session.mcp.headers);

See sessions via MCP.

Modifiers

session.tools() accepts modifiers to transform tool schemas and intercept execution:

const tools = await session.tools({
  modifySchema: ({ toolSlug, toolkitSlug, schema }) => ({
    ...schema,
    description: `${schema.description} (via my-app)`,
  }),
  beforeExecute: ({ toolSlug, toolkitSlug, params }) => params,
  afterExecute: ({ toolSlug, toolkitSlug, result }) => result,
});

See modify tool behavior.

Configuration

The Composio constructor accepts:

interface ComposioConfig {
  apiKey?: string | null; // Defaults to COMPOSIO_API_KEY
  baseURL?: string | null; // Custom API base URL
  provider?: TProvider; // Provider adapter (default: OpenAIProvider)
  allowTracking?: boolean; // Enable/disable telemetry (default: true)
  defaultHeaders?: ComposioRequestHeaders; // Extra headers for API requests
  disableVersionCheck?: boolean; // Skip the SDK version check (default: false)
  dangerouslyAllowAutoUploadDownloadFiles?: boolean; // Auto file upload/download during execution (default: false)
}

Environment variables:

  • COMPOSIO_API_KEY: your Composio API key
  • COMPOSIO_BASE_URL: custom API base URL
  • COMPOSIO_LOG_LEVEL: silent, error, warn, info, or debug
  • COMPOSIO_TOOLKIT_VERSION_<TOOLKIT>: pin a toolkit version, e.g. COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00

Beyond sessions

The Composio instance also exposes composio.toolkits, composio.triggers, composio.authConfigs, and composio.connectedAccounts for managing resources outside a session. The older direct tool execution flow (composio.tools.get and composio.tools.execute) still works but is legacy; prefer sessions for new code.

Support

License

MIT