Hive 多智能体生产级 Harness 实战指南:从 Colony 架构到快速上手

原创2026-09-22 19:08:461,974 阅读
文章标签:人工智能AI AgentAgent 框架多智能体大模型Agent 编排工具调用Agent 记忆

Hive 多智能体生产级 Harness 实战指南:从 Colony 架构到快速上手

导读

Hive 是一个面向生产环境的开源多智能体(Multi-Agent)运行时层,核心思路是"一个循环控制许多循环"(one loop controls many loops):以 Queen 为持久化、面向客户的主智能体,按需孵化出大量 Worker 克隆并行执行真实业务流程。本文以仓库 README.md 为骨架,结合 架构总览 与源码实现,系统讲解 Hive 的 Colony(蜂群)概念、单一 AgentLoop 执行原语、协调基质(Tracker / Task Plan / Event Bus / Reminder Hub)、可靠性机制与快速上手流程。读完本文,你将掌握 Hive 的核心架构、环境搭建、首个 Agent 的构建方式,以及它区别于"单 Agent"与"手工接线图式框架"的设计哲学。


一、Overview:Hive 是什么

Hive(本仓库即其开源镜像,项目定位为 "Multi-Agent Harness for Production AI")是一个零配置、模型无关(model-agnostic)的多智能体运行时,用于运行"智能体群体"(colonies of agents)。

一个 colony 是一组协同完成同一业务流程的专业化智能体,包含两个角色:

  • Queen(女王):持久化、面向客户的主智能体,负责对话、制定计划、亲自完成早期工作,并在需要规模化时孵化 Worker;
  • Worker(工蚁):由 Queen 按需生成的克隆体,各自领取一个明确子任务,并行执行后回报结果。

你只需要描述期望的结果(outcome),Queen 会先自己动手验证路径,再围绕该工作"长出"一个 colony 来可靠、规模化地运行它。

底层的机制是 "一个循环控制许多循环":Hive 只有唯一一个执行原语——AgentLoop。Queen 本身就是一个 agent loop,每个 Worker 都是它的克隆(同样的工具、同样的模型、各自独立的任务),无需编译任何图结构,也没有编排样板代码。colony 通过共享账本(shared ledger)与持久化计划进行协调,内置崩溃安全的状态、深度可观测性与人工监督能力。完整的机制说明见 docs/architecture/README.md。

二、核心特性一览

  • ✅ Agent 群体(Colonies):Queen 按需孵化 Worker 克隆,用于并行、长时运行的工作;
  • ✅ 单一原语、多循环:无需接线图,Queen 在运行时动态"生长"出 colony;
  • ✅ 共享 Tracker 账本 + 持久化任务计划:替代数据缓冲实现协调;
  • ✅ Queen 人格(persona):CEO 式路由 + 不断演进的限定范围记忆;
  • ✅ 崩溃安全的 Park/Resume、成本约束、带外(out-of-band)人工介入(Sentinel);
  • ✅ 零配置:无需技术配置即可起步;
  • ✅ 通用计算使用(General Compute Use)与浏览器使用(Browser Use),支持原生扩展;
  • ✅ 自定义模型支持(Custom Model Support)。

三、适用场景:Hive 适合谁、何时用

Hive 是面向"把 AI 智能体从原型推进到生产"的团队的多智能体 harness 层。适合 Hive 的场景:

  • 希望 AI 智能体执行真实业务流程,而非演示;
  • 需要规模化地处理状态、恢复与并行执行的运行时;
  • 需要通过反思(reflexion)、记忆与习得技能实现随时间自我改进的自适应智能体;
  • 需要人工介入控制(human-in-the-loop)、可观测性与成本上限;
  • 计划在生产环境中运行智能体,可用性、成本与可审计性至关重要。

而如果只是尝试简单的 Agent 链或一次性脚本,Hive 可能不是最轻的选择。

判断"何时该用 Hive"的标尺是:当瓶颈不再是模型本身、而是模型周围的 harness 时——比如需要状态持久化与崩溃恢复的长运行智能体、需要成本强制与审计轨迹的生产负载、需要反思 + 限定记忆 + 习得技能持续改进的智能体、需要共享 Tracker 账本 + 持久化计划协调的并行多智能体工作。

