Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 374 lines 9.85 KB
Rendered Raw
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 ```