跳转至

远程 Hermes Agent 后端

手册 · 相关指南

DeepTutor Connected Agents 可以调用 Hermes Agent 网关，而无需在 DeepTutor 容器中安装 Hermes CLI。该后端类型为 hermes_remote，其显示名称为 Hermes Agent (remote)。

配置

每个后端的设置位于常规 subagent.json 设置文档中的 backends.hermes_remote 之下：

  • enabled：聊天是否可以委托给此后端。
  • base_url：网关根地址，例如 http://hermes-uni:8642。
  • api_key_env：包含网关 bearer 令牌的环境变量名称。默认值为 DEEPTUTOR_HERMES_REMOTE_API_KEY。
  • profile：信息性的部署/配置文件标签；它不是凭据，也不用于构造 URL。
  • model、effort、system_prompt、auto_approve：与本地后端共享的运行控制项。
  • idle_timeout_seconds：SSE 帧之间的最大空闲间隔（默认 600）。网关发送的 keepalive 心跳会重置此看门狗计时器。

API 密钥仅限环境变量。它绝不会作为内联设置字段被接受、持久化，也不会由 GET /api/subagents/settings 返回。 网关 URL 必须是 HTTP(S)，且不得包含凭据、查询文本或片段。可选的 /p/<profile> 前缀支持 Hermes 多配置文件路由。 重定向永远不会被跟随。

HTTP 契约

适配器使用带 bearer 令牌的认证请求（Authorization: Bearer ...），并设置显式的连接/读取/写入/连接池超时。端点及机器可读的功能契约详见 Hermes API Server 指南。

  1. GET /v1/capabilities 检测可用性，并验证所配置的网关是否公布运行提交、事件流式传输、停止、审批响应和会话资源。检测会报告不同的 not_configured、key_missing、unreachable、unauthorized 和 incompatible 详细信息。
  2. POST /v1/runs 启动一次运行。请求使用 input 作为用户提示，instructions 作为可选的首次会话系统指令，model（如已配置），model_options.reasoning_effort（如已配置），以及 session_id（用于恢复会话）。服务器返回 HTTP 202，附带 { "run_id": "...", "status": "started" }。全新的运行将其运行 ID 用作会话 ID；恢复的运行则保留所提供的会话 ID。 在恢复运行之前，适配器会获取 GET /api/sessions/{session_id}/messages。它只保留非空的用户/助手行，排除工具行，并最多发送最近 40 行作为 conversation_history。404 表示会话已不存在：旧的会话 ID 和请求头会被丢弃，运行将以无历史记录的全新状态启动，同时重新应用 system_prompt。
  3. GET /v1/runs/{run_id}/events 是一个 SSE 流。帧中包含位于 data: 行中的 JSON。适配器消费以下事件对象： message.delta（delta）、tool.started（tool、preview）、 tool.completed（tool、error）、reasoning.available（text）、 approval.request、run.completed（output）、run.failed（error）和 run.cancelled。工具生命周期事件变为工具/工具结果行； 答案增量变为合并 ID 为 hermes_remote:final 的累积文本；其他生命周期事件变为日志/错误行。网关通过同一流发出工具/推理、文本/完成和审批事件。
  4. POST /v1/runs/{run_id}/approval 解决待处理的审批。当自动批准时，请求体为 { "choice": "once" }；当 auto_approve 为 false 时，请求体为 { "choice": "deny" }。审批响应失败会被暴露，运行会停止，而不是无限期等待。
  5. POST /v1/runs/{run_id}/stop 中断一次运行。取消操作会发出此请求，并带有受保护的、有界清理窗口，然后重新抛出取消异常；SSE 空闲超时则发出该请求并返回错误。

会话连续性同时使用网关文档中记载的 X-Hermes-Session-Id 请求头和 session_id 请求字段。适配器还会发送兼容性的 X-Hermes-Session 请求头。自定义 system_prompt 会在全新会话或历史记录查找报告会话已不存在（404）时发送。每个请求都携带固定的 CONSULT_ORIGIN_INSTRUCTION 递归防护，用于标识 DeepTutor Connected Agents 并指示网关代理直接回答，而不是委派回 DeepTutor。

/v1/runs API 没有图像上传字段。因此，附件及其 DeepTutor 本地路径不会发送到远程网关。

隔离与安全

此后端将 Hermes 网关保持在 DeepTutor 进程/容器之外：工具在网关主机上运行，而不是在 DeepTutor 中运行。将每个 DeepTutor 聊天限定在其各自返回的会话 ID 中；不要在用户或聊天之间共享会话 ID。确保 API_SERVER_KEY（网关的服务端密钥）和 DEEPTUTOR_HERMES_REMOTE_API_KEY（DeepTutor 端环境变量名对应的值）不会出现在设置文件、日志、事件文本和前端负载中。

流式传输是静默的，除了适配器暴露的结构化 SSE 生命周期。它不会轮询或重试 POST /v1/runs；调用方取消或空闲看门狗总是会尝试有界的停止。

实现与验证

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 dee/DeepTutor