四、快速开始:环境搭建与首个 Agent

4.1 前置条件(Prerequisites)

  • Python 3.11+(用于 Agent 开发);
  • 一个可用的 LLM Provider(为智能体提供算力);
  • ripgrep(可选,Windows 推荐):terminal_rg / terminal_glob 搜索工具使用 ripgrep 加速文件搜索;未安装时自动回退到 Python 实现。Windows 安装方式:winget install BurntSushi.ripgrep 或 scoop install ripgrep。

Windows 用户:原生 Windows 通过 quickstart.ps1 与 hive.ps1 支持(需 PowerShell 5.1+);WSL 也可用但非必需。

4.2 安装(Installation)

重要:Hive 采用 uv workspace 布局,不支持 pip install。在仓库根目录执行 pip install -e . 只会创建一个占位包,导致 Hive 无法正常工作。请务必使用 quickstart 脚本完成环境搭建。

# 克隆仓库(以当前开源镜像为例)
git clone <仓库地址>
cd hive

# macOS/Linux 快速启动
./quickstart.sh

# Windows(PowerShell)
.\quickstart.ps1

快速启动脚本(仓库根目录的 quickstart.sh)是一个交互式向导,依次完成:

  1. framework —— 核心 Agent 运行时与 Colony 运行时(安装在 core/.venv);
  2. aden_tools —— 提供 Agent 能力的 MCP 工具集(安装在 tools/.venv);
  3. credential store —— 加密的 API Key 存储(~/.hive/credentials);
  4. LLM provider —— 交互式默认模型配置,支持 Hive LLM 与 OpenRouter 等;
  5. 使用 uv 安装全部 Python 依赖;
  6. 最后在浏览器中打开 Hive 界面。

提示:之后想重新打开 Dashboard,在项目目录运行 hive open 即可。

4.3 构建你的第一个 Agent

在首页输入框直接输入你想构建的 Agent 描述。Queen 会向你提问、与你一起把方案敲定下来,然后开始执行——这是一个"人机协作澄清 + 自动执行"的过程。

4.4 使用模板 Agent

点击 "Try a sample agent" 浏览模板:可以直接运行模板,也可以在既有模板之上构建你自己的版本。仓库 examples/templates 下提供了多种可直接复用的模板,例如:

  • competitive_intel_agent(竞品情报)、deep_research_agent(深度研究)、email_inbox_management(邮箱管理)、meeting_scheduler(会议日程)、sdr_agent(SDR 外联)、tech_news_reporter(科技新闻)、twitter_news_agent(Twitter 新闻)、vulnerability_assessment(漏洞评估)等。

每个模板都包含 agent.json(或 agent.py)、config.py、flowchart.json、mcp_servers.json 等完整定义,可直接运行或作为二次开发的起点。

4.5 运行 Agent

选定 Agent(既有的或示例的)后,点击左上角的 Run 按钮即可运行;也可以直接与 Queen 对话,由她代为运行 Agent。

五、架构核心:Why Hive 与执行流程

Hive 的立场是:模型越强,Agent 能力的上限越高——但可靠性与生产价值取决于 harness。与其让你手工接线工作流图、定义每一次 Agent 交互、被动处理故障,Hive 翻转了范式:你描述结果,Queen 先亲自干,再长出 colony 规模化。这是结果驱动(outcome-driven)、自适应,且附带易用工具与集成。

其核心流程("How It Works",共 5 步):

  1. 描述结果 → 用自然语言说清目标;一个 CEO 式的 LLM 路由器挑选合适的 Queen;
  2. Queen 试点(pilot) → 她亲自完成一个单元的工作,验证路径并把过程记录进共享 Tracker;
  3. 系统化(Systematize) → 把验证过的协议提炼为 skill + playbook,形成可复现的流程;
  4. 扇出(Fan out) → run_worker 孵化 Worker 克隆 并行执行并回报;
  5. 收敛与监控(Converge & monitor) → Worker 把结果写入 Tracker;Queen 用 SQL 校验,实时指标、预算强制、崩溃安全恢复全程生效。

