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 443 lines 14.6 KB
Rendered Raw
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 ```