Jev AI API 与 AI Agent：构建可靠智能体工作流的实用指南

一个真正可用的 AI Agent，不仅需要一个能生成合理答案的大语言模型，还需要决定应该调用哪个模型、工具是否安全、是否需要补充上下文，以及什么时候应该交给人工处理。Jev AI API 正好适合作为这一层决策组件：输入 State 和 Typed Questions，再把结构化答案交回应用代码。

本文将介绍如何把 Jev AI API 接入 AI Agent，从一个边界清晰的判断开始，逐步实现模型路由、工具调用前的安全守护和人工复核。如果你还不了解 Jev 模型本身，可以先阅读 Jev AI 模型使用指南。

目录

• 为什么 Agent 需要 Jev AI 决策层
• Jev AI Agent 的最小架构
• 第一步：在调用工具前定义决策
• 第二步：设计 State 和 Questions
• 第三步：调用 Jev AI API
• 第四步：把答案接回 Agent 循环
• 第五步：安装 Jev Agent Skill
• 工具调用安全守护
• 人工复核与评估
• 生产环境上线清单
• 常见问题

为什么 Agent 需要 Jev AI 决策层

一个 Agent 工作流通常至少包含两类不同任务：

1. 生成与推理：理解请求、撰写内容、总结资料或规划动作序列。
2. 边界清晰的判断：选择路由、评估风险、检查条件，或决定工具调用是否需要批准。

生成式 LLM 适合第一类任务，Jev 更适合第二类任务。Jev 返回软件可以直接消费的类型化决策，应用不必从一段自然语言中解析结论，也不必把一个没有约束的 JSON 当成绝对可信的权限判断。

这一区分很重要，因为 Agent 不应该让同一个开放式模型既负责制定计划，又自动授权计划中的所有动作。独立的决策层可以把边界明确下来：

• Agent 可以提出一个动作；
• Jev 可以判断一个边界清晰的条件；
• 应用代码可以执行权限检查并决定最终动作。

这并不意味着每一步都要增加一次模型调用，而是要把高风险、难审计或执行错误成本高的判断单独隔离出来。

Jev AI Agent 的最小架构

一个实用的 Jev Agent 可以拆成五个组件：

组件	负责内容
Agent 编排器	维护循环、上下文和下一步计划
Jev AI API	针对当前 State 回答类型化问题
生成式模型	写作、总结、推理或生成计划
应用权限层	决定哪些工具和动作被允许
人工复核	处理不确定或高影响案例

编排器应该只传给 Jev 最小且有用的 State。State 可以包含用户请求、工具参数、账户政策、之前的验证结果或工作流当前步骤。如果一个判断只需要结构化对象，就没有必要把整个 Agent 对话记录全部发送给模型。

第一步：在调用工具前定义决策

接入 API 前，先列出 Agent 会反复做出的判断。最适合开始的场景通常有明确的答案空间，也有明确的下一步动作。

模型路由

使用 Choice 判断请求应该交给快速模型、深度推理模型、检索流程还是兜底路径。应用代码再根据选择调用对应模型。

工具调用风险

使用 Noul 判断一个动作是否敏感或需要批准。例如删除记录、发送外部消息、修改账户设置或发起付款。

任务严重程度与优先级

当 Agent 需要低、中、高、严重等有序等级时，使用 Score。这样队列优先级由结构化评分驱动，不必让生成式模型凭空生成一个数字。

完成度与上下文检查

可以让 Jev 判断当前 State 是否包含足够证据、长会话中的关键结果是否应该保留，或者 Agent 是否应该向用户请求澄清。

不要从“Agent 应该做什么？”这种开放问题开始。优先设计“哪个已批准的路由适用？”或“这个具体工具调用是否需要人工批准？”这类可以验证和执行的判断。

第二步：设计 State 和 Questions

Jev API 支持文本、JSON 对象和文本数组作为 State。对于 Agent，JSON 对象通常是最清晰的起点，因为它可以把用户请求、拟执行动作、政策和证据拆成独立字段。

{
  "state": {
    "user_request": "删除工作区中所有重复联系人。",
    "proposed_tool": "delete_contacts",
    "record_count": 1842,
    "has_backup": false,
    "policy": "批量破坏性操作必须人工批准"
  },
  "model": "jev-latest",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "应该选择哪条执行路径？",
      "criteria": {
        "proceed": "动作被允许，可以自动执行",
        "confirm": "需要用户或运营人员确认",
        "reject": "违反政策或当前不支持"
      }
    },
    "needs_human": {
      "type": "noul",
      "instructions": "这个拟执行动作是否需要人工批准？"
    }
  }
}

每个问题都应该是原子的。多个问题可以共享同一份 State 并行评估，因此一个请求就能同时返回路由、风险信号和人工复核信号，不需要连续发起三个 API 请求。

三种问题类型应当这样使用：

• Choice：从预定义选项中选择一个结果。
• Score：根据从低到高的有序标准进行评分。
• Noul：返回一个具体命题为真的概率。

问题 key 由应用自行定义，并会在 answers 中原样返回。建议保持 key 稳定，方便比较不同版本的日志、指标和下游动作。

第三步：调用 Jev AI API

在 Jev AI Playground 中验证 State 和问题有效后，再把它们接入服务端。评估端点是：

POST https://thejevai.com/v1/systemone

请求需要 Bearer API Key、application/json，以及三个顶层字段：state、model 和 questions。当前 API 文档中的旗舰模型名是 jev-latest。