对应关系可以概括为:自然语言描述 → Queen 试点证明路径 → 可复现流程 → 规模化并行 → 构造即恢复 → 可靠产出。

六、深入架构:一个循环控制许多循环

6.1 唯一执行原语:AgentLoop

core/framework/agent_loop/agent_loop.py 中的 AgentLoop 是一个多轮流式 LLM 循环,也是 Hive 唯一的执行单元。每一轮(turn):

  1. 流式输出模型的响应(文本与工具调用);
  2. 并行批量执行工具调用;
  3. 把结果回填到对话;
  4. 由 judge(评审器)决定是终止(judge 判定通过,或遇到干净的纯文本轮)还是继续迭代。

这个类运行一切:

  • Queen 是一个 AgentLoop,配置为长时对话监督——迭代次数近乎无界、上下文窗口大、工具预算宽裕(对应 worker_definition 注释中所述 Queen 配置约为 999_999 次迭代、180k 上下文);
  • 每个 Worker 是同一循环的克隆,但使用更紧的 LoopConfig。

6.2 Worker 的默认配置:单一事实来源

Worker 的运行时画像定义在 core/framework/agents/queen/worker_definition.py 中,DEFAULT_LOOP_CONFIG 是 Worker 工具调用画像的单一事实来源:

DEFAULT_LOOP_CONFIG: dict[str, int] = {
    "max_iterations": 3,              # 3 个"工作"迭代
    "grace_iterations": 1,            # + 1 个宽限迭代(保证回报)
    "tool_call_budget": 30,           # 每轮工具调用软预算
    "tool_call_hard_multiple": 3,     # 硬上限倍数:30/60 软检查点,90 硬停
    "tool_call_lifetime_budget": 200, # 跨所有轮的累计工具调用上限
    "max_context_tokens": 180_000,    # 压缩触发前的上下文预算
}

关键设计点:

  • Grace 迭代(宽限迭代):保证的收尾轮。即使 Worker 耗尽预算,也至少还有一次只允许调用 report_to_parent / task_update / tracker_upsert 的收尾机会——避免 Worker 静默死亡、永远没有回报;
  • 终身工具调用预算(lifetime budget):跨所有轮次的累计上限,防止被 Queen 抬高 max_iterations 的 Worker 无限扇出;达到上限后强制进入宽限收尾;
  • 上限白名单与边界:在 core/framework/host/colony_runtime.py 中,Queen 只能通过 run_worker 覆盖白名单内的字段(max_iterations、grace_iterations、tool_call_budget、tool_call_lifetime_budget、max_context_tokens),且值必须在 _LOOP_OVERRIDE_BOUNDS 边界内(如 grace_iterations 上限 3、tool_call_lifetime_budget 上限 2000);tool_call_hard_multiple 等其余字段由框架锁定,防止配置漂移。

6.3 Worker 的"刻意缺失"

Worker 是 Queen 的克隆,但刻意被收窄:无 persona、无历史记忆、无升级通道、不能孵化或委派子任务。它读取任务、使用工具、调用 report_to_parent。Fail-fast 是契约:被阻塞时,Worker 把部分状态持久化到 Tracker,并回报 failed/partial,而不是在变通方案上打转。

Worker 的系统提示词(同文件中的 WORKER_SYSTEM_PROMPT)把这些规则写成"不可协商"条款:不能孵化 Worker 或委派、不能提问或建议下一步(没有实时听众)、不能添加元评论等。

6.4 扇出工具:run_worker

在 colony 阶段,Queen 通过唯一工具 run_worker(实现于 core/framework/tools/queen_lifecycle_tools.py)进行委派:

