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
ts 448 lines 15 KB
Raw
1 /**
2 * OpenAI Toolset
3 *
4 * Author: Musthaq Ahamad <musthaq@composio.dev>
5 * Legacy Reference: https://github.com/ComposioHQ/composio/blob/master/js/src/toolsets/openai.ts
6 *
7 * This provider provides a set of tools for interacting with OpenAI's ChatCompletions API.
8 *
9 * @packageDocumentation
10 * @module providers/openai
11 */
12 import { OpenAI } from 'openai';
13 import {
14 BaseNonAgenticProvider,
15 Tool,
16 ExecuteToolModifiers,
17 ExecuteToolFnOptions,
18 ToolCallExecutionTarget,
19 ToolCallSession,
20 McpUrlResponse,
21 normalizeToolArguments,
22 deduplicateJsonSchemaRequiredArrays,
23 omitNullToolArguments,
24 toStrictJsonSchema,
25 logger,
26 } from '@composio/core';
27
28 export type OpenAiTool = OpenAI.Responses.FunctionTool;
29
30 /** Parameters emitted for a tool without input parameters under strict mode. */
31 const EMPTY_OBJECT_SCHEMA = {
32 type: 'object',
33 properties: {},
34 required: [],
35 additionalProperties: false,
36 } as const;
37 export type OpenAiMcpTool = OpenAI.Responses.Tool.Mcp;
38 export type OpenAiToolCollection = Array<OpenAiTool>;
39 export type OpenAIResponsesProviderOptions = {
40 /**
41 * Whether to use strict mode for function calls
42 * @default false
43 */
44 strict?: boolean;
45 };
46
47 /**
48 * OpenAI-specific MCP server response format
49 */
50 export class OpenAIResponsesProvider extends BaseNonAgenticProvider<
51 OpenAiToolCollection,
52 OpenAiTool,
53 OpenAiMcpTool[]
54 > {
55 readonly name = 'openai';
56 private strict: boolean | null;
57 /**
58 * Parameter schemas of the tools wrapped under strict mode, keyed by slug,
59 * so tool-call arguments can be reconciled against the schema the model
60 * actually saw.
61 */
62 private readonly strictInputSchemas = new Map<string, Record<string, unknown>>();
63
64 /**
65 * Creates a new instance of the OpenAIProvider.
66 *
67 * This is the default provider for the Composio SDK and is automatically
68 * available without additional installation.
69 *
70 * @param {OpenAIResponsesProviderOptions} [options] - Optional provider options
71 * @returns {OpenAIResponsesProvider} The OpenAIResponsesProvider instance
72 *
73 * @example
74 * ```typescript
75 * // The OpenAIProvider is used by default when initializing Composio
76 * const composio = new Composio({
77 * apiKey: 'your-api-key'
78 * });
79 *
80 * // You can also explicitly specify it
81 * const composio = new Composio({
82 * apiKey: 'your-api-key',
83 * provider: new OpenAIResponsesProvider({
84 * strict: true // Optional, default is false
85 * })
86 * });
87 * ```
88 */
89 constructor(options?: OpenAIResponsesProviderOptions) {
90 super();
91 this.strict = options?.strict ?? false;
92 }
93
94 /**
95 * Transform MCP URL response into OpenAI Responses-specific format.
96 * OpenAI Responses uses a custom format with type, server_label, server_url, and require_approval fields.
97 *
98 * @param data - The MCP URL response data
99 * @param serverName - Name of the MCP server
100 * @returns OpenAI-specific MCP server response format
101 */
102 override wrapMcpServerResponse(data: McpUrlResponse): OpenAiMcpTool[] {
103 logger.debug(
104 `Wrapping MCP server response for ${data.length} server(s): ${data.map(server => server.name).join(', ')}`
105 );
106 return data.map(item => ({
107 type: 'mcp',
108 server_label: item.name,
109 server_url: item.url,
110 require_approval: 'never',
111 }));
112 }
113
114 /**
115 * Wraps a Composio tool in the OpenAI function calling format.
116 *
117 * This method transforms a Composio tool definition into the format
118 * expected by OpenAI's function calling API.
119 *
120 * @param tool - The Composio tool to wrap
121 * @returns The wrapped tool in OpenAI format
122 *
123 * @example
124 * ```typescript
125 * // Wrap a single tool for use with OpenAI
126 * const composioTool = {
127 * slug: 'SEARCH_TOOL',
128 * description: 'Search for information',
129 * inputParameters: {
130 * type: 'object',
131 * properties: {
132 * query: { type: 'string' }
133 * },
134 * required: ['query']
135 * }
136 * };
137 *
138 * const openAITool = provider.wrapTool(composioTool);
139 * ```
140 */
141 override wrapTool(tool: Tool): OpenAiTool {
142 const inputParams = tool.inputParameters;
143 if (!this.strict) {
144 return {
145 name: tool.slug,
146 description: tool.description,
147 // Canonicalize required arrays at the vendor-schema emission boundary.
148 parameters: deduplicateJsonSchemaRequiredArrays(
149 (inputParams ?? {}) as Record<string, unknown>
150 ),
151 strict: this.strict,
152 type: 'function',
153 };
154 }
155
156 // Structured outputs enforce their contract at every depth: all
157 // properties required, closed objects, no annotation keywords. The strict
158 // rewrite keeps every parameter (optional ones become nullable) and
159 // reports constructs it cannot express; such a tool is sent without
160 // strict mode rather than with a narrower schema.
161 const source = (inputParams ?? EMPTY_OBJECT_SCHEMA) as Record<string, unknown>;
162 const strict = toStrictJsonSchema(source);
163 if (strict.unsupported.length > 0) {
164 const reasons = strict.unsupported
165 .map(entry => `${entry.path || '<root>'}: ${entry.keyword} (${entry.detail})`)
166 .join('; ');
167 logger.warn(
168 `OpenAIResponsesProvider: tool "${tool.slug}" is sent without strict mode because its schema cannot be expressed as strict structured outputs: ${reasons}`
169 );
170 this.strictInputSchemas.delete(tool.slug);
171 return {
172 name: tool.slug,
173 description: tool.description,
174 parameters: deduplicateJsonSchemaRequiredArrays(source),
175 strict: false,
176 type: 'function',
177 };
178 }
179 if (strict.totalChanges > 0) {
180 logger.debug(
181 `OpenAIResponsesProvider: strict mode rewrote ${strict.totalChanges} node(s) of tool "${tool.slug}": ${strict.changes
182 .map(change => `${change.path}: ${change.reason}`)
183 .join('; ')}`
184 );
185 }
186 this.strictInputSchemas.set(tool.slug, strict.source);
187
188 return {
189 name: tool.slug,
190 description: tool.description,
191 parameters: strict.schema,
192 strict: true,
193 type: 'function',
194 };
195 }
196
197 /**
198 * Wraps multiple Composio tools in the OpenAI function calling format.
199 *
200 * This method transforms a list of Composio tools into the format
201 * expected by OpenAI's function calling API.
202 *
203 * @param tools - Array of Composio tools to wrap
204 * @returns Array of wrapped tools in OpenAI format
205 *
206 * @example
207 * ```typescript
208 * // Wrap multiple tools for use with OpenAI
209 * const composioTools = [
210 * {
211 * slug: 'SEARCH_TOOL',
212 * description: 'Search for information',
213 * inputParameters: {
214 * type: 'object',
215 * properties: {
216 * query: { type: 'string' }
217 * }
218 * }
219 * },
220 * {
221 * slug: 'WEATHER_TOOL',
222 * description: 'Get weather information',
223 * inputParameters: {
224 * type: 'object',
225 * properties: {
226 * location: { type: 'string' }
227 * }
228 * }
229 * }
230 * ];
231 *
232 * const openAITools = provider.wrapTools(composioTools);
233 * ```
234 */
235 override wrapTools = (tools: Tool[]): OpenAiToolCollection => {
236 return tools.map(tool => this.wrapTool(tool));
237 };
238
239 /**
240 * Executes a tool call from OpenAI's chat completion.
241 *
242 * This method processes a tool call from OpenAI's chat completion API,
243 * executes the corresponding Composio tool, and returns the result.
244 *
245 * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
246 * @param {OpenAI.ChatCompletionMessageToolCall} tool - The tool call from OpenAI
247 * @param {ExecuteToolFnOptions} [options] - Optional execution options
248 * @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
249 * @returns {Promise<string>} The result of the tool call as a JSON string
250 *
251 * @example
252 * ```typescript
253 * // Execute a tool call from OpenAI
254 * const toolCall = {
255 * id: 'call_abc123',
256 * type: 'function',
257 * function: {
258 * name: 'SEARCH_TOOL',
259 * arguments: '{"query":"composio documentation"}'
260 * }
261 * };
262 *
263 * const result = await provider.executeToolCall(
264 * 'user123',
265 * toolCall,
266 * { connectedAccountId: 'conn_xyz456' }
267 * );
268 * console.log(JSON.parse(result));
269 * ```
270 */
271 async executeToolCall(
272 session: ToolCallSession,
273 tool: OpenAI.Responses.ResponseFunctionToolCall
274 ): Promise<string>;
275 async executeToolCall(
276 userId: string,
277 tool: OpenAI.Responses.ResponseFunctionToolCall,
278 options?: ExecuteToolFnOptions,
279 modifiers?: ExecuteToolModifiers
280 ): Promise<string>;
281 async executeToolCall(
282 executionTarget: ToolCallExecutionTarget,
283 tool: OpenAI.Responses.ResponseFunctionToolCall,
284 options?: ExecuteToolFnOptions,
285 modifiers?: ExecuteToolModifiers
286 ): Promise<string> {
287 // OpenAI always serializes tool arguments as a JSON string; normalize tolerates
288 // empty / object-shaped payloads too (issue #2406).
289 const normalizedArguments = normalizeToolArguments(tool.arguments, tool.name);
290 // Under strict mode optional parameters are emitted as required-nullable,
291 // so a `null` the tool's own schema does not accept means "omitted".
292 const strictSchema = this.strictInputSchemas.get(tool.name);
293 const arguments_ = strictSchema
294 ? omitNullToolArguments(normalizedArguments, strictSchema)
295 : normalizedArguments;
296 const result = await this.executeToolForTarget(
297 executionTarget,
298 tool.name,
299 arguments_,
300 options,
301 modifiers
302 );
303 return JSON.stringify(result);
304 }
305
306 /**
307 * Handles tool calls from OpenAI's response.
308 *
309 * This method processes tool calls from an OpenAI response,
310 * executes each tool call, and returns the results.
311 *
312 * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
313 * @param {OpenAI.ChatCompletion} chatCompletion - The response from OpenAI
314 * @param {ExecuteToolFnOptions} [options] - Optional execution options
315 * @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
316 * @returns {Promise<string[]>} Array of tool execution results as JSON strings
317 *
318 * @example
319 * ```typescript
320 * // Handle tool calls from a response
321 * const response = await openai.responses.create({
322 * model: 'gpt-4o-2024-11-20',
323 * input: 'What is the capital of France?',
324 * tools: await composio.tools.get(composioTools)
325 * });
326 *
327 * const inputItems = await composio.provider.handleToolCalls(
328 * 'user123',
329 * response.output
330 * );
331 * console.log(inputItems); // Array of tool execution results
332 *
333 * // Submit tool outputs back to OpenAI
334 * const response = await openai.responses.create({
335 * model: 'gpt-4o-2024-11-20',
336 * input: inputItems,
337 * tools: await composio.tools.get(composioTools),
338 * });
339 * ```
340 * ```
341 */
342 async handleToolCalls(
343 session: ToolCallSession,
344 toolCalls: OpenAI.Responses.ResponseOutputItem[]
345 ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>;
346 async handleToolCalls(
347 userId: string,
348 toolCalls: OpenAI.Responses.ResponseOutputItem[],
349 options?: ExecuteToolFnOptions,
350 modifiers?: ExecuteToolModifiers
351 ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>;
352 async handleToolCalls(
353 executionTarget: ToolCallExecutionTarget,
354 toolCalls: OpenAI.Responses.ResponseOutputItem[],
355 options?: ExecuteToolFnOptions,
356 modifiers?: ExecuteToolModifiers
357 ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]> {
358 this.assertToolCallExecutionOptions(executionTarget, options, modifiers);
359 const toolOutputs: OpenAI.Responses.ResponseInputItem.FunctionCallOutput[] = [];
360 for (const output of toolCalls) {
361 if (output.type === 'function_call') {
362 const tool_call = {
363 id: output.id,
364 name: output.name,
365 arguments: output.arguments,
366 } as OpenAI.Responses.ResponseFunctionToolCall;
367 try {
368 const toolOutput =
369 typeof executionTarget === 'string'
370 ? await this.executeToolCall(executionTarget, tool_call, options, modifiers)
371 : await this.executeToolCall(executionTarget, tool_call);
372 toolOutputs.push({
373 call_id: output.call_id ?? '',
374 type: 'function_call_output',
375 output: toolOutput,
376 // id: output.id ?? '',
377 status: 'completed',
378 });
379 } catch (error) {
380 toolOutputs.push({
381 call_id: output.call_id ?? '',
382 type: 'function_call_output',
383 output: error instanceof Error ? error.message : 'Unknown error',
384 // id: output.id ?? '',
385 status: 'incomplete',
386 });
387 }
388 }
389 }
390 return toolOutputs;
391 }
392
393 /**
394 * Handles all the tool calls from the OpenAI Responses API.
395 *
396 * This method processes tool calls from an OpenAI Responses request,
397 * executes each tool call, and returns the tool outputs for submission.
398 *
399 * @param {string | ToolCallSession} executionTarget - A user ID for direct tools or the session that produced session tools
400 * @param {OpenAI.Responses.Response} response - The Responses request object containing tool calls
401 * @param {ExecuteToolFnOptions} [options] - Optional execution options
402 * @param {ExecuteToolModifiers} [modifiers] - Optional execution modifiers
403 * @returns {Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>} Tool outputs to send back as Responses input items
404 *
405 * @example
406 * ```typescript
407 * // Handle tool calls from an OpenAI response
408 * const response = await openai.responses.create({
409 * model: 'gpt-4o-2024-11-20',
410 * input: 'What is the capital of France?',
411 * tools: await composio.tools.get(composioTools),
412 * tool_choice: 'auto',
413 * });
414 *
415 * const inputItems = await composio.provider.handleResponse('default', response);
416 *
417 * // Submit tool outputs back to OpenAI
418 * const response = await openai.responses.create({
419 * model: 'gpt-4o-2024-11-20',
420 * input: inputItems,
421 * tools: await composio.tools.get(composioTools),
422 * });
423 * ```
424 */
425 async handleResponse(
426 session: ToolCallSession,
427 response: OpenAI.Responses.Response
428 ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>;
429 async handleResponse(
430 userId: string,
431 response: OpenAI.Responses.Response,
432 options?: ExecuteToolFnOptions,
433 modifiers?: ExecuteToolModifiers
434 ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]>;
435 async handleResponse(
436 executionTarget: ToolCallExecutionTarget,
437 response: OpenAI.Responses.Response,
438 options?: ExecuteToolFnOptions,
439 modifiers?: ExecuteToolModifiers
440 ): Promise<OpenAI.Responses.ResponseInputItem.FunctionCallOutput[]> {
441 const tool_calls = response.output?.filter(output => output.type === 'function_call') || [];
442 if (typeof executionTarget === 'string') {
443 return this.handleToolCalls(executionTarget, tool_calls, options, modifiers);
444 }
445 this.assertToolCallExecutionOptions(executionTarget, options, modifiers);
446 return this.handleToolCalls(executionTarget, tool_calls);
447 }
448 }