人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载openjiuwen.agent_teams.schema.deep_agent_spec是 openJiuwenagent-core中负责团队角色team role可序列化声明式规格的模块它定义了一张冷构造蓝图把模型的连接信息、请求参数、工具、护栏rail、子智能体等全部折叠成 JSON 可序列化的 Pydantic 模型再通过build()/resolve_parts()还原成可运行的DeepAgent。读完本文你将掌握TeamModelConfig的字段语义与构造原理、DeepAgent 规格树的完整字段清单、能力提供者注册机制以及它在TeamAgentSpec团队装配流程中的实际落地方式。一、模块定位为什么agent_teams.schema.deep_agent_spec是一个薄再导出层从模块源码的模块注释可以确认openjiuwen/agent_teams/schema/deep_agent_spec.py 是一个为保持团队侧既有导入路径兼容而保留的再导出re-export层DeepAgentSpec、RailSpec、BuiltinToolSpec、SubAgentSpec以及它们的叶子类型TeamModelConfig、WorkspaceSpec、VisionModelSpec、AudioModelSpec、ProgressiveToolSpec、SysOperationSpec等的真源source of truth位于 harness 层openjiuwen/harness/schema/deep_agent_spec.py。再导出层保证from openjiuwen.agent_teams.schema.deep_agent_spec import DeepAgentSpec与from openjiuwen.harness.schema.deep_agent_spec import DeepAgentSpec拿到的是同一个类对象is恒等跨导入路径的恒等判断不受影响。团队拓扑相关的规格TeamSpec/TeamAgentSpec/ blueprint.py则保留在agent_teams侧不参与这次再导出。openjiuwen/agent_teams/schema/__init__.py进一步汇总了两类规格的公开导出面团队拓扑类DeepAgentSpec、LeaderSpec、StorageSpec、TeamAgentSpec、TransportSpec、register_storage、register_transport等来自blueprint以及本模块再导出的能力规格类AudioModelSpec、ProgressiveToolSpec、RailSpec、SubAgentSpec、SysOperationSpec、VisionModelSpec、WorkspaceSpec。二、TeamModelConfig团队角色的可序列化模型配置本文档核心TeamModelConfig是本 API 文档页面的主体内容它的定义与语义如下openjiuwen.agent_teams.TeamModelConfig—— 团队角色的可序列化模型配置Serializable model configuration for a team role。属性model_client_configModelClientConfig模型客户端配置必填。model_request_configModelRequestConfig可选模型请求配置默认None。在 harness 层源码中它是这样一个 Pydantic 模型openjiuwen/harness/schema/deep_agent_spec.pyclass TeamModelConfig(BaseModel): Serializable model configuration for a team role. model_client_config: ModelClientConfig model_request_config: Optional[ModelRequestConfig] None def build(self) - Model: Create a Model instance from this config. return Model( model_client_configself.model_client_config, model_configself.model_request_config, )两个关键点build()是配置到运行时的分界线TeamModelConfig本身是纯数据、可 JSON 序列化调用build()后才会构造出openjiuwen.core.foundation.llm.Model实例模型客户端client_provider的注册与选择发生在Model内部详见下文第四节。ModelSpec是TeamModelConfig的别名源码中ModelSpec TeamModelConfig明确注释为与 harness 命名约定对齐ModelSpec是给希望使用模型层名称的调用方的规范导入。两个名字指向同一个类对象因此is恒等成立。2.1 在 DeepAgentSpec / SubAgentSpec 中的使用方式TeamModelConfig不是孤立存在的它被挂在角色规格的model字段上DeepAgentSpec.model: Optional[TeamModelConfig]默认为None此时由团队装配方注入成员级模型见第六节agent_configurator的ctx.member_model or agent_spec.model回退逻辑SubAgentSpec.model: Optional[TeamModelConfig]默认为None子智能体构建时若self.model为None则回退到父智能体的模型build(parent_modelllm_model, ...)中的parent_model参数openjiuwen/harness/schema/deep_agent_spec.py。这保证了一个团队角色一套模型配置的声明式表达只需在规格里写清楚客户端与请求参数构造流程会负责把它物化为可调用的Model。三、配置底层的两个数据类ModelClientConfig 与 ModelRequestConfigTeamModelConfig的两个属性分别来自openjiuwen.core.foundation.llm。其完整字段定义见 API 文档 docs/en/2.Development Guide/API Docs/openjiuwen.core/foundation/llm/llm.mdModelClientConfig客户端配置数据类字段类型默认值说明client_idstruuid.uuid4()自动生成Runner 中注册的唯一客户端标识client_providerUnion[ProviderType, str]必填提供方标识内置枚举值OpenAI、OpenAIAccount、SiliconFlowapi_keystr当client_provider为OpenAIAccount时可省略其余内置提供方必填api_basestr必填API 基地址所有内置提供方含OpenAIAccount都要求显式提供不会自动填充默认值timeoutfloat60.0请求超时秒须大于 0max_retriesint3最大重试次数verify_sslboolTrue是否校验 SSL 证书ssl_certstr可选None当verify_sslTrue时需要的证书路径ModelRequestConfig单次请求参数配置数据类字段类型默认值说明model_namestr模型名别名modeltemperaturefloat0.95采样温度取值范围 [0, 1]top_pfloat0.95top_p 采样参数取值范围 [0, 1]max_tokensint可选None最大生成 token 数stopstr可选None停止序列一个典型的TeamModelConfig构造示例字段取值对齐上述文档from openjiuwen.core.foundation.llm import ModelClientConfig, ModelRequestConfig from openjiuwen.agent_teams.schema.deep_agent_spec import TeamModelConfig team_model TeamModelConfig( model_client_configModelClientConfig( client_idteam_llm, client_providerOpenAI, api_keyyour_api_key, api_basehttps://api.openai.com/v1, timeout60.0, max_retries3, verify_sslTrue, ), model_request_configModelRequestConfig( model_nameyour_model_name, temperature0.7, max_tokens1024, ), ) model team_model.build() # - openjiuwen.core.foundation.llm.Model四、DeepAgent 规格树从叶子类型到根规格除TeamModelConfig外本模块还再导出了一整套能力叶子类型。以下字段与默认值均取自 openjiuwen/harness/schema/deep_agent_spec.py 的类定义。4.1 叶子规格Leaf SpecVisionModelSpec视觉模型配置对应VisionModelConfigdataclassapi_key、base_urlDEFAULT_OPENAI_BASE_URL、modelDEFAULT_OPENAI_VISION_MODEL、max_retries3build()返回VisionModelConfig。AudioModelSpec音频模型配置对应AudioModelConfigapi_key、base_urlDEFAULT_OPENAI_BASE_URL、transcription_modelDEFAULT_OPENAI_AUDIO_TRANSCRIPTION_MODEL、question_answering_modelDEFAULT_OPENAI_AUDIO_QA_MODEL、max_retries3、http_timeoutDEFAULT_AUDIO_HTTP_TIMEOUT、max_audio_bytesDEFAULT_MAX_AUDIO_BYTES、acr_access_key、acr_access_secret、acr_base_urlDEFAULT_ACR_BASE_URLbuild()返回AudioModelConfig。上述默认常量定义于 openjiuwen/harness/schema/config.pyDEFAULT_OPENAI_BASE_URL https://api.openai.com/v1 DEFAULT_OPENROUTER_VISION_MODEL google/gemini-2.5-pro DEFAULT_OPENAI_VISION_MODEL gpt-4.1-mini DEFAULT_OPENAI_AUDIO_TRANSCRIPTION_MODEL gpt-4o-transcribe DEFAULT_OPENAI_AUDIO_QA_MODEL gpt-4o-audio-preview DEFAULT_ACR_BASE_URL https://identify-ap-southeast-1.acrcloud.com/v1/identify DEFAULT_AUDIO_HTTP_TIMEOUT 20 DEFAULT_MAX_AUDIO_BYTES 25 * 1024 * 1024此外VisionModelConfig与AudioModelConfig还各自提供from_env()工厂方法支持从VISION_API_KEY/AUDIO_API_KEY/OPENAI_API_KEY等环境变量一键装配见 openjiuwen/harness/schema/config.py 与 openjiuwen/harness/schema/config.py。WorkspaceSpec工作区规格root_path./、languagecn、stable_baseFalse。注释明确stable_baseTrue团队成员的默认情形时工作区根被解析为{repo_root}/.agent_teams/workspaces/从而在临时 worktree 清理后仍然存活build()返回Workspace。ProgressiveToolSpec渐进式工具暴露配置enabledTrue、search_limit5。挂到DeepAgentSpec.progressive_tool上即启用渐进式工具加载resolve_parts()会将其转换为progressive_tool_enabled与tool_search_limit两个配置_progressive_tool_kwargs()。SysOperationSpec系统操作规格id必填、modeOperationMode.LOCAL、work_configNone、gateway_configNone。resolve()是幂等的 get-or-create成员的系统操作 id 在会话生命周期内保持稳定团队暂停后由新消息重建成员 harness 时会重新解析到同一资源openjiuwen/harness/schema/deep_agent_spec.py。4.2 声明式能力引用RailSpec 与 BuiltinToolSpecRailSpec与BuiltinToolSpec都是通过类型名 参数声明式引用能力的规格结构完全镜像type: str必填params: dict[str, Any] {}。RailSpec.build()从_RAIL_PROVIDER_REGISTRY按type取工厂并调用factory(dict(self.params), context)未知类型例如旧版本持久化的、当前版本已移除的 rail只记 warning 并返回None不影响其余 rail 构建openjiuwen/harness/schema/deep_agent_spec.py。BuiltinToolSpec.build()从_TOOL_PROVIDER_REGISTRY取工厂未知类型抛出ValueError并列出已注册类型清单openjiuwen/harness/schema/deep_agent_spec.py。tool_id参数保留给成员级工具 id 命名空间实际按 agent 限定的 id 在AbilityManager.add_ability注册阶段完成有状态工具拿到 agent 限定 id无状态工具共享裸 id。4.3 能力提供者注册机制三个模块级注册表由三个注册函数驱动openjiuwen/harness/schema/deep_agent_spec.pyregister_rail_provider(name, factory)按RailSpec.type引用工厂签名为factory(params, context)可返回单个 rail 或 rail 列表register_tool_provider(name, factory)按BuiltinToolSpec.type引用签名同上register_subagent_provider(name, factory)按SubAgentSpec.factory_name引用工厂签名factory(factory_kwargs, context)返回SubAgentConfig或列表采用 opt-in 解析——只有factory_name命中注册表时才走工厂路径既有的 factory 名称不受影响。注释还强调内置 rail / tool / sub-agent 同样通过 manifest 目录在这里注册不再存在单独的类注册表同一名称的重复注册以后者覆盖前者。构建结果由_as_built_list()归一化为扁平列表并丢弃None空列表即视为跳过该能力。4.4 SubAgentSpec子智能体规格字段清单openjiuwen/harness/schema/deep_agent_spec.pyagent_card: AgentCard必填、system_prompt: str必填、tools: list[ToolCard | BuiltinToolSpec] []、mcps: list[McpServerConfig] []、model: Optional[TeamModelConfig] None、rails: Optional[list[RailSpec]] None、skills: Optional[list[str]] None、workspace: Optional[WorkspaceSpec] None、sys_operation: Optional[SysOperationSpec] None、language: Optional[str] None、prompt_mode: Optional[str] None、enable_task_loop: bool False、max_iterations: Optional[int] None、factory_name: Optional[str] None、factory_kwargs: dict[str, Any] {}。其build(parent_model, language, context)的解析顺序很有代表性openjiuwen/harness/schema/deep_agent_spec.py若factory_name命中_SUBAGENT_PROVIDER_REGISTRY直接由工厂构造否则依次解析model回退parent_model、workspace、rails逐个RailSpec.build并展平sys_operation通过resolve()幂等解析工具解析BuiltinToolSpec以{agent_card.id 或 name}.{type}作为工具 id 前缀构造ToolToolCard直接透传最后组装为运行时SubAgentConfig。4.5 DeepAgentSpec根规格与完整字段DeepAgentSpec的类注释明确了它的核心契约openjiuwen/harness/schema/deep_agent_spec.py用于构造 DeepAgent 的完全 JSON 可序列化规格。使用model_dump_json()序列化以便网络分发使用model_validate_json()反序列化后调用build()即可获得活的DeepAgent实例。完整字段清单默认值即源码默认值字段类型默认值语义要点modelOptional[TeamModelConfig]None角色模型配置见第二节cardOptional[AgentCard]None智能体身份卡system_promptOptional[str]None注入 ReAct 提示模板的系统提示词toolsOptional[list[ToolCard | BuiltinToolSpec]]None挂载工具卡或声明式引用mcpsOptional[list[McpServerConfig]]NoneMCP 服务器配置subagentsOptional[list[SubAgentSpec]]None子智能体规格railsOptional[list[RailSpec]]None护栏规格列表enable_task_loopboolTrue是否启用外层任务循环enable_async_subagentboolFalse异步子智能体模式True时 SubagentRail 注册会话级 spawn 工具enable_subagent_runtimeboolFalse持久子智能体运行时工具spawn/wait/list优先于enable_async_subagentadd_general_purpose_agentboolFalse是否额外挂一个通用型子智能体enable_security_railboolTrue是否启用安全护栏enable_tool_resilience_railboolTrue工具调用韧性护栏可重试失败的有限重试写/shell/spawn 等非幂等工具永不重试max_iterationsOptional[int]None单次 invoke 的内层 ReAct 迭代上限None表示不设限源码中映射为sys.maxsizeworkspaceOptional[WorkspaceSpec]None智能体自身产物的工作区不是shell 工作目录cwdOptional[str]Noneshell 命令运行目录 / 相对路径基准默认工作区根project_rootOptional[str]None项目身份锚点默认cwd用于访问边界检查而非路径解析skillsOptional[list[str]]None技能定义agent_template_specdict | NoneNone序列化的AgentTemplateSpec由异步 harness 宿主应用NativeHarness在成员运行前会重新校验enable_skill_discoveryboolFalse是否启用技能发现sys_operationOptional[SysOperationSpec]None系统操作规格languageOptional[str]None语言经resolve_language解析prompt_modeOptional[str]None提示词模式vision_modelOptional[VisionModelSpec]None视觉模型配置audio_modelOptional[AudioModelSpec]None音频模型配置enable_read_image_multimodalOptional[bool]None是否允许read_file原生附带图片None交给运行时探测显式设置可跳过探测enable_sys_operationboolTrue是否解析系统操作文件系统/shell/代码False时不注册任何相关工具资源enable_task_planningboolFalse任务规划开关restrict_to_sandboxboolFalse是否将文件操作限制在工作区/项目根构造时映射为restrict_to_work_dirauto_create_workspaceboolTrue是否自动创建工作区completion_timeoutfloat | None600.0单次任务循环迭代的最大等待秒数progressive_toolOptional[ProgressiveToolSpec]None渐进式工具暴露配置approval_required_toolsOptional[list[str]]None需要审批的工具列表context_engine_configOptional[Any]None转发给DeepAgentConfig.context_engine_config的上下文工程配置内层 ReAct 智能体据此配置上下文压缩阈值等JSON 可序列化kv_cache_affinity_configOptional[KVCacheAffinityConfig]NoneKV 缓存亲和配置五、构造流程build() 与 resolve_parts() 的两段式装配DeepAgentSpec的构造被拆成两段openjiuwen/harness/schema/deep_agent_spec.pyresolve_parts(context)—— 只解析不实例化。它先解析modelself.model.build()、语言、视觉/音频配置、工作区再基于调用方传入或冷启动时自举的BuildContext派生一个 per-build 视图浅拷贝 覆盖 workspace / member_card_id避免污染调用方字段。随后把父模型发布到build_ctx.extras[_parent_model]提前解析sys_operation并发布到build_ctx.extras[_parent_sys_operation]键常量PARENT_SYS_OPERATION_EXTRAS_KEY见 openjiuwen/harness/schema/build_context.py——子智能体工厂若拿到父的系统操作就不会让create_deep_agent新建一个绕过父沙箱的 LOCAL 操作依次构建 rails、subagents、tools最后委托给resolve_deep_agent_parts(...)返回DeepAgentParts。NativeHarness直接用这套 parts 做前向构造不产生一次性模板build()则把它物化为全新的DeepAgent。build(context)—— 物化为活的实例parts self.resolve_parts(context)后agent DeepAgent(parts.config.card)再apply_deep_agent_parts(agent, parts)返回。BuildContext是规格→运行时边界对象。它刻意不是 Pydantic 模型与TeamRuntimeContext一样永不参与 JSON 序列化openjiuwen/harness/schema/build_context.py字段含language、member_name、role、workspace、member_card_id、project_dir、team_outputs_dir、extras。平台可以子类化它添加类型化句柄或通过extras逃生舱叠加多个平台。跨序列化边界spawn 的子进程、分布式远端、冷恢复时接收方通过register_build_context_factory/build_context_from_seed从可序列化种子重建活的上下文。六、在团队装配中的落地TeamAgentSpec.agents 与 agent_configurator规格的最终消费方是团队装配。从 blueprint.py 可以看到TeamAgentSpec用agents: dict[str, DeepAgentSpec]按角色键leader/teammate对应TeamRole枚举值组织每个角色的 DeepAgent 规格并叠加团队级配置team_name、lifecycle、evolution_enabled、teammate_mode、spawn_mode、predefined_members、external_cli_agents、tiny_agents、model_pool等。装配阶段的关键逻辑在 openjiuwen/agent_teams/agent/agent_configurator.py模型回退model_config ctx.member_model or agent_spec.model——运行时上下文优先规格兜底成员化改写agent_spec.model_copy(update{...})以不可变方式注入card、model、workspace、cwd、project_root、sys_operation、tools、skills等成员级字段再交给DeepAgentSpec.build(context)走第五节的两段式装配默认SysOperationSpec在成员侧按{card.id}.sys_operation兜底生成团队成员的技能读取统一走core.team.skill_use按成员与团队的可见性声明收窄因此规格里的skills只作为成员声明的种子 allow-list 进入SkillUseRail参数而技能发现被刻意关闭。从源码结构可以推断这种声明式规格 装配方注入运行上下文的设计正是为了让一个TeamAgentSpec可以穿越成员 spawn、进程重启与恢复边界规格本体始终 JSON 可序列化活的句柄全部由装配方在build()阶段补齐。七、实践要点与序列化边界规格是纯数据运行句柄留在 build 阶段DeepAgentSpec/SubAgentSpec/TeamModelConfig以及各叶子类型都是 PydanticBaseModel可直接model_dump_json()序列化、model_validate_json()反序列化BuildContext、Model、Workspace等活句柄不应出现在序列化内容中。模型配置二选一客户端配置model_client_config必填且api_base不会被自动填充model_request_config可选未显式给出时走各字段默认值temperature0.95、top_p0.95。能力引用用声明式名称而非类rail / 内置工具 / 子智能体都通过type或factory_name从 provider 注册表解析未知 rail 类型会被跳过并告警未知工具类型则直接报错并列出可用类型——迁移升级时需注意旧规格里引用的名称是否仍被注册。团队成员的model可留空agent_configurator的ctx.member_model or agent_spec.model回退链保证留空时由运行时上下文注入适合模型池统一调度、角色规格只描述能力的团队编排场景。八、相关资源本模块再导出实现openjiuwen/agent_teams/schema/deep_agent_spec.py规格真源与构造逻辑openjiuwen/harness/schema/deep_agent_spec.py运行时配置数据类与默认常量openjiuwen/harness/schema/config.py运行时载体与跨边界重建openjiuwen/harness/schema/build_context.py团队级规格TeamAgentSpec/LeaderSpec等openjiuwen/agent_teams/schema/blueprint.py团队装配消费方openjiuwen/agent_teams/agent/agent_configurator.pyModelClientConfig/ModelRequestConfig完整字段docs/en/2.Development Guide/API Docs/openjiuwen.core/foundation/llm/llm.md赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐Orchard Core 角色与权限体系完全指南预定义角色、Recipe 配置与自定义权限声明Orchard Core 角色与权限体系完全指南预定义角色、Recipe 配置与自定义权限声明 本文以 Orchard Core 的 角色与权限主题文档 htCMS后端Web框架测试报告SteamOS-Waydroid-Installer支持的30热门Android游戏性能实测测试报告SteamOS Waydroid Installer支持的30热门Android游戏性能实测 SteamOS Waydroid Installer是CAS 中的 OpenID Connect Federation 协议角色、Subordinate 配置与实体声明签发CAS 中的 OpenID Connect Federation 协议角色、Subordinate 配置与实体声明签发 CASApereo CAS内置了对后端认证鉴权单点登录上一篇终极免费方案一键解锁WeMod完整高级功能告别订阅烦恼下一篇WarcraftHelper魔兽争霸III终极优化插件完整使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考