run_worker(tasks=[{"task": ..., "data": {...}}, ...], timeout=600)
  • Fire-and-forget(即发即忘):run_worker 立即返回;Worker 在后台运行,Queen 保持不被阻塞,可以继续与用户对话或派发更多工作;
  • 报告以"轮次"形式回家:Worker 完成时发出 SUBAGENT_REPORT 事件,Queen 在自己的对话中将其视为 [WORKER_REPORT] 用户轮——包含状态、一段话摘要与可选的结构化载荷。这就是"多循环"向"单循环"汇报的方式,不需要共享调用栈;
  • 并发是调度出来的,不是手工维护的:colony 接收全部 N 个任务,最多 max_concurrent_workers(默认 4,可用环境变量 HIVE_MAX_CONCURRENT_WORKERS 覆盖,见 core/framework/host/colony_runtime.py 中 _DEFAULT_MAX_CONCURRENT_WORKERS)同时运行,其余排队,前者结束后者补位。Queen 可以看到 running_now / queued / batch_remaining 的拆分;
  • 超时先软后硬:timeout(默认 600 秒)是软截止,向仍在运行的 Worker 注入"现在回报"的提示;由它派生的硬截止会强制停止掉队者。被强制停止或超时的 Worker 可通过 resume_worker_ids(可选 guidance)从保存的对话中恢复。

Worker 之间互相不可见、不可通信、不可等待,协调完全通过下面的共享基质完成。

七、Colony:部署单元与目录结构

一个 colony 是 Hive 的部署单元。在磁盘上它是一个独立目录 colonies/<name>/,存放该 colony 共享的一切:Worker 规格(worker.json)、Tracker 账本(data/tracker.db)与任务计划。Colony 具备三个特性:

  • 可移植(Portable)—— 通过 POST /api/colonies/import 以 tarball 形式导出/导入,一个运行良好的 colony 可以整体交给另一用户或机器;
  • 可调度(Schedulable)—— cron 触发器直接注入所属 Queen 的会话,colony 可以按时钟自行唤醒;
  • 长寿命(Long-lived)—— Queen 跨会话持久存在,Worker 随工作需求来去。

7.1 协调基质:替代"边"与数据缓冲的四件套

colony 没有图、没有边、没有共享数据缓冲,它通过四个轻量基质保持 Queen 与 Worker 舰队同步:

1. Tracker —— 共享 SQLite 黑板

每个 colony 有且仅有一个 tracker.db,由不可变的 ColonyBinding {name, dir, tracker_db}(见 core/framework/host/colony_binding.py)标识。binding 通过工具执行上下文穿线给 Queen、通过 input_data 穿线给 Worker,双方始终解析同一个数据库。没有 binding 的工具会拒绝调用——绝不自行拼路径(这防止了"幽灵 colony"目录的分裂脑问题)。

Tracker 是 colony 的结构化共享状态:

  • Queen 用 tracker_sql 建表(DDL),并用 tracker_register_writable 声明哪些列允许 Worker 写入;
  • Worker 用 tracker_upsert 记录发现——每个工作单元一行;
  • Queen 用 tracker_query(只读 SELECT)校验进度。"做了什么/还剩什么"永远是新鲜的 SQL 查询,而非可能因崩溃丢失的内存态。

2. Task Plan —— Queen 的持久化脊柱

文件备份的任务系统(core/framework/tasks/)为 Queen 的每一次对话提供持久化、结构化的计划(task_create / task_update / task_list)。它对用户可见、可随时编辑、并在会话重载后依然存在——计划比任何一次 Agent 运行都长寿。Colony 可以携带模板任务清单,Queen 进入时直接采纳,因此重复性工作流总能从同一份计划开始。

这里有一个清晰的分工:Tracker 保存结果(结构化行),Task Plan 保存意图(Queen 打算做什么)。Worker 也维护自己的小任务清单,在单次任务内保持组织性。

3. Event Bus —— 事件总线

core/framework/host/event_bus.py 是 colony 的发布/订阅骨干:SUBAGENT_REPORT 把 Worker 结果送回 Queen,CLIENT_* 事件把实时转录流式推送到 UI。它是"多循环"汇入"单循环"并上屏的方式,不需要共享调用栈。

4. Reminder Hub —— 工程化的注意力管理

