openJiuwen agent-core 的 create_deep_agent 工厂：一站式构建可运行 DeepAgent 的完整指南-北京尧图网络

人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载导读create_deep_agent是 openJiuwen agent-core 的 agent harness 框架openjiuwen.harness面向开发者的主入口工厂函数只需一次调用即可完成DeepAgent的身份卡片、工具、MCP 服务器、子智能体、护栏rail、工作区、技能等全部组件的装配与配置得到一个开箱即用、可直接invoke()/stream()运行的自主智能体。本文将以该函数为核心逐参数讲解其含义与默认行为并结合仓库源码揭示其解析装配 → 实例化配置 → 延迟初始化的内部流程最后给出可直接运行的实战示例帮助你快速上手构建复杂的多步任务 Agent。一、工厂函数全景签名与返回值create_deep_agent定义在 openjiuwen/harness/factory.py其核心签名如下create_deep_agent( model: str | BaseChatModel, *, card: AgentCard | None None, system_prompt: str | None None, tools: list[ToolCard] | None None, mcps: list[McpServerConfig] | None None, subagents: list[SubAgentConfig] | None None, rails: list[Rail] | None None, enable_task_loop: bool False, enable_async_subagent: bool False, add_general_purpose_agent: bool False, max_iterations: int 15, workspace: Workspace | str | None None, skills: list[str] | None None, backend: str | None None, sys_operation: SysOperation | None None, language: str | None None, prompt_mode: str | PromptMode | None None, vision_model_config: VisionModelConfig | None None, audio_model_config: AudioModelConfig | None None, enable_task_planning: bool False, restrict_to_work_dir: bool True, **config_kwargs, ) - DeepAgent返回类型一个已经完成配置configure()的DeepAgent实例可立即用于invoke()、stream()、follow_up()、steer()、abort()等运行时操作。构造流程工厂内部把参数组装成DeepAgentConfig实例化DeepAgent再调用其configure()完成内部ReActAgent、任务循环、工作区、护栏、工具与子智能体的装配。注意函数签名中的*表示除model外的所有参数都必须以关键字形式传入model既可以是模型名字符串也可以是预先构造好的模型实例BaseChatModel。从源码看实际推荐传入预先构造的Model实例参见 openjiuwen/harness/factory.py 与 openjiuwen/harness/deep_agent.py预构造模型可跳过惰性初始化直接注入内部ReActAgent。工厂的两步走内部实现从 factory.py 的源码可以看到工厂并非简单的一行封装而是把装配过程拆成了纯装配与物化两个阶段中间用DeepAgentParts数据类传递结果resolve_deep_agent_parts(...)factory.py#L188-L417只做装配不创建任何实例。完成工具归一化、可选通用子智能体注入、workspace / sys_operation 解析、DeepAgentConfig构建以及自动默认护栏Security / TaskPlanning / SkillUse / Subagent 等的计算。返回一个DeepAgentParts包含config、rails、tool_cards、tool_instances。apply_deep_agent_parts(agent, parts)factory.py#L420-L455把装配结果物化到目标DeepAgent上——调用agent.configure(parts.config)重建内部ReActAgent把具体工具实例注册到共享资源管理器resource manager把纯工具卡片注册到能力管理器ability manager再按挂载顺序把全部护栏加入队列。这种先解析、后应用的设计使得NativeHarness等宿主也能直接从规格说明spec自我配置而不必先构建一个一次性模板DeepAgent再复制配置——这是从源码结构可以看出的一个重要工程考量。二、核心参数详解一身份与模型model——智能体的大脑model是唯一的位置参数类型为str | BaseChatModel。传字符串时由框架按名字解析推荐传入通过openjiuwen.core.foundation.llm构造的Model实例。参考示例 examples/lsp/deep_agent_lsp_demo.py 的构造方式model init_model( providerOpenAI, model_name_MODEL_NAME, # 例如 gpt-4.1-mini api_key_API_KEY, api_base_API_BASE, verify_sslFalse, )也可以直接构造Model见 examples/harness/worktree/single_deepagent_e2e.pymodel Model( model_client_configModelClientConfig( client_providerOpenAI, api_keyapi_key, api_basehttps://api.openai.com/v1, timeout120, verify_sslFalse, ), model_configModelRequestConfig( modelgpt-4.1-mini, temperature0.2, top_p0.9, ), )card——身份卡片AgentCardAgentCard定义了智能体的名称与描述缺省为None时工厂自动创建一个namedeep_agent、descriptionDeepAgent instance的默认卡片factory.py#L239-L243。重要事实源码确认card.id是持久化身份被用作 checkpointer 键的一部分因此必须跨重启保持稳定否则会话状态将无法恢复。这一点在 factory.py 的文档字符串与 schema/config.py 的属性说明中均有明确阐述。建议总是显式传入AgentCardcardAgentCard( namelsp_demo, description具备 LSP 代码导航和文件编辑自动诊断能力的 AI 编程助手, )system_prompt——系统提示覆盖默认为None此时系统提示由 prompt builder 自动组装身份、工作区、工具、护栏、指南等各小节。显式传入时源码会把它作为identity 小节包装进SystemPromptBuilderdeep_agent.py#L1152-L1164这样所有护栏都能一致地基于 prompt builder 操作。参考 single_deepagent_e2e.pysystem_prompt( 你是一个编程助手。请严格按用户给出的步骤、依次调用工具完成任务每一步都必须用工具落地不要凭空假设结果。 ),三、核心参数详解二工具、MCP 与子智能体tools——工具注册list[ToolCard]挂载到智能体的能力管理器。从源码 factory.py#L83-L105 的_normalize_tools可知实际实现同时接受Tool实例与纯ToolCard两种对象并自动拆分Tool实例 → 同时产生tool_instances注册到共享资源管理器与其cardToolCard→ 仅作为卡片注册引用全局已注册工具其他类型 → 抛出TypeError。另外当free_search/paid_search未启用时会自动过滤对应工具卡片factory.py#L49-L51、deep_agent.py#L411-L425。DeepAgent默认会通过SysOperationRail等护栏注入read_file/write_file/edit_file/bash/glob/grep等编码工具集因此单纯编码任务甚至无需显式传tools。mcps——MCP 服务器配置list[McpServerConfig]。工厂会把这些配置挂载到能力管理器并在延迟初始化阶段通过Runner.resource_mgr.add_mcp_server注册到共享资源管理器deep_agent.py#L1197-L1235。若server_id已注册但配置不同会抛出错误相同则补充资源标签避免重复注册冲突。subagents 与 add_general_purpose_agent——子智能体subagentslist[SubAgentConfig]每个 SubAgentConfig 允许子智能体使用不同的模型、工具与提示含model、tools、mcps、system_prompt、skills、rails、workspace、factory_name/factory_kwargs等覆盖字段。运行时通过DeepAgent.create_subagent(subagent_type, subsession_id)按agent_card.name匹配并派生deep_agent.py#L1454-L1686。add_general_purpose_agentTrue自动把名称为general-purpose的通用子智能体注入到subagents列表首位factory.py#L108-L159。源码显示该注入会继承父智能体的 workspace 与 sys_operation确保通用子智能体不脱离父级的文件系统边界若用户已显式提供同名子智能体则不会重复注入。enable_async_subagent——同步/异步子智能体模式默认为False同步模式。从 factory.py#L513-L515 的文档与 rails.md 的概述可知FalseSubagentRail注册同步的TaskTool子任务按序完成True注册session工具异步派生子智能体可并行运行、通过会话工具交互。四、核心参数详解三任务循环与护栏enable_task_loop / max_iterations——任务循环enable_task_loopTrue启用外层自主任务循环outer task loop。DeepAgent以此把多次 ReAct 回合组织成一个持续到任务完成或中止的循环开启后还会自动追加一个TaskCompletionRail用于评估任务完成度并触发停止条件deep_agent.py#L778-L787。max_iterations内层 ReAct 单次 invoke 的最大迭代次数默认15传None表示无上限源码 schema/config.py#L262 与 factory.py#L518-L519。注意工厂文档中默认值写为15而DeepAgentConfig字段默认是None无上限——两者以你实际传入的值为准。rails——护栏注册与自动默认护栏rails接受Rail实例列表。关键设计工厂会自动补充你没有显式提供的默认护栏且不会重复挂载同类型护栏factory.py#L349-L410。默认护栏按挂载顺序包括护栏触发条件作用SecurityRail默认开启enable_security_railTrue注入安全系统提示小节应用命令白名单、路径校验等安全策略ModelAnomalyDetectionRail默认开启流式帧超时、重复输出重试、工具循环压缩TaskPlanningRailenable_task_planningTrue生成并维护结构化任务计划SkillUseRail传了skills或启用技能发现发现并调用已学习的技能SubagentRail存在subagents管理子智能体派生同步/异步ToolCallResilienceRail默认开启enable_tool_resilience_railTrue对可重试的工具调用失败做有界重试此外若宿主进程通过环境变量启用了在线 RL 训练工厂还会追加对应的在线训练护栏RLOnlineRail见 factory.py#L54-L80且不会重复添加同类型护栏。护栏的完整生命周期钩子before_round/after_round/before_tool_call/after_tool_call/on_init/on_complete与挂载规则详见 rails.md。enable_task_planning——任务规划enable_task_planningTrue时挂载TaskPlanningRail。还可配合model_selectionDict[Model, str]让不同的子任务使用不同的模型factory.py#L542-L545。五、核心参数详解四工作区、系统操作与多模态workspace——工作区Workspace实例或根路径字符串。字符串会被自动包装为Workspace(root_pathstr(workspace), languageresolved_language)不传时默认使用./当前目录作为工作区根factory.py#L262-L267。Workspace管理ROOT/SRC/DOCS/TESTS/DATA/OUTPUT/TEMP等命名节点并提供get_directory/get_node_path/set_directory等 API详见 workspace.md。从源码看workspace 是智能体自身产物的根memory、技能视图、生成文件而 shell 命令的真正工作目录由cwd控制默认等于 workspace 根——这两者是分离的层次schema/config.py#L224-L234。sys_operation 与 restrict_to_work_dir——系统操作与沙箱sys_operationshell/文件访问的SysOperation实例。不传时工厂会自动创建或复用一个OperationMode.LOCAL的实例其 id 稳定为{card.name}_{card.id}避免重复构建时报resource already exist错误factory.py#L269-L295。restrict_to_work_dir默认为True限制文件操作仅限工作区/项目根目录沙箱设为False则允许访问任意路径包括系统根目录。子智能体会继承自身配置与父级中更严格的值schema/config.py#L306-L308。language 与 prompt_mode——语言与提示装配模式language语言代码如cn、en。它决定工作区提示、技能描述、通用子智能体描述等提示内容的语言。prompt_modePromptMode枚举或字符串控制系统提示的装配粒度FULL默认包含全部提示小节身份、工作区、工具、护栏、指南MINIMAL仅保留身份与核心指南NONE不装配系统提示只用你传入的system_prompt。详见 prompts.md。vision_model_config / audio_model_config——多模态模型vision_model_configVisionModelConfig视觉模型配置默认gpt-4.1-mini、https://api.openai.com/v1、max_retries3支持from_env()从环境变量读取。当配置完整时工厂会自动创建视觉工具create_vision_tools并注入到工具列表factory.py#L248-L260重名工具不会重复注入。audio_model_configAudioModelConfig音频转写与问答模型配置默认gpt-4o-transcribe/gpt-4o-audio-preview、25 MB 音频上限、ACRCloud 指纹识别支持同样支持from_env()。另外通过**config_kwargs还可透传enable_read_image_multimodal控制 read_file 原生图片附件None自动探测、True始终附加、False仅返回元数据、permissions/permission_host工具权限护栏、parallel_tool_calls、progressive_tool_enabled等DeepAgentConfig扩展字段。未知字段会被忽略并打印告警日志factory.py#L343-L347。六、从创建到运行延迟初始化与完整使用流程create_deep_agent是同步函数创建后护栏只是排队异步注册发生在首次invoke()时惰性初始化见 factory.py#L490-L494。完整流程如下调用Runner.start()启动运行环境资源管理器等create_deep_agent(...)同步完成装配与configure()首次Runner.run_agent(agent, inputs)或agent.invoke(...)触发_ensure_initialized()deep_agent.py#L1288-L1378初始化 cwd ContextVar → 注册 MCP → 构建工作区目录DirectoryBuilder生成AGENT.md、memory/、skills/等脚手架可通过auto_create_workspaceFalse关闭→ 按优先级排序初始化护栏 → 标记完成此后即可反复invoke()/stream()或通过follow_up()/steer()/abort()与运行中的任务循环交互。DeepAgent运行时提供的核心方法详见 deep_agent.md方法作用async invoke(inputs, session)运行到完成并返回最终结果字典async stream(inputs, session, stream_modes)逐步产出中间流式事件async follow_up(msg, task_id, session)向运行中的任务循环投递后续消息async steer(msg, session)中途转向指令async abort(session)优雅中止当前任务循环add_rail(rail)追加注册护栏链式调用create_subagent(subagent_type, subsession_id)按类型创建子智能体load_state/save_state/clear_state(session)会话状态持久化与清理七、实战示例一最小可运行 DeepAgent结合示例 examples/harness/worktree/single_deepagent_e2e.py一个带完整编码能力 git worktree 工具的 Agent 只需import asyncio, os from openjiuwen.core.foundation.llm import Model, ModelClientConfig, ModelRequestConfig from openjiuwen.core.runner import Runner from openjiuwen.core.single_agent.schema.agent_card import AgentCard from openjiuwen.harness import create_deep_agent from openjiuwen.harness.rails.sys_operation_rail import SysOperationRail from openjiuwen.harness.tools.worktree import WorktreeRail async def main(): await Runner.start() try: agent create_deep_agent( modelModel( # 或 init_model(...) model_client_configModelClientConfig( client_provideros.getenv(MODEL_PROVIDER, OpenAI), api_keyos.getenv(API_KEY), api_baseos.getenv(API_BASE, https://api.openai.com/v1), timeout120, verify_sslFalse, ), model_configModelRequestConfig( modelos.getenv(MODEL_NAME, gpt-4.1-mini), temperature0.2, top_p0.9, ), ), cardAgentCard(nameworktree_demo, descriptionsingle deepagent worktree e2e), workspace/path/to/workspace, # 字符串自动包装为 Workspace languagecn, max_iterations20, rails[ SysOperationRail(), # 注入 read_file/write_file/edit_file/bash 等 WorktreeRail(), # 注入 enter_worktree/exit_worktree ], ) # 运行一次任务 result await Runner.run_agent( agent, {query: 请在工作区中创建 hello.py 并写入 print(hello)然后执行它}, sessionmy-session-id, # 固定 session_id 用于断点恢复 ) print(result.get(output)) finally: await Runner.stop() asyncio.run(main())关键点session_id固定复用即可让同一 agent 在中断/重启后从 checkpointer 恢复状态该示例正是通过固定的session_id完成了写入文件→强制中止→恢复→提交合并的完整端到端验证。八、实战示例二护栏组合与权限控制create_deep_agent的rails参数可自由组合各功能护栏。仓库中两个代表性组合1. LSP 文件系统护栏examples/lsp/deep_agent_lsp_demo.py叠加SysOperationRail与LspRail让 Agent 获得代码导航能力且编辑文件后自动触发 LSP 诊断注入实现写代码→检测→修复闭环agent create_deep_agent( modelmodel, cardAgentCard(namelsp_demo, descriptionLSP 代码导航助手), workspacestr(SAMPLE_CODE), rails[ SysOperationRail(), LspRail(optionsInitializeOptions(cwdstr(SAMPLE_CODE)), verboseTrue), ], max_iterations10, languagecn, )2. 工具权限护栏examples/permissions/permission_demo.py通过permissions与permission_host透传参数启用PermissionInterruptRail在before_tool_call阶段对敏感工具做 allow / ask / deny 判定ask会触发 Confirm 中断等待用户批准agent create_deep_agent( modelmodel, cardAgentCard(namepermission_demo, description演示工具权限护栏), workspacestr(workspace), max_iterations3, languagecn, permissionsexample_effective_permissions(), # {enabled: True, tools: {read_file: ask, ...}} permission_hosthost, )源码 deep_agent.py#L789-L804 确认只要permissions是启用状态的字典DeepAgent就会自动挂载PermissionInterruptRail无需手动在rails中传入。九、最佳实践与注意事项保持card.id稳定它是 checkpointer 的持久化键跨重启变化将导致会话状态无法恢复多个并发 Agent 共享同一card时可用tool_owner_id区分各自的工具实例注册默认回退到card.id见 deep_agent.py#L460-L477。优先传入预构造 Model源码显示预构造模型会被直接注入内部ReActAgentagent.set_llm(cfg.model)绕过惰性模型初始化减少首次调用的准备开销。善用自动默认护栏Security、ModelAnomalyDetection、ToolCallResilience 护栏默认开启且工厂会智能跳过你已显式提供的同类型护栏不必担心重复挂载。理解默认值语义工厂文档中的默认值如max_iterations15与DeepAgentConfig字段默认值None表示无上限可能不同生产环境建议显式指定关键参数。沙箱默认开启restrict_to_work_dirTrue是默认安全策略仅在工作区/项目根内放行文件操作如需系统级操作再显式关闭。首次 invoke 才真正初始化护栏注册、MCP 注册、工作区脚手架构建都在首次运行时惰性完成如需提前初始化可调用await agent.ensure_initialized()源码注释标明该方法主要面向测试与特殊宿主场景deep_agent.py#L1403-L1405。十、相关 API 索引运行时类DeepAgent工厂函数create_deep_agent配置结构DeepAgentConfig/SubAgentConfig/VisionModelConfig/AudioModelConfig护栏体系rails概览提示装配PromptMode/SystemPromptBuilder工作区Workspace实现源码openjiuwen/harness/factory.py、openjiuwen/harness/deep_agent.py、openjiuwen/harness/schema/config.py可运行示例examples/lsp/deep_agent_lsp_demo.py、examples/harness/worktree/single_deepagent_e2e.py、examples/permissions/permission_demo.py赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen agent-core DeepAgent 深度解析构建自主多步任务 Agent 的 Harness 运行时openJiuwen agent core DeepAgent 深度解析构建自主多步任务 Agent 的 Harness 运行时本篇技术指南围绕 openJ人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core Auto Harness Agent 工厂详解11 个阶段 Agent 的统一构建模式openJiuwen agent core Auto Harness Agent 工厂详解11 个阶段 Agent 的统一构建模式本文基于 Auto Har人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core DeepAgent 内置工具集openjiuwen.harness.tools 全指南openJiuwen agent core DeepAgent 内置工具集 openjiuwen.harness.tools 全指南本指南以 docs/en人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

openJiuwen agent-core 的 create_deep_agent 工厂：一站式构建可运行 DeepAgent 的完整指南

相关推荐

Mac外接显示器字体发虚？HiDPI开启原理与实战排查指南

光伏板缺陷检测实战：数据集构建、YOLOv8模型训练与部署全链路

SPECTER通道密码深度解析：ST3GG首创的跨RGB通道跳跃隐写术是怎么工作的

更多资讯

400万像素+小封装：智能家居摄像头画质升级的关键技术解析

Python康复评估系统源码解析：从数据清洗到评估算法落地

内核paging request崩溃排查：从日志证据链区分内存故障与驱动bug

花3万买来的教训：Bing优化服务商怎么挑，看完这篇少走2年弯路

Python人脸识别签到系统源码解析：特征向量、SQLite考勤与避坑指南

VB6删除文件到回收站

今日更新

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？