curl -X POST https://thejevai.com/v1/systemone \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": {
      "user_request": "删除工作区中所有重复联系人。",
      "proposed_tool": "delete_contacts",
      "has_backup": false,
      "policy": "批量破坏性操作必须人工批准"
    },
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "应该选择哪条执行路径？",
        "criteria": {
          "proceed": "允许且可以自动执行",
          "confirm": "需要用户或运营人员确认",
          "reject": "不允许或当前不支持"
        }
      },
      "needs_human": {
        "type": "noul",
        "instructions": "这个拟执行动作是否需要人工批准？"
      }
    }
  }'

把 JEV_API_KEY 放在服务端环境变量中。不要把它放进浏览器代码、Agent 对话记录、公开提示词或 Git 仓库。响应会按照问题 key 返回类型化答案，并在支持的类型中提供概率和置信度字段。

第四步：把答案接回 Agent 循环

Jev 返回的是判断信号，真正的执行权仍属于编排器和应用权限层。一个简单的路由边界可以这样实现：

const route = result.answers.route.choice;
const humanProbability = result.answers.needs_human.noul;

if (route === 'reject') {
  return respondSafely('This action is not allowed.');
}

if (route === 'confirm' || humanProbability >= 0.8) {
  return queueForHumanReview({ ticketId, result });
}

if (route === 'proceed') {
  return executeAllowedTool({ name: proposedTool, args, requestId });
}

return askForMoreContext();

即使 Jev 返回高概率批准，也要在应用代码中校验工具名、参数、用户权限、资源范围和请求 ID。不要把最终工具调用直接交给模型信号。

第五步：安装 Jev Agent Skill

对于编程 Agent 和兼容的 Agent 环境，官方 Jev Agent Skill 提供了一种可复用的方式，让 Agent 在保持宿主控制权的情况下请求边界清晰的判断。安装命令是：

npx skills add jev-ai/jev-agent-skill

然后配置 API Key 和语言环境变量：

export JEV_API_KEY="sk_your_key_here"
export JEV_LANGUAGE="zh-CN"

这个 Skill 可以帮助 Agent 选择 Choice、Score 或 Noul，发送最小必要 State，并理解结构化响应。但它不会获得执行付款、删除数据或绕过宿主审批系统的权限。

当前 API 字段、Agent Skill 引导、响应结构和错误行为，以 Jev AI 文档 为准。把 Skill 当作决策接口，而不是应用身份认证和权限控制的替代品。

工具调用安全守护

Agent 不应该从生成文本中推断授权。在工具真正执行前，应检查拟执行意图、政策、资源范围和风险。Jev 可以为这个检查提供类型化信号，而应用负责落实规则。

一个实用的安全守护链路是：

1. 规范化工具名称和参数。
2. 让 Jev 判断风险或是否需要批准。
3. 应用层执行白名单和权限校验。
4. 不确定的情况进入确认或人工复核。
5. 使用幂等键和审计记录执行工具。

对于破坏性或外部动作，应让多个控制点共同通过，而不是只信任一个概率阈值。即使模型信号看起来很有把握，政策层也应该能够拒绝动作。

人工复核与评估

概率和置信度是路由信号，不是业务正确性的保证。应使用历史样例选择阈值，并在上线后持续监控误报、漏报和人工复核量。

可以采用这样的策略：

• 高置信度、低影响：自动继续；
• 有歧义或陌生案例：请求更多上下文；
• 高影响或破坏性动作：必须批准；
• 输入不支持或格式错误：安全失败。

建议记录足以复现判断的元数据，包括问题版本、State 结构版本、选择结果、概率、置信度、最终动作以及人工是否修改了结果。不要记录 API Key，也不要保存不必要的个人数据。

生产环境上线清单

发布 Jev AI API 与 Agent 集成前，检查以下项目：

• Agent 的判断拥有边界清晰的答案空间。
• State 只包含问题真正需要的上下文。
• Choice、Score 和 Noul 与决策形状匹配。
• API Key 只存放在服务端，并且不会进入 Agent 日志。
• 超时、重试、限流和 API 错误都有安全兜底。
• 工具名称和参数在模型之外再次校验。
• 高影响操作受应用权限和必要的人工审批控制。
• 每次工具调用都有幂等策略和审计记录。
• 阈值经过典型样例和对抗样例测试。
• 评估数据与生产密钥、个人数据隔离。
• 日志可以把 Jev 答案关联到最终应用动作。

常见问题

Jev AI API 是另一个聊天补全 API 吗？

不是。它针对 State 和 Typed Questions 做评估，返回结构化答案，目标是成为应用内部的一个决策节点，而不是生成给人阅读的聊天记录。

Jev 应该替代 Agent 中的大语言模型吗？

通常不应该。生成式模型负责语言密集型工作，Jev 负责边界清晰的分类、路由、评分和安全判断。两者可以在同一个编排流程中协作。

Jev Agent Skill 会替我执行工具吗？

不会。它帮助兼容的编程 Agent 向 Jev 提出边界清晰的问题。Agent 宿主、应用权限、确定性政策检查和人工审批仍应控制最终动作。

一次请求可以问多个 Agent 问题吗？

可以。多个问题可以读取同一份 State 并行评估。当 Agent 需要在下一步动作前同时得到路由、风险和人工复核信号时，这种方式很有用。

总结

结合 Jev AI API 与 AI Agent 的关键，是让每个组件承担清晰的职责：Agent 和 LLM 负责理解与规划，Jev 负责回答小而明确、带概率信号的判断，应用代码负责权限检查和最终执行。

可以先从一个低风险工作流开始，在 Playground 中验证，再通过 /v1/systemone 接入服务端，最后逐步加入模型路由、工具守护和人工复核。这样构建出来的 Agent 更容易测试、更安全，也更适合稳定运行在生产环境中。