单一长时循环在扇出几十个 Worker 时容易"忘事"——忘记还有 Worker 在跑、忘记在上下文被修剪前持久化状态、忘记还有哪些工具可用。框架在约定好的时机持续注入建议性 <system-reminder> 上下文(core/framework/agent_loop/reminders.py 中的 ReminderHub / ReminderSource / ReminderPoint):

  • 生命周期点:SESSION_START、POST_TOOL_USE、TOOL_BUDGET_CHECKPOINT、PRE_COMPACT、POST_COMPACT、STOP;
  • 时间点:IDLE_TICK(后台计时器即使在 loop 停驻时也能轻推)与 STREAM_STALLED(流看门狗触发时的反应式提醒)。

具体来源包括:active_workers_reminder(用户重新参与时重新浮现进行中的 Worker,防止重复派发)、tracker_snapshot_reminder 与 colony_worker_snapshot_reminder(在工具预算检查点展示 Tracker 表与实时 Worker 舰队)、colony_parallel_nudge(试点后建议把协议沉淀为 playbook)、idle_nudge、tool_skill_reminders(按名称列出可用工具/技能面及按需加载完整 schema 的方式,而不是全部烘进静态提示词)。这是工程化的元认知——框架在管理长时、高扇出会话中模型的注意力。

7.2 成熟化弧线:先执行,后系统化

Queen 不会一开始就设计好 colony,而是分三阶段"长"出来(相关逻辑见 core/framework/agents/queen/incubating_evaluator.py):

  1. Independent(独立)—— Queen 作为独立对话 Agent 亲自干活;当任务表现出并行、重复或长时特征时,她可通过 suggest_colony 提议扩容;
  2. Incubating(孵化)—— start_incubating_colony 运行一个 fail-closed 的 LLM 门控,判断计划是否足够成熟值得提交。因为 fork 成本高昂(会结束交互式聊天、colony 转为无人值守运行),门控失败或不确定时返回 ready=False,Queen 自我纠正而不是贸然推进;
  3. Colony(蜂群)—— Queen 把 headless Worker 规格 fork 到磁盘,进入扇出模式。

标志性动作是 execute-first-then-systematize(先执行后系统化):Queen 亲自端到端完成一个单元的工作——pilot——把结果记入 Tracker;然后把验证过的协议提炼为可复用的 skill + playbook,并调用 run_playbook("收敛脊柱",见 core/framework/host/playbook/runner.py):一个确定性运行器,自身不持有持久状态、以 Tracker 为事实来源、为每行数据派发一个 Worker 克隆(带重试/退避、泳道与死信路径)。因为"还剩什么"永远是新鲜的 Tracker 查询,重跑 playbook 就是构造式的恢复(resume by construction)。

八、Queen 作为身份:人格、路由与记忆

8.1 13 个 YAML 人格

Queen 不是可互换的编排器,而是人格(persona)。仓库内置 13 个 YAML 定义的 Queen(目录 core/framework/agents/queen/queen_defaults/):sales、growth、legal、finance、fundraising、talent、technology、operations、product strategy、brand & design、content、market research、outbound、lead-gen 等,每个都带有注入系统提示词的 traits、background 与 behavior triggers。

以 queen_sales.yaml 为例,其结构包含:name(如 "Larry Ellison")、title(如 "Head of RevOps")、default_tool_categories(默认工具分类:email_senders、file_ops、terminal_basic、browser_basic、browser_interaction、research、context_awareness、charts、media 等)、default_preset_skills、core_traits、hidden_background(past_wound / deep_motive / behavioral_mapping)与 psychological_profile、behavior_triggers(触发条件 + 反应)等字段——让人格在业务判断上带来领域智慧,而不仅是任务执行。

8.2 CEO 式路由

你不需要从菜单里挑选 Queen。新请求到来时,一个 LLM 路由器读取请求并分派最匹配的 Queen——就像 CEO 把工作路由给对口的部门负责人。你描述结果,路由是自动的。

8.3 Queen Memory v2:限定范围的记忆

