@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, 06:00 UTC

next
md 302 lines 8.35 KB
Rendered Raw
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.