本页属于 2.0 文档,基于
v2.0.4 发布标签整理。SDK 示例请使用 AgentScope Java 2.0.4;当前开发版本的 API 请参阅 dev 文档。agentscope-extensions-jev 模块位于 agentscope-extensions-judge 父模块下,为 TypeSafe System One 和 Jev 提供 Java HTTP client。Jev 不是聊天模型,也不会注册成 AgentScope 的 Model provider;它适合在应用代码里做路由、评分、分类这类需要快速、类型安全、带置信度判断的决策。
何时使用
- 想把非结构化输入变成
Noul、Choice或Score类型结果。 - 需要校准概率和置信度,而不是生成一段文本。
- 想在调用更大的推理模型前做一次低成本预判。
添加依赖
快速上手
支持的问题类型
Spring Boot starter
agentscope.jev.api-key 可以不配置。未设置时,client 会依次读取
TYPESAFE_API_KEY 和 JEV_API_KEY 环境变量。
如果需要高级配置,可以定义 JevClientBuilderCustomizer bean。
Client 行为
- 调用
POST /v1/systemone。 - 默认使用
https://api.typesafe.ai和jev-latest。 - 未显式设置 API key 时读取
TYPESAFE_API_KEY;JEV_API_KEY仍作为兜底。 - 使用 AgentScope 共享的
HttpTransport。 - 默认每次请求 5 秒超时,可通过
timeout(Duration)配置。 - 对 HTTP
429、529、5xx响应按指数退避重试。 - 校验 answer key、answer 类型、概率和 score legend 是否与请求匹配。
- 对不可重试的客户端错误、重试耗尽和非法响应抛出
JevException。
示例中间件
io.agentscope.extensions.judge.jev.example 包里提供三个参考中间件。它们可以直接通过
ReActAgent.builder().middleware(...) 挂载,也可以复制到项目里按需调整提示词和阈值:
工具选择
JevToolSelectionMiddleware 会减少发送给主模型的 tool schema 数量,同时保留核心工具,
并用 Jev 对可选工具排序。
- 在
onReasoning阶段、模型调用前执行。 - 默认保留
load_skill_through_path、reset_tools和generate_response。 - 保留概率高于合成选项
__none__的可选工具,最多保留maxTools个。 - 每个 reasoning step 都会重新选择,并把完整
input.messages()状态发给 Jev。 - 超过 254 个工具时先分块,再对每块胜者重排。
failOpen(true)时,Jev 失败则保留原始工具列表。
模型路由
JevModelRouterMiddleware 会在 agent 调用模型前,让 Jev 在已配置的模型中做选择。
每个候选模型都有自己的路由标准,Jev 返回选择结果、校准概率和置信度。
- 读取最新用户消息,每个 agent 调用只决策一次。
- 只替换
ModelCallInput.model;消息、工具和生成参数原样透传。 - 选择结果、每个选项的概率和置信度存储在
JevModelRouterMiddleware.decision(ctx)中。 - 没有用户文本、置信度低于阈值、
failOpen(true)时 Jev 失败,或结果不可用时,回退到 agent 上配置的原始模型。 - 最多支持 255 个候选模型;超过会在配置阶段直接报错。
工具执行守卫
JevAutoModeMiddleware 在工具真正执行前,用 Jev 判断高风险调用是否可以自动放行。
- 在
onActing阶段、工具执行前执行,位于确定性PermissionEngine管线之前。 - 对名称命中
guardedTools且状态不是ALLOWED的调用,向 Jev 发送一个 yes/no 风险 问题(NoulQuestion),请求 state 里包含完整对话历史和工具参数。 - 多个 guarded 调用会合并为一个 Jev 请求,每个调用对应一个 question。
NoulAnswer.noul()即 P(safe),低于safetyThreshold的调用会被拒绝。- 被拒绝的调用不会执行:合成
DENIED的ToolResultBlock写入对话状态,然后只把安全的调用传给后续执行。 - 已经通过 HITL 确认为
ALLOWED的调用跳过 Jev 检查,人工确认优先。 failOpen(true)时,Jev 失败则放行;failOpen(false)时,Jev 失败则报错。