@devries-cameron20 / composio Mirror · read-only
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
md 262 lines 7.03 KB
Rendered Raw
1 # Providers API
2
3 Providers are adapters that allow Composio tools to be used with different AI platforms. The SDK comes with a default OpenAI provider and supports creating custom providers.
4
5 ## Base Provider Classes
6
7 Composio provides abstract base classes for creating providers:
8
9 ### BaseComposioProvider
10
11 The base type for all providers:
12
13 ```typescript
14 type BaseComposioProvider<TToolCollection, TTool> =
15 | BaseNonAgenticProvider<TToolCollection, TTool>
16 | BaseAgenticProvider<TToolCollection, TTool>;
17 ```
18
19 ### BaseNonAgenticProvider
20
21 Base class for non-agentic providers (those that don't have their own agency/autonomy):
22
23 ```typescript
24 abstract class BaseNonAgenticProvider<TToolCollection, TTool> extends BaseProvider {
25 readonly _isAgentic = false;
26
27 // Wrap a tool in the provider specific format
28 abstract wrapTool(tool: Tool): TTool;
29
30 // Wrap a list of tools in the provider specific format
31 abstract wrapTools(tools: Tool[]): TToolCollection;
32 }
33 ```
34
35 ### BaseAgenticProvider
36
37 Base class for agentic providers (those with their own agency/autonomy):
38
39 ```typescript
40 abstract class BaseAgenticProvider<TToolCollection, TTool> extends BaseProvider {
41 readonly _isAgentic = true;
42
43 // Wrap a tool in the provider specific format
44 abstract wrapTool(tool: Tool, executeTool: ExecuteToolFn): TTool;
45
46 // Wrap a list of tools in the provider specific format
47 abstract wrapTools(tools: Tool[], executeTool: ExecuteToolFn): TToolCollection;
48 }
49 ```
50
51 ## OpenAI Provider
52
53 The default provider for Composio SDK is the OpenAI Provider, which formats tools for use with OpenAI's API.
54
55 ```typescript
56 import { Composio } from '@composio/core';
57 import { OpenAIProvider } from '@composio/openai';
58
59 const composio = new Composio({
60 apiKey: 'your-api-key',
61 provider: new OpenAIProvider(),
62 });
63 ```
64
65 ### Methods
66
67 #### wrapTool(tool)
68
69 Transforms a Composio tool into an OpenAI function tool format.
70
71 ```typescript
72 const openaiTool = openaiProvider.wrapTool(composioTool);
73 ```
74
75 **Parameters:**
76
77 - `tool` (Tool): The Composio tool to transform
78
79 **Returns:** OpenAI.ChatCompletionTool - The tool in OpenAI format
80
81 #### wrapTools(tools)
82
83 Transforms a list of Composio tools into an array of OpenAI function tools.
84
85 ```typescript
86 const openaiTools = openaiProvider.wrapTools(composioTools);
87 ```
88
89 **Parameters:**
90
91 - `tools` (Tool[]): The list of Composio tools to transform
92
93 **Returns:** Array<OpenAI.ChatCompletionTool> - The tools in OpenAI format
94
95 #### executeToolCall(userId, tool, options?, modifiers?)
96
97 Executes a tool call from an OpenAI chat completion.
98
99 ```typescript
100 const result = await openaiProvider.executeToolCall(
101 'user123',
102 toolCall,
103 { connectedAccountId: 'conn_abc123' },
104 {
105 beforeExecute: ({ toolSlug, toolkitSlug, params }) => params,
106 afterExecute: ({ toolSlug, toolkitSlug, result }) => result,
107 }
108 );
109 ```
110
111 **Parameters:**
112
113 - `userId` (string): The user ID
114 - `tool` (OpenAI.ChatCompletionMessageToolCall): The tool call from OpenAI
115 - `options` (ExecuteToolFnOptions): Optional parameters for tool execution
116 - `modifiers` (ExecuteToolModifiers): Optional modifiers for request/response transformation
117
118 **Returns:** Promise<string> - The result of the tool call as JSON string
119
120 #### handleToolCalls(userId, chatCompletion, options?, modifiers?)
121
122 Handles tool calls from an OpenAI chat completion.
123
124 ```typescript
125 const outputs = await openaiProvider.handleToolCalls('user123', chatCompletion);
126 ```
127
128 **Parameters:**
129
130 - `userId` (string): The user ID
131 - `chatCompletion` (OpenAI.ChatCompletion): The chat completion containing tool calls
132 - `options` (ExecuteToolFnOptions): Optional parameters for tool execution
133 - `modifiers` (ExecuteToolModifiers): Optional modifiers for request/response transformation
134
135 **Returns:** Promise<OpenAI.ChatCompletionToolMessageParam[]> - The results of the tool calls
136
137 ### OpenAIResponsesProvider
138
139 OpenAI shut down the Assistants API on August 26, 2026, and the SDK no longer ships its helpers (`handleAssistantMessage`, `waitAndHandleAssistantToolCalls`, `waitAndHandleAssistantStreamToolCalls`). Use `OpenAIResponsesProvider` from `@composio/openai` with the [Responses API](https://developers.openai.com/api/docs/assistants/migration) instead.
140
141 ```typescript
142 import { Composio } from '@composio/core';
143 import { OpenAIResponsesProvider } from '@composio/openai';
144 import OpenAI from 'openai';
145
146 const openai = new OpenAI();
147 const composio = new Composio({ provider: new OpenAIResponsesProvider() });
148 const session = await composio.create('user123');
149 const tools = await session.tools();
150
151 const response = await openai.responses.create({
152 model: 'gpt-5',
153 input: 'Star the composiohq/composio repository on GitHub',
154 tools,
155 });
156 const toolOutputs = await composio.provider.handleResponse(session, response);
157 ```
158
159 `executeToolCall`, `handleToolCalls`, and `handleResponse` take the session that produced the tools, or a user ID for tools fetched with `tools.get()`. They return `function_call_output` items to send back with `previous_response_id`.
160
161 ## Creating Custom Providers
162
163 You can create custom providers by extending either `BaseNonAgenticProvider` or `BaseAgenticProvider`:
164
165 ```typescript
166 import { BaseNonAgenticProvider, Tool } from '@composio/core';
167
168 type AnthropicTool = {
169 name: string;
170 description: string;
171 parameters: Record<string, unknown>;
172 };
173
174 type AnthropicToolCollection = AnthropicTool[];
175
176 export class AnthropicProvider extends BaseNonAgenticProvider<
177 AnthropicToolCollection,
178 AnthropicTool
179 > {
180 readonly name = 'anthropic';
181
182 override wrapTool(tool: Tool): AnthropicTool {
183 return {
184 name: tool.slug,
185 description: tool.description || '',
186 parameters: tool.inputParameters || {},
187 };
188 }
189
190 override wrapTools(tools: Tool[]): AnthropicToolCollection {
191 return tools.map(tool => this.wrapTool(tool));
192 }
193
194 // Additional methods for handling Anthropic-specific functionality
195 }
196 ```
197
198 ## Types
199
200 ### ExecuteToolFn
201
202 ```typescript
203 type ExecuteToolFn = (
204 toolSlug: string,
205 input: Record<string, unknown>
206 ) => Promise<ToolExecuteResponse>;
207 ```
208
209 ### ExecuteToolFnOptions
210
211 ```typescript
212 interface ExecuteToolFnOptions {
213 connectedAccountId?: string;
214 customAuthParams?: CustomAuthParams;
215 }
216 ```
217
218 ### ExecuteToolModifiers
219
220 ```typescript
221 interface ExecuteToolModifiers {
222 beforeExecute?: beforeExecuteModifier;
223 afterExecute?: afterExecuteModifier;
224 }
225 ```
226
227 ### TransformToolSchemaModifier
228
229 ```typescript
230 type TransformToolSchemaModifier = (toolSlug: string, toolkitSlug: string, tool: Tool) => Tool;
231 ```
232
233 ### beforeExecuteModifier
234
235 ```typescript
236 type beforeExecuteModifier = (
237 toolSlug: string,
238 toolkitSlug: string,
239 params: ToolExecuteParams
240 ) => ToolExecuteParams;
241 ```
242
243 ### afterExecuteModifier
244
245 ```typescript
246 type afterExecuteModifier = (
247 toolSlug: string,
248 toolkitSlug: string,
249 result: ToolExecuteResponse
250 ) => ToolExecuteResponse;
251 ```
252
253 // Get tools with filters
254 const githubTools = await composio.tools.getRawComposioTools({
255 toolkits: ['github'],
256 });
257
258 // Get tools with schema transformation
259 const tools = await composio.tools.getRawComposioTools({}, (toolSlug, toolkitSlug, tool) => {
260 // Add custom properties to tool schema
261 return { ...tool, customProperty: 'value' };
262 });