Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
| 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 |