人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载导读本文围绕openjiuwen.agent_teams多智能体团队编排框架系统讲解以TeamAgentSpec为核心的配置体系——从团队级配置生命周期、成员模式、运输层、存储层到成员级DeepAgentSpec模型、工具、Guardrail、多模态再到团队构建与冷启动/恢复的运行路径。读完本文你将能够独立编写一份可运行的团队 YAML/JSON 配置、通过TeamAgentSpec.model_validate()加载并build()出可直接执行任务的 Leader 智能体并理解Runner.run_agent_team_streaming()与TeamAgent.recover_from_session()在会话恢复场景中的分工。一、openjiuwen.agent_teams 模块概览openjiuwen.agent_teams是 openJiuwen agent-core 中负责多智能体团队编排的 SDK 模块。与单智能体DeepAgent不同团队场景引入了一位 Leader 与若干 Teammate 的分工结构Leader 负责接收任务、调度成员、审批关键操作Teammate 负责实际执行子任务。整个团队由一份JSON 可序列化的规范Spec描述核心入口是TeamAgentSpec。模块的官方 API 文档结构如下本文引用路径均为相对仓库根目录的全局路径文档说明agent_teams.mdAgentTeams 公开接口TeamAgentSpec、DeepAgentSpec、LeaderSpec等schema/schema.md团队配置子结构VisionModelSpec、AudioModelSpec、WorkspaceSpec、RailSpec、SubAgentSpec、TeamModelConfig等schema/deep_agent_spec.mdTeamModelConfig模型配置详情rails/team_permission_rail.md团队权限 RailLeader 审批编排与确认响应模型tools/tool_permissions.mdLeader / Teammate / Human Agent 的内置协作工具集在源码侧openjiuwen/agent_teams/目录见 openjiuwen/agent_teams/schema/blueprint.py承载了上述 API 的全部实现包括团队蓝图blueprint.py、成员拓扑schema/team.py、团队 Agent 运行时agent/team_agent.py以及团队级 Runner 入口openjiuwen/core/runner/team_runner.py。二、TeamAgentSpec团队级配置规范TeamAgentSpec是用于构建 TeamAgent 的完全 JSON 可序列化规范源码注释见 blueprint.py它把按角色划分的DeepAgentSpec与团队级配置组合在一起。agents字典的键对应TeamRole枚举值leader、teammate等其中leader键是必填的teammate可选缺省时回退使用 Leader 的配置。2.1 核心字段一览下表完整覆盖TeamAgentSpec的团队级字段默认值与约束以源码为准字段类型 / 默认值说明agentsdict[str, DeepAgentSpec]必填。按角色划分的成员配置必须包含leader键team_namestr agent_team团队名称lifecyclestr temporary团队生命周期temporary任务完成后解散或persistent跨会话保留teammate_modestr build_mode成员执行模式build_mode直接完成任务或plan_mode需要 Leader 审批计划spawn_modestr process成员启动方式process子进程或inprocess同一事件循环leaderLeaderSpec LeaderSpec()Leader 身份配置predefined_memberslist[TeamMemberSpec] []预配置成员一旦提供Leader 将跳过spawn_member工具transportTransportSpec None传输层配置storageStorageSpec None存储层配置worktreeWorktreeConfig None成员的工作树worktree隔离配置workspaceTeamWorkspaceConfig None成员共享工作区配置metadatadict[str, Any] {}附加元数据enable_permissionsbool False开启团队权限审批路径开启后由TeamPermissionRail处理 Teammate 工具权限Leader 解析ask决策2.2 运输层与存储层的可插拔设计TransportSpec与StorageSpec是团队基础设施的注册表驱动抽象实现见 blueprint.pyTransportSpectype支持inprocess、pyzmqparams传入后端特定参数。源码中_TRANSPORT_REGISTRY还内置了hybrid类型见_ensure_builtin_infra_registered()。自定义传输层可通过register_transport(name, cls)注册。StorageSpectype支持sqlite、postgresql、mysql其中memory是:memory:SQLite 的别名DatabaseConfig会把db_typememory规范化为 sqlite connection_string:memory:。自定义存储层通过register_storage(name, cls)注册。一个值得注意的联动规则源码 validator_default_transport_for_spawn_mode见 blueprint.py当spawn_modeinprocess且未显式配置transport时框架会自动物化为TransportSpec(typeinprocess)使转储出的 Spec 总是携带实际会使用的传输层而当spawn_modeprocess时transport保持None强制调用方在涉及跨进程 Teammate 时显式配置如pyzmq的跨进程后端。此外源码中TeamAgentSpec还提供了几个文档未列出的团队级增强字段均来自 blueprint.py可供深入配置evolution_enabled默认True团队自演进覆盖开关决定工作区文件中演进而来的值是否覆盖代码/数据库默认值model_pool/model_router/model_intelli_router三个互斥的模型池来源build()时展开为扁平model_pool视图分别对应轮询分配、单端点路由如 OpenRouter/LiteLLM 代理与客户端可靠路由IntelliRouterModelClient按 tpm/rpm 预算进行重试与故障转移enable_hittHuman-in-the-Team 能力上限与expose_human_agents_to_teammatesenable_bridgeBridge-Agent 能力上限本地队友通过纯文本协议对接远程独立 Agentenable_fork上下文继承checkpoint(name)、spawn_teammate的fork/fork_source/compact属性仅在spawn_modeinprocess下生效enable_swarmflow与swarmflow_budgetLeader 独享的swarmflow(script_path, args)编排工具与 Token 预算上限dispatch_modeautonomous共享任务板、成员按专长认领或scheduledLeader 预先将任务分配给具名成员由调度运行时完成每个交接。这些字段在build()时还会经过一组model_validator做早期失败校验例如model_pool/model_router/model_intelli_router三选一冲突、external_cli_agents的cli_agent重名、default_max_review_rounds 1、stale_claim_idle_timeout 0、steer_batch_size 0等确保配置错误在构建期而非运行中被发现。2.3 LeaderSpec 与 TeamMemberSpecLeaderSpecblueprint.py描述 Leader 身份字段默认值说明member_nameteam_leader成员标识符display_nameTeam Leader显示名称persona天才项目管理专家人格设定描述LeaderSpec继承自MemberSpecBase后者定义了desc公开简介会出现在其他成员的 roster 中与prompt私有工作约定只注入成员自身的系统提示词的公私分离设计。Leader 的prompt在build时固定构建团队后不再重新生成以保持 Leader 系统提示词前缀的 KV-cache 稳定。TeamMemberSpecschema/team.py用于predefined_members预定义成员字段默认值说明member_name—必填成员标识符display_name—必填显示名称role_typeteammate成员角色leader或teammate该基类限定为非 bridge 角色见源码Literal约束persona—必填人格设定描述prompt_hintNone初始提示词提示predefined_members实际是一个以role_type为判别字段的Pydantic v2 判别联合PredefinedMemberSpec可解析为BridgeMemberSpec/ExternalCliMemberSpec/TeamMemberSpec见 blueprint.py。三、DeepAgentSpec成员级配置规范DeepAgentSpec描述团队中单个 DeepAgent 的完整配置用于TeamAgentSpec.agents字典。它本身位于 harness 层openjiuwen.harness.schema.deep_agent_specopenjiuwen.agent_teams.schema.deep_agent_spec是对它的薄重导出见 openjiuwen/agent_teams/schema/deep_agent_spec.py保证既有团队导入路径兼容且指向同一对象。3.1 核心字段一览以下是文档中列出的DeepAgentSpec完整字段默认值以源码 openjiuwen/harness/schema/deep_agent_spec.py 为准字段默认值说明modelNoneLLM 模型配置TeamModelConfigcardNoneAgent 身份卡AgentCardsystem_promptNone自定义系统提示词toolsNone工具列表ToolCard或BuiltinToolSpecmcpsNoneMCP 服务器配置McpServerConfigsubagentsNone子智能体配置SubAgentSpecrailsNoneGuardrail 配置RailSpecenable_task_loopTrue源码/ 文档标False任务迭代循环开关文档对应False为默认描述注意源码当前默认值为Trueenable_async_subagentFalse异步子智能体执行开关add_general_purpose_agentFalse添加通用目的子智能体max_iterationsNone文档标15最大循环迭代次数源码当前默认None团队场景通常由上层配置给定workspaceNone工作区配置WorkspaceSpecskillsNone技能名称列表sys_operationNone系统操作配置SysOperationSpeclanguageNone语言cn或enprompt_modeNone提示词模式vision_modelNone视觉模型配置VisionModelSpecaudio_modelNone音频模型配置AudioModelSpecenable_task_planningFalse任务规划 Rail 开关restrict_to_sandboxFalse将文件操作限制在沙箱内auto_create_workspaceTrue自动创建工作区目录completion_timeout600.0慢轮次告警阈值秒None表示关闭告警progressive_toolNone渐进式工具加载配置ProgressiveToolSpecapproval_required_toolsNone需要 Leader 审批的工具名列表仅 Teammate 生效提示API 文档与当前源码在enable_task_loop文档Falsevs 源码True与max_iterations文档15vs 源码None上存在默认值差异。撰写配置时建议以当前仓库源码deep_agent_spec.py为准或在配置中显式指定避免依赖默认值的不确定性。3.2 模型配置TeamModelConfigTeamModelConfig是团队成员角色的可序列化模型配置实现见 deep_agent_spec.py字段说明model_client_config必填。模型客户端配置ModelClientConfig定义于openjiuwen.core.foundation.llmmodel_request_config可选。模型请求配置ModelRequestConfig默认None其build()方法直接构造一个Model实例Model(model_client_config..., model_config...)。ModelSpec是TeamModelConfig的别名两者指向同一类对象。3.3 Guardrail 与声明式工具RailSpec / BuiltinToolSpecRailSpec与BuiltinToolSpec都采用提供者注册表解析见 deep_agent_spec.pyRailSpectype指定 Guardrail 类型如task_planning、skill_useparams为参数。构建时通过_RAIL_PROVIDER_REGISTRY找到工厂并以factory(params, context)调用。未知类型例如旧版本 checkpoint 中已删除的 Rail会记录警告并跳过不影响其余 Rail 构建。BuiltinToolSpectype指定工具类型如web_search、web_fetchparams为构造参数。通过_TOOL_PROVIDER_REGISTRY解析未知类型会抛出ValueError。两者对应的注册 API 为register_rail_provider(name, factory)、register_tool_provider(name, factory)与register_subagent_provider(name, factory)均从openjiuwen.agent_teams重导出。内置 Rail/工具也通过 manifest 目录在此注册。四、子配置结构schema详解openjiuwen.agent_teams.schema下的子配置类通常作为 YAML/JSON 配置中的嵌套字段出现详见 schema/schema.md。4.1 VisionModelSpec 与 AudioModelSpec多模态模型VisionModelSpec视觉模型配置字段默认值说明api_keyAPI 密钥base_urlhttps://api.openai.com/v1基础 URLmodelgpt-4.1-mini模型名称max_retries3最大重试次数AudioModelSpec音频模型配置字段默认值说明api_keyAPI 密钥base_urlhttps://api.openai.com/v1基础 URLtranscription_modelgpt-4o-transcribe转写模型question_answering_modelgpt-4o-audio-preview问答模型max_retries3最大重试次数http_timeout20HTTP 超时毫秒max_audio_bytes25 * 1024 * 1024最大音频字节数acr_access_keyACR 访问密钥acr_access_secretACR 访问密钥密文acr_base_urlhttps://identify-ap-southeast-1.acrcloud.com/v1/identifyACR 基础 URL4.2 WorkspaceSpec 与 ProgressiveToolSpecWorkspaceSpec工作区配置当stable_baseTrue时工作区路径锚定在.agent_teams/workspaces/下以在临时 worktree 清理后仍然存续源码注释见 deep_agent_spec.py。字段默认值说明root_path./根目录路径languagecn语言stable_baseFalse为True时使用稳定工作区路径ProgressiveToolSpec渐进式工具暴露配置字段enabled默认True。源码中还包含search_limit默认5构建时转换为progressive_tool_enabled与tool_search_limit两个参数见 deep_agent_spec.py。4.3 SysOperationSpec 与 SubAgentSpecSysOperationSpec系统操作配置字段说明id操作 ID必填mode操作模式local或sandbox默认localwork_config本地工作配置LocalWorkConfig默认Nonegateway_config沙箱网关配置SandboxGatewayConfig默认None源码中SysOperationSpec.resolve()是幂等的 get-or-create操作成员的系统操作 ID 在会话生命周期内保持稳定团队暂停后新消息重建每个成员 harness 时会复用同一资源 ID 而非重复创建见 deep_agent_spec.py。SubAgentSpec子智能体配置字段默认值说明agent_card—必填Agent 身份卡system_prompt—必填系统提示词tools[]工具列表ToolCard或BuiltinToolSpecmcps[]MCP 服务器配置modelNone模型配置railsNoneGuardrail 配置skillsNone技能列表workspaceNone工作区配置sys_operationNone系统操作配置languageNone语言prompt_modeNone提示词模式enable_task_loopFalse任务循环开关max_iterationsNone最大迭代次数factory_nameNone工厂名称命中_SUBAGENT_PROVIDER_REGISTRY时直接由工厂构建factory_kwargs{}工厂关键字参数SubAgentSpec.build()在解析工具时会为BuiltinToolSpec生成带前缀的工具 ID{agent_card.id}.{tool_type}并支持父模型回退self.model is None时使用parent_model。五、构建与运行团队model_validate build文档明确指出构建 Leader 的唯一公开路径是TeamAgentSpec(...).build()from openjiuwen.agent_teams import TeamAgentSpec, DeepAgentSpec leader TeamAgentSpec( agents{leader: DeepAgentSpec()}, team_namedemo_team, ).build()5.1 从 YAML/JSON 加载配置TeamAgentSpec.model_validate(data: dict)继承自 PydanticBaseModel可从字典/JSON 解析配置典型场景是从 YAML/JSON 文件加载import yaml from openjiuwen.agent_teams.schema.blueprint import TeamAgentSpec with open(config.yaml) as f: cfg yaml.safe_load(f) spec TeamAgentSpec.model_validate(cfg)5.2 启动 Runner 并流式运行构建得到的是已配置好的 Leader 实例真正执行需要先启动 Runner。文档示例使用openjiuwen.core.runner.runner.Runnerfrom openjiuwen.core.runner.runner import Runner await Runner.start() leader spec.build() async for chunk in Runner.run_agent_team_streaming(leader, inputs{query: hello}): print(chunk)底层实现上Runner.run_agent_team_streaming()见 openjiuwen/core/runner/team_runner.py接受str | TeamAgentSpec | BaseAgent三种输入传TeamAgentSpec或团队名时走 TeamAgent 路径先由_get_team_runtime_manager().activate(spec, session, inputs)完成激活决策再逐 chunk 产出结果memberTrue时则进入已构建 Teammate / Human-Agent 的 spawn-only 流式路径绕过 pool 与 activate。5.3 预定义成员与存储配置示例结合测试用例如 tests/unit_tests/agent_teams/test_predefined_team.py可以写出带预定义成员的完整配置from openjiuwen.agent_teams import TeamAgentSpec, DeepAgentSpec, TeamMemberSpec, StorageSpec spec TeamAgentSpec( agents{leader: DeepAgentSpec()}, team_namepredefined_team, predefined_members[ TeamMemberSpec( member_namebackend-dev, display_nameBackend Developer, descSenior backend engineer, promptCheck tasks and start working, ), TeamMemberSpec( member_namefrontend-dev, display_nameFrontend Developer, descSenior frontend engineer, ), ], storageStorageSpec(typememory), # memory 即 :memory: SQLite )系统级端到端测试tests/system_tests/agent_swarm/agent_team_hitt_phase2_e2e.py展示了enable_hittTrue场景下如何在predefined_members中声明TeamRole.HUMAN_AGENT角色的人类成员spec TeamAgentSpec( agents{leader: DeepAgentSpec()}, team_nameTEAM_NAME, spawn_modeinprocess, enable_hittTrue, predefined_members[ TeamMemberSpec( member_nameHUMAN_AGENT_MEMBER_NAME, display_nameHuman Operator, role_typeTeamRole.HUMAN_AGENT, personaExternal user proxy for the phase-2 inbox demo, ), ], storageStorageSpec(typememory), )注意build()时的一致性校验_validate_hitt_consistency、_validate_bridge_consistency、_validate_reserved_names见 blueprint.py若predefined_members中声明了HUMAN_AGENT/PASSIVE_HUMAN角色但未开启enable_hittTrue或声明了BRIDGE_AGENT但未开启enable_bridgeTrue构建会直接报错反之开启能力上限却不预置成员是允许的可依赖运行期动态spawn_member。5.4 团队恢复persistent 生命周期与 recover_from_session文档特别强调没有专门用于恢复 persistent 团队的独立助手函数。恢复的推荐方式是复用同一份 Spec将同一份 spec 传给Runner.run_agent_team_streaming(agent_teamspec, session...)运行时基于内存池与会话 checkpoint 自动决策冷启动cold、热启动warm还是会话切换session-switch。对于需要直接拿到 Leader 实例的运维脚本底层路径是from openjiuwen.agent_teams import TeamAgent agent TeamAgent.recover_from_session(session, team_name, runtime_specspec) await agent.recover_team()TeamAgent.recover_from_session()的实现见 openjiuwen/agent_teams/agent/team_agent.py从会话命名空间读取team_name对应的 checkpoint 桶并重建 Leaderruntime_spec用于重新注入build_context与memory.embedding_config这两个字段是Field(excludeTrue)不会在 checkpoint 往返中存活缺省时直接使用恢复出的 spec从 seed 重建上下文。recover_team()则由恢复管理器完成成员状态回放。六、运行约束与最佳实践综合文档与源码以下约束与建议可提升团队配置的健壮性agents必须含leader键build()的第一步即检查缺失会抛出ValueError见 blueprint.py。spawn_mode与transport的联动inprocess自动补inprocess传输层process必须显式配置跨进程后端如pyzmq否则涉及跨进程 Teammate 时无法通信。模型池三选一model_pool、model_router、model_intelli_router互斥同时配置会在model_validate阶段报错见_validate_pool_router_exclusive。预留成员名human_agent、user等名称被运行时保留RESERVED_MEMBER_NAMES除team_leader外普通成员不得使用。持久化团队复用同一 Spec冷/热/会话切换由运行时自动决策不要为恢复编写额外的构建助手。权限审批当enable_permissionsTrue时TeamPermissionRail接管 Teammate 的工具权限Leader 负责解析ask决策Teammate 的敏感工具可在DeepAgentSpec.approval_required_tools中声明为需审批。七、总结openjiuwen.agent_teams以TeamAgentSpec为单一配置入口把团队拓扑Leader/Teammate/Human/Bridge、团队基础设施transport/storage/worktree/workspace、成员能力模型、工具、Guardrail、多模态、子智能体统一为 JSON 可序列化的 Pydantic 模型。通过model_validate()从 YAML/JSON 加载、build()物化为 TeamAgent再交由Runner.run_agent_team_streaming()执行即可在 openJiuwen agent-core 中快速搭建一套具备任务调度、成员协作、权限审批与跨会话恢复能力的多智能体团队。本文涉及的字段、默认值、校验规则与恢复路径均以当前仓库源码为据配置时若与 API 文档存在默认值出入建议以源码为准并显式声明关键参数。赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen agent-core 多 Agent 团队编排TeamAgentSpec 配置体系与构建、恢复入口实战指南openJiuwen agent core 多 Agent 团队编排TeamAgentSpec 配置体系与构建、恢复入口实战指南 openjiuwen.age人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openjiuwen.agent_teams 多智能体团队编排TeamAgentSpec 配置、构建与恢复实战指南openjiuwen.agent_teams 多智能体团队编排TeamAgentSpec 配置、构建与恢复实战指南 导读 openjiuwen.agent_t人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen AgentTeams 多智能体团队框架配置指南从 TeamAgentSpec 到团队构建、运行与恢复openJiuwen AgentTeams 多智能体团队框架配置指南从 TeamAgentSpec 到团队构建、运行与恢复 openjiuwen.agent_人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习上一篇技术架构Vanna如何通过向量检索增强生成重构SQL查询范式下一篇终极鼠标翻译神器一触即达的多语言浏览革命创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
