Hive Agent Framework 声明式 Agent 构建指南agent.json 架构、节点/边配置与执行图实战【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址: https://gitcode.com/gh_mirrors/hive48/hive本篇技术指南以 Hive Agent Framework 的framework_guide.md速查文档为主线系统讲解如何在 Hive 中以纯声明式 JSON 定义生产级多智能体工作流从agent.json的完整 Schema、节点与边的字段语义、工具访问策略到set_output合成工具、图生命周期、loop_config、数据溢出工具、Fan-Out/Fan-In 并行执行与 Judge 判定系统并深入 Hive 源码core/framework/loader/agent_loader.py、core/framework/orchestrator/等印证底层实现。读完本文你将能够独立编写、加载、校验并运行一个不包含任何 Python 业务代码的 Hive Agent。架构总览声明式 JSON 即 Agent在 Hive Agent Framework 中Agent 就是一份声明式 JSON 配置不再需要手写 Python 类、节点注册代码或启动入口。一个标准的 Agent 包结构如下exports/my_agent/ agent.json # 整个 Agent 的定义唯一必需文件 mcp_servers.json # MCP 工具服务器配置可选推荐改用 registry 引用这份架构的核心理念是没有 Python 文件没有__init__.py、__main__.py、config.py也没有nodes/目录。Agent 的执行图Graph、目标Goal、节点Node、边Edge全部由 JSON 数据驱动由框架统一加载并构建运行时。仓库中的实际模板如 examples/templates/competitive_intel_agent/agent.json、examples/templates/deep_research_agent/agent.json均遵循该结构。说明框架同时保留了基于 Python 模块的旧式 Agent 格式含agent.py、nodes/、config.py详见下文「Agent 加载机制」。声明式 JSON 是当前推荐的主流方式。Agent 加载机制AgentLoader.load()Agent 的加载入口是AgentLoader.load()它读取agent.json并据此构建完整的执行图。加载逻辑位于 core/framework/loader/agent_loader.py若目录中存在agent.json走声明式加载路径调用load_agent_config()将 JSON 校验为AgentConfigPydantic 模型再转换为GraphSpec执行图与Goal目标若存在agent.pyLegacy 格式则以Python 模块方式加载通过_import_agent_module()导入包并从模块级变量读取goal、nodes、edges、entry_node等若目录下是 colony worker 目录包含{worker_name}.json这类 worker 配置load()会自动解析第一个 worker JSON 并构建最小GraphSpec。加载完成后AgentLoader通过run()一次性、阻塞式执行供hive run与程序化调用使用或start()trigger()长生命周期运行时供前端/女王会话使用来驱动执行。加载阶段还会执行预加载校验run_preload_validation与凭据校验缺失必要凭据时会快速失败并给出可操作的提示。从源码看声明式与旧式导出的关键区分点是顶层是否带name键声明式agent.json顶层为name/goal/nodes/edges/entry_node/terminal_nodes等旧式导出顶层为graph/goal两个键。load_agent_config()与load_agent_export()分别处理这两种格式见 core/framework/loader/agent_loader.py。agent.json Schema 全字段详解agent.json的完整结构如下来自 framework_guide 的示例可原样复制使用{ name: my-agent, version: 1.0.0, description: What this agent does, goal: { description: What to achieve, success_criteria: [criterion 1, criterion 2], constraints: [constraint 1] }, identity_prompt: You are a helpful agent., conversation_mode: continuous, loop_config: { max_iterations: 100, tool_call_budget: 30, max_context_tokens: 32000 }, mcp_servers: [ {name: hive_tools}, {name: gcu-tools} ], variables: { spreadsheet_id: 1ZVx... }, nodes: [...], edges: [...], entry_node: process, terminal_nodes: [] }该 Schema 在仓库中的权威定义是 core/framework/schemas/agent_config.py 中的AgentConfigPydantic 模型各字段语义如下字段类型默认值说明namestr必填Agent 名称versionstr1.0.0配置版本号descriptionstrNoneAgent 用途描述goalobject必填目标定义description要达成的目标、success_criteria成功标准列表、constraints硬约束列表identity_promptstrAgent 级身份提示词连续对话模式下的静态身份层conversation_modestrcontinuous对话模式见「连续对话模式」一节loop_configobject见下执行循环配置仅三个合法键mcp_serverslist[]MCP 服务器引用列表按名称从~/.hive/mcp_registry/解析variablesdict{}模板变量注入到 system_prompt 与 identity_promptnodeslist必填节点定义列表edgeslist必填边定义列表entry_nodestr必填起始节点 IDterminal_nodeslist[]终止节点 ID 列表[]表示常驻 Agententry_pointslist[]入口点列表省略时自动创建一个default手动入口toolsobjectexplicitAgent 级工具默认策略节点未覆盖时继承modelstrNone指定模型缺省读取全局配置max_tokensint4096LLM 响应最大 token 数max_cost_per_runfloatNone单次运行的资源上限可选pipelinedict{}按 Agent 覆盖 pipeline 阶段与全局 pipeline 配置同格式关键实现细节goal的转换load_agent_config()会把success_criteria逐条转换为SuccessCriterion(idsc-{i}, metricllm_judge)把constraints转换为Constraint(constraint_typehard, categorygeneral)构成Goal模型。loop_config默认值AgentConfig的默认loop_config为{max_iterations: 100, tool_call_budget: 30, max_context_tokens: 180_000}framework_guide 示例中的32000是可调小以节省上下文的实践值。mcp_servers解析AgentLoader._setup()会从agent.json读取mcp_servers引用列表交给McpRegistryStage在运行时启动对应 MCP 服务器并注册其工具MCP 工具不在加载时注册而是在AgentHost.start()的 pipeline 阶段注入。Agent 级tools继承若某节点未显式声明工具策略则回退继承 Agent 顶层tools配置见load_agent_config中nc.tools.policy explicit and nc.tools.allowed之外的分支逻辑。模板变量{{variable_name}}system_prompt与identity_prompt支持{{variable_name}}占位符变量在顶层variables对象中定义加载时统一解析替换{ variables: {sheet_id: 1ZVx...}, nodes: [{ id: start, system_prompt: Use sheet: {{sheet_id}} }] }适用场景包括需要注入到提示词中的配置值如 Google Sheets 的 spreadsheet_id、API 端点、账户名等避免把环境相关值硬编码进提示词。源码实现_resolve_template_vars()core/framework/loader/agent_loader.py使用正则\{\{(.?)\}\}匹配占位符替换为variables中对应键的值未命中的占位符保持原样不会报错。该函数会同时应用于每个节点的system_prompt与顶层的identity_prompt。Node 字段执行图的基本单元NodeConfig声明式 Schema 定义与NodeSpec运行时规格见 core/framework/orchestrator/node.py共同定义了节点的完整字段语义字段类型默认值说明idstr必填节点标识使用 kebab-casenamestrid展示名称descriptionstr必填节点职责描述node_typestrevent_loop节点类型声明式场景目前为event_loopLLM 驱动的编排循环input_keyslist[]本节点从共享内存/输入读取的键output_keyslist[]本节点通过set_output写入的键system_promptstrLLM 指令toolsobject{}工具访问策略见下一节nullable_output_keyslist[]允许保持未设置的输出键max_node_visitsint1单次图运行中本节点的最大执行次数0 不限用于常驻 Agentsuccess_criteriastr面向 Judge 评估的自然语言完成标准client_facingboolfalse输出是否直接展示给用户当前已废弃见下max_iterationsint30节点内循环最大迭代数skip_judgeboolfalse为 true 时完全跳过 Judge用于女王这类对话节点max_retriesintNone节点失败重试次数modelstrNone指定该节点使用的模型缺省继承图默认几个需要特别注意的语义max_node_visits的两种默认声明式NodeConfig默认1一次性执行0表示无限forever-alive Agent而底层NodeSpec默认0无限。load_agent_config()仅在值不等于1时才显式透传该字段。配合terminal_nodes: []即可构建常驻 Agent如女王下属的持续处理节点。client_facing已废弃NodeSpec.is_queen_node()规定只有 id 为queen的节点允许直接与用户交互supports_direct_user_io()只对女王流返回 True。对非女王节点设置client_facing: true会触发deprecated_client_facing_warning()的兼容性警告正确做法是worker 的审查与提问一律通过 escalate 升级给女王处理。input_keys/output_keys的权限语义NodeContext通过DataBuffer.with_permissions()为每个节点创建受限视图——节点只能读取input_keys、写入output_keys越权读写会抛PermissionError见 core/framework/orchestrator/node.py。工具访问策略explicit / all / none每个节点通过 policy 对象声明自己的工具访问范围{tools: {policy: explicit, allowed: [web_search, save_data]}} {tools: {policy: all}} {tools: {policy: none}}三种策略的语义explicit默认只允许allowed列表中列出的工具allowed为空列表 零工具。推荐用于绝大多数节点。all允许注册表中的全部工具典型用于浏览器自动化节点。none不授予任何工具典型用于 handoff/总结类节点。NodeSpec.tool_access_policy字段的官方描述同样支持allall tools from registry、explicit仅列出工具、none无工具三档。版本注意framework_guide 允许policy: all但当前仓库的声明式 Schemacore/framework/schemas/agent_config.py中ToolAccessConfig的_reject_policy_all校验器会拒绝policy all强制要求把用到的工具逐一列进allowed以确保 Agent 只暴露真正需要的工具面。从当前代码结构看声明式agent.json/agent.yaml中应使用explicit列表或none如需浏览器自动化全量工具面需确认运行版本对all的支持方式。这也是anti_patterns.md中「不要在tools里写escalate/set_output」的原因——它们是框架合成工具运行时自动注入只需要在allowed中列出list_agent_tools()返回的真实 MCP 工具。Edge 字段与条件路由边Edge定义节点之间的流转关系。声明式字段如下字段类型说明from_nodestr源节点 IDto_nodestr目标节点 IDconditionstron_success、on_failure、always、conditional及底层支持的llm_decidecondition_exprstr条件路由时求值的 Python 表达式priorityint优先级值越大越先求值condition_expr的典型用法needs_more_research Truestr(next_action).lower() revise底层实现core/framework/orchestrator/edge.pyEdgeCondition枚举定义五种条件EdgeSpec.should_traverse()依次判断always恒为真on_success依赖源节点成功on_failure依赖源节点失败conditional调用_evaluate_condition()对condition_expr求值llm_decide则把当前目标、输出、buffer 上下文交给 LLM 做目标感知的路由决策LLM 不可用时回退为on_success。条件表达式在受限的沙箱环境中求值——通过safe_evalAST 白名单执行见 core/framework/orchestrator/safe_eval.py求值上下文包含output源节点输出字典buffer共享数据缓冲区resultoutput.get(result)快捷引用true/false允许表达式书写小写布尔值以及buffer 中所有键的直接展开——因此next_action这类由set_output写入的键可以直接在表达式中引用。多个出边按priority降序求值get_outgoing_edges()按-priority排序。声明式EdgeConfig的默认priority为1底层EdgeSpec默认0。关键模式Key Patterns少而丰富的节点CRITICAL硬性要求 3-6 个节点绝大多数 Agent 的节点数硬性上限是 3-6 个。每个节点边界都会序列化输出、破坏上下文中的信息。除非满足以下条件之一否则应当合并节点客户端边界不同的交互模型工具集完全不重叠需要并行执行fan-out 分支。典型双节点结构process (autonomous) - review (queen-mediated)其中女王queen拥有 intake接收用户请求的职责worker Agent 不应设置面向客户的 intake 节点执行中途的 review 应通过女王升级escalation完成而不是让 worker 直接与用户对话。这与anti_patterns.md的 worker 错误清单一致「给 worker 添加 client-facing intake 节点」是反模式。set_output 合成工具set_output是框架注入的合成工具不需要也不能在节点tools列表中声明必须与真实工具调用分开、在独立的一轮turn中调用anti_patterns.md明确将「在调用工具的同轮调用 set_output」列为设计错误set_output(key, value)将值写入共享缓冲区DataBufferkey必须是该节点output_keys中声明的键。实现细节core/framework/agent_loop/internals/synthetic_tools.pybuild_set_output_tool()仅为声明了output_keys的节点生成set_output工具参数key使用enum限定为合法的输出键handle_set_output()会对非法键返回错误结果并具备从截断 JSON 中恢复key/value的容错逻辑_raw字段兜底。工具描述还提示值超过约 2000 字符时会被自动保存到数据文件此时应传文件名而非大段文本与「数据工具」一节呼应。图生命周期Graph Lifecycle模式terminal_nodes适用场景连续循环Continuous loop[node-with-output-keys]所有 Agent 的默认模式线性Linear[last-node]一次性/批处理 Agent每个图必须至少有一个终止节点GraphSpec.validate()会对空terminal_nodes给出警告但常驻 Agent 可有意用[]配合max_node_visits: 0实现 forever-alive。GraphSpec.validate()还会校验入口/终止节点是否存在、边引用的源/目标是否存在、是否存在不可达节点、并行event_loop节点的 output_keys 是否重叠见「Fan-Out / Fan-In」。连续对话模式Continuous Conversation Modeconversation_mode只有两个合法状态continuous—— 推荐。对话上下文跨节点流转同一会话贯穿所有event_loop节点工具累积、提示词分层组合完全省略该字段 —— 每个节点使用隔离的独立对话。非法取值client_facing、interactive、shared。声明式 Schema 的默认值即为continuousGraphSpec.conversation_mode的官方描述也是continuous默认/isolated二选一见 core/framework/orchestrator/edge.py。loop_config仅三个合法键loop_config只允许以下三个键{ max_iterations: 100, tool_call_budget: 20, max_context_tokens: 32000 }键默认值含义max_iterations100节点循环的最大迭代次数NodeConfig.max_iterations默认 30属节点级tool_call_budget30单轮/单次运行中允许的工具调用预算max_context_tokens180000上下文窗口上限示例中的 32000 是控制成本的实践值该配置最终挂载到GraphSpec.loop_config并传递给EventLoopNode的执行循环。数据工具溢出Spillover当数据量超出上下文窗口时使用以下数据工具将大对象落盘并按需分页读取save_data(filename, data)—— 写入会话数据目录load_data(filename, offset, limit)—— 分页读取list_data_files()—— 列出数据文件serve_file_to_user(filename, label)—— 向用户提供可点击的文件 URI。data_dir由框架自动注入无需在配置中声明。与set_output配合的推荐用法是大结果先save_data落盘set_output只传递文件名引用如google_sheets_get_values_1.txt下一阶段再用load_data加载——这正是set_output工具描述中「传文件名而非大段文本」的设计意图。数据目录会随 Agent 运行环境创建于会话存储路径下~/.hive/agents/agent_name/见AgentLoader的_storage_path逻辑。Fan-Out / Fan-In 并行执行从同一源节点出发的多条on_success边 并行执行fan-out。GraphSpec.detect_fan_out_nodes()会识别出带多条ON_SUCCESS出边的节点detect_fan_in_nodes()则识别汇聚节点fan-in等待所有前驱分支完成。并行硬性约束并行节点的 output_keys 必须互不重叠disjoint。GraphSpec.validate()会检查 fan-out 的多个event_loop目标节点是否存在输出键冲突并报错Fan-out from source_id: event_loop nodes A and B both write to output_key key. Parallel event_loop nodes must have disjoint output_keys to prevent last-wins data loss.此外DataBuffer.write_async()提供按 key 的锁保证并行写入时无竞态见 core/framework/orchestrator/node.py。Judge 系统判定节点是否完成Implicit隐式默认当 LLM 结束且没有产生工具调用、同时所有必需输出键均已设置时判定 ACCEPT若有真实工具调用则继续循环RETRY若输出键缺失则注入 RETRY 反馈提示补全见 core/framework/agent_loop/internals/judge_pipeline.py 的隐式判定逻辑。SchemaJudge针对 Pydantic 模型做结构化校验framework_guide 文档说明。judge_turn()的完整评估层级为Level 0 短路mark_complete、skip_judge、工具延续→ Level 1 自定义 JudgeJudgeProtocol→ Level 2 隐式 Judge输出键检查 可选的自然语言success_criteria质量门。当节点声明success_criteria时隐式 Judge 升级为 Level 2输出键满足后再由一次快速的 LLM 评估对话是否达成该自然语言标准见NodeSpec.success_criteria的字段描述。nullable_output_keys中的键允许保持未设置而不触发校验失败。工具发现与打包验证永远先调用list_agent_tools()查看当前可用的工具不要依赖静态工具清单MCP 服务器可能随注册表变化而增减工具list_agent_tools() # 完整摘要 list_agent_tools(groupgmail, output_schemafull) # 深入某个类别list_agent_tools由工具注册表暴露见 core/framework/loader/tool_registry.py 中对hive_tools等 MCP 服务器的导出说明。它返回的是运行时实际注册的工具面因此能避免「虚构工具」类错误——anti_patterns.md点名的常见幻觉工具包括csv_read、csv_write、file_upload、database_query、bulk_fetch_emails等并不存在的名称。构建完成后运行validate_agent_package({name})对 Agent 包做整体校验。该流程覆盖图结构合法性入口/终止节点、边引用、可达性、并行键冲突、目标是否定义成功标准、必需工具是否已注册、以及工具与节点类型所需的凭据是否就绪AgentLoader.validate()见 core/framework/loader/agent_loader.py。校验结果以ValidationResult形式返回errors、warnings、missing_tools、missing_credentials其中valid为 false 时会阻止run()执行。常见反模式速查结合 core/framework/agents/queen/reference/anti_patterns.md编写 Agent 时应规避使用不存在的工具——先list_agent_tools()验证错误的 mcp_servers.json 格式——扁平 dict 而非mcpServers包装command应为uv且 args 为[run, python, ...]cwd指向../../tools虚构工具——构建前list_agent_tools()、构建后validate_agent_package()在同一轮调用 set_output 与真实工具——分轮调用给 worker 添加 client-facing intake 节点——intake 归女王worker 从自主处理节点开始审查/审批走女王升级把escalate或set_output写进节点tools列表——它们是运行时自动注入的框架合成工具对 forever-alive Agent 调用runner.run()——没有终止节点会永远挂起应改写结构化测试校验图结构、节点规格、AgentLoader.load()能否成功依赖缺失凭据跑集成测试——用pytest.skip()跳过。更完整的声明式配置参考含process/handoff双节点、反馈环next_action revise、升级环next_action escalated、entry_points定时触发器、GCU 浏览器节点与 YAML 迁移说明见 core/framework/agents/queen/reference/file_templates_declarative.md。总结Hive Agent Framework 用一份agent.json取代了传统数百行的 Python Agent 样板代码nodes/edges声明执行图goal声明目标与成功标准工具策略与loop_config控制执行边界set_output与数据工具桥接上下文与外部存储隐式/自定义 Judge 判定完成状态list_agent_tools()与validate_agent_package()保证构建正确性。遵循「3-6 个节点」「连续对话」「女王持有 intake」三条铁律即可用纯声明式配置构建可运行、可校验、可并行扩展的生产级 Agent。【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址: https://gitcode.com/gh_mirrors/hive48/hive创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
