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 144 lines 6.91 KB
Rendered Raw
1 # @composio/core
2
3 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.
4
5 Full documentation lives at [docs.composio.dev](https://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`](https://www.npmjs.com/package/@composio/slim).
6
7 ## Installation
8
9 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](https://docs.composio.dev/docs/quickstart) for framework setup.
10
11 ```bash
12 npm install @composio/core
13 ```
14
15 ## Quickstart
16
17 Grab a `COMPOSIO_API_KEY` from the [dashboard](https://dashboard.composio.dev/settings), then create a session:
18
19 ```typescript
20 import { Composio } from '@composio/core';
21
22 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
23
24 // Each session is scoped to one of your users
25 const session = await composio.create('user_123');
26 const tools = await session.tools();
27 ```
28
29 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.
30
31 Sessions persist on the server. For multi-turn conversations, store `session.sessionId` and reuse it instead of calling `create()` again:
32
33 ```typescript
34 const session = await composio.use(sessionId);
35 ```
36
37 See [what a session is](https://docs.composio.dev/docs/how-composio-works) and [configuring sessions](https://docs.composio.dev/docs/configuring-sessions) for restricting toolkits, auth configs, and connected accounts.
38
39 ## Execution results
40
41 `session.execute(toolSlug, arguments)` returns a plain `ToolRouterSessionExecuteResponse` object:
42
43 ```typescript
44 const result = await session.execute('COMPOSIO_SEARCH_TOOLS', {
45 queries: [{ use_case: 'find recent emails' }],
46 });
47 if (result.resultType === 'completed') {
48 console.log(result.data);
49 } else { // 'failed' or 'blocked', even if error is empty
50 console.error(result.resultType, result.error);
51 }
52 ```
53
54 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.
55
56 `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()`.
57
58 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.
59
60 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.
61
62 ## Providers
63
64 A provider formats session tools for your agent framework and wires up execution:
65
66 ```typescript
67 import { Composio } from '@composio/core';
68 import { OpenAIAgentsProvider } from '@composio/openai-agents';
69
70 const composio = new Composio({ provider: new OpenAIAgentsProvider() });
71
72 const session = await composio.create('user_123');
73 const tools = await session.tools(); // ready to pass to the OpenAI Agents SDK
74 ```
75
76 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](https://github.com/ComposioHQ/composio#providers) and the [framework quickstarts](https://docs.composio.dev/docs/quickstart).
77
78 ## MCP
79
80 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:
81
82 ```typescript
83 const session = await composio.create('user_123', { mcp: true });
84
85 console.log(session.mcp.url);
86 console.log(session.mcp.headers);
87 ```
88
89 See [sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp).
90
91 ## Modifiers
92
93 `session.tools()` accepts modifiers to transform tool schemas and intercept execution:
94
95 ```typescript
96 const tools = await session.tools({
97 modifySchema: ({ toolSlug, toolkitSlug, schema }) => ({
98 ...schema,
99 description: `${schema.description} (via my-app)`,
100 }),
101 beforeExecute: ({ toolSlug, toolkitSlug, params }) => params,
102 afterExecute: ({ toolSlug, toolkitSlug, result }) => result,
103 });
104 ```
105
106 See [modify tool behavior](https://docs.composio.dev/docs/tools-direct/modify-tool-behavior/schema-modifiers).
107
108 ## Configuration
109
110 The `Composio` constructor accepts:
111
112 ```typescript
113 interface ComposioConfig {
114 apiKey?: string | null; // Defaults to COMPOSIO_API_KEY
115 baseURL?: string | null; // Custom API base URL
116 provider?: TProvider; // Provider adapter (default: OpenAIProvider)
117 allowTracking?: boolean; // Enable/disable telemetry (default: true)
118 defaultHeaders?: ComposioRequestHeaders; // Extra headers for API requests
119 disableVersionCheck?: boolean; // Skip the SDK version check (default: false)
120 dangerouslyAllowAutoUploadDownloadFiles?: boolean; // Auto file upload/download during execution (default: false)
121 }
122 ```
123
124 Environment variables:
125
126 - `COMPOSIO_API_KEY`: your Composio API key
127 - `COMPOSIO_BASE_URL`: custom API base URL
128 - `COMPOSIO_LOG_LEVEL`: `silent`, `error`, `warn`, `info`, or `debug`
129 - `COMPOSIO_TOOLKIT_VERSION_<TOOLKIT>`: pin a toolkit version, e.g. `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
130
131 ## Beyond sessions
132
133 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](https://docs.composio.dev/docs/tools-direct/executing-tools) flow (`composio.tools.get` and `composio.tools.execute`) still works but is legacy; prefer sessions for new code.
134
135 ## Support
136
137 - [Documentation](https://docs.composio.dev)
138 - [TypeScript SDK reference](https://docs.composio.dev/reference/sdk-reference/typescript)
139 - [Discord community](https://discord.gg/composio)
140 - [Open an issue](https://github.com/ComposioHQ/composio/issues)
141
142 ## License
143
144 MIT