DeepSeek Harness 20 天实战:第 16 天——使用 Python SDK 驱动 Agent
上一篇,我们梳理了 Session 事件、工具结果和遥测,重点是如何定位 Agent 任务发生了什么。
今天换一个角度:如果我们希望在自己的 Python 程序中提交任务、获取结果、观察事件,并在进程退出后恢复会话,应该怎么做?
DeepSeek Harness 提供 Python SDK,用于从 Python 程序启动并驱动 Harness 运行时。本文将完成一个边界清楚的最小示例,并解释结果字段、会话恢复和超时处理。
版本说明:本文依据截至 2026 年 11 月 21 日可查阅的 DeepSeek Harness 官方主分支源码与文档整理。项目仍处于实验性开发者预览阶段,SDK 接口、Profile 和模型支持可能变化。实践时请以安装版本的文档为准。
一、Python SDK 在架构中扮演什么角色?
Python SDK 不是把 Harness 的全部逻辑直接实现成一个 Python 函数库。官方文档描述的主要路径是:
- Python 程序创建 SDK 客户端。
- SDK 按需启动 Harness 运行时子进程。
- Python 与子进程通过标准输入输出上的逐行 JSON-RPC 通信。
- Harness 运行时负责 Agent、模型路由、工具和 Session。
- SDK 将结果与通知交还给 Python 程序。
可以把职责分为两层:
| 层次 | 主要职责 |
|---|---|
| Python SDK | 管理运行时连接、提交输入、接收结果与通知 |
| Harness 运行时 | 加载 Profile 和插件、执行 Agent、维护会话及工具 |
这种分层带来一个重要结论:Python 代码能调用什么,不只由 SDK 决定,还取决于运行时加载了什么 Profile 和插件。
二、安装与运行前提
官方用户指南列出的前提包括:
- Python 3.10 或更高版本。
- 安装版本支持的平台与架构。
- 可用的模型服务和对应凭据。
- 独立的工作区和 Harness home。
官方列出的安装命令是:
python -m pip install deepseek-harness-sdk
当前官方文档说明,安装 SDK 时会安装与其版本匹配的平台运行时包;正常使用打包运行时不要求系统预先安装 Node.js。平台和版本支持情况应以实际发布包为准。
两个需要明确的目录
运行 SDK 前,要区分:
cwd:Agent 使用的工作目录。dsh_home:Harness 保存配置、Session 和其他运行资源的目录。
Python SDK 要求显式选择 Harness home,不会悄悄使用默认用户目录。实际使用中,应为实验选择独立目录,避免混入已有会话或插件配置。
凭据从哪里来?
当前 SDK 文档说明,运行时可以读取环境中的 DEEPSEEK_API_KEY;也可以通过 SDK 配置显式提供凭据。
实际项目中,优先使用受控的环境变量或部署的凭据管理方式。不要把真实密钥写进源码、会话提示或日志。
三、实践:提交一个不需要工具的简单任务
这个示例只请求一段文本回答,目的是先验证 SDK 初始化、模型调用和结果读取。
实验边界
准备以下内容:
- 一个可用的模型服务及凭据。
- 一个独立的 Harness home。
- 一个独立工作区。
- 当前安装版本支持的 Provider 和模型。
下面的模型名称来自官方示例;如果你的部署不支持该模型,应替换为适配器实际支持的模型。
from pathlib import Path
from deepseek_harness import DeepSeekHarness
def main() -> None:
# 将这两个路径替换为自己环境中的独立目录。
dsh_home = Path("/absolute/path/to/isolated-dsh-home")
workspace = Path("/absolute/path/to/disposable-workspace")
with DeepSeekHarness(
dsh_home=str(dsh_home),
cwd=str(workspace),
provider="deepseek-official",
model="deepseek-v4-flash",
) as harness:
result = harness.run(
"请用一句话解释什么是上下文窗口。不要调用工具。",
session_id="python-demo-001",
)
print("Session:", result.session_id)
print("Finish reason:", result.finish_reason)
print("Response:", result.final_response)
if __name__ == "__main__":
main()
执行前,应按实际环境替换路径并配置凭据。首次运行会涉及启动运行时和调用模型;不要把示例中的提示语当成工具权限控制。
为什么使用 with?
DeepSeekHarness 会按需启动运行时子进程,并在同一个实例中复用它。退出上下文管理器时,SDK 会关闭相关资源。
如果不使用 with,应在适当的清理路径中调用 close()。运行时进程的生命周期应由应用明确管理,尤其是在异常或服务关闭时。
四、RunResult 里有什么?
当前 Python SDK 的高层调用返回 RunResult。官方文档列出的主要字段包括:
| 字段 | 用途 |
|---|---|
session_id | 接收本次输入的 Session 标识 |
final_response | 活动区间中最后提交的根 Session 助手文本 |
finish_reason | 最后一个根 Session 轮次的结束原因,可能为空 |
events | 活动区间内的根 Session 事件 |
notifications | 根 Session 及已知子 Session 的相关通知 |
final_response 是方便使用的最终文本,但不应单独作为成功判断。调用方还需要检查 finish_reason、异常和业务结果。
对于普通提示,官方文档描述的活动区间从输入取得持久化收件确认开始,到 Agent 下次整体空闲结束。区间内可能包含其他重叠活动,因此最终文本不一定只能由这一次提示单独决定。
一个保守的结果检查方式
result = harness.run(
"请用一句话解释什么是上下文窗口。不要调用工具。",
session_id="python-demo-001",
)
if result.finish_reason != "completed":
raise RuntimeError(
f"Agent activity did not complete normally: {result.finish_reason}"
)
print(result.final_response)
这里将 completed 作为这个普通问答示例的预期结束状态。对于命令、取消、输出上限或其他活动,应结合当前 SDK 文档处理对应结果;不要把所有非空文本都视为成功。
五、在同一 Session 中继续对话
在同一个 Harness 实例中复用 Session 标识,可以继续该会话的上下文。
例如,在第一次调用之后:
follow_up = harness.run(
"结合刚才的回答,再解释为什么需要为输出预留空间。",
session_id=result.session_id,
)
print(follow_up.final_response)
这适合同一个连续任务。如果两个任务互不相关,应使用不同 Session 标识,避免无关历史相互影响。
同时,Session 隔离不自动意味着文件系统隔离。两个 Session 仍可能使用同一工作区或相同外部凭据,具体取决于运行时配置。
六、进程重启后恢复会话
如果 Python 进程已经退出,不能只假设重新创建一个同名句柄就等于从持久化存储恢复。
当前官方 Python SDK 提供 resume_session():
from deepseek_harness import DeepSeekHarness
saved_session_id = "python-demo-001"
with DeepSeekHarness(
dsh_home="/absolute/path/to/isolated-dsh-home",
cwd="/absolute/path/to/disposable-workspace",
provider="deepseek-official",
model="deepseek-v4-flash",
) as harness:
session = harness.resume_session(saved_session_id)
result = session.run(
"请根据之前的讨论,用一句话总结输出预留的作用。"
)
print(result.finish_reason)
print(result.final_response)
恢复时应保留原 Session 标识,并使用原先的 Harness home 和相应工作区。
官方文档说明:
resume_session()恢复已持久化历史,并准备好继续执行。- 缺失、不可读、不兼容或正在被占用的 Session 会报错,不会静默创建替代 Session。
start_session(id)只打开延迟使用的句柄,不等于请求恢复持久化会话。- 恢复 Session 不会恢复之前的 Shell、浏览器或其他外部进程。
因此,继续任务前仍需检查外部世界状态。尤其是上次中断时正在执行有副作用的操作,不能仅凭 Session 恢复成功就盲目重试。
七、观察运行通知
第 15 篇介绍了事件与运行轨迹。Python SDK 可以在高层 Session.run() 中接收通知。
下面的示例只打印通知方法名,避免默认把完整载荷中的文件内容或其他敏感信息输出到日志:
from deepseek_harness import DeepSeekHarness
def observe(notification) -> None:
print("Notification:", notification.method)
with DeepSeekHarness(
dsh_home="/absolute/path/to/isolated-dsh-home",
cwd="/absolute/path/to/disposable-workspace",
provider="deepseek-official",
model="deepseek-v4-flash",
) as harness:
session = harness.start_session("python-observe-001")
result = session.run(
"请简要解释工具调用的作用。不要实际调用工具。",
on_notification=observe,
)
print("Finish reason:", result.finish_reason)
print("Response:", result.final_response)
当前文档说明,on_notification 可以接收该 Session 树中的活动通知;RunResult.events 则只包含根 Session 事件。若任务使用子 Agent,不应把两者当作完全相同的数据集合。
生产应用应根据需要选择和脱敏通知字段,而不是无条件记录完整提示、工具参数和结果。
八、Profile 会影响 SDK 的能力
当前官方文档区分了完整 sdk Profile 与 sdk-minimal Profile。
| Profile | 适合的理解方式 |
|---|---|
sdk | 较完整的 SDK 运行时组合,提供当前文档所述的原生命令等能力 |
sdk-minimal | 独立的最小组合,提供其明确列出的能力;并非完整 Profile 的简单开关 |
官方文档说明,sdk-minimal 包含 Shell、本地执行、JSONL Session 和自动压缩等能力,但不包含完整 Profile 的全部工具与设置能力。它对不支持的斜杠输入也可能按普通提示处理。
因此:
- 不要因为 Profile 名称带有
minimal,就假设它天然只读或没有命令执行能力。 - 不要假设完整 Profile 支持的每个原生命令在
sdk-minimal中都有相同行为。 - 自定义 Profile 必须保留 SDK 所需的服务端能力,否则可能在启动或初始化时失败。
权限仍需结合 Profile、实际工具、沙箱和部署环境单独确认。
九、超时、异常和重试
将 SDK 接入应用时,需要区分三个状态:
- 调用正常返回,任务完成:检查
finish_reason和业务结果。 - 调用正常返回,但任务未正常完成:例如返回了错误或达到输出上限。
- SDK 抛出异常:可能涉及初始化、协议、传输或通知观察等失败。
超时不等于任务回滚
当前 Python SDK 文档明确指出,超时或观察回调失败不会自动回滚运行时已经执行的工作,也不构成自动重试的依据。
此外,request_timeout_seconds 限制的是协议响应等待,并不是对后续全部 Agent 活动的总时长保证。
如果任务可能创建资源或修改外部系统:
- 保留 Session 标识和相关操作标识。
- 检查 Session 事件及外部系统状态。
- 确认上次操作是否已发生。
- 再决定能否安全重试。
对于只读、可重复的查询,也应根据服务限制设置合理的重试策略,而不是无限重试。
十、审批与无人值守程序
Python 程序可能没有交互界面,但 Agent 使用的工具仍可能遇到需要审批的操作。
当前官方 SDK 文档说明:如果应用选择接收客户端审批请求,应先准备好并发的请求处理线程或循环,再启用相应选项。审批决定是一次性的;无效响应或连接丢失会按关闭策略处理。
不要在无人值守程序中把所有审批请求自动批准。应先明确:
- 哪些操作本来就不应出现在该工作流中。
- 哪些操作可以在受限环境中执行。
- 哪些操作必须交由授权人员判断。
- 没有应答方时,任务如何停止并报告。
第 17 篇会进一步讨论 Headless 与 ACP 自动化中的执行边界。
十一、常见问题排查
1. 导入失败
检查安装的发行包是否为 deepseek-harness-sdk,以及运行脚本使用的 Python 环境是否与安装时一致。导入模块名是 deepseek_harness。
2. 运行时无法启动
检查:
- 是否显式提供有效的
dsh_home。 - 当前平台是否有匹配的运行时包。
- 选择的 Profile 是否存在且包含 SDK 服务端。
- 目录权限和运行时诊断信息。
3. 初始化阶段提示模型不可用
检查 Provider 是否由当前 Profile 注册、模型名称是否被适配器支持,以及可选推理强度是否适用于该模型。初始化失败不等于模型已经收到并处理提示。
4. 有 final_response,但任务状态异常
同时检查 finish_reason、事件和应用自己的验收条件。模型输出了文字,不必然代表任务按预期完成。
5. 无法恢复旧会话
检查 Session 标识、原 Harness home、持久化后端、格式兼容性及是否已有其他写入者占用。不要在恢复失败后静默创建同名新任务并当作原任务继续。
6. 通知回调失败后,外部状态不确定
检查回调异常和 Session 轨迹。观察失败不会撤销已经发生的运行时操作;对于外部副作用,先核对实际状态再处理。
总结
Python SDK 提供了从 Python 程序驱动 DeepSeek Harness 的高层入口,但应用仍需要管理运行时、Session 和操作边界。
今天需要记住:
- Python SDK 通过 JSON-RPC 与独立 Harness 运行时通信。
- 显式配置独立的
dsh_home和工作区,并管理子进程生命周期。 - 同时检查
final_response、finish_reason和必要的事件,而不是只看最终文本。 - 持久化恢复使用
resume_session();它不会恢复外部进程。 - 超时或观察失败不意味着任务回滚,重试前要核对外部状态。
下一篇,我们将继续讨论 Headless 与 ACP 自动化:当 Agent 在没有图形界面的环境中运行,或通过协议与其他客户端协作时,如何处理生命周期、权限和结果交付。
参考资料
- DeepSeek Harness 官方源码:Python SDK README
- DeepSeek Harness 官方文档:Python SDK 入门指南
- DeepSeek Harness 官方源码:Python SDK 最小示例
- DeepSeek Harness 官方源码:SDK JSON-RPC Server 包说明
- DeepSeek Harness 官方源码:SDK 包组说明
422



被折叠的 条评论
为什么被折叠?



