Skip to content

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 Ahamad4b6b28486ee0
diff --git a/ts/docs/advanced/custom-providers.md b/ts/docs/advanced/custom-providers.md
index 6f8f7ca15..571f2315e 100644
--- a/ts/docs/advanced/custom-providers.md
+++ b/ts/docs/advanced/custom-providers.md
@@ -7,33 +7,45 @@ This guide provides a comprehensive walkthrough of creating custom providers for
The Composio SDK uses a provider architecture to adapt tools for different AI frameworks. The provider handles:
1. **Tool Format Transformation**: Converting Composio tools into formats compatible with specific AI platforms
-2. **Tool Execution**: Managing the flow of tool execution and results
+2. **Tool Execution**: Managing the flow of tool execution and results through the `executeTool` method
3. **Platform-Specific Integration**: Providing helper methods for seamless integration
+4. **MCP Server Support**: Optional transformation of MCP server responses
## Types of Providers
There are two types of providers:
-1. **Non-Agentic Providers**: Transform tools for platforms that don't have their own agency (e.g., OpenAI)
-2. **Agentic Providers**: Transform tools for platforms that have their own agency (e.g., LangChain, AutoGPT)
+1. **Non-Agentic Providers**: Transform tools for platforms that don't have their own agency (e.g., OpenAI, Anthropic, Google)
+2. **Agentic Providers**: Transform tools for platforms that have their own agency (e.g., LangChain)
## Provider Class Hierarchy
```
-BaseProvider (Abstract)
-├── BaseNonAgenticProvider (Abstract)
-│ └── OpenAIProvider (Concrete)
+BaseProvider<TMcpResponse> (Abstract)
+├── BaseNonAgenticProvider<TToolCollection, TTool, TMcpResponse> (Abstract)
+│ ├── OpenAIProvider (Concrete - ships with @composio/core)
+│ ├── AnthropicProvider (Concrete - @composio/anthropic)
+│ ├── GoogleProvider (Concrete - @composio/google)
│ └── [Your Custom Non-Agentic Provider] (Concrete)
-└── BaseAgenticProvider (Abstract)
+└── BaseAgenticProvider<TToolCollection, TTool, TMcpResponse> (Abstract)
+ ├── LangchainProvider (Concrete - @composio/langchain)
└── [Your Custom Agentic Provider] (Concrete)
```
## Creating a Non-Agentic Provider
-Non-agentic providers implement the `BaseNonAgenticProvider` abstract class:
+Non-agentic providers extend the `BaseNonAgenticProvider` abstract class. Here's how to create one:
```typescript
-import { BaseNonAgenticProvider, Tool } from '@composio/core';
+import {
+ BaseNonAgenticProvider,
+ Tool,
+ ToolExecuteParams,
+ ExecuteToolModifiers,
+ ExecuteToolFnOptions,
+ McpUrlResponse,
+ McpServerGetResponse,
+} from '@composio/core';
// Define your tool format
interface MyAITool {
@@ -49,11 +61,29 @@ interface MyAITool {
// Define your tool collection format
type MyAIToolCollection = MyAITool[];
+// Optional: Define custom MCP response format
+type MyAIMcpResponse = {
+ url: string;
+ name: string;
+ type: 'url';
+}[];
+
// Create your provider
-export class MyAIProvider extends BaseNonAgenticProvider<MyAIToolCollection, MyAITool> {
+export class MyAIProvider extends BaseNonAgenticProvider<
+ MyAIToolCollection,
+ MyAITool,
+ MyAIMcpResponse
+> {
// Required: Unique provider name for telemetry
readonly name = 'my-ai-platform';
+ /**
+ * Creates a new instance of MyAIProvider.
+ */
+ constructor() {
+ super();
+ }
+
// Required: Method to transform a single tool
override wrapTool(tool: Tool): MyAITool {
return {
@@ -72,31 +102,65 @@ export class MyAIProvider extends BaseNonAgenticProvider<MyAIToolCollection, MyA
return tools.map(tool => this.wrapTool(tool));
}
+ // Optional: Transform MCP server responses to your format
+ wrapMcpServerResponse(data: McpUrlResponse): MyAIMcpResponse {
+ return data.map(item => ({
+ url: item.url,
+ name: item.name,
+ type: 'url',
+ }));
+ }
+
// Optional: Custom helper methods for your AI platform
async executeMyAIToolCall(
userId: string,
toolCall: {
name: string;
arguments: Record<string, unknown>;
- }
+ },
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
): Promise<string> {
// Use the built-in executeTool method
- const result = await this.executeTool(toolCall.name, {
- userId,
+ const payload: ToolExecuteParams = {
arguments: toolCall.arguments,
- });
+ connectedAccountId: options?.connectedAccountId,
+ customAuthParams: options?.customAuthParams,
+ customConnectionData: options?.customConnectionData,
+ userId: userId,
+ };
+ const result = await this.executeTool(toolCall.name, payload, modifiers);
return JSON.stringify(result.data);
}
+
+ // Optional: Handle multiple tool calls from your AI platform
+ async handleMyAIToolCalls(
+ userId: string,
+ toolCalls: Array<{ name: string; arguments: Record<string, unknown> }>,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
+ ): Promise<string[]> {
+ const results = await Promise.all(
+ toolCalls.map(toolCall => this.executeMyAIToolCall(userId, toolCall, options, modifiers))
+ );
+ return results;
+ }
}
```
## Creating an Agentic Provider
-Agentic providers implement the `BaseAgenticProvider` abstract class:
+Agentic providers extend the `BaseAgenticProvider` abstract class. The key difference is that agentic providers receive an `ExecuteToolFn` to handle tool execution:
```typescript
-import { BaseAgenticProvider, Tool, ExecuteToolFn } from '@composio/core';
+import {
+ BaseAgenticProvider,
+ Tool,
+ ExecuteToolFn,
+ McpUrlResponse,
+ McpServerGetResponse,
+} from '@composio/core';
// Define your tool format
interface AgentTool {
@@ -112,11 +176,28 @@ interface AgentToolkit {
createAgent: (config: Record<string, unknown>) => unknown;
}
+// Optional: Define custom MCP response format
+type MyAgentMcpResponse = {
+ url: URL;
+ name: string;
+}[];
+
// Create your provider
-export class MyAgentProvider extends BaseAgenticProvider<AgentToolkit, AgentTool> {
+export class MyAgentProvider extends BaseAgenticProvider<
+ AgentToolkit,
+ AgentTool,
+ MyAgentMcpResponse
+> {
// Required: Unique provider name for telemetry
readonly name = 'my-agent-platform';
+ /**
+ * Creates a new instance of MyAgentProvider.
+ */
+ constructor() {
+ super();
+ }
+
// Required: Method to transform a single tool with execute function
override wrapTool(tool: Tool, executeToolFn: ExecuteToolFn): AgentTool {
return {
@@ -152,6 +233,14 @@ export class MyAgentProvider extends BaseAgenticProvider<AgentToolkit, AgentTool
};
}
+ // Optional: Transform MCP server responses to your format
+ wrapMcpServerResponse(data: McpUrlResponse): MyAgentMcpResponse {
+ return data.map(item => ({
+ url: new URL(item.url),
+ name: item.name,
+ }));
+ }
+
// Optional: Custom helper methods for your agent platform
async runAgent(agentToolkit: AgentToolkit, prompt: string): Promise<unknown> {
const agent = agentToolkit.createAgent({});
@@ -291,13 +380,21 @@ export class EnhancedOpenAIProvider extends OpenAIProvider {
## Example: Anthropic Claude Provider
-Here's a more complete example for Anthropic's Claude:
+Here's a real-world example based on the actual Anthropic provider implementation:
```typescript
-import { BaseNonAgenticProvider, Tool } from '@composio/core';
+import {
+ BaseNonAgenticProvider,
+ Tool,
+ ToolExecuteParams,
+ ExecuteToolModifiers,
+ ExecuteToolFnOptions,
+ McpUrlResponse,
+} from '@composio/core';
import Anthropic from '@anthropic-ai/sdk';
-interface ClaudeTool {
+// Define the tool format for Anthropic
+interface AnthropicTool {
name: string;
description: string;
input_schema: {
@@ -305,174 +402,268 @@ interface ClaudeTool {
properties: Record<string, unknown>;
required?: string[];
};
+ cache_control?: { type: 'ephemeral' };
}
-type ClaudeToolCollection = ClaudeTool[];
+type AnthropicToolCollection = AnthropicTool[];
-export class ClaudeProvider extends BaseNonAgenticProvider<ClaudeToolCollection, ClaudeTool> {
- readonly name = 'claude';
- private client: Anthropic;
+// Define tool use block type
+interface AnthropicToolUseBlock {
+ type: 'tool_use';
+ id: string;
+ name: string;
+ input: Record<string, unknown>;
+}
- constructor(apiKey: string) {
+// Define custom MCP response format for Anthropic
+type AnthropicMcpServerGetResponse = {
+ type: 'url';
+ url: string;
+ name: string;
+}[];
+
+export class AnthropicProvider extends BaseNonAgenticProvider<
+ AnthropicToolCollection,
+ AnthropicTool,
+ AnthropicMcpServerGetResponse
+> {
+ readonly name = 'anthropic';
+ private cacheTools: boolean = false;
+
+ constructor(options?: { cacheTools?: boolean }) {
super();
- this.client = new Anthropic({
- apiKey,
- });
+ this.cacheTools = options?.cacheTools ?? false;
}
- override wrapTool(tool: Tool): ClaudeTool {
+ override wrapTool(tool: Tool): AnthropicTool {
return {
name: tool.slug,
description: tool.description || '',
- input_schema: {
+ input_schema: (tool.inputParameters || {
type: 'object',
- properties: tool.inputParameters?.properties || {},
- required: tool.inputParameters?.required || [],
- },
+ properties: {},
+ required: [],
+ }) as any,
+ cache_control: this.cacheTools ? { type: 'ephemeral' } : undefined,
};
}
- override wrapTools(tools: Tool[]): ClaudeToolCollection {
+ override wrapTools(tools: Tool[]): AnthropicToolCollection {
return tools.map(tool => this.wrapTool(tool));
}
- // Helper method to create a Claude message with tools
- async createMessage(prompt: string, tools: ClaudeToolCollection, userId: string) {
- const response = await this.client.messages.create({
- model: 'claude-3-opus-20240229',
- max_tokens: 1024,
- system: 'You are a helpful assistant with access to tools.',
- messages: [{ role: 'user', content: prompt }],
- tools,
- });
+ // Transform MCP URL response into Anthropic-specific format
+ wrapMcpServerResponse(data: McpUrlResponse): AnthropicMcpServerGetResponse {
+ return data.map(item => ({
+ url: item.url,
+ name: item.name,
+ type: 'url',
+ }));
+ }
- // Process tool calls if any
- if (
- response.content.some(
- content => content.type === 'tool_use' && 'name' in content && 'input' in content
- )
- ) {
- const toolResponses = await Promise.all(
- response.content
- .filter(content => content.type === 'tool_use')
- .map(async (content: any) => {
- const result = await this.executeTool(content.name, {
- userId,
- arguments: content.input,
- });
-
- return {
- type: 'tool_result',
- tool_use_id: content.id,
- content: JSON.stringify(result.data),
- };
- })
- );
-
- // Continue the conversation with tool results
- const followupResponse = await this.client.messages.create({
- model: 'claude-3-opus-20240229',
- max_tokens: 1024,
- system: 'You are a helpful assistant with access to tools.',
- messages: [
- { role: 'user', content: prompt },
- { role: 'assistant', content: response.content },
- { role: 'user', content: toolResponses },
- ],
- tools,
- });
+ // Execute a single tool call from Anthropic
+ async executeToolCall(
+ userId: string,
+ toolUse: AnthropicToolUseBlock,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
+ ): Promise<string> {
+ const payload: ToolExecuteParams = {
+ arguments: toolUse.input,
+ connectedAccountId: options?.connectedAccountId,
+ customAuthParams: options?.customAuthParams,
+ customConnectionData: options?.customConnectionData,
+ userId: userId,
+ };
+ const result = await this.executeTool(toolUse.name, payload, modifiers);
+ return JSON.stringify(result.data);
+ }
+
+ // Handle tool calls from Anthropic message response
+ async handleToolCalls(
+ userId: string,
+ message: Anthropic.Message,
+ options?: ExecuteToolFnOptions,
+ modifiers?: ExecuteToolModifiers
+ ): Promise<Anthropic.Messages.MessageParam[]> {
+ const outputs: Anthropic.Messages.ToolResultBlockParam[] = [];
+
+ // Extract tool use blocks from message content
+ const toolUseBlocks: AnthropicToolUseBlock[] = [];
+ for (const content of message.content) {
+ if (
+ typeof content === 'object' &&
+ content !== null &&
+ 'type' in content &&
+ content.type === 'tool_use' &&
+ 'id' in content &&
+ 'name' in content &&
+ 'input' in content
+ ) {
+ toolUseBlocks.push({
+ type: 'tool_use',
+ id: String(content.id),
+ name: String(content.name),
+ input: content.input as Record<string, unknown>,
+ });
+ }
+ }
- return followupResponse;
+ // Execute each tool call
+ for (const toolUse of toolUseBlocks) {
+ const toolResult = await this.executeToolCall(userId, toolUse, options, modifiers);
+ outputs.push({
+ type: 'tool_result',
+ tool_use_id: toolUse.id,
+ content: toolResult,
+ cache_control: this.cacheTools ? { type: 'ephemeral' } : undefined,
+ });
}
- return response;
+ return outputs.length > 0 ? [{ role: 'user', content: outputs }] : [];
}
}
```
## Example: LangChain Provider
-Here's an example for LangChain:
+Here's a real-world example based on the actual LangChain provider implementation:
```typescript
-import { BaseAgenticProvider, Tool, ExecuteToolFn } from '@composio/core';
-import { DynamicTool } from 'langchain/tools';
-import { ChatOpenAI } from 'langchain/chat_models/openai';
-import { initializeAgentExecutorWithOptions } from 'langchain/agents';
-
-interface LangChainTool extends DynamicTool {
- name: string;
- description: string;
- func: (input: Record<string, unknown>) => Promise<string>;
-}
-
-interface LangChainToolkit {
- tools: LangChainTool[];
- createExecutor: (options: { model: string }) => Promise<any>;
-}
-
-export class LangChainProvider extends BaseAgenticProvider<LangChainToolkit, LangChainTool> {
+import {
+ BaseAgenticProvider,
+ jsonSchemaToZodSchema,
+ Tool,
+ ExecuteToolFn,
+ McpUrlResponse,
+ McpServerGetResponse,
+} from '@composio/core';
+import { DynamicStructuredTool } from '@langchain/core/tools';
+
+export type LangChainToolCollection = Array<DynamicStructuredTool>;
+
+export class LangchainProvider extends BaseAgenticProvider<
+ LangChainToolCollection,
+ DynamicStructuredTool
+> {
readonly name = 'langchain';
- override wrapTool(tool: Tool, executeToolFn: ExecuteToolFn): LangChainTool {
- return new DynamicTool({
- name: tool.slug,
- description: tool.description || '',
- func: async (input: string) => {
- try {
- // Parse input from string to object
- const args = typeof input === 'string' ? JSON.parse(input) : input;
-
- // Execute the tool
- const result = await executeToolFn(tool.slug, args);
-
- if (!result.successful) {
- throw new Error(result.error || 'Tool execution failed');
- }
-
- // Return the result
- return JSON.stringify(result.data);
- } catch (error) {
- return `Error: ${error.message}`;
- }
- },
- }) as LangChainTool;
+ constructor() {
+ super();
}
- override wrapTools(tools: Tool[], executeToolFn: ExecuteToolFn): LangChainToolkit {
- const langchainTools = tools.map(tool => this.wrapTool(tool, executeToolFn));
+ // Transform MCP URL response into standard format
+ wrapMcpServerResponse(data: McpUrlResponse): McpServerGetResponse {
+ return data.map(item => ({
+ url: new URL(item.url),
+ name: item.name,
+ })) as McpServerGetResponse;
+ }
- return {
- tools: langchainTools,
- createExecutor: async ({ model }) => {
- const llm = new ChatOpenAI({
- modelName: model || 'gpt-4',
- temperature: 0,
- });
+ override wrapTool(tool: Tool, executeTool: ExecuteToolFn): DynamicStructuredTool {
+ const toolName = tool.slug;
+ const description = tool.description;
+ const appName = tool.toolkit?.name?.toLowerCase();
+
+ if (!appName) {
+ throw new Error('App name is not defined');
+ }
+
+ if (!tool.inputParameters) {
+ throw new Error('Tool input parameters are not defined');
+ }
- return await initializeAgentExecutorWithOptions(langchainTools, llm, {
- agentType: 'chat-zero-shot-react-description',
- verbose: true,
- });
- },
+ // Convert JSON schema to Zod schema for LangChain
+ const parameters = jsonSchemaToZodSchema(tool.inputParameters);
+
+ const func = async (...args: unknown[]): Promise<unknown> => {
+ const result = await executeTool(toolName, args[0] as Record<string, unknown>);
+ return JSON.stringify(result);
};
+
+ return new DynamicStructuredTool({
+ name: toolName,
+ description: description || '',
+ schema: parameters,
+ func: func,
+ });
}
- // Helper method to run the agent
- async runAgent(toolkit: LangChainToolkit, prompt: string, model = 'gpt-4'): Promise<string> {
- const executor = await toolkit.createExecutor({ model });
- const result = await executor.call({ input: prompt });
- return result.output;
+ override wrapTools(tools: Tool[], executeTool: ExecuteToolFn): LangChainToolCollection {
+ return tools.map(tool => this.wrapTool(tool, executeTool));
}
}
```
+### Usage with LangChain
+
+```typescript
+import { Composio } from '@composio/core';
+import { LangchainProvider } from '@composio/langchain';
+import { ChatOpenAI } from '@langchain/openai';
+import { AgentExecutor, createOpenAIFunctionsAgent } from 'langchain/agents';
+import { ChatPromptTemplate, MessagesPlaceholder } from '@langchain/core/prompts';
+
+// Initialize Composio with LangChain provider
+const composio = new Composio({
+ apiKey: 'your-composio-api-key',
+ provider: new LangchainProvider()
+});
+
+// Get tools for LangChain
+const tools = await composio.tools.get('user123', {
+ toolkits: ['github']
+});
+
+// Create LangChain agent
+const llm = new ChatOpenAI({
+ modelName: 'gpt-4',
+ temperature: 0
+});
+
+const prompt = ChatPromptTemplate.fromMessages([
+ ['system', 'You are a helpful assistant with access to GitHub tools.'],
+ ['human', '{input}'],
+ new MessagesPlaceholder('agent_scratchpad')
+]);
+
+const agent = await createOpenAIFunctionsAgent({
+ llm,
+ tools,
+ prompt
+});
+
+const agentExecutor = new AgentExecutor({
+ agent,
+ tools,
+ verbose: true
+});
+
+// Use the agent
+const result = await agentExecutor.invoke({
+ input: 'Create a new GitHub repository called "my-project"'
+});
+
+console.log(result.output);
+```
+
## Best Practices
1. **Keep providers focused**: Each provider should integrate with one specific platform
-2. **Handle errors gracefully**: Catch and transform errors from tool execution
+2. **Handle errors gracefully**: Catch and transform errors from tool execution in your helper methods
3. **Follow platform conventions**: Adopt naming and structural conventions of the target platform
-4. **Optimize for performance**: Cache transformed tools when possible
-5. **Add helper methods**: Provide convenient methods for common platform-specific operations
-6. **Provide clear documentation**: Document your provider's unique features and usage
-7. **Use telemetry**: Set a meaningful provider name for telemetry insights
+4. **Implement proper types**: Use TypeScript generics to ensure type safety for your tool formats
+5. **Add helper methods**: Provide convenient methods for common platform-specific operations like `executeToolCall` and `handleToolCalls`
+6. **Support MCP servers**: Implement `wrapMcpServerResponse` if your platform needs custom MCP server response formatting
+7. **Use the built-in executeTool method**: Always use `this.executeTool()` for tool execution rather than implementing your own
+8. **Provide clear documentation**: Document your provider's unique features and usage patterns
+9. **Use meaningful provider names**: Set a descriptive provider name for telemetry and debugging
+10. **Handle authentication properly**: Pass through `ExecuteToolFnOptions` for connected accounts and custom auth parameters
+
+## Key Implementation Notes
+
+- **Non-agentic providers** receive tools and transform them for direct use with AI platforms
+- **Agentic providers** receive both tools and an `ExecuteToolFn` to create autonomous agents
+- The `executeTool` method is injected by the Composio core and handles all authentication and execution logic
+- MCP server support is optional but recommended for providers that need custom server response formatting
+- All providers should extend the appropriate base class and implement the required abstract methods