mini-SWE-agent 的 Portkey Response API 模型（portkey_response）：基于 OpenAI Responses API 的原生工具调用接入指南

人工智能大模型AI Agent代码智能体【免费下载链接】mini-swe-agentThe 100 line AI agent that solves GitHub issues or helps you in your command line. Radically simple, no huge configs, no giant monorepo—but scores 74% on SWE-bench verified!项目地址https://gitcode.com/gh_mirrors/mi/mini-swe-agent点击查看免费下载导读本指南以仓库文档 docs/reference/models/portkey_response.md 为核心深入讲解 mini-SWE-agent 中PortkeyResponseAPIModel这一模型类——它通过 Portkey 网关调用 OpenAI Responses API/responses端点以原生工具调用native tool calling的方式驱动 agent 执行 bash 命令。读完本文你将掌握portkey_response模型类的完整配置方法、每个配置参数的语义与默认值、其无状态消息扁平化机制、成本核算与重试策略的底层实现并能够基于仓库源码与测试用例验证其行为。一、模型定位为什么需要 portkey_responsemini-SWE-agent 通过model_class机制支持多种模型后端。在 模型选择入口 src/minisweagent/models/init.py 中注册表_MODEL_CLASS_MAPPING将两个 Portkey 相关类分别映射为portkey→minisweagent.models.portkey_model.PortkeyModel走 Portkey 的 Chat Completions/completion端点portkey_response→minisweagent.models.portkey_response_model.PortkeyResponseAPIModel走 Portkey 的 Responses/response端点。文档 docs/reference/models/overview.md 对两者的定位做了清晰区分PortkeyModel使用/completion端点而PortkeyResponseAPIModel使用/response端点并支持原生工具调用。仓库主页 docs/index.md 也提到项目同时支持/completion与/response两类端点。portkey_response的价值在于OpenAI 系模型如 GPT-5 系列的 Responses API 提供扩展推理reasoning与结构化的function_call输出能力而 Portkey 作为 AI 网关可以统一接入多个上游厂商并提供路由、可观测性、缓存等能力。当你想通过 Portkey 使用支持 Responses API 的模型时就应选用portkey_response模型类。二、安装与前置条件PortkeyResponseAPIModel依赖portkey-ai包。在 portkey_response_model.py 顶部 通过try/except ImportError强制检查依赖try: from portkey_ai import Portkey except ImportError: raise ImportError( The portkey-ai package is required to use PortkeyResponseAPIModel. Please install it with: pip install portkey-ai )因此使用前需要pip install portkey-ai随后必须配置PORTKEY_API_KEY环境变量。源码在init方法 中会读取该变量缺失时直接抛出ValueError并提示两种设置方式# 方式一临时导出 export PORTKEY_API_KEYYOUR_KEY # 方式二永久写入 mini 全局配置文件推荐 mini-extra config set PORTKEY_API_KEY YOUR_KEY如果你的 Portkey 账号使用虚拟密钥Virtual Key还可以设置PORTKEY_VIRTUAL_KEY环境变量源码会将其作为virtual_key参数传给 Portkey 客户端见init方法。三、快速配置命令行与 YAML 两种方式与所有模型类一致portkey_response既可以通过命令行参数指定也可以在 agent 配置文件中声明参见 docs/models/quickstart.md 的 Model classes 一节。3.1 命令行方式mini -m gpt-5-mini --model-class portkey_response其中-m/--model指定模型名--model-class指定后端类。在 get_model_class 中model_class可以是注册表里的快捷名如portkey_response也可以是完整的导入路径如minisweagent.models.portkey_response_model.PortkeyResponseAPIModel。3.2 YAML 配置方式在 agent 配置文件中默认配置文件的位置会在运行mini时打印详见 docs/advanced/yaml_configuration.mdmodel: model_class: portkey_response model_name: openai/gpt-5.1 model_kwargs: drop_params: true reasoning_effort: medium verbosity: mediummodel_kwargs会被原样合并进client.responses.create(...)的调用参数见下文源码分析用于传递temperature、reasoning_effort等模型级参数。仓库基准配置 swebench_modal.yaml 给出了一个在 SWE-bench 场景下通过 Portkey 使用 GPT-5 mini 的真实示例该示例使用portkey类走 Chat Completions若模型要求 Responses API 则把model_class换成portkey_response即可model: model_name: gpt-5-mini model_class: portkey provider: openai model_kwargs: drop_params: true四、配置参数详解PortkeyResponseAPIModelConfig是一个 pydanticBaseModel定义于 portkey_response_model.py各参数语义如下参数类型默认值说明model_namestr必填传给 Portkey 的模型名如openai/gpt-5.1或gpt-5-minimodel_kwargsdict[str, Any]{}额外请求参数temperature、reasoning_effort、drop_params等会与运行时kwargs合并后传给responses.createlitellm_model_registryPath \| str \| None$LITELLM_MODEL_REGISTRY_PATH自定义模型注册表 JSON 路径用于向 litellm 注册额外模型以便成本核算litellm_model_name_overridestr当 Portkey 模型名与 litellm 成本表中的模型名不一致时用它覆盖成本核算所用模型名cost_trackingdefault \| ignore_errors$MSWEA_COST_TRACKING或default成本核算出错时的行为ignore_errors表示忽略错误并将成本记为 0format_error_templatestr{{ error }}模型输出不符合预期格式时用于渲染报错消息的 Jinja2 模板observation_templatestrreturncode.../returncodeoutput.../output等工具执行结果渲染模板含exception_info、returncode、output三个变量multimodal_regexstr从内容中提取多模态素材的正则空字符串表示禁用多模态处理其中format_error_template与observation_template的具体渲染逻辑分别位于工具解析与观测格式化阶段见第六节。litellm_model_registry在初始化时若指向存在的文件会通过litellm.utils.register_model加载自定义模型价格信息见init方法。五、核心机制一无状态会话与消息扁平化PortkeyResponseAPIModel的类文档字符串明确标注了它的关键设计约束见 类定义This implementation is stateless - each request must include the full conversation history. previous_response_id is not used.这一点与同为 Responses API 后端的litellm_response类后者通过previous_response_id跨轮次维护会话状态参见 docs/reference/models/litellm_response_toolcall.md形成鲜明对比。因此每次请求都必须携带完整对话历史。由于每次请求都会把上一轮的 response 对象塞回消息列表_prepare_messages_for_api负责将这些对象扁平化为标准输入项见 方法实现def _prepare_messages_for_api(self, messages: list[dict]) - list[dict]: result [] for msg in messages: if msg.get(object) response: for item in msg.get(output, []): result.append({k: v for k, v in item.items() if k ! extra}) else: result.append({k: v for k, v in msg.items() if k ! extra}) return result即遇到object response的消息时把它内部的output列表由function_call、message等输出项组成展开成平铺的输入项所有消息统一剔除内部使用的extra字段。测试 test_response_api_model_stateless_flattens_response 验证了这一点含response对象的输入会被压平为function_callfunction_call_outputmessage的序列后再发给responses.create。六、核心机制二原生工具调用的完整调用链6.1 工具定义Responses API 使用扁平结构无嵌套function键描述工具。BASH_TOOL_RESPONSE_API定义于 actions_toolcall_response.py是 agent 唯一的工具——bashBASH_TOOL_RESPONSE_API { type: function, name: bash, description: Execute a bash command, parameters: { type: object, properties: { command: {type: string, description: The bash command to execute} }, required: [command], }, }6.2 请求构造每次查询最终调用 Portkey 客户端的responses.create见 _querydef _query(self, messages, **kwargs): return self.client.responses.create( modelself.config.model_name, inputmessages, tools[BASH_TOOL_RESPONSE_API], **(self.config.model_kwargs | kwargs), )model_kwargs与调用方传入的kwargs以后者优先的方式合并Python 3.9 的|字典合并运算符。测试 test_response_api_model_with_model_kwargs 确认了temperature、max_tokens等参数会原样透传。6.3 工具调用解析响应返回后_parse_actions调用parse_toolcall_actions_response见 actions_toolcall_response.py。该函数遍历response.output筛选type function_call的条目若没有任何工具调用用format_error_template渲染错误信息并抛出FormatError消息内容为 No tool calls found in the response. Every response MUST include at least one tool call.对每个function_calljson.loads解析arguments校验工具名必须是bash且参数必须包含command任一校验失败即抛FormatError成功则产出{command: ..., tool_call_id: call_id or id}的动作列表。测试 test_response_api_model_basic_query 与 test_response_api_model_multiple_tool_calls 分别覆盖单条与多条function_call的解析路径。6.4 观测消息格式化工具执行结果通过format_observation_messages回填给模型底层是format_toolcall_observation_messages见 actions_toolcall_response.py使用observation_template渲染每个动作的执行输出含exception_info、returncode、output若动作带有tool_call_id则生成type function_call_output且带call_id的消息这正是 Responses API 原生工具调用所需的回传格式无tool_call_id的即人类直接下达的命令则回退为role: user的普通消息未执行的动作会被填充为{output: , returncode: -1, exception_info: action was not executed}。消息构造入口format_message见 portkey_response_model.py会把字符串内容包装为{type: input_text, text: ...}结构确保消息符合 Responses API 的input规范。七、成本核算与全局统计尽管请求走 Portkey成本核算仍依赖 litellm。_calculate_cost见 portkey_response_model.py调用litellm.cost_calculator.completion_cost核算所用模型名默认为model_name若设置了litellm_model_name_override则优先使用后者——这正是 docs/models/troubleshooting.md 中提到的场景当 Portkey 模型名与 litellm 价格表中的模型名不一致时如grok-code-fast-1需要手动覆盖若计算出的成本不为正数assert cost 0.0或计算过程抛异常默认会抛出RuntimeError并提示两种规避方式配置文件中设置cost_tracking: ignore_errors或全局export MSWEA_COST_TRACKINGignore_errors在ignore_errors模式下成本记为 0.0 继续执行测试 test_response_api_model_zero_cost_assertion 验证了默认模式下零成本会抛错。每次查询的成本会被累加到全局统计GLOBAL_MODEL_STATS定义于 models/init.py该统计器支持通过MSWEA_GLOBAL_COST_LIMIT/MSWEA_GLOBAL_CALL_LIMIT设置全局限额。同时query返回的消息会附加extra字段包含解析出的actions、cost与timestamp见 query 方法。测试 test_response_api_model_cost_tracking 验证了单次成本与全局累计值的联动。八、错误处理、格式错误与重试策略8.1 格式错误与响应持久化当模型响应无法解析出合法工具调用时query会捕获FormatError把cost写入错误消息的extra并尽力将原始响应序列化后一并附加response.model_dump(modejson)失败时回退为repr(response)见 query 方法。这样 agent 上层可以把失败现场持久化便于排查。finish_reason_from_responses_api见 actions_toolcall_response.py还会把 Responses API 的截断状态映射为模板变量当status incomplete且incomplete_details.reason max_output_tokens时映射为length与 Chat Completions 的finish_reason语义对齐使同一套错误模板在两类端点上都能工作。8.2 重试机制query外层使用retry工具见 utils/retry.py基于 tenacity 实现最多尝试MSWEA_MODEL_RETRY_STOP_AFTER_ATTEMPT次默认 10指数退避等待wait_exponential(multiplier1, min4, max60)即从 4 秒起、最长 60 秒类属性abort_exceptions [KeyboardInterrupt, TypeError, ValueError]见 portkey_response_model.py对应的异常不重试、直接抛出。测试 test_response_api_model_retry_on_rate_limit 验证了限流场景下会重试并最终成功而 test_response_api_model_no_retry_on_type_error 验证了TypeError只调用一次即失败。九、序列化与模板变量serialize()输出模型配置快照其中model_type为完整导入路径minisweagent.models.portkey_response_model.PortkeyResponseAPIModelconfig为model_dump(modejson)的结果见 serialize测试 test_response_api_model_serialize 对此做了校验。get_template_vars()返回完整的配置字典供 agent 的提示词模板渲染使用测试 test_response_api_model_get_template_vars 验证了model_name等键的存在。十、版本迁移与注意事项在 v2 迁移文档 docs/advanced/v2_migration.md 中旧类名portkey_response_api已更名为portkey_response如果你从旧版本升级需要在配置中同步更新model_class名称。此外还需注意三点无状态约束portkey_response不使用previous_response_id每次请求必须携带完整历史对话较长时 token 开销与延迟会随之上升这也是它与litellm_response有状态的主要取舍差异。成本核算依赖 litellmPortkey 模型名需要能在 litellm 价格表中找到否则要使用litellm_model_name_override或通过litellm_model_registry注册自定义模型必要时用cost_tracking: ignore_errors跳过成本核算。环境变量依赖PORTKEY_API_KEY是硬性要求缺失时模型初始化直接失败可选地使用PORTKEY_VIRTUAL_KEY绑定虚拟密钥。全局密钥的管理方式可参考 docs/advanced/global_configuration.md 与 docs/models/quickstart.md。十一、进一步阅读模型类完整源码src/minisweagent/models/portkey_response_model.pyResponses API 工具调用解析与观测格式化src/minisweagent/models/utils/actions_toolcall_response.py模型类注册与选择逻辑src/minisweagent/models/init.py重试工具src/minisweagent/models/utils/retry.py单元测试tests/models/test_portkey_response_model.py模型配置快速上手docs/models/quickstart.md各模型类总览docs/reference/models/overview.md模型类迁移对照docs/advanced/v2_migration.md赞分享人工智能大模型AI Agent代码智能体【免费下载链接】mini-swe-agentThe 100 line AI agent that solves GitHub issues or helps you in your command line. Radically simple, no huge configs, no giant monorepo—but scores 74% on SWE-bench verified!项目地址https://gitcode.com/gh_mirrors/mi/mini-swe-agent点击查看免费下载相关推荐Genkit Go 的 Anthropic 插件基于原生 Messages API 接入 Claude 模型Genkit Go 的 Anthropic 插件基于原生 Messages API 接入 Claude 模型 导读 本文讲解 Genkit Go 生态中 go人工智能大模型后端AI AgentRAG工具调用使用 agno 接入 Ollama Responses API本地模型、工具调用与结构化输出的完整实战指南使用 agno 接入 Ollama Responses API本地模型、工具调用与结构化输出的完整实战指南 导读 本文围绕 agno 仓库中 cookbook人工智能大模型AI AgentAgent 框架多智能体工具调用RAGAgent 工作流Agent 记忆Instructor 全面接入 OpenAI Responses API结构化输出、内置工具与类型安全的实战指南Instructor 全面接入 OpenAI Responses API结构化输出、内置工具与类型安全的实战指南 Instructor 已在当前仓库中正式支持人工智能大模型AI 应用上一篇300%提速神经网络数据查询终极优化GraphQL集成实战指南下一篇iOS动画性能优化实战案例Spring库的应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考