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 669 lines 18.8 KB
Rendered Raw
1 # Creating Custom Providers
2
3 This guide provides a comprehensive walkthrough of creating custom providers for the Composio SDK, enabling integration with different AI frameworks and platforms.
4
5 ## Provider Architecture
6
7 The Composio SDK uses a provider architecture to adapt tools for different AI frameworks. The provider handles:
8
9 1. **Tool Format Transformation**: Converting Composio tools into formats compatible with specific AI platforms
10 2. **Tool Execution**: Managing the flow of tool execution and results through the `executeTool` method
11 3. **Platform-Specific Integration**: Providing helper methods for seamless integration
12 4. **MCP Server Support**: Optional transformation of MCP server responses
13
14 ## Types of Providers
15
16 There are two types of providers:
17
18 1. **Non-Agentic Providers**: Transform tools for platforms that don't have their own agency (e.g., OpenAI, Anthropic, Google)
19 2. **Agentic Providers**: Transform tools for platforms that have their own agency (e.g., LangChain)
20
21 ## Provider Class Hierarchy
22
23 ```
24 BaseProvider<TMcpResponse> (Abstract)
25 ├── BaseNonAgenticProvider<TToolCollection, TTool, TMcpResponse> (Abstract)
26 │ ├── OpenAIProvider (Concrete - ships with @composio/core)
27 │ ├── AnthropicProvider (Concrete - @composio/anthropic)
28 │ ├── GoogleProvider (Concrete - @composio/google)
29 │ └── [Your Custom Non-Agentic Provider] (Concrete)
30 └── BaseAgenticProvider<TToolCollection, TTool, TMcpResponse> (Abstract)
31 ├── LangchainProvider (Concrete - @composio/langchain)
32 └── [Your Custom Agentic Provider] (Concrete)
33 ```
34
35 ## Creating a Non-Agentic Provider
36
37 Non-agentic providers extend the `BaseNonAgenticProvider` abstract class. Here's how to create one:
38
39 ```typescript
40 import {
41 BaseNonAgenticProvider,
42 Tool,
43 ToolExecuteParams,
44 ExecuteToolModifiers,
45 ExecuteToolFnOptions,
46 McpUrlResponse,
47 McpServerGetResponse,
48 } from '@composio/core';
49
50 // Define your tool format
51 interface MyAITool {
52 name: string;
53 description: string;
54 parameters: {
55 type: string;
56 properties: Record<string, unknown>;
57 required?: string[];
58 };
59 }
60
61 // Define your tool collection format
62 type MyAIToolCollection = MyAITool[];
63
64 // Optional: Define custom MCP response format
65 type MyAIMcpResponse = {
66 url: string;
67 name: string;
68 type: 'url';
69 }[];
70
71 // Create your provider
72 export class MyAIProvider extends BaseNonAgenticProvider<
73 MyAIToolCollection,
74 MyAITool,
75 MyAIMcpResponse
76 > {
77 // Required: Unique provider name for telemetry
78 readonly name = 'my-ai-platform';
79
80 /**
81 * Creates a new instance of MyAIProvider.
82 */
83 constructor() {
84 super();
85 }
86
87 // Required: Method to transform a single tool
88 override wrapTool(tool: Tool): MyAITool {
89 return {
90 name: tool.slug,
91 description: tool.description || '',
92 parameters: {
93 type: 'object',
94 properties: tool.inputParameters?.properties || {},
95 required: tool.inputParameters?.required || [],
96 },
97 };
98 }
99
100 // Required: Method to transform a collection of tools
101 override wrapTools(tools: Tool[]): MyAIToolCollection {
102 return tools.map(tool => this.wrapTool(tool));
103 }
104
105 // Optional: Transform MCP server responses to your format
106 wrapMcpServerResponse(data: McpUrlResponse): MyAIMcpResponse {
107 return data.map(item => ({
108 url: item.url,
109 name: item.name,
110 type: 'url',
111 }));
112 }
113
114 // Optional: Custom helper methods for your AI platform
115 async executeMyAIToolCall(
116 userId: string,
117 toolCall: {
118 name: string;
119 arguments: Record<string, unknown>;
120 },
121 options?: ExecuteToolFnOptions,
122 modifiers?: ExecuteToolModifiers
123 ): Promise<string> {
124 // Use the built-in executeTool method
125 const payload: ToolExecuteParams = {
126 arguments: toolCall.arguments,
127 connectedAccountId: options?.connectedAccountId,
128 customAuthParams: options?.customAuthParams,
129 customConnectionData: options?.customConnectionData,
130 userId: userId,
131 };
132
133 const result = await this.executeTool(toolCall.name, payload, modifiers);
134 return JSON.stringify(result.data);
135 }
136
137 // Optional: Handle multiple tool calls from your AI platform
138 async handleMyAIToolCalls(
139 userId: string,
140 toolCalls: Array<{ name: string; arguments: Record<string, unknown> }>,
141 options?: ExecuteToolFnOptions,
142 modifiers?: ExecuteToolModifiers
143 ): Promise<string[]> {
144 const results = await Promise.all(
145 toolCalls.map(toolCall => this.executeMyAIToolCall(userId, toolCall, options, modifiers))
146 );
147 return results;
148 }
149 }
150 ```
151
152 ## Creating an Agentic Provider
153
154 Agentic providers extend the `BaseAgenticProvider` abstract class. The key difference is that agentic providers receive an `ExecuteToolFn` to handle tool execution:
155
156 ```typescript
157 import {
158 BaseAgenticProvider,
159 Tool,
160 ExecuteToolFn,
161 McpUrlResponse,
162 McpServerGetResponse,
163 } from '@composio/core';
164
165 // Define your tool format
166 interface AgentTool {
167 name: string;
168 description: string;
169 execute: (args: Record<string, unknown>) => Promise<unknown>;
170 schema: Record<string, unknown>;
171 }
172
173 // Define your tool collection format
174 interface AgentToolkit {
175 tools: AgentTool[];
176 createAgent: (config: Record<string, unknown>) => unknown;
177 }
178
179 // Optional: Define custom MCP response format
180 type MyAgentMcpResponse = {
181 url: URL;
182 name: string;
183 }[];
184
185 // Create your provider
186 export class MyAgentProvider extends BaseAgenticProvider<
187 AgentToolkit,
188 AgentTool,
189 MyAgentMcpResponse
190 > {
191 // Required: Unique provider name for telemetry
192 readonly name = 'my-agent-platform';
193
194 /**
195 * Creates a new instance of MyAgentProvider.
196 */
197 constructor() {
198 super();
199 }
200
201 // Required: Method to transform a single tool with execute function
202 override wrapTool(tool: Tool, executeToolFn: ExecuteToolFn): AgentTool {
203 return {
204 name: tool.slug,
205 description: tool.description || '',
206 schema: tool.inputParameters || {},
207 execute: async (args: Record<string, unknown>) => {
208 const result = await executeToolFn(tool.slug, args);
209 if (!result.successful) {
210 throw new Error(result.error || 'Tool execution failed');
211 }
212 return result.data;
213 },
214 };
215 }
216
217 // Required: Method to transform a collection of tools with execute function
218 override wrapTools(tools: Tool[], executeToolFn: ExecuteToolFn): AgentToolkit {
219 const agentTools = tools.map(tool => this.wrapTool(tool, executeToolFn));
220
221 return {
222 tools: agentTools,
223 createAgent: config => {
224 // Create an agent using the tools
225 return {
226 run: async (prompt: string) => {
227 // Implementation depends on your agent framework
228 console.log(`Running agent with prompt: ${prompt}`);
229 // The agent would use the tools.execute method to run tools
230 },
231 };
232 },
233 };
234 }
235
236 // Optional: Transform MCP server responses to your format
237 wrapMcpServerResponse(data: McpUrlResponse): MyAgentMcpResponse {
238 return data.map(item => ({
239 url: new URL(item.url),
240 name: item.name,
241 }));
242 }
243
244 // Optional: Custom helper methods for your agent platform
245 async runAgent(agentToolkit: AgentToolkit, prompt: string): Promise<unknown> {
246 const agent = agentToolkit.createAgent({});
247 return await agent.run(prompt);
248 }
249 }
250 ```
251
252 ## Using Your Custom Provider
253
254 After creating your provider, use it with the Composio SDK:
255
256 ```typescript
257 import { Composio } from '@composio/core';
258 import { MyAIProvider } from './my-ai-provider';
259
260 // Create your provider instance
261 const myProvider = new MyAIProvider();
262
263 // Initialize Composio with your provider
264 const composio = new Composio({
265 apiKey: 'your-composio-api-key',
266 provider: myProvider,
267 });
268
269 // Get tools - they will be transformed by your provider
270 const tools = await composio.tools.get('default', {
271 toolkits: ['github'],
272 });
273
274 // Use the tools with your AI platform
275 console.log(tools); // These will be in your custom format
276 ```
277
278 ## Provider State and Context
279
280 Your provider can maintain state and context:
281
282 ```typescript
283 export class StatefulProvider extends BaseNonAgenticProvider<ToolCollection, Tool> {
284 readonly name = 'stateful-provider';
285
286 // Provider state
287 private requestCount = 0;
288 private toolCache = new Map<string, any>();
289 private config: ProviderConfig;
290
291 constructor(config: ProviderConfig) {
292 super();
293 this.config = config;
294 }
295
296 override wrapTool(tool: Tool): ProviderTool {
297 this.requestCount++;
298
299 // Use the provider state/config
300 const enhancedTool = {
301 // Transform the tool
302 name: this.config.useUpperCase ? tool.slug.toUpperCase() : tool.slug,
303 description: tool.description,
304 schema: tool.inputParameters,
305 };
306
307 // Cache the transformed tool
308 this.toolCache.set(tool.slug, enhancedTool);
309
310 return enhancedTool;
311 }
312
313 override wrapTools(tools: Tool[]): ProviderToolCollection {
314 return tools.map(tool => this.wrapTool(tool));
315 }
316
317 // Custom methods that use provider state
318 getRequestCount(): number {
319 return this.requestCount;
320 }
321
322 getCachedTool(slug: string): ProviderTool | undefined {
323 return this.toolCache.get(slug);
324 }
325 }
326 ```
327
328 ## Advanced: Provider Composition
329
330 You can compose functionality by extending existing providers:
331
332 ```typescript
333 import { OpenAIProvider } from '@composio/openai';
334
335 // Extend the OpenAI provider with custom functionality
336 export class EnhancedOpenAIProvider extends OpenAIProvider {
337 // Add properties
338 private analytics = {
339 toolCalls: 0,
340 errors: 0,
341 };
342
343 // Override methods to add functionality
344 override async executeToolCall(userId, tool, options, modifiers) {
345 this.analytics.toolCalls++;
346
347 try {
348 // Call the parent implementation
349 const result = await super.executeToolCall(userId, tool, options, modifiers);
350 return result;
351 } catch (error) {
352 this.analytics.errors++;
353 throw error;
354 }
355 }
356
357 // Add new methods
358 getAnalytics() {
359 return this.analytics;
360 }
361
362 async executeWithRetry(userId, tool, options, modifiers, maxRetries = 3) {
363 let attempts = 0;
364 let lastError;
365
366 while (attempts < maxRetries) {
367 try {
368 return await this.executeToolCall(userId, tool, options, modifiers);
369 } catch (error) {
370 lastError = error;
371 attempts++;
372 await new Promise(resolve => setTimeout(resolve, 1000 * attempts));
373 }
374 }
375
376 throw lastError;
377 }
378 }
379 ```
380
381 ## Example: Anthropic Claude Provider
382
383 Here's a real-world example based on the actual Anthropic provider implementation:
384
385 ```typescript
386 import {
387 BaseNonAgenticProvider,
388 Tool,
389 ToolExecuteParams,
390 ExecuteToolModifiers,
391 ExecuteToolFnOptions,
392 McpUrlResponse,
393 } from '@composio/core';
394 import Anthropic from '@anthropic-ai/sdk';
395
396 // Define the tool format for Anthropic
397 interface AnthropicTool {
398 name: string;
399 description: string;
400 input_schema: {
401 type: string;
402 properties: Record<string, unknown>;
403 required?: string[];
404 };
405 cache_control?: { type: 'ephemeral' };
406 }
407
408 type AnthropicToolCollection = AnthropicTool[];
409
410 // Define tool use block type
411 interface AnthropicToolUseBlock {
412 type: 'tool_use';
413 id: string;
414 name: string;
415 input: Record<string, unknown>;
416 }
417
418 // Define custom MCP response format for Anthropic
419 type AnthropicMcpServerGetResponse = {
420 type: 'url';
421 url: string;
422 name: string;
423 }[];
424
425 export class AnthropicProvider extends BaseNonAgenticProvider<
426 AnthropicToolCollection,
427 AnthropicTool,
428 AnthropicMcpServerGetResponse
429 > {
430 readonly name = 'anthropic';
431 private cacheTools: boolean = false;
432
433 constructor(options?: { cacheTools?: boolean }) {
434 super();
435 this.cacheTools = options?.cacheTools ?? false;
436 }
437
438 override wrapTool(tool: Tool): AnthropicTool {
439 return {
440 name: tool.slug,
441 description: tool.description || '',
442 input_schema: (tool.inputParameters || {
443 type: 'object',
444 properties: {},
445 required: [],
446 }) as any,
447 cache_control: this.cacheTools ? { type: 'ephemeral' } : undefined,
448 };
449 }
450
451 override wrapTools(tools: Tool[]): AnthropicToolCollection {
452 return tools.map(tool => this.wrapTool(tool));
453 }
454
455 // Transform MCP URL response into Anthropic-specific format
456 wrapMcpServerResponse(data: McpUrlResponse): AnthropicMcpServerGetResponse {
457 return data.map(item => ({
458 url: item.url,
459 name: item.name,
460 type: 'url',
461 }));
462 }
463
464 // Execute a single tool call from Anthropic
465 async executeToolCall(
466 userId: string,
467 toolUse: AnthropicToolUseBlock,
468 options?: ExecuteToolFnOptions,
469 modifiers?: ExecuteToolModifiers
470 ): Promise<string> {
471 const payload: ToolExecuteParams = {
472 arguments: toolUse.input,
473 connectedAccountId: options?.connectedAccountId,
474 customAuthParams: options?.customAuthParams,
475 customConnectionData: options?.customConnectionData,
476 userId: userId,
477 };
478 const result = await this.executeTool(toolUse.name, payload, modifiers);
479 return JSON.stringify(result.data);
480 }
481
482 // Handle tool calls from Anthropic message response
483 async handleToolCalls(
484 userId: string,
485 message: Anthropic.Message,
486 options?: ExecuteToolFnOptions,
487 modifiers?: ExecuteToolModifiers
488 ): Promise<Anthropic.Messages.MessageParam[]> {
489 const outputs: Anthropic.Messages.ToolResultBlockParam[] = [];
490
491 // Extract tool use blocks from message content
492 const toolUseBlocks: AnthropicToolUseBlock[] = [];
493 for (const content of message.content) {
494 if (
495 typeof content === 'object' &&
496 content !== null &&
497 'type' in content &&
498 content.type === 'tool_use' &&
499 'id' in content &&
500 'name' in content &&
501 'input' in content
502 ) {
503 toolUseBlocks.push({
504 type: 'tool_use',
505 id: String(content.id),
506 name: String(content.name),
507 input: content.input as Record<string, unknown>,
508 });
509 }
510 }
511
512 // Execute each tool call
513 for (const toolUse of toolUseBlocks) {
514 const toolResult = await this.executeToolCall(userId, toolUse, options, modifiers);
515 outputs.push({
516 type: 'tool_result',
517 tool_use_id: toolUse.id,
518 content: toolResult,
519 cache_control: this.cacheTools ? { type: 'ephemeral' } : undefined,
520 });
521 }
522
523 return outputs.length > 0 ? [{ role: 'user', content: outputs }] : [];
524 }
525 }
526 ```
527
528 ## Example: LangChain Provider
529
530 Here's a real-world example based on the actual LangChain provider implementation:
531
532 ```typescript
533 import {
534 BaseAgenticProvider,
535 jsonSchemaToZodSchema,
536 Tool,
537 ExecuteToolFn,
538 McpUrlResponse,
539 McpServerGetResponse,
540 } from '@composio/core';
541 import { DynamicStructuredTool } from '@langchain/core/tools';
542
543 export type LangChainToolCollection = Array<DynamicStructuredTool>;
544
545 export class LangchainProvider extends BaseAgenticProvider<
546 LangChainToolCollection,
547 DynamicStructuredTool
548 > {
549 readonly name = 'langchain';
550
551 constructor() {
552 super();
553 }
554
555 // Transform MCP URL response into standard format
556 wrapMcpServerResponse(data: McpUrlResponse): McpServerGetResponse {
557 return data.map(item => ({
558 url: new URL(item.url),
559 name: item.name,
560 })) as McpServerGetResponse;
561 }
562
563 override wrapTool(tool: Tool, executeTool: ExecuteToolFn): DynamicStructuredTool {
564 const toolName = tool.slug;
565 const description = tool.description;
566 const appName = tool.toolkit?.name?.toLowerCase();
567
568 if (!appName) {
569 throw new Error('App name is not defined');
570 }
571
572 if (!tool.inputParameters) {
573 throw new Error('Tool input parameters are not defined');
574 }
575
576 // Convert JSON schema to Zod schema for LangChain
577 const parameters = jsonSchemaToZodSchema(tool.inputParameters);
578
579 const func = async (...args: unknown[]): Promise<unknown> => {
580 const result = await executeTool(toolName, args[0] as Record<string, unknown>);
581 return JSON.stringify(result);
582 };
583
584 return new DynamicStructuredTool({
585 name: toolName,
586 description: description || '',
587 schema: parameters,
588 func: func,
589 });
590 }
591
592 override wrapTools(tools: Tool[], executeTool: ExecuteToolFn): LangChainToolCollection {
593 return tools.map(tool => this.wrapTool(tool, executeTool));
594 }
595 }
596 ```
597
598 ### Usage with LangChain
599
600 ```typescript
601 import { Composio } from '@composio/core';
602 import { LangchainProvider } from '@composio/langchain';
603 import { ChatOpenAI } from '@langchain/openai';
604 import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
605 import { ChatPromptTemplate, MessagesPlaceholder } from '@langchain/core/prompts';
606
607 // Initialize Composio with LangChain provider
608 const composio = new Composio({
609 apiKey: 'your-composio-api-key',
610 provider: new LangchainProvider()
611 });
612
613 // Get tools for LangChain
614 const tools = await composio.tools.get('user123', {
615 toolkits: ['github']
616 });
617
618 // Create LangChain agent
619 const llm = new ChatOpenAI({
620 modelName: 'gpt-4',
621 temperature: 0
622 });
623
624 const prompt = ChatPromptTemplate.fromMessages([
625 ['system', 'You are a helpful assistant with access to GitHub tools.'],
626 ['human', '{input}'],
627 new MessagesPlaceholder('agent_scratchpad')
628 ]);
629
630 const agent = await createOpenAIFunctionsAgent({
631 llm,
632 tools,
633 prompt
634 });
635
636 const agentExecutor = new AgentExecutor({
637 agent,
638 tools,
639 verbose: true
640 });
641
642 // Use the agent
643 const result = await agentExecutor.invoke({
644 input: 'Create a new GitHub repository called "my-project"'
645 });
646
647 console.log(result.output);
648 ```
649
650 ## Best Practices
651
652 1. **Keep providers focused**: Each provider should integrate with one specific platform
653 2. **Handle errors gracefully**: Catch and transform errors from tool execution in your helper methods
654 3. **Follow platform conventions**: Adopt naming and structural conventions of the target platform
655 4. **Implement proper types**: Use TypeScript generics to ensure type safety for your tool formats
656 5. **Add helper methods**: Provide convenient methods for common platform-specific operations like `executeToolCall` and `handleToolCalls`
657 6. **Support MCP servers**: Implement `wrapMcpServerResponse` if your platform needs custom MCP server response formatting
658 7. **Use the built-in executeTool method**: Always use `this.executeTool()` for tool execution rather than implementing your own
659 8. **Provide clear documentation**: Document your provider's unique features and usage patterns
660 9. **Use meaningful provider names**: Set a descriptive provider name for telemetry and debugging
661 10. **Handle authentication properly**: Pass through `ExecuteToolFnOptions` for connected accounts and custom auth parameters
662
663 ## Key Implementation Notes
664
665 - **Non-agentic providers** receive tools and transform them for direct use with AI platforms
666 - **Agentic providers** receive both tools and an `ExecuteToolFn` to create autonomous agents
667 - The `executeTool` method is injected by the Composio core and handles all authentication and execution logic
668 - MCP server support is optional but recommended for providers that need custom server response formatting
669 - All providers should extend the appropriate base class and implement the required abstract methods