Composio OpenAI Provider 实战指南将 1000 工具接入 OpenAI Function Calling【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读Composio 的 OpenAI Provider 是 TypeScript SDK 的默认 Provider负责把 Composio 工具tool统一转换成 OpenAI 兼容的函数调用function calling格式并打通 Chat Completions、Assistants、流式响应三大执行路径。读完本文你将掌握如何用composio/core与composio/openai初始化 Provider、获取格式化工具、处理工具调用回执以及通过 Modifiers 对工具的 Schema 与执行过程做细粒度定制。文中所有关键结论均可在当前仓库的源码与测试中找到依据。OpenAI Provider 的定位与核心能力OpenAI Provider 是 Composio SDK 的默认 Provider。在 composio.ts 中SDK 初始化时会自动执行this.provider config?.provider ?? new OpenAIProvider()也就是说你什么都不配置SDK 也会默认使用它。其核心能力包含四部分将 Composio 工具格式化为 OpenAI 函数工具OpenAI.ChatCompletionTool处理 Chat Completions 响应中的工具调用handleToolCalls处理 OpenAI AssistantsAssistant API的工具调用处理带工具调用的流式响应。从源码结构看OpenAIProvider继承自BaseNonAgenticProviderTToolCollection, TTool见 BaseProvider.ts这意味着它是非 Agentic Provider工具由你显式传给模型工具的执行通过 SDK 注入的全局执行函数完成。它同时是composio/core内置 Provider随 SDK 一起发布无需单独安装即可使用OpenAIProvider.ts 中的注释明确说明了这一点。基础用法默认与显式两种初始化方式由于 OpenAI Provider 是默认 Provider最简单的初始化方式是直接传入 Composio API Keyimport { Composio } from composio/core; // OpenAI Provider is used by default const composio new Composio({ apiKey: your-composio-api-key, });也可以显式指定 Providerimport { Composio } from composio/core; import { OpenAIProvider } from composio/openai; // Explicitly specify the OpenAI Provider const composio new Composio({ apiKey: your-composio-api-key, provider: new OpenAIProvider(), });其中composio/openai只是对外便捷导出的封装包其源码 index.ts 只是把OpenAIProvider从composio/core重新导出因此直接使用composio/core即可无需额外引入该包。需要说明的是仓库 README.md 建议同时安装openai官方客户端库并在环境中配置COMPOSIO_API_KEY与OPENAI_API_KEY。获取 OpenAI 格式的工具composio.tools.get()返回的工具在 OpenAI Provider 下已经是标准的 OpenAI 函数工具格式可以直接透传给openai.chat.completions.create()import { Composio } from composio/core; import OpenAI from openai; const composio new Composio({ apiKey: your-composio-api-key, }); const openai new OpenAI({ apiKey: your-openai-api-key, }); // Get GitHub tools from Composio const tools await composio.tools.get(default, { toolkits: [github], }); // The tools are already formatted for OpenAI console.log(tools[0]); // { type: function, function: { name: GITHUB_GET_REPO, ... } } // Use the tools with OpenAI const completion await openai.chat.completions.create({ model: gpt-4, messages: [ { role: system, content: You are a helpful assistant with GitHub tools. }, { role: user, content: Find information about the Composio SDK repository }, ], tools, // Pass the tools to OpenAI });底层转换逻辑wrapTool 与 wrapTools工具的格式化由wrapTool/wrapTools两个方法完成实现在 OpenAIProvider.tswrapTool(tool)把单个 Composio 工具映射为{ type: function, function: { name, description, parameters } }wrapTools(tools)只是对工具数组逐个调用wrapTool并返回数组在生成parameters之前会调用deduplicateJsonSchemaRequiredArrays对 JSON Schema 的required数组做去重避免重复项引发 OpenAI 校验失败对应测试见 openai.test.ts对于没有inputParameters的工具转换后parameters保持undefined测试用例覆盖了这一边界情况openai.test.ts。处理 Chat Completions 的工具调用当模型决定调用工具时响应中的completion.choices[0].message.tool_calls会携带工具调用列表。此时使用openaiProvider.handleToolCalls()即可批量执行这些工具并得到可回填的tool消息import { Composio } from composio/core; import { OpenAIProvider } from composio/openai; import OpenAI from openai; const composio new Composio({ apiKey: your-composio-api-key, }); const openai new OpenAI({ apiKey: your-openai-api-key, }); // Get the OpenAI Provider const openaiProvider composio.provider as OpenAIProvider; // Get GitHub tools const tools await composio.tools.get(default, { toolkits: [github], }); // Create a chat completion const completion await openai.chat.completions.create({ model: gpt-4, messages: [ { role: system, content: You are a helpful assistant with GitHub tools. }, { role: user, content: Find information about the Composio SDK repository }, ], tools, }); // Check if there are tool calls if (completion.choices[0].message.tool_calls) { // Handle the tool calls const toolOutputs await openaiProvider.handleToolCalls( default, // userId completion, { connectedAccountId: connected_account_123 } // Optional ); // Continue the conversation with the tool outputs const followupCompletion await openai.chat.completions.create({ model: gpt-4, messages: [ { role: system, content: You are a helpful assistant with GitHub tools. }, { role: user, content: Find information about the Composio SDK repository }, completion.choices[0].message, ...toolOutputs, ], tools, }); console.log(followupCompletion.choices[0].message.content); }handleToolCalls 的源码级行为从 OpenAIProvider.ts 的实现可以看到几个关键设计只处理第一个 choice当n 1时只会执行chatCompletion.choices[0]中的工具调用。源码注释解释了原因——每个 choice 对应一个独立的助手回合若逐个执行所有 choice每个工具会被重复执行且属于备选完成alternative completions的tool_call_id将无人回应。测试用例 openai.test.ts 专门验证了这一点支持并行工具调用一条 assistant 消息中可以包含多个tool_callsOpenAI 默认开启 parallel tool calls每个调用都会独立执行并生成对应的{ role: tool, tool_call_id, content }结果否则下一次请求会因部分tool_call_id未得到回应而失败对应测试见 openai.test.ts非 function 类型的调用会被跳过if (toolCall.type ! function) continue;返回值为OpenAI.ChatCompletionToolMessageParam[]可直接展开到下一次请求的messages数组中。executeToolCall单次调用的执行细节handleToolCalls内部对每个调用调用executeToolCallOpenAIProvider.ts它的核心逻辑是使用normalizeToolArguments把 OpenAI 序列化好的参数字符串JSON 字符串解析为对象该函数能容忍空字符串与对象形态的载荷源码注释提到这是为 issue #2406 做的兼容处理通过executeToolForTarget路由到直接工具 API 或 Tool Router 会话执行将执行结果JSON.stringify后作为content返回。executeToolForTarget定义在 BaseProvider.ts当传入的是userId字符串时会构造{ arguments, connectedAccountId, customAuthParams, customConnectionData, userId }调用全局执行函数当传入的是会话对象时则走会话的execute方法。注意直接执行选项与 Modifiers 不能与 Tool Router 会话同时使用否则会抛出TypeError见 BaseProvider.ts。使用 OpenAI Assistants 集成 Composio 工具OpenAI Provider 为 Assistants API 提供了两个辅助方法waitAndHandleAssistantToolCalls非流式和waitAndHandleAssistantStreamToolCalls流式。完整流程如下import { Composio } from composio/core; import { OpenAIProvider } from composio/openai; import OpenAI from openai; const composio new Composio({ apiKey: your-composio-api-key, }); const openai new OpenAI({ apiKey: your-openai-api-key, }); // Get the OpenAI Provider const openaiProvider composio.provider as OpenAIProvider; // Get GitHub tools const tools await composio.tools.get(default, { toolkits: [github], }); // Create an assistant with Composio tools const assistant await openai.beta.assistants.create({ name: GitHub Assistant, instructions: You are a helpful assistant with GitHub tools., model: gpt-4, tools, }); // Create a thread const thread await openai.beta.threads.create(); // Add a message to the thread await openai.beta.threads.messages.create(thread.id, { role: user, content: Find information about the Composio SDK repository, }); // Run the assistant const run await openai.beta.threads.runs.create(thread.id, { assistant_id: assistant.id, }); // Wait for the run to complete and handle any tool calls const finalRun await openaiProvider.waitAndHandleAssistantToolCalls( default, // userId openai, run, thread, { connectedAccountId: connected_account_123 } // Optional ); // Get the assistants response const messages await openai.beta.threads.messages.list(thread.id); console.log(messages.data[0].content);waitAndHandleAssistantToolCalls 的工作原理该方法OpenAIProvider.ts维护一个轮询循环只要 run 的状态处于queued、in_progress、requires_action三者之一就持续处理。当状态为requires_action时调用handleAssistantMessage提取run.required_action.submit_tool_outputs.tool_calls逐个执行工具并把{ tool_call_id, output }通过openai.beta.threads.runs.submitToolOutputs提交回 OpenAI其他状态则每 500ms 重新拉取一次 run 状态直到 run 进入终态后返回最终的 run 对象。handleAssistantMessage的实现在 OpenAIProvider.ts它使用Promise.all并发执行全部工具调用为每个调用生成{ tool_call_id, output: JSON.stringify(tool_response) }形式的输出。若 run 中没有任何工具调用则返回空数组对应测试 openai.test.ts。处理带工具调用的流式响应对于需要实时反馈的交互场景可以使用createAndStream配合waitAndHandleAssistantStreamToolCalls后者是一个 AsyncGenerator会逐事件产出并自动处理requires_actionimport { Composio } from composio/core; import { OpenAIProvider } from composio/openai; import OpenAI from openai; const composio new Composio({ apiKey: your-composio-api-key, }); const openai new OpenAI({ apiKey: your-openai-api-key, }); // Get the OpenAI Provider const openaiProvider composio.provider as OpenAIProvider; // Get GitHub tools const tools await composio.tools.get(default, { toolkits: [github], }); // Create an assistant with Composio tools const assistant await openai.beta.assistants.create({ name: GitHub Assistant, instructions: You are a helpful assistant with GitHub tools., model: gpt-4, tools, }); // Create a thread const thread await openai.beta.threads.create(); // Add a message to the thread await openai.beta.threads.messages.create(thread.id, { role: user, content: Find information about the Composio SDK repository, }); // Run the assistant with streaming const runStream await openai.beta.threads.runs.createAndStream(thread.id, { assistant_id: assistant.id, }); // Process the stream and handle tool calls for await (const event of openaiProvider.waitAndHandleAssistantStreamToolCalls( default, // userId openai, runStream, thread, { connectedAccountId: connected_account_123 } // Optional )) { // Process different event types if (event.event thread.message.created) { console.log(New message created); } else if (event.event thread.message.delta) { console.log(Message update:, event.data.delta.content); } else if (event.event thread.run.requires_action) { console.log(Run requires action (tools being executed)); } else if (event.event thread.run.completed) { console.log(Run completed); } }流式实现的两个阶段waitAndHandleAssistantStreamToolCallsOpenAIProvider.ts分两阶段工作流式阶段for await遍历runStream的每个事件先yield事件让调用方实时处理再检查事件类型。收到thread.run.requires_action时调用handleAssistantMessage执行工具并提交输出遇到thread.run.completed / failed / cancelled / expired之一即跳出循环收尾阶段流结束后用记录的runId重新retrieverun继续轮询处理queued / in_progress / requires_action状态直到进入终态。若整个流中都没有出现过thread.run.created拿不到 runId则抛出No run ID found错误。使用 Modifiers 定制工具的 Schema 与执行Modifiers 允许在工具交付给模型之前改写其 Schema在执行前后拦截参数与结果。它们分为三类类型定义见 modifiers.types.tsmodifySchemaTransformToolSchemaModifiermodifiers.types.ts在 Schema 暴露给消费方之前做转换典型用途是精简描述、增删参数、给工具重命名等beforeExecutemodifiers.types.ts在执行前拦截并修改params如注入自定义认证参数、转换输入格式afterExecutemodifiers.types.ts在执行后转换result如精简返回字段、增强错误信息。在 OpenAI Provider 下组合使用import { Composio } from composio/core; import { OpenAIProvider } from composio/openai; const composio new Composio({ apiKey: your-composio-api-key, }); // Get GitHub tools with modifiers const tools await composio.tools.get( default, { toolkits: [github], }, { // Modify tool schema modifySchema: (toolSlug, toolkitSlug, tool) { // Make tool descriptions more concise for OpenAI if (tool.description tool.description.length 100) { tool.description tool.description.substring(0, 100) ...; } return tool; }, // Modify parameters before execution beforeExecute: ({ toolSlug, toolkitSlug, params }) { console.log(Executing ${toolSlug} tool); return params; }, // Transform results after execution afterExecute: ({ toolSlug, toolkitSlug, result }) { // Format the result data for better presentation if (result.successful toolSlug GITHUB_GET_REPO) { result.data { name: result.data.name, description: result.data.description, stars: result.data.stargazers_count, forks: result.data.forks_count, url: result.data.html_url, }; } return result; }, } );从 BaseProvider.ts 可以看到Modifiers 会作为第三个参数透传给 SDK 注入的全局执行函数测试用例 openai.test.ts 验证了connectedAccountId、customAuthParams等执行选项和 Modifiers 都能正确传递到工具执行层。类型定义一览OpenAI Provider 导出的核心类型与类OpenAIProvider.ts// OpenAI tool type (matches OpenAIs API) type OpenAiTool OpenAI.ChatCompletionTool; // Collection of OpenAI tools type OpenAiToolCollection ArrayOpenAiTool; // The provider class class OpenAIProvider extends BaseNonAgenticProviderOpenAiToolCollection, OpenAiTool { readonly name openai; wrapTool(tool: Tool): OpenAiTool; wrapTools(tools: Tool[]): OpenAiToolCollection; executeToolCall( userId: string, tool: OpenAI.ChatCompletionMessageToolCall, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers ): Promisestring; handleToolCalls( userId: string, chatCompletion: OpenAI.ChatCompletion, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers ): PromiseOpenAI.ChatCompletionToolMessageParam[]; handleAssistantMessage( userId: string, run: OpenAI.Beta.Threads.Run, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers ): PromiseOpenAI.Beta.Threads.Runs.RunSubmitToolOutputsParams.ToolOutput[]; waitAndHandleAssistantStreamToolCalls( userId: string, client: OpenAI, runStream: StreamOpenAI.Beta.Assistants.AssistantStreamEvent, thread: OpenAI.Beta.Threads.Thread, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers ): AsyncGeneratorOpenAI.Beta.Assistants.AssistantStreamEvent, void, unknown; waitAndHandleAssistantToolCalls( userId: string, client: OpenAI, run: OpenAI.Beta.Threads.Run, thread: OpenAI.Beta.Threads.Thread, options?: ExecuteToolFnOptions, modifiers?: ExecuteToolModifiers ): PromiseOpenAI.Beta.Threads.Run; }需要留意ExecuteToolFnOptions与ExecuteToolModifiers均可选前者支持connectedAccountId关联已连接账户、customAuthParams、customConnectionData后者支持modifySchema、beforeExecute、afterExecute等钩子。此外OpenAIProvider还重写了wrapMcpServerResponseOpenAIProvider.ts用于将 MCP URL 响应转换为标准 MCP server 响应格式。进阶提示Responses API 与废弃说明仓库中composio/openai包还额外导出了OpenAIResponsesProvider见 index.ts用于对接 OpenAI 新一代 Responses API其 README.md 明确建议新建 Agentic 流程优先使用 Responses Provider扩展既有 Chat Completions 代码库时再使用OpenAIProvider。Responses Provider 支持{ strict: true }选项会把工具 Schema 规范化为 OpenAI 结构化输出Structured Outputs要求的封闭对象形态无法表达 strict 模式的 Schema如允许任意键的对象、allOf、prefixItems、未解析的$ref会被降级为非 strict 模式并记录警告具体逻辑见 OpenAIResponsesProvider.ts。另外源码中handleAssistantMessage、waitAndHandleAssistantToolCalls、waitAndHandleAssistantStreamToolCalls三个 Assistant API 相关方法均带有deprecated标记OpenAIProvider.ts注释指出 Assistant API 已废弃将在下一个大版本中移除建议改用 Responses API 或 Chat Completions API。在构建新项目时应优先评估 Responses API 方案。结语通过本文可以完整掌握 Composio OpenAI Provider 的初始化、工具格式化、三种工具调用处理路径Chat Completions、Assistants、流式以及 Modifiers 定制能力。其底层实现在 OpenAIProvider.ts 与 BaseProvider.ts 中清晰可读配套测试 openai.test.ts 则验证了并行工具调用、多 choice 处理、参数传递等关键行为可作为理解该 Provider 行为的权威参考。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考