Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Fix provider docs (#1849)
Musthaq Ahamad committed
Aug 15, 2025 at 09:57 UTC
4b6b28486ee06c1e147d96857056c9e03db55fda
1 file changed
+336
-145
ts/docs/advanced/custom-providers.md
+336
-145
@@ -7,33 +7,45 @@ This guide provides a comprehensive walkthrough of creating custom providers for
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
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
17
-1. **Non-Agentic Providers**: Transform tools for platforms that don't have their own agency (e.g., OpenAI)
18
-2. **Agentic Providers**: Transform tools for platforms that have their own agency (e.g., LangChain, AutoGPT)
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
```
23
-BaseProvider (Abstract)
24
-├── BaseNonAgenticProvider (Abstract)
25
-│ └── OpenAIProvider (Concrete)
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)
27
-└── BaseAgenticProvider (Abstract)
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
33
-Non-agentic providers implement the `BaseNonAgenticProvider` abstract class:
37
+Non-agentic providers extend the `BaseNonAgenticProvider` abstract class. Here's how to create one:
38
39
```typescript
36
-import { BaseNonAgenticProvider, Tool } from '@composio/core';
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 {
@@ -49,11 +61,29 @@ interface MyAITool {
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
53
-export class MyAIProvider extends BaseNonAgenticProvider<MyAIToolCollection, MyAITool> {
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 {
@@ -72,31 +102,65 @@ export class MyAIProvider extends BaseNonAgenticProvider<MyAIToolCollection, MyA
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>;
81
- }
120
+ },
121
+ options?: ExecuteToolFnOptions,
122
+ modifiers?: ExecuteToolModifiers
123
): Promise<string> {
124
// Use the built-in executeTool method
84
- const result = await this.executeTool(toolCall.name, {
85
- userId,
125
+ const payload: ToolExecuteParams = {
126
arguments: toolCall.arguments,
87
- });
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
96
-Agentic providers implement the `BaseAgenticProvider` abstract class:
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
99
-import { BaseAgenticProvider, Tool, ExecuteToolFn } from '@composio/core';
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 {
@@ -112,11 +176,28 @@ interface AgentToolkit {
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
116
-export class MyAgentProvider extends BaseAgenticProvider<AgentToolkit, AgentTool> {
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 {
@@ -152,6 +233,14 @@ export class MyAgentProvider extends BaseAgenticProvider<AgentToolkit, AgentTool
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({});
@@ -291,13 +380,21 @@ export class EnhancedOpenAIProvider extends OpenAIProvider {
380
381
## Example: Anthropic Claude Provider
382
294
-Here's a more complete example for Anthropic's Claude:
383
+Here's a real-world example based on the actual Anthropic provider implementation:
384
385
```typescript
297
-import { BaseNonAgenticProvider, Tool } from '@composio/core';
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
300
-interface ClaudeTool {
396
+// Define the tool format for Anthropic
397
+interface AnthropicTool {
398
name: string;
399
description: string;
400
input_schema: {
@@ -305,174 +402,268 @@ interface ClaudeTool {
402
properties: Record<string, unknown>;
403
required?: string[];
404
};
405
+ cache_control?: { type: 'ephemeral' };
406
}
407
310
-type ClaudeToolCollection = ClaudeTool[];
408
+type AnthropicToolCollection = AnthropicTool[];
409
312
-export class ClaudeProvider extends BaseNonAgenticProvider<ClaudeToolCollection, ClaudeTool> {
313
- readonly name = 'claude';
314
- private client: Anthropic;
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
316
- constructor(apiKey: string) {
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();
318
- this.client = new Anthropic({
319
- apiKey,
320
- });
435
+ this.cacheTools = options?.cacheTools ?? false;
436
}
437
323
- override wrapTool(tool: Tool): ClaudeTool {
438
+ override wrapTool(tool: Tool): AnthropicTool {
439
return {
440
name: tool.slug,
441
description: tool.description || '',
327
- input_schema: {
442
+ input_schema: (tool.inputParameters || {
443
type: 'object',
329
- properties: tool.inputParameters?.properties || {},
330
- required: tool.inputParameters?.required || [],
331
- },
444
+ properties: {},
445
+ required: [],
446
+ }) as any,
447
+ cache_control: this.cacheTools ? { type: 'ephemeral' } : undefined,
448
};
449
}
450
335
- override wrapTools(tools: Tool[]): ClaudeToolCollection {
451
+ override wrapTools(tools: Tool[]): AnthropicToolCollection {
452
return tools.map(tool => this.wrapTool(tool));
453
}
454
339
- // Helper method to create a Claude message with tools
340
- async createMessage(prompt: string, tools: ClaudeToolCollection, userId: string) {
341
- const response = await this.client.messages.create({
342
- model: 'claude-3-opus-20240229',
343
- max_tokens: 1024,
344
- system: 'You are a helpful assistant with access to tools.',
345
- messages: [{ role: 'user', content: prompt }],
346
- tools,
347
- });
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
349
- // Process tool calls if any
350
- if (
351
- response.content.some(
352
- content => content.type === 'tool_use' && 'name' in content && 'input' in content
353
- )
354
- ) {
355
- const toolResponses = await Promise.all(
356
- response.content
357
- .filter(content => content.type === 'tool_use')
358
- .map(async (content: any) => {
359
- const result = await this.executeTool(content.name, {
360
- userId,
361
- arguments: content.input,
362
- });
363
-
364
- return {
365
- type: 'tool_result',
366
- tool_use_id: content.id,
367
- content: JSON.stringify(result.data),
368
- };
369
- })
370
- );
371
-
372
- // Continue the conversation with tool results
373
- const followupResponse = await this.client.messages.create({
374
- model: 'claude-3-opus-20240229',
375
- max_tokens: 1024,
376
- system: 'You are a helpful assistant with access to tools.',
377
- messages: [
378
- { role: 'user', content: prompt },
379
- { role: 'assistant', content: response.content },
380
- { role: 'user', content: toolResponses },
381
- ],
382
- tools,
383
- });
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
385
- return followupResponse;
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
388
- return response;
523
+ return outputs.length > 0 ? [{ role: 'user', content: outputs }] : [];
524
}
525
}
526
```
527
528
## Example: LangChain Provider
529
395
-Here's an example for LangChain:
530
+Here's a real-world example based on the actual LangChain provider implementation:
531
532
```typescript
398
-import { BaseAgenticProvider, Tool, ExecuteToolFn } from '@composio/core';
399
-import { DynamicTool } from 'langchain/tools';
400
-import { ChatOpenAI } from 'langchain/chat_models/openai';
401
-import { initializeAgentExecutorWithOptions } from 'langchain/agents';
402
-
403
-interface LangChainTool extends DynamicTool {
404
- name: string;
405
- description: string;
406
- func: (input: Record<string, unknown>) => Promise<string>;
407
-}
408
-
409
-interface LangChainToolkit {
410
- tools: LangChainTool[];
411
- createExecutor: (options: { model: string }) => Promise<any>;
412
-}
413
-
414
-export class LangChainProvider extends BaseAgenticProvider<LangChainToolkit, LangChainTool> {
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
417
- override wrapTool(tool: Tool, executeToolFn: ExecuteToolFn): LangChainTool {
418
- return new DynamicTool({
419
- name: tool.slug,
420
- description: tool.description || '',
421
- func: async (input: string) => {
422
- try {
423
- // Parse input from string to object
424
- const args = typeof input === 'string' ? JSON.parse(input) : input;
425
-
426
- // Execute the tool
427
- const result = await executeToolFn(tool.slug, args);
428
-
429
- if (!result.successful) {
430
- throw new Error(result.error || 'Tool execution failed');
431
- }
432
-
433
- // Return the result
434
- return JSON.stringify(result.data);
435
- } catch (error) {
436
- return `Error: ${error.message}`;
437
- }
438
- },
439
- }) as LangChainTool;
551
+ constructor() {
552
+ super();
553
}
554
442
- override wrapTools(tools: Tool[], executeToolFn: ExecuteToolFn): LangChainToolkit {
443
- const langchainTools = tools.map(tool => this.wrapTool(tool, executeToolFn));
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
445
- return {
446
- tools: langchainTools,
447
- createExecutor: async ({ model }) => {
448
- const llm = new ChatOpenAI({
449
- modelName: model || 'gpt-4',
450
- temperature: 0,
451
- });
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
453
- return await initializeAgentExecutorWithOptions(langchainTools, llm, {
454
- agentType: 'chat-zero-shot-react-description',
455
- verbose: true,
456
- });
457
- },
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
461
- // Helper method to run the agent
462
- async runAgent(toolkit: LangChainToolkit, prompt: string, model = 'gpt-4'): Promise<string> {
463
- const executor = await toolkit.createExecutor({ model });
464
- const result = await executor.call({ input: prompt });
465
- return result.output;
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
473
-2. **Handle errors gracefully**: Catch and transform errors from tool execution
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
475
-4. **Optimize for performance**: Cache transformed tools when possible
476
-5. **Add helper methods**: Provide convenient methods for common platform-specific operations
477
-6. **Provide clear documentation**: Document your provider's unique features and usage
478
-7. **Use telemetry**: Set a meaningful provider name for telemetry insights
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