每位 Queen 携带 Queen Memory v2(见 core/framework/agents/queen/queen_memory_v2.py、reflection_agent.py、recall_selector.py):~/.hive/memories/ 下按 global / per-colony / per-queen 分域存放的 markdown 记忆文件,由冷却门控(cooldown-gated)的反思代理写入、由召回选择器在后续会话中检索——不是向量库,而是她反思进去、再读回来的结构化文件。这让她跨会话积累关于你与你的业务的上下文。与之相对,Worker 是无记忆的:每次运行都是全新开始。

8.4 Queen 拥有什么

  • 对话(The conversation)—— colony 唯一的客户端面向;
  • 计划(The plan)—— 文件备份、跨重载存活的 任务清单;
  • Tracker(The tracker)—— 她建立 colony 的共享 账本、分派工作、用 SQL 校验结果;
  • 升级(Escalation)—— 需要人介入时,她通过 Sentinel 带外升级,等对方回复后恢复。

九、可靠性内建于原语:每个 Agent 都继承

因为所有角色都是同一个 loop,harness 特性只写一处,每个 Agent 自动继承:

  • Park / Resume(停驻/恢复):loop 把游标持久化到磁盘,需要等待时停驻——包括 ASK_USER、CREDENTIAL_FORM、COLONY_SUGGESTION、AWAITING_QUEEN、USER_STOPPED、COLD_INTERRUPTED(运行时中途死亡)、LLM_ERROR、DOOM_LOOP 等场景。磁盘是事实来源,崩溃或重启后精确地从断点恢复(见 core/framework/agent_loop/internals/cursor_persistence.py);
  • 上下文管理:结构保持型压缩(structure-preserving compaction)+ 工具结果的 pointer/spillover 模式,让长会话不超上下文预算、也不丢信息;
  • 停滞与末日循环检测:TTFT/事件间隔流看门狗 + n-gram 相似度检查,捕获卡住的轮次与重复的工具调用;
  • Judge 门控的终止:只有当 judge 流水线满足条件时,一轮才"验收"(详见下节);
  • 人工介入是带外的(out-of-band):升级不是图中的一个节点——Queen 通过 Sentinel(core/framework/sentinel/)升级给人类,这是账号绑定的 Slack/Telegram 频道。loop 停驻,人类回复被注入,loop 恢复。

9.1 工具结果截断与 Pointer 模式

Agent 经常产生或消费超出上下文预算的工具结果(网页搜索、抓取页面、大型 API 响应)。Hive 使用 pointer 模式:大结果持久化到磁盘,对话中替换为紧凑的文件引用,Agent 按需通过 load_data() 解引用。工作方式:

  1. 每个工具结果都保存为文件(配置了 spillover 目录时),使用短单调命名(如 web_search_1.txt)最小化 token 开销;JSON 做 pretty-print 以便 load_data 的按行分页;计数器在恢复时从已有文件复原;
  2. 对话拿到的是指针而非载荷:≤ 30KB 的结果带 [Saved to '…'] 注解直接透传(Agent 当轮即可操作);更大的结果替换为预览 + load_data(...) 指针。30KB 阈值刻意宽松以减少额外往返;
  3. load_data(filename, offset, limit) 按需取回完整结果,且自身永不被再次 spill(无循环引用);超大 load_data 结果会被截断并附分页提示;
  4. 指针在压缩后依然存活:结构保持型压缩保留工具调用消息(已是微型指针),把自由文本散文 spill 到编号的 conversation_N.md 文件中并替换为引用。Agent 精确知道它调用过每个工具、每个结果在哪;
  5. 系统提示词每轮列出全部 spillover 文件,Agent 永远知道可以重读什么。

9.2 Judge 流水线

终止由三级 judge 决定(core/framework/agent_loop/internals/judge_pipeline.py),按序评估:

级别 触发 机制 判定
Level 0(短路) 总是 必需输出键是否已设置?工具调用是否仍在进行? 键缺失则 RETRY;工具运行中则继续
Level 1(自定义 judge) 设置了 JudgeProtocol 用户提供的 judge 检查助手文本、工具调用、累加器状态、迭代次数——拥有完整权限 带反馈的 ACCEPT / RETRY / ESCALATE
Level 2(隐式) 无自定义 judge、键齐备 输出键检查 + 可选的、针对 success_criteria 的对话感知质量门 ACCEPT 或带反馈的 RETRY

