@devries-cameron20 / composio-1 / commits / 4b6b28486
Fork 0

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