Hive 多智能体框架快速上手：从描述结果到运行 Agent 集群的完整实战指南

人工智能AI Agent多智能体MCP 服务工具调用浏览器控制【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址https://gitcode.com/gh_mirrors/hive48/hive点击查看免费下载导读本文以 HiveAden HiveMulti-Agent Harness for Production AI项目为对象系统讲解其核心设计理念与从零到一的部署使用路径。你将理解 Hive一个执行原语Agent Loop驱动多个循环Queen 与 Worker 克隆的 Colony 架构掌握基于quickstart.sh/quickstart.ps1的安装流程、第一个 Agent 的创建与运行方法以及 LLM 提供商配置、MCP 工具集成等关键实操。读完本文你能够独立完成 Hive 的本地部署、模型配置与首个生产级多智能体任务的跑通。一、Hive 是什么为生产负载而生的多智能体运行时Hive 是面向智能体集群Colonies的零配置、模型无关model-agnostic运行时。一个Colony集群由一组分工明确的智能体组成共同驱动一条业务流程Queen女王——持久化、面向客户的前台智能体负责主导对话、维护计划、孵化集群若干 Worker工人——由 Queen 按需生成的、执行具体工作单元的智能体副本。Hive 的使用范式与传统智能体框架截然相反你只需用自然语言描述期望的结果Queen 先亲自完成一个工作单元验证路径再围绕该工作成长为一个集群以可靠的方式规模化执行。你不需要手写工作流图graph不需要编排样板代码。Hive 底层机制是一个循环控制多个循环one loop controlling many loops。整个框架只有一个执行原语——Agent Loop架构文档 中明确其实现位于 agent_loop.pyQueen 本身就是一个 Agent Loop每个 Worker 是该循环的clone克隆——相同的工具、相同的模型只注入不同的单一任务。集群通过共享账本ledger与持久化计划协同崩溃安全状态、深度可观测性与人工监督都内建在这唯一的原语之中因此每个智能体都自动继承这些可靠性能力。二、Hive 适合谁定位与选型判断Hive 是面向把 AI 智能体从原型推向生产的团队的多智能体 harness 层。单智能体工具能出色完成个人任务但缺少支撑完整业务流程的严谨性rigor。以下情况适合选择 Hive希望 AI 智能体真正执行业务流程而不只是跑 Demo需要能在规模上处理状态、恢复与并行执行的运行时需要能自我改进、自适应、随时间变好的智能体必须要有human-in-the-loop 控制、可观测性与成本上限计划把智能体部署到生产环境其中可用性、成本与可审计性至关重要。反之如果你只是用简单智能体链或一次性脚本做实验Hive 可能并非最佳选择。何时使用 Hive当瓶颈不再是模型本身而是模型周边的 harness 时——例如需要状态持久化与崩溃恢复的长时运行智能体、需要成本强制、可观测性与审计轨迹的生产负载、通过反思/记忆/技能随时间改进的智能体、需要通过共享 tracker 账本与持久化计划协同的并行多智能体任务以及需要随模型能力提升而同步扩展的框架。三、快速开始环境要求与安装3.1 环境要求Python 3.11智能体开发必需一个为智能体提供动力的LLM 提供商Anthropic / OpenAI / OpenRouter / Hive LLM 等详见配置章节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 也是可选方案但并非必需。3.2 安装步骤重要提示Hive 采用uvworkspace 布局不支持pip install安装。在仓库根目录执行pip install -e .只会生成一个占位包Hive 无法正常工作。请务必使用下方的 quickstart 脚本完成环境搭建。# 克隆仓库 git clone https://gitcode.com/gh_mirrors/hive48/hive cd hive # macOS / Linux 运行 quickstart ./quickstart.sh # WindowsPowerShell .\quickstart.ps1安装脚本quickstart.sh会自动完成以下配置组件说明framework核心智能体运行时与执行器位于core/.venvaden_tools为智能体能力提供的 MCP 工具集位于tools/.venvcredential store加密的 API 密钥存储~/.hive/credentialsLLM provider交互式默认模型配置包含 Hive LLM 与 OpenRouter依赖通过uv安装全部 Python 依赖安装完成后脚本会在浏览器中打开 Hive 界面。之后如需重新打开仪表盘在项目目录执行hive open即可。源码视角阅读 quickstart.sh 可以看到完整的交互式引导逻辑——它会依次检查 Python 版本要求 ≥3.11并优先挑选python3.11/3.12/3.13、自动安装缺失的uv、校验 Node.js ≥20用于构建前端仪表盘产物输出到core/frontend/dist/、检查 sqlite3 / tesseract / Chrome-Edge 浏览器等运行时依赖并通过 check_requirements.py 批量验证framework、aden_tools、litellm三个核心模块的导入。模型选择菜单的数据来自 model_catalog.py 的get_default_models()/get_models_catalogue()/get_presets()首次配置会写落到~/.hive/configuration.json。3.3 创建你的第一个 Agent在首页Home输入框中输入你想创建的智能体描述。Queen 会向你提问并与你协作打磨出一个解决方案——你描述结果Queen 负责落地。3.4 使用模板 Agent点击Try a sample agent浏览模板列表。你可以直接运行某个模板也可以选择在现有模板基础上创建你自己的版本。仓库内置了丰富的示例模板见 examples/templates例如competitive_intel_agent竞品情报、deep_research_agent深度研究、email_inbox_management收件箱管理、job_hunter求职助手、meeting_scheduler会议调度、sdr_agent销售开发代表、tech_news_reporter科技新闻、vulnerability_assessment漏洞评估等每个模板都包含agent.py、config.py、flowchart.json与README.md可直接作为二次开发的起点。3.5 运行 Agent选择现有智能体或示例智能体后即可运行。你可以点击左上角的Run按钮也可以直接与 Queen 对话由它替你运行智能体。一切面向结果而非手动作图连线。四、核心工作流描述结果 → 试点 → 系统化 → 扇出 → 收敛Hive 的价值主张集中在一条核心工作流上原文用一张 Mermaid 流程图完整呈现该流程在 key_concepts/colony.md 的 How a colony grows 一节有更详细的阶段化描述4.1 逐步拆解它是如何工作的描述结果→ 用自然语言说明你想要什么一个 CEO 风格的 LLM 路由器会读取请求并自动匹配最合适的 Queen。Queen 不是通用的协调器而是一个身份persona——Hive 内置 13 个 YAML 定义的默认 Queen销售、增长、法务、财务、人才、技术、运营、产品策略、品牌设计、内容、市场研究、外呼、线索挖掘每个都有特质、背景与行为触发词源码位于 queen_defaults。路由是自动完成的你无需手动挑选。Queen 试点Pilot→ Queen 亲自完成一个工作单元验证路径可行并把结果记录到共享 tracker 账本中。系统化Systematize→ 把验证过的协议沉淀为skill playbook——一个可重复执行的流程。playbook 不持有任何自身状态以 tracker 为唯一事实来源它按行分派 worker 克隆带重试/退避与死信路径。由于还剩什么永远是一次新鲜的 tracker 查询重跑 playbook 即天然断点续跑resume by construction。扇出Fan Out→run_worker生成 worker 克隆它们并行执行并回报结果。run_worker是即发即忘fire-and-forget的Queen 不被阻塞可继续与用户对话或派发更多工作。收敛与监督Converge Monitor→ Worker 把结果写入 trackerQueen 通过 SQL 校验配合实时指标、预算强制与崩溃安全恢复。Queen 的成熟度经历三个阶段Independent独立工作→Incubatingfail-closed 门槛校验计划是否足够成熟因为分叉集群成本高——交互式对话结束、集群转为无人值守→Colony分叉落盘并进入扇出模式。4.2 源码级佐证架构文档docs/architecture/README.md引用了 colony_runtime.py 中的核心注释每个 worker 都是 Queen 的 AgentLoop 的精确副本——相同工具、相同提示、相同 LLM……ColonyRuntime 取代 AgentHost 与 ExecutionManager。没有图、没有边、没有节点、没有数据缓冲区只有派生出 N 个独立克隆让它们运行收集结果。Worker 的预算由 worker_definition.py 定义3 次工作迭代 1 次宽限迭代grace iteration外加每次调用与生命周期内两次工具调用预算上限保证 worker 无法无界扇出。宽限迭代是强制性的收尾轮——即使预算耗尽worker 仍能调用report_to_parent/task_update/tracker_upsert绝不会无声死亡。五、协调基座无图的集群如何协同Hive 没有编译后的 DAG集群通过四个轻量基座完成协同详见 coordination.md5.1 Tracker——共享 SQLite 账本每个集群一个tracker.db是完成什么/还剩什么的唯一事实来源。Queen 负责建表tracker_sqlDDL并声明 worker 可写列tracker_register_writableWorker 通过tracker_upsert记录结果每个工作单元一行Queen 用tracker_query仅 SELECT随时校验进度。状态落在真实数据库中而非内存崩溃不丢任何东西。每个 tracker 都受一个不可变的ColonyBinding名称/目录/数据库路径实现见 colony_binding.py约束贯穿 Queen 与每个 worker——没有绑定上下文的工具会拒绝执行从机制上杜绝了两个集群写错账本的可能。5.2 任务计划Task Plan——Queen 的持久化主干Queen 维护一个持久化、文件支撑的任务清单对用户可见、可随时编辑、跨会话存活。计划承载意图Queen 打算做什么tracker 承载结果结构化行。集群甚至可以自带模板计划让周期性工作流每次从同一份检查清单开始。5.3 事件总线Event Bus——实时神经系统实现位于 event_bus.pyworker 报告以SUBAGENT_REPORT事件流回 Queen实时转录以CLIENT_*事件流到前端 UI。多循环借此汇入单循环并上屏无需共享调用栈。5.4 提醒中枢Reminder Hub——工程化的注意力单个长生命周期循环在扇出几十个 worker 时容易失控忘记还有 worker 在跑、忘记在上下文剪枝前持久化状态、忘记可用工具。Hive 在既定时刻向循环注入咨询性system-reminder实现见 reminders.py 的 ReminderHub/ReminderSource/ReminderPoint生命周期点SESSION_START、POST_TOOL_USE、TOOL_BUDGET_CHECKPOINT、PRE_COMPACT、POST_COMPACT、STOP与时间点IDLE_TICK 后台滴答器、STREAM_STALLED 流看门狗。提醒源让 Queen 保持集群感知重新接入时重新浮现进行中的 worker 防止重复派发、快照 tracker 表与 worker 集群、剪枝前提醒持久化、试点后建议沉淀 playbook、按名列出可用工具/技能以保持静态提示词精简。5.5 人工介入Sentinel哨兵人工监督不是图中的节点而是名为Sentinel的带外通道out-of-band。Queen 需要人时审批、判断、缺失凭据通过账号绑定的Slack 或 Telegram频道升级。循环暂停park并将状态持久化到磁盘人类回复后答案被注入循环从断点精确恢复。因为升级内建于原语而非图中任何智能体都可在任意点暂停等待人工判断集群可以暂停几分钟到几天而不丢失位置。六、模型与系统集成LiteLLM 与 MCPHive 刻意设计为模型无关model-agnostic与系统无关system-agnosticLLM 灵活性——Hive Framework 通过 LiteLLM 兼容提供商支持 Anthropic、OpenAI、OpenRouter、Hive LLM 以及其他托管或本地模型。原文档 FAQ 明确通过 LiteLLM 可接入 100 提供商包括 OpenAIGPT-4/GPT-4o、AnthropicClaude、Google Gemini、DeepSeek、Mistral、Groq、OpenRouter、Hive LLM 等只需设置对应 API 密钥环境变量并指定模型名。本地模型——支持 Ollama 等本地模型模型名使用ollama/model-name格式如ollama/llama3、ollama/mistral并确保 Ollama 本地运行。业务系统连接——Hive Framework 设计上通过MCPModel Context Protocol把 CRM、客服、消息、数据、文件与内部 API 等各类业务系统以工具形式接入。集群内每个智能体都有内建工具访问权限由于 Queen 与 worker 共享同一工具表面你新增的任何能力对整个集群都可用。七、配置参考全局配置、环境变量与存储Hive 的配置通过环境变量与智能体级配置文件完成没有集中的config.yaml或 Docker Compose。完整清单见 docs/configuration.md。7.1 全局配置~/.hive/configuration.jsonquickstart.sh在安装时生成保存所有智能体默认使用的 LLM 提供商、模型与 max_tokens智能体自身config.py可覆盖{ llm: { provider: anthropic, model: claude-sonnet-4-5-20250929, max_tokens: 8192, api_key_env_var: ANTHROPIC_API_KEY }, created_at: 2026-01-15T12:00:0000:00 }默认max_tokens8192定义于framework.orchestrator.edge的DEFAULT_MAX_TOKENS。修改方式重跑quickstart.sh或直接编辑该文件。7.2 环境变量LLM 提供商真实执行至少需要其一# Anthropic主要提供商 export ANTHROPIC_API_KEYsk-ant-... # OpenAI可选经 LiteLLM 使用 GPT 模型 export OPENAI_API_KEYsk-... # OpenRouter可选 export OPENROUTER_API_KEY... # Hive LLM可选 export HIVE_API_KEY... # Cerebras / Groq可选 export CEREBRAS_API_KEY... export GROQ_API_KEY...提供商配置要点以configuration.json的llm段为例原生支持提供商DeepSeek、Mistral、Together AI、xAI、Perplexityprovider设为deepseek/mistral/together/xai/perplexitymodel用标准模型名如deepseek-chat无需api_baseOpenRouterprovider: openroutermodel用原始模型 ID如x-ai/grok-4.20-betaapi_base为https://openrouter.ai/api/v1粘贴带openrouter/前缀的模型名时 Hive 会自动规范化Hive LLMprovider: hive常见模型值queen、kimi-k2.6、kimi-k2.5、GLM-5api_base为https://api.adenhq.commax_tokens可到 32768。搜索工具可选BRAVE_SEARCH_API_KEYBrave 网页搜索、EXA_API_KEYExa 搜索。运行时标志MOCK_MODE1无 LLM 调用的结构校验模式、HIVE_CREDENTIAL_KEY~/.hive/credentials凭据库的 Fernet 加密密钥、AGENT_STORAGE_PATH自定义智能体存储路径默认~/.hive/agents/{agent_name}/。7.3 MCP 服务器配置.mcp.jsonMCP 服务器配置在项目根的.mcp.json{ mcpServers: { files-tools: { command: uv, args: [run, files_server.py, --stdio], cwd: tools }, tools: { command: uv, args: [run, mcp_server.py, --stdio], cwd: tools } } }其中files-tools服务器暴露文件 I/Oread_file、write_file、edit_file、hashline_edit、search_filesQueen/Worker 的文件操作主要通过terminal-tools服务器terminal_exec、terminal_rg/terminal_glob完成其 cwd 默认指向会话工作目录tools服务器暴露网页搜索、PDF 读取、CSV 处理等集成工具。7.4 存储布局Hive 采用基于文件的持久化无需外部数据库状态位于HIVE_HOME$HIVE_HOME/ agents/queens/queen_id/ # Queen 档案 会话 colonies/name/ # 每个集群一个自包含目录 worker.json # 集群的 worker克隆规格 data/tracker.db # 集群共享的 SQLite 账本 memories/ # 作用域 Queen 记忆global / colony / queen credentials/ # 加密凭据存储每个集群自包含于自己的目录这是其可移植性的来源可导出/导入为 tarball。存储由framework.storage.FileStorage管理无需外部数据库配置。八、常见问题FAQ精选QHive 与其他智能体框架的本质区别是什么Hive 运行的是智能体集群而非单智能体或手工连线的智能体图。多数框架强制你编译由不同节点与边组成的图Hive 只有一个执行原语——Queen 本身就是一个 agent loop每个 worker 都是它的 clone。编排是运行时的run_worker扇出而非编译后的 DAG集群通过共享 tracker 账本协同而非数据缓冲区。在这一一循环多循环核心之上Hive 是生产级 harness——崩溃安全暂停/恢复、成本强制、实时可观测性与带外 human-in-the-loop因只有一种智能体类型而被每个智能体继承。QHive 支持 human-in-the-loop 工作流吗支持。Queen 通过Sentinel账号绑定的 Slack/Telegram 频道向人类带外升级。agent loop 暂停状态持久化到磁盘、通知人类回复后从断点精确恢复。由于升级不是图中的节点集群内任何智能体都可在任意点暂停等待人工决策并支持可配置的超时与升级策略。QHive 支持哪些编程语言Framework 由 Python 构建JavaScript/TypeScript SDK 在路线图上见 docs/roadmap.md。Q成本控制如何工作Hive 提供细粒度预算控制花费上限、限流与自动模型降级策略可在团队、智能体或工作流级别设置预算并具备实时成本追踪与告警。QHive 是开源的吗是。Hive 完全基于 Apache License 2.0 开源见 LICENSE并积极鼓励社区贡献。九、可靠性内建于原语因为所有参与者都是同一个 loopharness 特性只需实现一次、处处继承详见 architecture/README.md 的 Reliability is in the primitive暂停/恢复——循环将游标持久化到磁盘在ASK_USER、CREDENTIAL_FORM、COLONY_SUGGESTION、USER_STOPPED、COLD_INTERRUPTED、LLM_ERROR、DOOM_LOOP等状态下暂停磁盘是事实来源崩溃或重启精确续跑上下文管理——保留结构的压缩compaction与工具结果指针模式pointer pattern大结果落盘对话中只保留紧凑文件引用Agent 通过load_data()按需解引用≤30KB的结果直接透传并附[Saved to …]标注更大的结果以预览 load_data(...)指针替换指针可穿越压缩存活停滞与死循环检测——TTFT/事件间隔流看门狗 n-gram 相似度检查捕获卡住的轮次与重复工具调用裁判门控终止judge-gated termination——三级裁判管线judge_pipeline.pyLevel 0 检查必需输出键与待执行工具Level 1 自定义JudgeProtocol拥有完全判定权Level 2 隐式质量门按 success criteria 判定。RETRY的反馈以[Judge feedback]用户消息注入对话下一轮循环同时看到上次尝试与批评并自我修正——这就是会话内反思reflexion自纠错机制无需重训模型。十、安全、贡献与许可证安全安全相关担忧请参阅 SECURITY.md。贡献社区贡献受到欢迎尤其鼓励为 framework 编写工具、集成与示例智能体。流程为搜索/创建 issue 并获取指派重要提交 PR 前必须先让人指派 issue避免重复劳动→ fork 仓库 → 创建特性分支git checkout -b feature/amazing-feature→ 提交git commit -m Add amazing feature→ 推送 → 打开 PR。详细指南见 CONTRIBUTING.md。许可证本项目基于Apache License 2.0发布见 LICENSE。延伸阅读开发者指南——面向开发者的全面指南开始使用——快速设置说明配置指南——全部配置选项架构概览——系统的设计与结构The Colony、The Queen、The Worker Agent、The Loop、Coordination、Goals Outcomes、How a Colony Improves——核心概念系列赞分享人工智能AI Agent多智能体MCP 服务工具调用浏览器控制【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址https://gitcode.com/gh_mirrors/hive48/hive点击查看免费下载相关推荐Hive 多智能体生产运行时Multi-Agent Harness完整指南Colony 集群模型、Queen/Worker 架构与零配置快速上手Hive 多智能体生产运行时Multi Agent Harness完整指南Colony 集群模型、Queen/Worker 架构与零配置快速上手 本篇技术人工智能AI Agent多智能体MCP 服务工具调用浏览器控制Hive 多智能体生产级 Harness 实战指南从 Colony 架构到快速上手Hive 多智能体生产级 Harness 实战指南从 Colony 架构到快速上手 导读 Hive 是一个面向生产环境的开源多智能体Multi Agent人工智能AI Agent多智能体MCP 服务工具调用浏览器控制Hive 快速上手指南从零搭建生产级多智能体框架并构建你的第一个 AgentHive 快速上手指南从零搭建生产级多智能体框架并构建你的第一个 Agent 本文是 Aden HiveMulti Agent Harness for Pr人工智能AI Agent多智能体MCP 服务工具调用浏览器控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考