RETRY 判定的反馈以 [Judge feedback] 用户消息注入,下一轮 Agent 能看到自己的上一次尝试与批评并调整。这种上下文内反思(in-context reflexion)——反馈 → 反思 → 修正——是 Agent 在单次会话内自我纠正的方式,无需任何模型重训练。

十、目标与结果驱动:Goal 是一等公民

Hive 信奉 Outcome-Driven Development(ODD,结果驱动开发),它对比了三种范式:

  • **Task-Driven(任务驱动)**问"代码正确吗?"——定义显式步骤,成功 = 步骤无错跑完;但 Agent 可能步骤全对、产出无用;
  • **Goal-Driven(目标驱动)**问"我们在解决对的问题吗?"——捕获意图,但目标可能含糊("提升客户满意度"无法告诉你何时算完);
  • Outcome-Driven(结果驱动)问"系统产出期望的结果了吗?"——定义可度量的成功标准、硬约束与上下文,按实际结果评估。这正是 Hive 的实现。

在 Hive 中,Goal 不是字符串描述,而是结构化对象(core/framework/schemas/goal.py):

  • Success Criteria(成功标准):带权重的成功标准定义"完成"长什么样,是多维质量度量而非二元通过/失败。指标类型可为 output_contains、output_equals、llm_judge 或 custom;权重表达什么最重要;
  • Constraints(约束):定义不允许发生什么,是护栏。hard 约束不可协商(违反即升级或失败),soft 约束是偏好(可适度变通);类别包括 time、cost、safety、scope、quality;
  • Context(上下文):领域知识、偏好、背景信息,注入到 Agent 的每一次 LLM 调用,使其始终带着全貌推理。

Goal 生命周期为 DRAFT → READY → ACTIVE → COMPLETED / FAILED / SUSPENDED,执行期间每个目标的状态全程可见。好处有三:Agent 可自我纠正(judge 用这些标准决定 accept/retry/escalate)、改进有靶点(框架知道它错过了哪条标准,这正是驱动 colony 改进的精确信号)、人类保持控制(约束划出边界,边界内 Agent 自由探索)。

十一、Colony 如何改进:四个带内机制

Hive 不跨"世代"重生成图(旧文档中的"进化"概念已不存在于当前架构),而是通过四个带内机制改进——都属运行系统的一部分,无需手工编辑工作流或重训模型。两个在会话内、两个跨会话:

  1. 会话内:Reflexion(反思)—— judge 每次判定 retry 时把反馈注入对话,下一轮 Agent 看到上次尝试与批评并调整;
  2. 跨会话:限定范围的演化记忆—— Queen 工作期间,冷却门控的反思步骤把持久笔记写入分域 markdown 记忆,召回选择器在后续会话检索;这是"靠记住"改进,不是"靠重写";
  3. 跨会话:习得的、工具门控的技能—— Queen 验证过的做法可成为 skill 加入基线;skill 是工具门控的,只有所需工具实际存在时才激活,Queen 不会尝试运行她无装备的协议;
  4. 跨会话:系统化(playbook)—— pilot 验证路径后提炼为 skill + playbook,确定性运行器跨 Worker 克隆收敛剩余批次;playbook 自身无状态、Tracker 为事实来源、每单元派发一个 Worker(带重试/退避/死信路径),重跑即恢复——一次性成功变成可复现、自恢复的流程。

重要区分:这些机制让 colony 更可靠,而非更"通用智能"。它记住什么有效、编码为技能、把验证过的 pilot 变成可复现流程——这是对已遇到过的问题类型的改进。真正的新情况交给 human-in-the-loop,而每次人类介入的决策都会成为 Queen 可记住、可复用的上下文。

十二、集成:模型无关与系统无关

