用 Python SDK 程序化驱动 DeepSeek Harness从 Web UI 到生产 Agent前三篇我们理解了 Harness 是什么、架构怎么搭、和同类比好在哪。这一篇终于落到代码官方除了 Web UI还提供了 Python SDK让你能在自己的 Python 程序里启动会话、发送任务、接收结果把 Harness 从「交互式玩具」变成「可编程的生产组件」。本文带你从安装到跑通一个真实任务并讲清楚生命周期、会话复用和运行时选择这几个最容易踩坑的点。一、Python SDK 能做什么先说清楚 Python SDK 的定位它不是让你在 Python 里重新实现一个 Agent而是让你远程驱动Harness 内核。具体能力启动会话在 Python 里创建一个 Harness 会话发送任务把一段自然语言任务交给 Agent接收结果拿到 Agent 完成后的输出接收通知订阅 Agent 运行过程中的事件通知复用会话保留同一会话的 Bash 进程、工作目录、环境变量。这意味着你可以把 Harness 嵌进一个 Flask/FastAPI 服务、一个数据流水线、一个自动化脚本让它成为一个「可调用的智能体」。二、安装一个 pip 命令官方已经发布了 Python SDK 包安装很简单pipinstalldeepseek-harness-sdk如果是从源码仓库安装也可以gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harness python-mvenv .venvsource.venv/bin/activate# Windows 用 .venv\Scripts\activatepython-mpipinstalldeepseek-harness-sdk安装完成后核心入口是deepseek_harness模块下的DeepSeekHarness类。三、最小示例跑通第一个任务先看一个最小可运行的例子直接感受它的 API 形态frompathlibimportPathfromdeepseek_harnessimportDeepSeekHarness workspacePath(./my-project)sessionsPath(./.sessions)withDeepSeekHarness(providerdeepseek-official,modeldeepseek-v4-flash,max_tokens49_152,cwdstr(workspace),session_rootstr(sessions),cordisstr(config),# 你的 cordis 配置文件路径)asharness:resultharness.run(Inspect the repository and fix the failing tests.,session_idexample-001,)print(result)几个关键参数说明参数含义provider模型提供方这里用 DeepSeek 官方model模型名deepseek-v4-flash是速度最快的选项max_tokens最大输出 Token49_152是 Flash 的常见配置cwdAgent 可访问的工作目录workspacesession_root会话日志和状态的落盘目录cordisCordis 配置文件路径四、生命周期延迟启动 上下文复用DeepSeekHarness有两个容易误解、但非常重要的行为1. 延迟启动DeepSeekHarness会延迟启动内置运行时并持续复用直到退出with上下文管理器。也就是说在进入with块之前它不会真正拉起 Agent 运行时只有第一次调用harness.run(...)时才会启动。这能省下不必要的启动开销。2. 会话复用 保留 Bash 状态这是最关键的一点很多人会在这里踩坑复用同一个 harness 与 session_id会保留该会话拥有的 Bash 进程包括它的工作目录、已导出的环境变量与 shell 函数。这意味着独立任务 → 用新的 session_id延续同一段对话/持久 shell 状态 → 复用原有 id。举个例子。假设你想让 Agent 先装依赖、再跑测试、再改代码这三个步骤如果各自用新 session_id那第二步就看不到第一步pip install的结果环境变量、venv 激活状态都没了。正确做法是复用同一个 session_id让它们在同一段持久 shell 里继续withDeepSeekHarness(providerdeepseek-official,modeldeepseek-v4-flash,cwdstr(workspace),session_rootstr(sessions),)asharness:# 第一步安装依赖harness.run(Set up the project and install dependencies.,session_idtask-001)# 第二步复用同一 session_id延续同一个 shellharness.run(Now run the test suite and report failures.,session_idtask-001)# 第三步继续复用修复失败harness.run(Fix the failing tests you just ran.,session_idtask-001)这三步共享同一个 Bash 进程第二步能「看见」第一步装好的依赖第三步能「看见」第二步的测试输出。五、默认组合极简到只有两个工具官方 Python SDK 的默认组合preset非常克制值得你心里有数项默认值系统提示词DSH_SYSTEM_PROMPT环境变量未设置则用You are a helpful software engineer模型model参数回退DSH_MODEL默认deepseek-v4-flash暴露给模型的工具仅bash与str_replace_editor字符串替换编辑器Bash 超时300 秒编辑器输出上限16,000上下文压缩已启用这个组合省略了harness 身份、workspace 提示词文本、skill技能、一次性 Bash、任务工具、上下文压缩以外的其他面向模型的插件。沙箱策略被事实记录为运行时用户上下文而不会追加到系统提示词中。也就是说Python SDK 默认给你的是一个极简模式的 Agent——只有 shell 和文件编辑两个工具。这正是官方用来跑模型基准测试的那个组合。如果你需要更多能力子智能体、网页访问、技能等需要自己在 cordis 配置里组装。六、沙箱与安全默认是「危险全访问」这里有一个必须严肃对待的安全提醒。Python SDK 的默认组合使用danger-full-access级别的沙箱Bash 和编辑器可以修改运行时进程有权访问的任何路径。官方对此的明确警告是只能在可丢弃的 checkout 或容器内运行。也就是说不要在一个包含你重要数据的真实项目目录里用默认配置跑一个不受控的 Agent。正确姿势用一个可丢弃的 git checkout克隆一份干净的副本或者跑在Docker 容器 / 虚拟机里给 Agent 一个隔离的 workspacecwd指向一个空目录或副本目录。这也呼应了第 1 篇提到的Harness 的沙箱主要约束文件操作网络访问和进程可见性不在其约束范围内。生产环境务必额外加固。七、一个更贴近生产的封装示例把上面的知识串起来写一个「可复用任务执行器」的骨架frompathlibimportPathfromdeepseek_harnessimportDeepSeekHarnessclassHarnessWorker:def__init__(self,workspace:str,model:strdeepseek-v4-flash):self.workspacePath(workspace)self.sessionsself.workspace/.sessionsself.sessions.mkdir(parentsTrue,exist_okTrue)self.modelmodeldefrun(self,prompt:str,session_id:str):独立任务用新 session_id延续任务复用同一 idwithDeepSeekHarness(providerdeepseek-official,modelself.model,max_tokens49_152,cwdstr(self.workspace),session_rootstr(self.sessions),)asharness:returnharness.run(prompt,session_idsession_id)if__name____main__:workerHarnessWorker(./sandbox-repo)# 独立任务print(worker.run(List all TODO comments in the codebase.,job-001))# 连续任务复用 sessionworker.run(Create a new branch and add a README.,job-002)resultworker.run(Now commit the changes with a clear message.,job-002)print(result)八、运行时选择与配置进阶Python SDK 参考文档还介绍了几个进阶点这里给出要点运行时选择你可以在配置层切换底层的运行时实现例如用不同的会话持久化后端、不同的沙箱后端而不改业务代码配置cordis通过cordis参数传入配置文件决定 Agent 装载哪些插件工具、技能、子智能体、工作流等通知NotificationsSDK 支持订阅 Agent 运行过程中的事件通知适合做进度展示、日志采集、异步任务回调Cordis primer官方文档有「Cordis primer」章节介绍组合语法值得在需要自定义组装时精读。如果只想快速验证官方还提供了jsonrpc-agent示例用 JSON-RPC 在极简模式下复现基准测试仓库的BENCHMARK.md有详细指引。九、小结Python SDK 把 DeepSeek Harness 从「交互式 Web UI」变成「可编程 Agent 组件」核心就三句话DeepSeekHarness上下文管理器承载生命周期延迟启动、退出即释放session_id决定状态边界——独立任务用新 id延续任务复用 id保留 Bash 进程与环境默认是极简 危险全访问——生产环境务必隔离 workspace、加固沙箱。下一篇我们更进一步手写一个 Harness 插件把它挂到dsh-plugin生态上看看「一切皆插件」在开发者侧到底意味着什么。标签#DeepSeek #Python #AI Agent #Harness #编程实战 用 Python SDK 程序化驱动 DeepSeek Harness：从 Web UI 到生产 Agent
用 Python SDK 程序化驱动 DeepSeek Harness从 Web UI 到生产 Agent前三篇我们理解了 Harness 是什么、架构怎么搭、和同类比好在哪。这一篇终于落到代码官方除了 Web UI还提供了 Python SDK让你能在自己的 Python 程序里启动会话、发送任务、接收结果把 Harness 从「交互式玩具」变成「可编程的生产组件」。本文带你从安装到跑通一个真实任务并讲清楚生命周期、会话复用和运行时选择这几个最容易踩坑的点。一、Python SDK 能做什么先说清楚 Python SDK 的定位它不是让你在 Python 里重新实现一个 Agent而是让你远程驱动Harness 内核。具体能力启动会话在 Python 里创建一个 Harness 会话发送任务把一段自然语言任务交给 Agent接收结果拿到 Agent 完成后的输出接收通知订阅 Agent 运行过程中的事件通知复用会话保留同一会话的 Bash 进程、工作目录、环境变量。这意味着你可以把 Harness 嵌进一个 Flask/FastAPI 服务、一个数据流水线、一个自动化脚本让它成为一个「可调用的智能体」。二、安装一个 pip 命令官方已经发布了 Python SDK 包安装很简单pipinstalldeepseek-harness-sdk如果是从源码仓库安装也可以gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harness python-mvenv .venvsource.venv/bin/activate# Windows 用 .venv\Scripts\activatepython-mpipinstalldeepseek-harness-sdk安装完成后核心入口是deepseek_harness模块下的DeepSeekHarness类。三、最小示例跑通第一个任务先看一个最小可运行的例子直接感受它的 API 形态frompathlibimportPathfromdeepseek_harnessimportDeepSeekHarness workspacePath(./my-project)sessionsPath(./.sessions)withDeepSeekHarness(providerdeepseek-official,modeldeepseek-v4-flash,max_tokens49_152,cwdstr(workspace),session_rootstr(sessions),cordisstr(config),# 你的 cordis 配置文件路径)asharness:resultharness.run(Inspect the repository and fix the failing tests.,session_idexample-001,)print(result)几个关键参数说明参数含义provider模型提供方这里用 DeepSeek 官方model模型名deepseek-v4-flash是速度最快的选项max_tokens最大输出 Token49_152是 Flash 的常见配置cwdAgent 可访问的工作目录workspacesession_root会话日志和状态的落盘目录cordisCordis 配置文件路径四、生命周期延迟启动 上下文复用DeepSeekHarness有两个容易误解、但非常重要的行为1. 延迟启动DeepSeekHarness会延迟启动内置运行时并持续复用直到退出with上下文管理器。也就是说在进入with块之前它不会真正拉起 Agent 运行时只有第一次调用harness.run(...)时才会启动。这能省下不必要的启动开销。2. 会话复用 保留 Bash 状态这是最关键的一点很多人会在这里踩坑复用同一个 harness 与 session_id会保留该会话拥有的 Bash 进程包括它的工作目录、已导出的环境变量与 shell 函数。这意味着独立任务 → 用新的 session_id延续同一段对话/持久 shell 状态 → 复用原有 id。举个例子。假设你想让 Agent 先装依赖、再跑测试、再改代码这三个步骤如果各自用新 session_id那第二步就看不到第一步pip install的结果环境变量、venv 激活状态都没了。正确做法是复用同一个 session_id让它们在同一段持久 shell 里继续withDeepSeekHarness(providerdeepseek-official,modeldeepseek-v4-flash,cwdstr(workspace),session_rootstr(sessions),)asharness:# 第一步安装依赖harness.run(Set up the project and install dependencies.,session_idtask-001)# 第二步复用同一 session_id延续同一个 shellharness.run(Now run the test suite and report failures.,session_idtask-001)# 第三步继续复用修复失败harness.run(Fix the failing tests you just ran.,session_idtask-001)这三步共享同一个 Bash 进程第二步能「看见」第一步装好的依赖第三步能「看见」第二步的测试输出。五、默认组合极简到只有两个工具官方 Python SDK 的默认组合preset非常克制值得你心里有数项默认值系统提示词DSH_SYSTEM_PROMPT环境变量未设置则用You are a helpful software engineer模型model参数回退DSH_MODEL默认deepseek-v4-flash暴露给模型的工具仅bash与str_replace_editor字符串替换编辑器Bash 超时300 秒编辑器输出上限16,000上下文压缩已启用这个组合省略了harness 身份、workspace 提示词文本、skill技能、一次性 Bash、任务工具、上下文压缩以外的其他面向模型的插件。沙箱策略被事实记录为运行时用户上下文而不会追加到系统提示词中。也就是说Python SDK 默认给你的是一个极简模式的 Agent——只有 shell 和文件编辑两个工具。这正是官方用来跑模型基准测试的那个组合。如果你需要更多能力子智能体、网页访问、技能等需要自己在 cordis 配置里组装。六、沙箱与安全默认是「危险全访问」这里有一个必须严肃对待的安全提醒。Python SDK 的默认组合使用danger-full-access级别的沙箱Bash 和编辑器可以修改运行时进程有权访问的任何路径。官方对此的明确警告是只能在可丢弃的 checkout 或容器内运行。也就是说不要在一个包含你重要数据的真实项目目录里用默认配置跑一个不受控的 Agent。正确姿势用一个可丢弃的 git checkout克隆一份干净的副本或者跑在Docker 容器 / 虚拟机里给 Agent 一个隔离的 workspacecwd指向一个空目录或副本目录。这也呼应了第 1 篇提到的Harness 的沙箱主要约束文件操作网络访问和进程可见性不在其约束范围内。生产环境务必额外加固。七、一个更贴近生产的封装示例把上面的知识串起来写一个「可复用任务执行器」的骨架frompathlibimportPathfromdeepseek_harnessimportDeepSeekHarnessclassHarnessWorker:def__init__(self,workspace:str,model:strdeepseek-v4-flash):self.workspacePath(workspace)self.sessionsself.workspace/.sessionsself.sessions.mkdir(parentsTrue,exist_okTrue)self.modelmodeldefrun(self,prompt:str,session_id:str):独立任务用新 session_id延续任务复用同一 idwithDeepSeekHarness(providerdeepseek-official,modelself.model,max_tokens49_152,cwdstr(self.workspace),session_rootstr(self.sessions),)asharness:returnharness.run(prompt,session_idsession_id)if__name____main__:workerHarnessWorker(./sandbox-repo)# 独立任务print(worker.run(List all TODO comments in the codebase.,job-001))# 连续任务复用 sessionworker.run(Create a new branch and add a README.,job-002)resultworker.run(Now commit the changes with a clear message.,job-002)print(result)八、运行时选择与配置进阶Python SDK 参考文档还介绍了几个进阶点这里给出要点运行时选择你可以在配置层切换底层的运行时实现例如用不同的会话持久化后端、不同的沙箱后端而不改业务代码配置cordis通过cordis参数传入配置文件决定 Agent 装载哪些插件工具、技能、子智能体、工作流等通知NotificationsSDK 支持订阅 Agent 运行过程中的事件通知适合做进度展示、日志采集、异步任务回调Cordis primer官方文档有「Cordis primer」章节介绍组合语法值得在需要自定义组装时精读。如果只想快速验证官方还提供了jsonrpc-agent示例用 JSON-RPC 在极简模式下复现基准测试仓库的BENCHMARK.md有详细指引。九、小结Python SDK 把 DeepSeek Harness 从「交互式 Web UI」变成「可编程 Agent 组件」核心就三句话DeepSeekHarness上下文管理器承载生命周期延迟启动、退出即释放session_id决定状态边界——独立任务用新 id延续任务复用 id保留 Bash 进程与环境默认是极简 危险全访问——生产环境务必隔离 workspace、加固沙箱。下一篇我们更进一步手写一个 Harness 插件把它挂到dsh-plugin生态上看看「一切皆插件」在开发者侧到底意味着什么。标签#DeepSeek #Python #AI Agent #Harness #编程实战