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 | # Core Concepts |
| 2 | |
| 3 | Composio SDK is built around a set of key concepts that work together to provide a seamless integration experience for third-party services and tools. |
| 4 | |
| 5 | ## User IDs |
| 6 | |
| 7 | User IDs are the **core foundation** of accessing and executing tools in Composio. Every tool execution, connection authorization, and account management operation requires a `userId` parameter that identifies which user's context the operation should be performed in. |
| 8 | |
| 9 | ### ⚠️ Critical Security Considerations |
| 10 | |
| 11 | User IDs are crucial for security and data isolation. You must be extremely careful when handling user IDs to ensure: |
| 12 | |
| 13 | - Users can only access their own connected accounts |
| 14 | - Tool executions are performed in the correct user context |
| 15 | - No unauthorized access to other users' data |
| 16 | |
| 17 | ### The `default` User ID |
| 18 | |
| 19 | The `default` userId refers to the default account of your Composio project and should **only be used for**: |
| 20 | |
| 21 | - **Testing and development** environments |
| 22 | - **Single-user applications** where external users don't connect their own accounts |
| 23 | - **Internal tools** where all operations are performed by your system |
| 24 | |
| 25 | ```typescript |
| 26 | // ❌ Don't use 'default' in production for multi-user apps |
| 27 | const tools = await composio.tools.get('default', { |
| 28 | toolkits: ['github'], |
| 29 | }); |
| 30 | |
| 31 | |
| 32 | // ❌ This could expose other users' data |
| 33 | const result = await composio.tools.execute('GITHUB_GET_REPO', { |
| 34 | userId: 'default', |
| 35 | arguments: { owner: 'example', repo: 'repo' }, |
| 36 | }); |
| 37 | ``` |
| 38 | |
| 39 | ### Production User IDs |
| 40 | |
| 41 | In production applications with multiple users, always use unique identifiers for each user. The best practices are: |
| 42 | |
| 43 | #### ✅ **Recommended: Database UUID** |
| 44 | |
| 45 | ```typescript |
| 46 | // Use your database's user ID (UUID, primary key, etc.) |
| 47 | const userId = user.id; // e.g., "550e8400-e29b-41d4-a716-446655440000" |
| 48 | |
| 49 | const tools = await composio.tools.get(userId, { |
| 50 | toolkits: ['github'], |
| 51 | }); |
| 52 | |
| 53 | // Get tools for a specific user |
| 54 | const userTools = await composio.tools.get(userId, { |
| 55 | toolkits: ['github'], |
| 56 | }); |
| 57 | |
| 58 | const result = await composio.tools.execute('GITHUB_GET_REPO', { |
| 59 | userId: userId, |
| 60 | arguments: { owner: 'example', repo: 'repo' }, |
| 61 | }); |
| 62 | ``` |
| 63 | |
| 64 | #### ✅ **Acceptable: Unique Username/Identifier** |
| 65 | |
| 66 | ```typescript |
| 67 | // Use a unique, stable identifier from your system |
| 68 | const userId = user.username; // e.g., "john_doe_123" |
| 69 | // or |
| 70 | const userId = user.externalId; // e.g., "auth0|507f1f77bcf86cd799439011" |
| 71 | ``` |
| 72 | |
| 73 | #### ⚠️ **Not Recommended: Email Address** |
| 74 | |
| 75 | ```typescript |
| 76 | // While functional, emails can change and may cause issues |
| 77 | const userId = user.email; // e.g., "user@example.com" |
| 78 | ``` |
| 79 | |
| 80 | ### Organization-Based Applications |
| 81 | |
| 82 | For **multi-user applications** where users are part of an organization and apps are connected at the **organization level** (not individual user level), use the **organization ID** as the `userId`: |
| 83 | |
| 84 | #### When to Use Organization IDs |
| 85 | |
| 86 | - **Team/Organization tools**: Apps like Slack, Microsoft Teams, or project management tools where the entire organization shares connections |
| 87 | - **Enterprise applications**: Where IT administrators connect apps for the whole organization |
| 88 | - **Shared resources**: When multiple users need access to the same connected accounts (shared Gmail account, company GitHub org, etc.) |
| 89 | - **Role-based access**: Where permissions are managed at the organization level |
| 90 | |
| 91 | #### ✅ **Recommended: Organization ID Pattern** |
| 92 | |
| 93 | ```typescript |
| 94 | // Use the organization/team/workspace ID |
| 95 | const userId = organization.id; // e.g., "org_550e8400-e29b-41d4-a716-446655440000" |
| 96 | // or |
| 97 | const userId = `org_${organization.slug}`; // e.g., "org_acme-corp" |
| 98 | |
| 99 | // All users in the organization share the same connected accounts |
| 100 | const tools = await composio.tools.get(userId, { |
| 101 | toolkits: ['slack', 'github'], |
| 102 | }); |
| 103 | |
| 104 | // Execute tools in the organization context |
| 105 | const result = await composio.tools.execute('SLACK_SEND_MESSAGE', { |
| 106 | userId: userId, // organization ID |
| 107 | arguments: { |
| 108 | channel: '#general', |
| 109 | text: 'Hello from the team!', |
| 110 | }, |
| 111 | }); |
| 112 | ``` |
| 113 | |
| 114 | #### Example: Organization-Based Application |
| 115 | |
| 116 | ```typescript |
| 117 | import { Composio } from '@composio/core'; |
| 118 | |
| 119 | const composio = new Composio({ |
| 120 | apiKey: process.env.COMPOSIO_API_KEY, |
| 121 | }); |
| 122 | |
| 123 | // 1. Admin connects Slack for the entire organization |
| 124 | async function connectOrganizationToSlack(organizationId: string, adminUserId: string) { |
| 125 | // Use organization ID as userId in Composio |
| 126 | const connectionRequest = await composio.toolkits.authorize(organizationId, 'slack'); |
| 127 | |
| 128 | // Store the connection request for the admin to complete |
| 129 | await storeConnectionRequest(organizationId, adminUserId, connectionRequest); |
| 130 | |
| 131 | return connectionRequest.redirectUrl; |
| 132 | } |
| 133 | |
| 134 | // 2. Any user in the organization can use the connected tools |
| 135 | async function sendSlackMessage(organizationId: string, channel: string, message: string) { |
| 136 | return await composio.tools.execute('SLACK_SEND_MESSAGE', { |
| 137 | userId: organizationId, // organization ID, not individual user ID |
| 138 | arguments: { |
| 139 | channel: channel, |
| 140 | text: message, |
| 141 | }, |
| 142 | }); |
| 143 | } |
| 144 | |
| 145 | // 3. Check if organization has required connections |
| 146 | async function getOrganizationTools(organizationId: string) { |
| 147 | return await composio.tools.get(organizationId, { |
| 148 | toolkits: ['slack', 'github', 'jira'], |
| 149 | }); |
| 150 | } |
| 151 | |
| 152 | // Usage in your API endpoint |
| 153 | app.post('/api/slack/message', async (req, res) => { |
| 154 | const { channel, message } = req.body; |
| 155 | const organizationId = req.user.organizationId; // Get from your auth system |
| 156 | |
| 157 | // Verify user has permission to send messages for this organization |
| 158 | if (!(await userCanSendMessages(req.user.id, organizationId))) { |
| 159 | return res.status(403).json({ error: 'Insufficient permissions' }); |
| 160 | } |
| 161 | |
| 162 | try { |
| 163 | const result = await sendSlackMessage(organizationId, channel, message); |
| 164 | res.json(result.data); |
| 165 | } catch (error) { |
| 166 | res.status(500).json({ error: 'Failed to send message' }); |
| 167 | } |
| 168 | }); |
| 169 | ``` |
| 170 | |
| 171 | #### Organization vs Individual User Pattern |
| 172 | |
| 173 | ```typescript |
| 174 | // ❌ Wrong: Using individual user IDs when apps are connected at org level |
| 175 | const userTools = await composio.tools.get(req.user.id, { |
| 176 | toolkits: ['slack'], // This would fail if Slack is connected to the org, not the user |
| 177 | }); |
| 178 | |
| 179 | // ✅ Correct: Using organization ID for org-level connections |
| 180 | const orgTools = await composio.tools.get(req.user.organizationId, { |
| 181 | toolkits: ['slack'], // This works because Slack is connected to the organization |
| 182 | }); |
| 183 | |
| 184 | // ✅ Hybrid: Some tools at user level, some at org level |
| 185 | const userPersonalTools = await composio.tools.get(req.user.id, { |
| 186 | toolkits: ['gmail'], // User's personal Gmail |
| 187 | }); |
| 188 | |
| 189 | const orgSharedTools = await composio.tools.get(req.user.organizationId, { |
| 190 | toolkits: ['slack', 'jira'], // Organization's shared tools |
| 191 | }); |
| 192 | ``` |
| 193 | |
| 194 | ### Example: Multi-User Application Flow |
| 195 | |
| 196 | ```typescript |
| 197 | import { Composio } from '@composio/core'; |
| 198 | |
| 199 | const composio = new Composio({ |
| 200 | apiKey: process.env.COMPOSIO_API_KEY, |
| 201 | }); |
| 202 | |
| 203 | // 1. User initiates GitHub connection |
| 204 | async function connectUserToGitHub(userId: string) { |
| 205 | const connectionRequest = await composio.toolkits.authorize(userId, 'github'); |
| 206 | return connectionRequest.redirectUrl; |
| 207 | } |
| 208 | |
| 209 | // 2. Get user's connected GitHub tools |
| 210 | async function getUserGitHubTools(userId: string) { |
| 211 | return await composio.tools.get(userId, { |
| 212 | toolkits: ['github'], |
| 213 | }); |
| 214 | } |
| 215 | |
| 216 | // 3. Execute tool for specific user |
| 217 | async function getUserRepos(userId: string) { |
| 218 | return await composio.tools.execute('GITHUB_LIST_REPOS', { |
| 219 | userId: userId, |
| 220 | arguments: { |
| 221 | per_page: 10, |
| 222 | }, |
| 223 | }); |
| 224 | } |
| 225 | |
| 226 | // Usage in your API endpoint |
| 227 | app.get('/api/github/repos', async (req, res) => { |
| 228 | const userId = req.user.id; // Get from your auth system |
| 229 | |
| 230 | try { |
| 231 | const repos = await getUserRepos(userId); |
| 232 | res.json(repos.data); |
| 233 | } catch (error) { |
| 234 | res.status(500).json({ error: 'Failed to fetch repos' }); |
| 235 | } |
| 236 | }); |
| 237 | ``` |
| 238 | |
| 239 | ### Best Practices |
| 240 | |
| 241 | 1. **Always validate user IDs** before passing them to Composio methods |
| 242 | 2. **Use your authentication system** to ensure users can only access their own data |
| 243 | 3. **Keep user IDs consistent** across your application and Composio |
| 244 | 4. **Never expose user IDs** in client-side code or logs |
| 245 | 5. **Use meaningful, stable identifiers** that won't change over time |
| 246 | |
| 247 | ## Tools |
| 248 | |
| 249 | Tools are the fundamental units of functionality in Composio. Each tool represents a specific action that can be performed, such as "Get GitHub Repository" or "Send Email". Tools have: |
| 250 | |
| 251 | - **Slug**: A unique identifier (e.g., `GITHUB_GET_REPO`) |
| 252 | - **Name**: A human-readable name (e.g., "Get GitHub Repository") |
| 253 | - **Description**: A description of what the tool does |
| 254 | - **Input Parameters**: The arguments required to execute the tool |
| 255 | - **Output Parameters**: The data returned by the tool |
| 256 | |
| 257 | Tools are organized into toolkits and can be executed through the Composio SDK. |
| 258 | |
| 259 | ```typescript |
| 260 | // Example: Execute a GitHub tool |
| 261 | const result = await composio.tools.execute('GITHUB_GET_REPO', { |
| 262 | userId: 'default', |
| 263 | arguments: { |
| 264 | owner: 'composio', |
| 265 | repo: 'sdk', |
| 266 | }, |
| 267 | }); |
| 268 | ``` |
| 269 | |
| 270 | ## Toolkits |
| 271 | |
| 272 | Toolkits are collections of related tools grouped by service or functionality. For example, the "GitHub" toolkit includes tools for interacting with repositories, issues, pull requests, and more. |
| 273 | |
| 274 | Toolkits typically require authentication to be accessed, which is managed through connected accounts. |
| 275 | |
| 276 | ```typescript |
| 277 | // Example: Get all tools from the GitHub toolkit |
| 278 | const tools = await composio.tools.get('default', { |
| 279 | toolkits: ['github'], |
| 280 | }); |
| 281 | ``` |
| 282 | |
| 283 | ## Connected Accounts |
| 284 | |
| 285 | Connected Accounts represent a user's connection to an external service (toolkit). They store authentication tokens and other information needed to access the service. |
| 286 | |
| 287 | The SDK provides methods to create, manage, and use connected accounts: |
| 288 | |
| 289 | ```typescript |
| 290 | // Example: Initiate a connection to GitHub |
| 291 | const connectionRequest = await composio.toolkits.authorize('user123', 'github'); |
| 292 | |
| 293 | // Example: Wait for the connection to be established |
| 294 | const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionRequest.id); |
| 295 | ``` |
| 296 | |
| 297 | ## Auth Configs |
| 298 | |
| 299 | Auth Configs define how authentication works for a particular toolkit. They specify the auth scheme (OAuth2, API Key, etc.) and other authentication-related details. |
| 300 | |
| 301 | Auth Configs are usually created automatically when authorizing a toolkit but can also be created manually. |
| 302 | |
| 303 | ```typescript |
| 304 | // Example: Create an auth config for GitHub |
| 305 | const authConfig = await composio.authConfigs.create('github', { |
| 306 | type: 'use_composio_managed_auth', |
| 307 | name: 'GitHub Auth Config', |
| 308 | }); |
| 309 | ``` |
| 310 | |
| 311 | ## Providers |
| 312 | |
| 313 | Providers are adapters that allow tools to be used with different AI platforms or frameworks. The default provider is OpenAIProvider, which formats tools for use with OpenAI's API. |
| 314 | |
| 315 | Providers handle the transformation of tools into the format required by the AI platform and manage the execution flow. |
| 316 | |
| 317 | ```typescript |
| 318 | // Example: Initialize Composio with OpenAI provider |
| 319 | const composio = new Composio({ |
| 320 | apiKey: 'your-api-key', |
| 321 | provider: new OpenAIProvider(), |
| 322 | }); |
| 323 | ``` |
| 324 | |
| 325 | ## MCP (Model Control Protocol) |
| 326 | |
| 327 | MCP is a standardized protocol for exposing tools and capabilities to AI models. It acts as a bridge between AI agents and external services, providing secure and managed access to tools through MCP servers. |
| 328 | |
| 329 | ### What is MCP? |
| 330 | |
| 331 | Model Control Protocol (MCP) is designed to solve the challenge of connecting AI models to external tools in a secure, scalable way. Instead of directly integrating tools into AI models, MCP provides: |
| 332 | |
| 333 | - **Standardized Communication**: A common protocol that different AI frameworks can understand |
| 334 | - **Security Isolation**: Tools run in separate MCP servers, isolating them from the AI model |
| 335 | - **Dynamic Tool Discovery**: AI models can discover available tools at runtime |
| 336 | - **Provider Flexibility**: Works with multiple AI frameworks through provider adapters |
| 337 | |
| 338 | ### MCP Servers |
| 339 | |
| 340 | MCP servers are the core component that expose tools to AI models. Each server: |
| 341 | |
| 342 | - **Hosts specific toolkits**: You choose which toolkits and tools to expose |
| 343 | - **Manages authentication**: Handles auth for the tools it exposes |
| 344 | - **Provides secure URLs**: Generates URLs that AI agents can connect to |
| 345 | - **Supports multiple connections**: Can serve multiple users or AI agents |
| 346 | |
| 347 | ```typescript |
| 348 | // Example: Create an MCP server |
| 349 | const mcpServer = await composio.mcp.create( |
| 350 | "email-assistant", |
| 351 | [ |
| 352 | { |
| 353 | toolkit: "gmail", |
| 354 | authConfigId: "ac_gmail123", |
| 355 | allowedTools: ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"] |
| 356 | } |
| 357 | ], |
| 358 | { isChatAuth: true } |
| 359 | ); |
| 360 | |
| 361 | // Get server URLs for AI agent to connect |
| 362 | const serverUrls = await mcpServer.getServer({ |
| 363 | connectedAccountIds: { gmail: "connected_account_id" } |
| 364 | }); |
| 365 | ``` |
| 366 | |
| 367 | ### MCP vs Direct Tool Execution |
| 368 | |
| 369 | There are two ways to use tools in Composio: |
| 370 | |
| 371 | 1. **Direct Execution** (Traditional approach): |
| 372 | ```typescript |
| 373 | // Directly execute tools through the SDK |
| 374 | const result = await composio.tools.execute('GITHUB_GET_REPO', { |
| 375 | userId: 'user123', |
| 376 | arguments: { owner: 'example', repo: 'repo' } |
| 377 | }); |
| 378 | ``` |
| 379 | |
| 380 | 2. **MCP Protocol** (Recommended for AI agents): |
| 381 | ```typescript |
| 382 | // Create MCP server and let AI agent discover/execute tools |
| 383 | const server = await composio.mcp.create("github-server", [...]); |
| 384 | const urls = await server.getServer({...}); |
| 385 | // AI agent connects to URLs and executes tools autonomously |
| 386 | ``` |
| 387 | |
| 388 | ### When to Use MCP |
| 389 | |
| 390 | Use MCP when: |
| 391 | - Building AI agents that need tool access |
| 392 | - Working with frameworks that support MCP (Claude, Mastra, etc.) |
| 393 | - You want standardized tool discovery and execution |
| 394 | - Security isolation between AI and tools is important |
| 395 | - You need to expose tools to multiple AI agents |
| 396 | |
| 397 | Use direct execution when: |
| 398 | - Building traditional applications without AI |
| 399 | - You need fine-grained control over tool execution |
| 400 | - Working with simple scripts or automation |
| 401 | - MCP overhead isn't necessary |
| 402 | |
| 403 | ## Custom Tools |
| 404 | |
| 405 | Custom Tools allow you to attach your own local tools to Tool Router sessions. Define them with `experimental_createTool`, then pass them to `composio.create()` under `experimental.localTools`. |
| 406 | |
| 407 | ```typescript |
| 408 | import { Composio, experimental_createTool } from '@composio/core'; |
| 409 | import { z } from 'zod'; |
| 410 | |
| 411 | const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY }); |
| 412 | |
| 413 | const customTool = experimental_createTool('MY_CUSTOM_TOOL', { |
| 414 | name: 'My Custom Tool', |
| 415 | description: 'A custom tool that does something specific', |
| 416 | inputParams: z.object({ |
| 417 | param1: z.string().describe('First parameter'), |
| 418 | param2: z.number().optional().describe('Optional parameter'), |
| 419 | }), |
| 420 | execute: async (input) => { |
| 421 | return { result: `Received ${input.param1}` }; |
| 422 | }, |
| 423 | }); |
| 424 | |
| 425 | const session = await composio.create('default', { |
| 426 | experimental: { localTools: [customTool] }, |
| 427 | }); |
| 428 | |
| 429 | const result = await session.execute('MY_CUSTOM_TOOL', { |
| 430 | param1: 'hello', |
| 431 | }); |
| 432 | ``` |
| 433 | |
| 434 | ## Triggers |
| 435 | |
| 436 | Triggers allow your application to respond to events from external services. They define when and how your application should take action based on external events. |
| 437 | |
| 438 | ```typescript |
| 439 | // Example: Get available triggers |
| 440 | const triggers = await composio.triggers.get({ |
| 441 | toolkits: ['github'], |
| 442 | }); |
| 443 | ``` |