Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Fix provider docs (#1849)
Musthaq Ahamad4b6b28486ee0
diff --git a/ts/docs/advanced/custom-providers.md b/ts/docs/advanced/custom-providers.mdindex 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 forThe 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` method3. **Platform-Specific Integration**: Providing helper methods for seamless integration+4. **MCP Server Support**: Optional transformation of MCP server responses## Types of ProvidersThere 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 formatinterface MyAITool {@@ -49,11 +61,29 @@ interface MyAITool {// Define your tool collection formattype 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 telemetryreadonly name = 'my-ai-platform';+ /**+ * Creates a new instance of MyAIProvider.+ */+ constructor() {+ super();+ }+// Required: Method to transform a single tooloverride wrapTool(tool: Tool): MyAITool {return {@@ -72,31 +102,65 @@ export class MyAIProvider extends BaseNonAgenticProvider<MyAIToolCollection, MyAreturn 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 platformasync 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 formatinterface 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 telemetryreadonly name = 'my-agent-platform';+ /**+ * Creates a new instance of MyAgentProvider.+ */+ constructor() {+ super();+ }+// Required: Method to transform a single tool with execute functionoverride 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 platformasync 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 Practices1. **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 methods3. **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