Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 06:00 UTC
| 1 | # Creating Custom Providers |
| 2 | |
| 3 | Composio SDK allows you to create custom providers to integrate with different AI platforms and frameworks. This guide explains how to create custom providers for both agentic and non-agentic platforms. |
| 4 | |
| 5 | ## Provider Types |
| 6 | |
| 7 | Composio supports two types of providers: |
| 8 | |
| 9 | 1. **Non-Agentic Providers**: For platforms where the provider simply formats tools but doesn't have its own agency (e.g., OpenAI). |
| 10 | 2. **Agentic Providers**: For platforms where the provider has its own agency and can execute tools autonomously (e.g., an agent framework). |
| 11 | |
| 12 | ## Creating a Non-Agentic Provider |
| 13 | |
| 14 | Non-agentic providers extend the `BaseNonAgenticProvider` class: |
| 15 | |
| 16 | ```typescript |
| 17 | import { BaseNonAgenticProvider, Tool } from '@composio/core'; |
| 18 | |
| 19 | // Define the tool type for your provider |
| 20 | type AnthropicTool = { |
| 21 | name: string; |
| 22 | description: string; |
| 23 | parameters: Record<string, unknown>; |
| 24 | }; |
| 25 | |
| 26 | // Define the collection type for your provider |
| 27 | type AnthropicToolCollection = AnthropicTool[]; |
| 28 | |
| 29 | // Create the provider class |
| 30 | export class AnthropicProvider extends BaseNonAgenticProvider< |
| 31 | AnthropicToolCollection, |
| 32 | AnthropicTool |
| 33 | > { |
| 34 | // Define the provider name (used for telemetry) |
| 35 | readonly name = 'anthropic'; |
| 36 | |
| 37 | // Implement the wrapTool method |
| 38 | override wrapTool(tool: Tool): AnthropicTool { |
| 39 | return { |
| 40 | name: tool.slug, |
| 41 | description: tool.description || '', |
| 42 | parameters: tool.inputParameters || {}, |
| 43 | }; |
| 44 | } |
| 45 | |
| 46 | // Implement the wrapTools method |
| 47 | override wrapTools(tools: Tool[]): AnthropicToolCollection { |
| 48 | return tools.map(tool => this.wrapTool(tool)); |
| 49 | } |
| 50 | |
| 51 | // Add provider-specific methods |
| 52 | async handleToolUsage(userId: string, toolName: string, params: Record<string, unknown>) { |
| 53 | const result = await this.executeTool(toolName, { |
| 54 | userId, |
| 55 | arguments: params, |
| 56 | }); |
| 57 | |
| 58 | return JSON.stringify(result); |
| 59 | } |
| 60 | } |
| 61 | ``` |
| 62 | |
| 63 | ## Creating an Agentic Provider |
| 64 | |
| 65 | Agentic providers extend the `BaseAgenticProvider` class: |
| 66 | |
| 67 | ```typescript |
| 68 | import { BaseAgenticProvider, Tool, ExecuteToolFn } from '@composio/core'; |
| 69 | |
| 70 | // Define the tool type for your provider |
| 71 | type LangchainTool = { |
| 72 | name: string; |
| 73 | description: string; |
| 74 | func: Function; |
| 75 | }; |
| 76 | |
| 77 | // Define the collection type for your provider |
| 78 | type LangchainToolCollection = { |
| 79 | tools: LangchainTool[]; |
| 80 | executor: (tool: LangchainTool, input: Record<string, unknown>) => Promise<unknown>; |
| 81 | }; |
| 82 | |
| 83 | // Create the provider class |
| 84 | export class LangchainProvider extends BaseAgenticProvider<LangchainToolCollection, LangchainTool> { |
| 85 | // Define the provider name (used for telemetry) |
| 86 | readonly name = 'langchain'; |
| 87 | |
| 88 | // Implement the wrapTool method (note the executeToolFn parameter) |
| 89 | override wrapTool(tool: Tool, executeToolFn: ExecuteToolFn): LangchainTool { |
| 90 | return { |
| 91 | name: tool.slug, |
| 92 | description: tool.description || '', |
| 93 | func: async (input: Record<string, unknown>) => { |
| 94 | const result = await executeToolFn(tool.slug, input); |
| 95 | return result.data; |
| 96 | }, |
| 97 | }; |
| 98 | } |
| 99 | |
| 100 | // Implement the wrapTools method (note the executeToolFn parameter) |
| 101 | override wrapTools(tools: Tool[], executeToolFn: ExecuteToolFn): LangchainToolCollection { |
| 102 | const langchainTools = tools.map(tool => this.wrapTool(tool, executeToolFn)); |
| 103 | |
| 104 | return { |
| 105 | tools: langchainTools, |
| 106 | executor: async (tool, input) => { |
| 107 | return await tool.func(input); |
| 108 | }, |
| 109 | }; |
| 110 | } |
| 111 | |
| 112 | // Add provider-specific methods |
| 113 | async createAgent(tools: LangchainToolCollection, model: any) { |
| 114 | // Create a Langchain agent with the tools |
| 115 | // This is just an example, the actual implementation would depend on the Langchain API |
| 116 | return { |
| 117 | run: async (prompt: string) => { |
| 118 | // Run the agent with the prompt |
| 119 | // The agent would use the tools.executor to execute tools |
| 120 | }, |
| 121 | }; |
| 122 | } |
| 123 | } |
| 124 | ``` |
| 125 | |
| 126 | ## Using a Custom Provider |
| 127 | |
| 128 | Once you've created a custom provider, you can use it with the Composio SDK: |
| 129 | |
| 130 | ```typescript |
| 131 | import { Composio } from '@composio/core'; |
| 132 | import { AnthropicProvider } from './providers/anthropic-provider'; |
| 133 | |
| 134 | // Create an instance of your custom provider |
| 135 | const anthropicProvider = new AnthropicProvider(); |
| 136 | |
| 137 | // Initialize Composio with your custom provider |
| 138 | const composio = new Composio({ |
| 139 | apiKey: 'your-composio-api-key', |
| 140 | provider: anthropicProvider, |
| 141 | }); |
| 142 | |
| 143 | // Get tools using your custom provider |
| 144 | const tools = await composio.tools.get('default', { |
| 145 | toolkits: ['github'], |
| 146 | }); |
| 147 | |
| 148 | // Now you can use these tools with Anthropic's API |
| 149 | // The tools will be formatted according to your provider's implementation |
| 150 | ``` |
| 151 | |
| 152 | ## Provider Methods |
| 153 | |
| 154 | ### Common Methods |
| 155 | |
| 156 | Both types of providers have these methods available: |
| 157 | |
| 158 | #### executeTool(toolSlug, body, modifiers?) |
| 159 | |
| 160 | Executes a tool using the global execute function. This is useful for implementing provider-specific helper methods that need to execute tools. |
| 161 | |
| 162 | ```typescript |
| 163 | async executeTool( |
| 164 | toolSlug: string, |
| 165 | body: ToolExecuteParams, |
| 166 | modifiers?: ExecuteToolModifiers |
| 167 | ): Promise<ToolExecuteResponse>; |
| 168 | ``` |
| 169 | |
| 170 | Example: |
| 171 | |
| 172 | ```typescript |
| 173 | class MyProvider extends BaseNonAgenticProvider<MyToolCollection, MyTool> { |
| 174 | // Other methods... |
| 175 | |
| 176 | async executeWithContext( |
| 177 | userId: string, |
| 178 | toolSlug: string, |
| 179 | args: Record<string, unknown>, |
| 180 | context: string |
| 181 | ) { |
| 182 | // Add context to the arguments |
| 183 | const argsWithContext = { ...args, context }; |
| 184 | |
| 185 | // Execute the tool |
| 186 | return this.executeTool(toolSlug, { |
| 187 | userId, |
| 188 | arguments: argsWithContext, |
| 189 | }); |
| 190 | } |
| 191 | } |
| 192 | ``` |
| 193 | |
| 194 | ### Non-Agentic Provider Methods |
| 195 | |
| 196 | Non-agentic providers must implement these methods: |
| 197 | |
| 198 | #### wrapTool(tool) |
| 199 | |
| 200 | Transforms a Composio tool into the provider-specific format. |
| 201 | |
| 202 | ```typescript |
| 203 | wrapTool(tool: Tool): TTool; |
| 204 | ``` |
| 205 | |
| 206 | #### wrapTools(tools) |
| 207 | |
| 208 | Transforms a list of Composio tools into the provider-specific collection format. |
| 209 | |
| 210 | ```typescript |
| 211 | wrapTools(tools: Tool[]): TToolCollection; |
| 212 | ``` |
| 213 | |
| 214 | ### Agentic Provider Methods |
| 215 | |
| 216 | Agentic providers must implement these methods: |
| 217 | |
| 218 | #### wrapTool(tool, executeToolFn) |
| 219 | |
| 220 | Transforms a Composio tool into the provider-specific format, with access to an execute function. |
| 221 | |
| 222 | ```typescript |
| 223 | wrapTool(tool: Tool, executeToolFn: ExecuteToolFn): TTool; |
| 224 | ``` |
| 225 | |
| 226 | #### wrapTools(tools, executeToolFn) |
| 227 | |
| 228 | Transforms a list of Composio tools into the provider-specific collection format, with access to an execute function. |
| 229 | |
| 230 | ```typescript |
| 231 | wrapTools(tools: Tool[], executeToolFn: ExecuteToolFn): TToolCollection; |
| 232 | ``` |
| 233 | |
| 234 | ## Examples |
| 235 | |
| 236 | ### Claude Provider Example |
| 237 | |
| 238 | ```typescript |
| 239 | import { BaseNonAgenticProvider, Tool } from '@composio/core'; |
| 240 | |
| 241 | type ClaudeTool = { |
| 242 | name: string; |
| 243 | description: string; |
| 244 | input_schema: { |
| 245 | type: string; |
| 246 | properties: Record<string, unknown>; |
| 247 | required?: string[]; |
| 248 | }; |
| 249 | }; |
| 250 | |
| 251 | type ClaudeToolCollection = ClaudeTool[]; |
| 252 | |
| 253 | export class ClaudeProvider extends BaseNonAgenticProvider<ClaudeToolCollection, ClaudeTool> { |
| 254 | readonly name = 'claude'; |
| 255 | |
| 256 | override wrapTool(tool: Tool): ClaudeTool { |
| 257 | // Convert the input parameters to Claude's format |
| 258 | const inputSchema = { |
| 259 | type: 'object', |
| 260 | properties: tool.inputParameters?.properties || {}, |
| 261 | required: tool.inputParameters?.required || [], |
| 262 | }; |
| 263 | |
| 264 | return { |
| 265 | name: tool.slug, |
| 266 | description: tool.description || '', |
| 267 | input_schema: inputSchema, |
| 268 | }; |
| 269 | } |
| 270 | |
| 271 | override wrapTools(tools: Tool[]): ClaudeToolCollection { |
| 272 | return tools.map(tool => this.wrapTool(tool)); |
| 273 | } |
| 274 | |
| 275 | // Helper method for Claude tool execution |
| 276 | async executeClaudeTool(userId: string, toolName: string, input: Record<string, unknown>) { |
| 277 | const result = await this.executeTool(toolName, { |
| 278 | userId, |
| 279 | arguments: input, |
| 280 | }); |
| 281 | |
| 282 | return result.data; |
| 283 | } |
| 284 | } |
| 285 | ``` |
| 286 | |
| 287 | ### LangChain Provider Example |
| 288 | |
| 289 | ```typescript |
| 290 | import { BaseAgenticProvider, Tool, ExecuteToolFn } from '@composio/core'; |
| 291 | |
| 292 | // These types would match the actual LangChain API |
| 293 | type LangChainTool = { |
| 294 | name: string; |
| 295 | description: string; |
| 296 | schema: any; |
| 297 | call: (input: Record<string, unknown>) => Promise<any>; |
| 298 | }; |
| 299 | |
| 300 | type LangChainToolCollection = LangChainTool[]; |
| 301 | |
| 302 | export class LangChainProvider extends BaseAgenticProvider<LangChainToolCollection, LangChainTool> { |
| 303 | readonly name = 'langchain'; |
| 304 | |
| 305 | override wrapTool(tool: Tool, executeToolFn: ExecuteToolFn): LangChainTool { |
| 306 | return { |
| 307 | name: tool.slug, |
| 308 | description: tool.description || '', |
| 309 | schema: tool.inputParameters || {}, |
| 310 | call: async (input: Record<string, unknown>) => { |
| 311 | const result = await executeToolFn(tool.slug, input); |
| 312 | if (!result.successful) { |
| 313 | throw new Error(result.error || 'Tool execution failed'); |
| 314 | } |
| 315 | return result.data; |
| 316 | }, |
| 317 | }; |
| 318 | } |
| 319 | |
| 320 | override wrapTools(tools: Tool[], executeToolFn: ExecuteToolFn): LangChainToolCollection { |
| 321 | return tools.map(tool => this.wrapTool(tool, executeToolFn)); |
| 322 | } |
| 323 | |
| 324 | // LangChain-specific helper methods |
| 325 | createAgent(tools: LangChainToolCollection, model: any) { |
| 326 | // Implement LangChain agent creation |
| 327 | // This is just a placeholder - the actual implementation would use the LangChain API |
| 328 | } |
| 329 | } |
| 330 | ``` |
| 331 | |
| 332 | ## Advanced: Provider Context |
| 333 | |
| 334 | You can store provider-specific context or state in your provider class: |
| 335 | |
| 336 | ```typescript |
| 337 | class ProviderWithContext extends BaseNonAgenticProvider<MyToolCollection, MyTool> { |
| 338 | readonly name = 'provider-with-context'; |
| 339 | |
| 340 | // Provider-specific context |
| 341 | private cache = new Map<string, any>(); |
| 342 | private config: any; |
| 343 | |
| 344 | constructor(config: any) { |
| 345 | super(); |
| 346 | this.config = config; |
| 347 | } |
| 348 | |
| 349 | override wrapTool(tool: Tool): MyTool { |
| 350 | // Use the config when wrapping tools |
| 351 | const customizedTool = { |
| 352 | name: tool.slug, |
| 353 | description: this.config.addDescriptionPrefix |
| 354 | ? `[${this.config.descriptionPrefix}] ${tool.description}` |
| 355 | : tool.description, |
| 356 | // Other properties... |
| 357 | }; |
| 358 | |
| 359 | // Cache the tool for later use |
| 360 | this.cache.set(tool.slug, customizedTool); |
| 361 | |
| 362 | return customizedTool; |
| 363 | } |
| 364 | |
| 365 | override wrapTools(tools: Tool[]): MyToolCollection { |
| 366 | return tools.map(tool => this.wrapTool(tool)); |
| 367 | } |
| 368 | |
| 369 | // Custom method that uses the cache |
| 370 | getTool(slug: string): MyTool | undefined { |
| 371 | return this.cache.get(slug); |
| 372 | } |
| 373 | } |
| 374 | ``` |