Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # OpenAI Provider |
| 2 | |
| 3 | The OpenAI Provider is the default provider for the Composio SDK. It transforms Composio tools into a format compatible with OpenAI's function calling capabilities. |
| 4 | |
| 5 | ## Overview |
| 6 | |
| 7 | The OpenAI Provider allows you to: |
| 8 | |
| 9 | 1. Format Composio tools as OpenAI function tools |
| 10 | 2. Handle tool calls from OpenAI chat completions |
| 11 | 3. Handle tool calls from the OpenAI Responses API through `OpenAIResponsesProvider` |
| 12 | |
| 13 | ## Basic Usage |
| 14 | |
| 15 | The OpenAI Provider is used by default when you initialize the Composio SDK: |
| 16 | |
| 17 | ```typescript |
| 18 | import { Composio } from '@composio/core'; |
| 19 | |
| 20 | // OpenAI Provider is used by default |
| 21 | const composio = new Composio({ |
| 22 | apiKey: 'your-composio-api-key', |
| 23 | }); |
| 24 | ``` |
| 25 | |
| 26 | You can also explicitly specify the OpenAI Provider: |
| 27 | |
| 28 | ```typescript |
| 29 | import { Composio } from '@composio/core'; |
| 30 | import { OpenAIProvider } from '@composio/openai'; |
| 31 | |
| 32 | // Explicitly specify the OpenAI Provider |
| 33 | const composio = new Composio({ |
| 34 | apiKey: 'your-composio-api-key', |
| 35 | provider: new OpenAIProvider(), |
| 36 | }); |
| 37 | ``` |
| 38 | |
| 39 | ## Getting Tools for OpenAI |
| 40 | |
| 41 | The OpenAI Provider transforms Composio tools into OpenAI function tools: |
| 42 | |
| 43 | ```typescript |
| 44 | import { Composio } from '@composio/core'; |
| 45 | import OpenAI from 'openai'; |
| 46 | |
| 47 | const composio = new Composio({ |
| 48 | apiKey: 'your-composio-api-key', |
| 49 | }); |
| 50 | |
| 51 | const openai = new OpenAI({ |
| 52 | apiKey: 'your-openai-api-key', |
| 53 | }); |
| 54 | |
| 55 | // Get GitHub tools from Composio |
| 56 | const tools = await composio.tools.get('default', { |
| 57 | toolkits: ['github'], |
| 58 | }); |
| 59 | |
| 60 | // The tools are already formatted for OpenAI |
| 61 | console.log(tools[0]); // { type: 'function', function: { name: 'GITHUB_GET_REPO', ... } } |
| 62 | |
| 63 | // Use the tools with OpenAI |
| 64 | const completion = await openai.chat.completions.create({ |
| 65 | model: 'gpt-4', |
| 66 | messages: [ |
| 67 | { role: 'system', content: 'You are a helpful assistant with GitHub tools.' }, |
| 68 | { role: 'user', content: 'Find information about the Composio SDK repository' }, |
| 69 | ], |
| 70 | tools, // Pass the tools to OpenAI |
| 71 | }); |
| 72 | ``` |
| 73 | |
| 74 | ## Handling Tool Calls from OpenAI Chat Completions |
| 75 | |
| 76 | When OpenAI's model decides to call a tool, you can use the OpenAI Provider to handle it: |
| 77 | |
| 78 | ```typescript |
| 79 | import { Composio } from '@composio/core'; |
| 80 | import { OpenAIProvider } from '@composio/openai'; |
| 81 | import OpenAI from 'openai'; |
| 82 | |
| 83 | const composio = new Composio({ |
| 84 | apiKey: 'your-composio-api-key', |
| 85 | }); |
| 86 | |
| 87 | const openai = new OpenAI({ |
| 88 | apiKey: 'your-openai-api-key', |
| 89 | }); |
| 90 | |
| 91 | // Get the OpenAI Provider |
| 92 | const openaiProvider = composio.provider as OpenAIProvider; |
| 93 | |
| 94 | // Get GitHub tools |
| 95 | const tools = await composio.tools.get('default', { |
| 96 | toolkits: ['github'], |
| 97 | }); |
| 98 | |
| 99 | // Create a chat completion |
| 100 | const completion = await openai.chat.completions.create({ |
| 101 | model: 'gpt-4', |
| 102 | messages: [ |
| 103 | { role: 'system', content: 'You are a helpful assistant with GitHub tools.' }, |
| 104 | { role: 'user', content: 'Find information about the Composio SDK repository' }, |
| 105 | ], |
| 106 | tools, |
| 107 | }); |
| 108 | |
| 109 | // Check if there are tool calls |
| 110 | if (completion.choices[0].message.tool_calls) { |
| 111 | // Handle the tool calls |
| 112 | const toolOutputs = await openaiProvider.handleToolCalls( |
| 113 | 'default', // userId |
| 114 | completion, |
| 115 | { connectedAccountId: 'connected_account_123' } // Optional |
| 116 | ); |
| 117 | |
| 118 | // Continue the conversation with the tool outputs |
| 119 | const followupCompletion = await openai.chat.completions.create({ |
| 120 | model: 'gpt-4', |
| 121 | messages: [ |
| 122 | { role: 'system', content: 'You are a helpful assistant with GitHub tools.' }, |
| 123 | { role: 'user', content: 'Find information about the Composio SDK repository' }, |
| 124 | completion.choices[0].message, |
| 125 | ...toolOutputs, |
| 126 | ], |
| 127 | tools, |
| 128 | }); |
| 129 | |
| 130 | console.log(followupCompletion.choices[0].message.content); |
| 131 | } |
| 132 | ``` |
| 133 | |
| 134 | ## Working with OpenAI Responses |
| 135 | |
| 136 | Use `OpenAIResponsesProvider` for new agentic flows; it replaces the Assistants API, which OpenAI shut down on August 26, 2026. It formats Composio tools for the Responses API and returns `function_call_output` items that you can pass back with `previous_response_id`. |
| 137 | |
| 138 | ```typescript |
| 139 | import { Composio } from '@composio/core'; |
| 140 | import { OpenAIResponsesProvider } from '@composio/openai'; |
| 141 | import OpenAI from 'openai'; |
| 142 | |
| 143 | const composio = new Composio({ |
| 144 | apiKey: 'your-composio-api-key', |
| 145 | provider: new OpenAIResponsesProvider(), |
| 146 | }); |
| 147 | |
| 148 | const openai = new OpenAI({ |
| 149 | apiKey: 'your-openai-api-key', |
| 150 | }); |
| 151 | |
| 152 | // Create a session for your user |
| 153 | const session = await composio.create('default'); |
| 154 | const tools = await session.tools(); |
| 155 | |
| 156 | let response = await openai.responses.create({ |
| 157 | model: 'gpt-5', |
| 158 | tools, |
| 159 | input: 'Find information about the Composio SDK repository', |
| 160 | }); |
| 161 | |
| 162 | while (response.output.some(item => item.type === 'function_call')) { |
| 163 | const toolOutputs = await composio.provider.handleResponse(session, response); |
| 164 | response = await openai.responses.create({ |
| 165 | model: 'gpt-5', |
| 166 | tools, |
| 167 | previous_response_id: response.id, |
| 168 | input: toolOutputs, |
| 169 | }); |
| 170 | } |
| 171 | |
| 172 | console.log(response.output_text); |
| 173 | ``` |
| 174 | |
| 175 | ## Modifiers with OpenAI Provider |
| 176 | |
| 177 | You can use modifiers with the OpenAI Provider to transform tools and tool execution: |
| 178 | |
| 179 | ```typescript |
| 180 | import { Composio } from '@composio/core'; |
| 181 | import { OpenAIProvider } from '@composio/openai'; |
| 182 | |
| 183 | const composio = new Composio({ |
| 184 | apiKey: 'your-composio-api-key', |
| 185 | }); |
| 186 | |
| 187 | // Get GitHub tools with modifiers |
| 188 | const tools = await composio.tools.get( |
| 189 | 'default', |
| 190 | { |
| 191 | toolkits: ['github'], |
| 192 | }, |
| 193 | { |
| 194 | // Modify tool schema |
| 195 | modifySchema: (toolSlug, toolkitSlug, tool) => { |
| 196 | // Make tool descriptions more concise for OpenAI |
| 197 | if (tool.description && tool.description.length > 100) { |
| 198 | tool.description = tool.description.substring(0, 100) + '...'; |
| 199 | } |
| 200 | return tool; |
| 201 | }, |
| 202 | |
| 203 | // Modify parameters before execution |
| 204 | beforeExecute: ({ toolSlug, toolkitSlug, params }) => { |
| 205 | console.log(`Executing ${toolSlug} tool`); |
| 206 | return params; |
| 207 | }, |
| 208 | |
| 209 | // Transform results after execution |
| 210 | afterExecute: ({ toolSlug, toolkitSlug, result }) => { |
| 211 | // Format the result data for better presentation |
| 212 | if (result.successful && toolSlug === 'GITHUB_GET_REPO') { |
| 213 | result.data = { |
| 214 | name: result.data.name, |
| 215 | description: result.data.description, |
| 216 | stars: result.data.stargazers_count, |
| 217 | forks: result.data.forks_count, |
| 218 | url: result.data.html_url, |
| 219 | }; |
| 220 | } |
| 221 | return result; |
| 222 | }, |
| 223 | } |
| 224 | ); |
| 225 | ``` |
| 226 | |
| 227 | ## Type Definitions |
| 228 | |
| 229 | The OpenAI Provider exports these types: |
| 230 | |
| 231 | ```typescript |
| 232 | // OpenAI tool type (matches OpenAI's API) |
| 233 | type OpenAiTool = OpenAI.ChatCompletionTool; |
| 234 | |
| 235 | // Collection of OpenAI tools |
| 236 | type OpenAiToolCollection = Array<OpenAiTool>; |
| 237 | |
| 238 | // The provider class |
| 239 | class OpenAIProvider extends BaseNonAgenticProvider<OpenAiToolCollection, OpenAiTool> { |
| 240 | readonly name = 'openai'; |
| 241 | |
| 242 | wrapTool(tool: Tool): OpenAiTool; |
| 243 | wrapTools(tools: Tool[]): OpenAiToolCollection; |
| 244 | |
| 245 | executeToolCall( |
| 246 | userId: string, |
| 247 | tool: OpenAI.ChatCompletionMessageToolCall, |
| 248 | options?: ExecuteToolFnOptions, |
| 249 | modifiers?: ExecuteToolModifiers |
| 250 | ): Promise<string>; |
| 251 | |
| 252 | handleToolCalls( |
| 253 | userId: string, |
| 254 | chatCompletion: OpenAI.ChatCompletion, |
| 255 | options?: ExecuteToolFnOptions, |
| 256 | modifiers?: ExecuteToolModifiers |
| 257 | ): Promise<OpenAI.ChatCompletionToolMessageParam[]>; |
| 258 | } |
| 259 | |
| 260 | // The tool type for the Responses API |
| 261 | // (the Responses provider's OpenAiTool is OpenAI.Responses.FunctionTool) |
| 262 | type ResponsesTool = OpenAI.Responses.FunctionTool; |
| 263 | |
| 264 | // The provider class for the Responses API |
| 265 | // (OpenAIResponsesProvider re-exports from '@composio/openai') |
| 266 | class OpenAIResponsesProvider extends BaseNonAgenticProvider< |
| 267 | ResponsesTool[], |
| 268 | ResponsesTool |
| 269 | > { |
| 270 | readonly name = 'openai'; |
| 271 | |
| 272 | wrapTool(tool: Tool): ResponsesTool; |
| 273 | wrapTools(tools: Tool[]): ResponsesTool[]; |
| 274 | |
| 275 | executeToolCall( |
| 276 | userId: string, |
| 277 | tool: OpenAI.Responses.ResponseFunctionToolCall, |
| 278 | options?: ExecuteToolFnOptions, |
| 279 | modifiers?: ExecuteToolModifiers |
| 280 | ): Promise<string>; |
| 281 | |
| 282 | handleToolCalls( |
| 283 | userId: string, |
| 284 | toolCalls: OpenAI.Responses.ResponseOutputItem[], |
| 285 | options?: ExecuteToolFnOptions, |
| 286 | modifiers?: ExecuteToolModifiers |
| 287 | ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>; |
| 288 | |
| 289 | handleResponse( |
| 290 | userId: string, |
| 291 | response: OpenAI.Responses.Response, |
| 292 | options?: ExecuteToolFnOptions, |
| 293 | modifiers?: ExecuteToolModifiers |
| 294 | ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>; |
| 295 | } |
| 296 | ``` |
| 297 | |
| 298 | Like the chat completions provider, the Responses provider also accepts a |
| 299 | `ToolCallSession` as the execution target, and it can wrap MCP servers for the |
| 300 | Responses API via `wrapMcpServerResponse`. See |
| 301 | `ts/packages/providers/openai/src/OpenAIResponsesProvider.ts` for the full |
| 302 | surface. |