多智能体任务持久化：Kanban看板与Gateway网关实战

之前我们在第 1 集里提到过多智能体系统的基本结构多个 Agent 各自负责不同的任务互相之间通过消息或共享状态协作。但在实际跑起来之后很多人会发现几个很现实的问题任务做到一半进程重启了进度丢了怎么办多个 Agent 同时抢任务怎么避免重复执行Agent 要 7×24 小时待命网络抖动、模型接口超时、网关挂掉系统能不能自己恢复这些问题单靠给每个 Agent 写一个while True轮询是解决不了的。更合理的做法是引入两个关键组件Kanban 看板和Gateway 网关。本文围绕 Hermes 多智能体系统完整拆解如何使用 Kanban 做任务状态管理如何使用 Gateway 做模型路由与请求转发并给出任务持久化、Agent 自动恢复的配置思路与排错方法。适合读者正在搭建多智能体应用、想把任务从“脚本级”升级到“服务级”、或者已经被各种 gateway 报错折磨过的开发者。本文以 Hermes 环境为例思路同样可以迁移到其他 Agent 编排框架中。1. 为什么多智能体需要 Kanban 和 Gateway1.1 多智能体系统面临的三大问题先抛开 Hermes 的术语从通用角度理解。一个多智能体系统一旦进入真实业务场景至少会遇到下面三个问题第一个问题是任务状态不可见。一个任务提交给 AgentAgent 到底在执行中、已完成、失败还是卡死了如果没有统一的状态存储你只能靠日志或者人肉观察任务一多就完全失控。第二个问题是任务容易被重复消费。多个 Agent 都在监听同一个任务源如果缺少锁定机制同一个任务可能被两个 Agent 同时抢去执行轻则浪费 token重则产生重复的线上操作。第三个问题是进程状态不可靠。Agent 进程崩溃、宿主机重启、网络中断内存中的任务状态全部丢失。等你把进程重新拉起来Agent 根本不记得自己刚才在干什么。这三个问题指向同一组解决方案任务持久化和统一网关。任务持久化负责把“任务当前到哪一步了”记录下来统一网关负责把“模型调用、工具调用、认证信息”收敛到一个入口让 Agent 不需要关心底层模型接口的细节。1.2 Hermes 中的 Kanban 看板做了什么Kanban 本身来自精益生产核心是可视化任务流转。在 Hermes 多智能体系统中Kanban 被用来作为任务队列和状态管理的数据结构。它的工作方式并不复杂。看板由多个列表组成每个列表代表任务的一个状态例如Backlog待处理→ In Progress执行中→ Blocked阻塞→ Done已完成每个任务是一张卡片卡片从左侧列表移动到右侧列表就是对任务状态的一次更新。这样做的好处是任务状态不仅存储在 Agent 的内存里还落到了本地数据库或文件中。即使 Agent 进程重启重启后依然可以从 Kanban 中读取每个任务的当前位置继续处理未完成的任务从而实现 7×24 待命。1.3 Gateway 网关在多智能体中的定位Gateway 在本文语境下不是 Spring Cloud 那种微服务网关而是面向 AI 应用的一层模型网关。它负责统一接收 Agent 发出的模型请求然后路由到对应的模型供应商。为什么要加这一层直接让 Agent 调用模型不行吗可以但会有几个麻烦。第一每个 Agent 如果都要单独配置模型 API Key、Endpoint、模型名称配置会非常分散。第二不同模型提供商的请求格式不完全一致Agent 切换模型时代码要跟着改。第三你希望团队里所有 Agent 访问同一个模型池不能每个 Agent 都自己接一套供应商。Gateway 把这些统一收敛起来Agent 只需要知道自己要什么能力的模型Gateway 负责转发、鉴权、重试和路由。实际运行 Hermes 时如果漏掉了启动 Gateway 这一步或者 Gateway 端口被占用就很容易出现类似502 Bad Gateway、gateway: not reachable、gateway token missing这类报错。2. 环境准备与版本说明在开始配置前先明确运行环境。不同操作系统的启动脚本不同本文以常见本地开发环境为例重点演示配置思路。2.1 运行环境要求Hermes 多智能体系统建议在以下环境中运行项目建议操作系统Windows 10/11、macOS、Linux推荐运行时Node.js 18 或更高版本部分组件可能依赖Python3.9 或更高版本部分 Agent Skill 依赖磁盘空间至少 2GB 可用空间网络需要能访问模型供应商接口注意Hermes 的版本更新较快具体版本号需要根据你的实际安装来源确认。本文中的配置示例是通用思路不建议直接照搬到生产环境请以官方文档和实际版本为准。2.2 安装 Hermes根据项目场景Hermes 通常通过命令行安装。一个典型流程如下# 安装 Hermes CLI npm install -g hermes # 验证安装 hermes --version不过不同分支的安装方式差异较大。如果安装后找不到hermes命令可以检查 Node.js 的全局 bin 目录是否在系统 PATH 中。某些版本还提供桌面端应用Hermes Desktop和本地一键启动脚本例如Windowswindows-start.batmacOSmac-start.command这类脚本通常会帮你启动 Gateway、初始化数据目录并拉起本地 Web 控制台。2.3 项目目录结构说明建议在项目根目录下规划如下结构hermes-workspace/ ├── config/ │ ├── gateway.yaml │ └── kanban.yaml ├── data/ │ ├── kanban/ │ └── logs/ ├── skills/ │ ├── skill-code-review/ │ └── skill-data-collect/ ├── agents/ │ ├── agent-a.yaml │ └── agent-b.yaml ├── windows-start.bat └── mac-start.command这里的核心思路是配置、数据、技能、Agent 定义分离。数据目录单独存放这样系统升级时不会覆盖你的任务数据。3. 核心原理拆解3.1 Kanban 看板的列与卡片Kanban 的数据模型并不复杂。一个看板包含多个列Column每列有唯一的名称每列包含多张卡片Card每张卡片代表一个任务。在 Hermes 的实现中卡片的字段通常包含字段含义id卡片唯一标识title任务标题description任务描述或上下文status当前所在列assignee负责执行的 Agent 标识metadata附加元数据例如重试次数、依赖任务created_at创建时间updated_at更新时间任务持久化的核心就是每次卡片状态变化时都把最新状态写回 Kanban 存储。这样即使 Agent 宕机卡片停留在In Progress列重启后 Agent 可以识别出“这些卡片尚未完成”并继续处理。3.2 Gateway 路由与模型接入Gateway 的工作流程类似一个反向代理Agent 发送模型请求到 Gateway。Gateway 检查请求头中的认证信息。Gateway 根据配置的模型路由规则选择合适的模型供应商。调用上游模型接口。将响应返回给 Agent。在配置文件中Gateway 通常需要指定监听端口、认证 Token 以及模型路由规则。一个简化示例# config/gateway.yaml server: host: 127.0.0.1 port: 15721 auth: token: your-gateway-token model_routes: - name: fast-model provider: openai-compatible base_url: https://api.example.com/v1 model: fast-model-name - name: reasoning-model provider: openai-compatible base_url: https://api.example.com/v1 model: reasoning-model-name这里要特别提醒不同版本的 Hermes 对 Gateway 端口和默认 Token 的约定可能不同。一些版本通过环境变量注入 Token例如export HERMES_GATEWAY_TOKENyour-gateway-token如果启动 Agent 时没有配置 Token就会出现类似unauthorized: gateway token missing的报错。解决的思路不是关闭鉴权而是找到正确的 Token 配置方式比如打开 Dashboard 复制 Token或者从环境变量注入。3.3 任务持久化与 7×24 待命“7×24 待命”不是说让进程永久不重启而是指进程重启后依然能够从持久化存储中恢复任务状态继续干活。要达到这个目标需要满足三个条件第一个条件任务状态必须落盘。如果任务状态只存在 Agent 进程的变量里进程一退出就什么都没了。Hermes 通过 Kanban 的持久化存储解决这个问题任务卡片写入本地数据库或 JSON 文件。第二个条件启动时自动恢复。Agent 启动后应该首先扫描 Kanban 中所有处于In Progress或Blocked状态的任务决定是继续执行、重新执行还是标记为失败。不能启动后只处理新任务。第三个条件具备失败重试机制。模型接口超时、网络抖动、第三方工具返回异常这些在长时间运行中不可避免。Kanban 卡片上的metadata字段可以记录重试次数超过阈值后把卡片移动到Blocked列等待人工介入或后续自动补偿。4. 完整实战搭建一个带持久化任务的多智能体看板下面进入实操环节。我们以一个极简的 Hermes 多智能体场景为例两个 Agent一个负责代码审查一个负责数据收集共同监听一个 Kanban 看板任务提交后由 Gateway 统一路由模型请求Agent 重启后自动恢复未完成任务。4.1 启动 Gateway 网关首先启动 Gateway。启动前先确认端口没有被占用。# 检查端口占用以 Windows 和 Linux/macOS 为例 # Linux/macOS lsof -i :15721 # Windows netstat -ano | findstr 15721随后执行启动脚本或者手动启动 Gateway 服务# Windows windows-start.bat # macOS ./mac-start.command启动后Gateway 默认监听在127.0.0.1:15721。此时可以通过一个简单的健康检查请求验证curl http://127.0.0.1:15721/health如果返回正常说明 Gateway 已就绪。如果返回类似unexpected status 502 bad gateway先不要急着查模型配置而是按第 5 节的排查顺序来。4.2 配置模型路由在config/gateway.yaml中配置模型路由。下面给出一个更完整的示例# config/gateway.yaml server: host: 127.0.0.1 port: 15721 auth: token: hermes-demo-token model_routes: - name: default provider: anthropic-compatible base_url: http://127.0.0.1:15721/v1 model: claude-sonnet-4-20250514 - name: fast provider: openai-compatible base_url: https://api.openai.com/v1 model: gpt-4o-mini logging: level: info output: ./data/logs/gateway.log配置说明provider供应商类型。Hermes 中常见的类型包括anthropic-compatible、openai-compatible、deepseek-compatible等。base_url模型接口地址。model模型名称。auth.token访问 Gateway 需要的令牌Agent 请求时必须在请求头中携带。如果你使用的是 DeepSeek 等国产模型供应商通常也提供 OpenAI 兼容接口可以配置为openai-compatible。一个常见的路由错误是 Agent 请求里带的是 Anthropic 模型名但 Gateway 配置的路由模型名不匹配报错信息类似doesnt look like an anthropic model: expected a gateway model route reference这个报错的含义是Agent 指定了一个模型引用但 Gateway 的路由表中找不到对应的路由。解决方法是确认 Agent 配置中的模型引用名与 Gateway 路由名一致。4.3 创建 Kanban 看板任务启动 Gateway 后创建 Kanban 看板。Hermes 提供了命令行工具或 Dashboard 来管理看板。先创建看板hermes kanban create --name main-board再向后端列表中添加任务卡片hermes kanban add-card \ --board main-board \ --column Backlog \ --title 检查 user-service 代码质量 \ --description 对 user-service 模块进行代码审查输出问题清单添加第二条任务hermes kanban add-card \ --board main-board \ --column Backlog \ --title 采集用户行为日志 \ --description 从日志文件中提取用户行为数据统计 PV/UV此时看板中应该有两张卡片状态都是Backlog。在 Dashboard 的界面中你也能看到这两张卡片并且可以把卡片拖拽到其他列。这一步操作在底层对应的是卡片status字段的更新和持久化。4.4 启动 Agent 消费任务下面分别启动两个 Agent。Agent A 的配置# agents/agent-code-review.yaml name: code-review-agent description: 代码审查 Agent kanban: board: main-board watch_columns: - Backlog claim_column: In Progress gateway: base_url: http://127.0.0.1:15721 token: hermes-demo-token model_route: default persistence: enabled: true store: ./data/kanban auto_recover: trueAgent B 的配置# agents/agent-data-collect.yaml name: data-collect-agent description: 数据收集 Agent kanban: board: main-board watch_columns: - Backlog claim_column: In Progress gateway: base_url: http://127.0.0.1:15721 token: hermes-demo-token model_route: fast persistence: enabled: true store: ./data/kanban auto_recover: true启动 Agent Ahermes agent start --config agents/agent-code-review.yaml启动 Agent Bhermes agent start --config agents/agent-data-collect.yamlAgent 启动后会持续监听Backlog列。当它发现Backlog列有新卡片时会把卡片移动到In Progress列然后调用 Gateway 获取模型响应执行对应 Skill最后把卡片移动到Done列。4.5 验证任务持久化与自动恢复这是本文最重要的验证部分。首先让 Agent A 正在处理一张卡片时直接强制终止进程。比如在 Linux/macOS 下执行kill -9 agent-a-pid或者在 Windows 下直接关闭对应的终端窗口。此时查询看板状态hermes kanban list --board main-board预期结果是Agent A 之前处理的那张卡片仍然停留在In Progress列并没有因为进程退出而回到Backlog也没有直接变成Done。接着重新启动 Agent Ahermes agent start --config agents/agent-code-review.yaml观察其启动日志。如果配置了auto_recover: trueAgent 启动后会扫描In Progress列发现未完成卡片继续执行。这一过程就是“任务持久化 7×24 待命”的核心演示进程可以重启任务状态不丢Agent 可以自动接续。如果 Agent 在多次重试后仍然无法完成卡片建议将其移动到Blocked列避免无限重试浪费模型额度。5. 常见问题与排查思路在实际部署中高频问题集中在 Gateway 启停、Token 配置、端口冲突和网络代理这几个方面。下面整理一份排查清单。5.1 502 Bad Gateway问题现象常见原因解决思路unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responsesGateway 服务未启动或模型供应商侧返回 502先确认 Gateway 健康检查是否通过再确认上游模型接口的可达性检查模型路由配置是否有误502 bad gateway: cc switch local proxy failed while handling本地代理切换失败或上游请求被本地代理拦截检查系统代理设置确认是否有全局代理干扰本地请求必要时将127.0.0.1加入 no-proxy排查顺序建议确认 Gateway 进程是否在运行。检查端口监听状态。检查 Gateway 日志找到具体是哪个上游请求返回了 502。手动 curl 模型供应商接口验证上游是否正常。5.2 Gateway Token Missing问题现象常见原因解决思路unauthorized: gateway token missing (open the dashboard url and paste the token)Agent 启动时未携带 Token从 Dashboard 复制 Token或通过环境变量注入确认 Agent 配置中的 Token 与 Gateway 配置一致在配置文件里检查token字段是否确实填入了值。有些配置模板中 Token 是空的需要手动填入。5.3 WebSocket 连接不可达问题现象常见原因解决思路gateway: not reachable at ws://127.0.0.1:18789Gateway 监听端口不是 18789或 WebSocket 服务未启动检查实际端口确认 18789 是否是 WebSocket 端口确认 Gateway 版本是否支持 WebSocket 通道这类报错通常发生在 Gateway 的 HTTP 服务和 WebSocket 服务端口不一致时。需要查阅当前版本的端口约定不要盲目修改配置文件。5.4 模型路由解析报错问题现象常见原因解决思路doesnt look like an anthropic model: expected a gateway model route referenceAgent 的模型引用名与 Gateway 路由名不匹配检查 Agent 配置中model_route是否在 Gateway 的model_routes中存在确认用的是路由名而不是原始模型名5.5 Agent 执行超时问题现象常见原因解决思路the agent execution provider did not respond in time上游模型响应太慢或 Agent 在等待某个工具调用超时确认模型路由指向的模型是否本身速度较慢检查 Agent 的超时配置考虑通过 Gateway 切换到更快的模型路由6. 最佳实践与工程建议6.1 配置分离与命名规范建议把 Gateway、Kanban、Agent 三类配置拆开存放不要写在同一个文件里。命名上做到“见名知意”Agent 配置agent-职责.yamlSkill 配置skill-功能.yamlGateway 路由gateway.yaml这样做的好处是后续新增 Agent 或新增模型路由时不需要改动已有配置降低误操作风险。6.2 Token 与敏感信息管理Gateway Token、模型 API Key 是敏感信息不建议硬编码在配置文件中提交到 Git。推荐做法使用环境变量注入。使用.env文件并在.gitignore中忽略。在 CI/CD 中使用密钥管理服务。本地调试时可以使用.env文件简化流程HERMES_GATEWAY_TOKENyour-gateway-token OPENAI_API_KEYyour-openai-key DEEPSEEK_API_KEYyour-deepseek-key6.3 Kanban 任务设计每张卡片代表一个不可拆分的最小任务。如果任务过大Agent 执行中途失败后恢复成本会很高。建议任务描述里写清楚前置条件。预期输出。涉及的工具和 Skill。校验标准什么结果可以视为“已完成”。任务描述越清晰Agent 在长时间运行中的行为越可预期。6.4 失败重试与阻塞策略为每个任务设置最大重试次数。超过阈值后不要继续重试而是移动到Blocked列。对于Blocked列的任务可以设置定时扫描在满足条件后自动移回In Progress也可以等待人工干预。一个简单的重试逻辑卡片领取 → 执行 → 失败 ↓ 记录重试次数 metadata.retry_count 1 ↓ retry_count max_retry ? 回到 In Progress 重试 : 移到 Blocked6.5 日志与监控无论是什么 Agent 框架日志都是排查问题最重要的手段。建议至少记录Gateway 请求日志谁在什么时间调用了哪个模型路由耗时多久。Agent 执行日志哪张卡片被哪个 Agent 领取执行到哪一步。持久化日志卡片状态变更记录。如果日常使用 Dashboard也可以通过 Dashboard 观察看板列的数量变化判断任务是否存在堆积。6.6 生产环境注意从本地部署切换到生产环境时建议关注以下几点将 Kanban 持久化存储切换到独立的数据目录并配置定期备份。Gateway 与 Agent 不要部署在同一台机器的同一端口冲突位置。对模型路由增加限流和熔断配置避免某个上游模型抖动影响所有 Agent。启动脚本应具备开机自启能力如 systemd 或 Windows 计划任务。定期检查Blocked列处理长时间卡住的任务。7. 总结与下一步学习路线本篇文章围绕 Hermes 多智能体系统讲清楚了三个关键点。第一Kanban 看板是多智能体任务状态管理的基础设施。它让任务状态从 Agent 内存中剥离出来成为可查询、可恢复、可流转的持久化数据。第二Gateway 网关是模型调用的统一入口。它解决的不只是“网络转发”还包括模型路由、认证管理和上游故障隔离。第三任务持久化是 7×24 待命的前提。Agent 进程可以随时重启只要 Kanban 数据还在系统就能恢复执行。接下来可以继续关注这几个方向如何为 Agent 编写自定义 Skill与 Kanban 任务联动。如何配置 Gateway 的多上游负载均衡与故障转移。如何在多个 Agent 之间进行更精细的权限隔离。如果你在实操中也遇到了 Gateway 启动失败、Token 无效、任务恢复不了的问题建议先确认三件事Gateway 是否真的启动了、Token 是否一致、看板数据目录是否有写入权限。这三点能解决大部分初期的部署困惑。如果本文对你顺利跑通 Hermes 多智能体看板有帮助可以收藏备用。后续我会继续更新 Skill 编写和 Agent 编排相关的内容欢迎在评论区交流你遇到的报错。