Hive 生来模型无关、系统无关:

  • LLM 灵活性:通过 LiteLLM 兼容 provider 支持 Anthropic、OpenAI、OpenRouter、Hive LLM 以及其他托管或本地模型(100+ 提供商)。设置对应 API Key 环境变量并指定模型名即可(provider 配置示例见 docs/configuration.md);本地模型(如 Ollama)使用 ollama/model-name 格式(例如 ollama/llama3);
  • 业务系统连通性:通过 MCP 把各类业务系统接入为工具——CRM、客服、消息、数据、文件与内部 API 等。因为 Queen 与 Worker 共享同一工具面,你添加的一个能力整个 colony 都可用(100+ 集成工具,另有 General Compute Use 与 Browser Use 原生扩展)。

十三、常见问题(FAQ)

Q: Hive 支持哪些 LLM provider? A: 通过 LiteLLM 支持 100+ provider,包括 OpenAI(GPT-4、GPT-4o)、Anthropic(Claude 系列)、Google Gemini、DeepSeek、Mistral、Groq、OpenRouter 与 Hive LLM。设置对应 API Key 环境变量并指定模型名即可。

Q: 能用本地模型(如 Ollama)吗? A: 可以。用 ollama/model-name 格式(如 ollama/llama3、ollama/mistral),确保本地运行 Ollama 即可。

Q: Hive 与其他 Agent 框架有何不同? A: Hive 运行的是 Agent 群体(colonies),而非单 Agent 或手工接线的图。多数框架要求你编译由节点和边组成的图;Hive 只有一个执行原语——Queen 本身是 agent loop,每个 Worker 是它的 克隆。编排是运行时 run_worker 扇出,而非编译好的 DAG;colony 通过 共享 Tracker 账本 而非数据缓冲协调。在此核心之上,Hive 是生产级 harness——崩溃安全 park/resume、成本强制、实时可观测性、带外人工介入——因为只有一种 Agent,所以每个 Agent 都继承这一切。

Q: Hive 是开源的? A: 是,Apache License 2.0 全开源(见 LICENSE),欢迎社区贡献(指南见 CONTRIBUTING.md)。

Q: 支持 human-in-the-loop 工作流吗? A: 支持。Queen 通过 Sentinel(账号绑定的 Slack/Telegram 频道)带外升级给人类。Agent loop 停驻(状态持久化到磁盘)、通知人类、在对方回复时从断点恢复。因为升级不是图中的一个节点,colony 中任何 Agent 都可在任意时刻暂停等待人工判断,且支持可配置超时与升级策略(详见 架构总览 的可靠性章节)。

Q: Hive 用什么语言编写? A: 框架为 Python;JavaScript/TypeScript SDK 在路线图上。

Q: Hive Agent 能交互外部工具与 API 吗? A: 能。colony 中每个 Agent 都有内置工具访问能力;通过 MCP 连接外部 API、数据库与服务——包括 100+ 集成工具与 General Compute Use / Browser Use 原生扩展。

Q: 成本控制如何工作? A: 提供细粒度预算控制:支出上限、节流、自动模型降级策略;可在团队、Agent 或工作流层级设置预算,并实时跟踪成本与告警。

十四、进一步阅读

结语

Hive 的架构主张可以浓缩为五点(与 架构总览 的总结一致):Colony 是单元(Queen + 若干 Worker 克隆共享一个磁盘工作区、一个 Tracker、一个计划);一个循环、许多循环(单一 AgentLoop 原语既是 Queen 也是每个 Worker,编排是运行时扇出而非编译图);无图协调(共享 SQLite Tracker、持久化任务计划、事件总线、提醒中枢取代边与数据缓冲);先执行后系统化(Independent → Incubating → Colony;先 pilot,再沉淀为 skill + playbook 用 run_playbook 收敛);可靠性内建于原语(磁盘 park/resume、压缩 + pointer 模式、停滞/末日循环检测、judge 门控终止、Sentinel 带外升级——因为只有一种 Agent,所以每个 Agent 都继承)。对于想把真实业务流程交给多智能体系统、又需要生产级可靠性保障的团队,这是一个值得从 quickstart 开始实际跑通的架构范本。

登录后查看全文
hive