agentscope-extensions-judge 下,与 JEV 同级,通过独立于聊天模型 API 的 OpenAIDecisionsClient 使用。应用可以根据结果分类请求或决定下一步动作。
官方指南将该 API 标记为公开测试阶段。API reference列出了 gpt-6-luna,客户端以它作为默认模型。能否访问服务取决于你的 OpenAI 账号。
依赖和首次决策
此功能面向2.1.0-SNAPSHOT,需要使用包含该扩展的构建。使用 AgentScope BOM 时可以省略依赖版本。
OPENAI_API_KEY。builder 显式设置的密钥优先于环境变量。执行以下示例会将文本和问题发送给 OpenAI,可能产生费用。
DecisionRequest 包含 1–400 个名称唯一的问题。请求中的可选模型会覆盖客户端模型。构造时会复制输入和问题集合,因此请求可以安全复用。可选的 promptCacheKey() 用于划分缓存复用;本扩展不暴露 prompt_cache_options 或显式缓存断点,OpenAI 会使用默认隐式缓存。decide() 返回冷 Mono,每次订阅都会发送请求,适合响应式应用;decideBlocking() 则供非响应式线程使用。
问题和答案
所有公开类型均位于io.agentscope.extensions.judge.openaidecisions 包。
选项值可以是字符串或布尔值,
"true" 和 true 是不同选项。选项和等级的描述均可省略。置信度与选中选项的概率分别保留,不能直接视为业务正确率保证;应使用带标签样本确定阈值。
任何问题都可能返回 DecisionAnswer.Refusal,执行后续动作前应显式检查该类型。同一个 DecisionResult 中仍会保留其他有效答案和 usage。拒绝不会被转换成零概率或猜测的选项。
客户端按名称匹配答案,按值或索引匹配分布项,不依赖响应顺序。缺失、重复、未知或类型不匹配的答案都会被拒绝。每个选项或等级必须且只能出现一次;数值字段必须存在且有限;概率和置信度必须位于 [0, 1];概率总和与 1 的误差不得超过 1e-6 × 选项数。选中值必须属于提供的选项,评分必须在相同容差内符合等级索引的加权平均值。客户端保留原值,不做归一化。非法响应会使整个 Mono 以 OpenAIDecisionsException 失败。
DecisionResult.usage() 保留提供商返回的输入、输出和总 token 数,并将提供商的 token 详情字段平铺为 cachedTokens、cacheWriteTokens 和 reasoningTokens。缺失 usage 为 null,缺失的单个计数和详情字段也保持 null,真实的零仍为零。失败调用不暴露 usage。
图片和混合输入
纯图片输入使用DecisionInput.image(url);文本和图片混合时使用 DecisionInput(text, imageUrls),最多 128 张图片,编码为一条用户消息。下面的 pngBytes 表示由应用加载的 PNG 数据。
配置和失败处理
默认 API base 为https://api.openai.com/v1。baseUrl() 接受带版本号的 API base(可包含网关路径前缀),或完整的 /decisions 地址。base URL 不允许包含用户凭据、查询参数和片段。自定义地址时应保留 API 版本路径。
默认超时为 30 秒,必须为正值。阻塞 SDK 调用运行在 Reactor 的 boundedElastic 调度器上,超时也会传递给 SDK。超时和取消会向执行任务发送中断,正在进行的网络请求何时停止取决于 SDK transport。通过封装层创建的客户端需要调用 close() 或使用 try-with-resources 释放 SDK 连接。Spring 会在上下文关闭时关闭自动配置的客户端。
HTTP 错误可通过 OpenAIDecisionsException.getStatusCode() 获取状态码。HTTP 429、5xx、客户端超时、SDK I/O 错误及 SDK 明确标记为可重试的错误携带重试提示。非法响应和永久性 HTTP 错误不重试。客户端生成的异常不会附带提供商原始响应体或底层 SDK 的原始异常链。
封装层重试默认关闭,保持每次订阅只尝试一次。可以显式启用与 JEV 相同的重试次数和初始退避:
defaults() 允许额外重试两次,初始退避为 500ms,使用带抖动的指数退避。通过 new OpenAIDecisionsRetryPolicy(maxRetries, initialBackoff) 自定义限制;disabled() 不允许重试。超时分别作用于每次尝试,总耗时还包括重试及退避。重试耗尽后保留最后一次脱敏异常。拒答仍是正常返回的结果,不触发重试。
封装层会关闭自行创建的 SDK 客户端的重试。builder().client(openAIClient) 借用已有 SDK 客户端,其凭据、base URL、重试配置和生命周期由拥有者管理。启用封装层重试前应关闭借用客户端自身的重试,避免调用次数相乘。取消会停止响应式重试序列,正在进行的网络请求何时停止仍取决于 transport。
Agent 中间件示例
io.agentscope.extensions.judge.openaidecisions.example 提供三个需要显式启用的中间件,覆盖 JEV 的模型路由、工具筛选和自动执行判断场景,不依赖 JEV 扩展。默认均关闭,需配置 .enabled(true)。它们是应用接入示例,不会自动注册为 Spring bean。
路由器接受 2–255 个命名模型候选。默认在请求包含工具时保留原模型,并在包含 response format 时检查候选的原生结构化输出能力。只有确认候选支持当前工具、输入模态和输出要求后,才应通过
.compatible((input, choice) -> ...) 放开对应请求。路由和筛选默认 failOpen(true),设为 false 时传播请求失败。工具执行判断显式配置 failOpen(true) 后会放行请求失败和缺少上下文的情况,但拒答始终不会转为执行许可。
筛选器保留 load_skill_through_path、reset_tools 和 generate_response,这些工具不占可选工具名额。可通过 alwaysIncludeTools(Set.of(...)) 自定义。当前请求的 ToolChoice.Specific 指定的工具若存在于输入目录中,也会保留且不占名额;筛选器不对其评分,也不会创建该工具。确定无关时可以移除全部可选工具。筛选默认仅提交最近八条非空白文本消息,总文本最多 8,000 字符,可用 maxContextMessages 和 maxContextChars 调整。工具结果块中的文本也纳入相同的消息数和字符预算。工具执行判断采用相同的固定窗口,另将实际工具名和参数作为 JSON 证据提交。这些示例不会转发对话中的图片。筛选和执行判断超过 400 题时会顺序分批请求。
ALLOWED 的调用。通过模型判断并不授予核心权限:放行及非保护调用仍进入正常执行管线。被拒绝的调用不会进入后续派发器,而会生成 DENIED 工具结果消息及 start/text/end 事件,让模型依据结果继续处理。评估过程中取消不会派发工具,也不会生成拒绝消息。
这些示例没有实现 JEV 更广的执行模式、确认记录、分阶段路由、RAG、上下文压缩和评测扩展。测试使用本地 fixture 和桩决策,不代表真实提供商效果,也不验证生产安全阈值。
可运行场景
agentscope-examples/openai-decisions 模块提供 io.agentscope.examples.decisions.OpenAIDecisionsMiddlewareExample,可独立运行 route(模型路由)、select(工具筛选)和 guard(执行判断)三个场景。程序打印 Decisions 答案、实际调用的模型和工具列表,以及工具结果状态。业务工具全部使用模拟实现,删除文件也不会改变文件系统;运行 main 会真实调用 Decisions 和 Chat Completions API。
在仓库根目录运行:
OPENAI_API_KEY、OPENAI_MODEL(支持工具调用的 Chat Completions 模型),以及 OPENAI_FAST_MODEL(仅 route 必需)。模型名不带 openai: 前缀。将 route 替换为 select 或 guard 即可切换场景,也可以通过 "-Dexec.args=route Design a distributed task scheduler" 追加自定义提示词。模块 README 包含环境变量设置和离线验证命令。真实决策结果及聊天模型是否调用工具取决于模型,示例提示词不保证特定路由或拒绝结果。
当任一聊天模型为 gpt-6-luna 时,示例会为该模型设置 reasoning_effort=none,以满足 Chat Completions 工具调用的要求。此配置仅用于聊天请求,Decisions 和其他聊天模型保留默认配置。
如果连接超时,请按示例模块 README 配置 JVM 的 HTTP/HTTPS 代理属性,让两个客户端都使用代理。main 方法会在回退前输出脱敏的 Decisions 失败原因,并在退出时关闭 Reactor 共享调度器;此关闭操作仅适用于独立运行的示例。
Spring Boot
使用 starter 依赖替代直接引入扩展,然后注入OpenAIDecisionsClient。
agentscope.openai-decisions.enabled=false 可禁用客户端创建,用户自定义的客户端 bean 优先。可以实现 OpenAIDecisionsClientBuilderCustomizer 传入官方 SDK 客户端或覆盖属性,Spring 在绑定属性之后按顺序应用 customizer。
设置 retry.max-retries=2 可启用封装层重试。次数必须非负,退避必须为正值。这些属性配置客户端,不启用中间件;需要在每个 Agent 上显式注册所需中间件。
完整的三问题示例和图片输入辅助方法位于 agentscope-examples/documentation/src/main/java/io/agentscope/examples/documentation2/judge/OpenAIDecisionsExample.java。