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
| 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 | }); |