自学教程

DeepSeek Harness Python SDK 调用

DeepSeek Harness

一、Python SDK 简介

DeepSeek Harness 除 Web UI、命令行 CLI 之外，还提供 Python SDK，允许开发者在 Python 代码中直接创建、运行 Agent 任务，将 Harness 的智能体能力嵌入到自己的自动化脚本、数据分析工具、后端服务中。

Python SDK 本质是对 Harness 内核的远程调用封装，不是独立运行的大模型库。它需要一个正在运行的 Harness 服务实例（可以是本地 dsh web、桌面版启动的后台服务），SDK 通过 HTTP 接口和 Harness 服务通信，复用 Harness 原有的插件、沙箱、工作区、轨迹日志、Profile 运行模式等全部能力。

核心要点：

  1. Python SDK 只负责发起任务、读取执行结果、获取轨迹；Agent 的工具调度、沙箱执行、模型调用依然由 Harness 服务完成。
  2. 支持四种 Profile（标准、PTC、极简、创造模式），代码内可自由指定。
  3. 会话、轨迹、工作区隔离规则和 Web UI 完全一致。

二、环境准备

1. 前提条件

  • 已经安装并成功启动 DeepSeek Harness 服务（dsh web 或桌面版，默认地址 http://127.0.0.1:3080）
  • Harness 服务已经提前配置好模型 API Key、模型提供商
  • Python 环境：推荐 Python 3.10+

2. 安装 SDK 包

pip install @deepseek/harness-sdk

如果包名有变动，以官方文档为准。

三、基础示例：简单任务调用

使用标准模式，指定工作区，提交任务并等待结果。

from harness_sdk import HarnessClient# 连接本地正在运行的 Harness 服务
client = HarnessClient(base_url="http://127.0.0.1:3080")
# 创建会话，指定 profile 和工作区目录
session = client.create_session(
    profile="standard",
    workspace="/path/to/your/workspace"
)
# 提交任务指令
task = session.run_task("列出当前目录所有 Markdown 文件，并统计每个文件行数")
# 等待任务执行完成
result = task.wait()
# 输出最终结果
print("Agent 输出结果：")
print(result.output)
# 获取完整轨迹日志（用于调试）
trajectory = session.get_trajectory()
print("完整事件轨迹：", trajectory)

四、切换 Profile（运行模式）

只需要修改 profile 参数，即可切换四种预设模式。

# PTC 模式
session = client.create_session(profile="ptc", workspace="/path/to/workspace")# 极简基准模式
session = client.create_session(profile="minimal", workspace="/path/to/workspace")
# 创造模式
session = client.create_session(profile="creative", workspace="/path/to/workspace")

五、流式读取任务输出

长任务适合流式回调，实时获取 Agent 输出和工具调用事件：

from harness_sdk import HarnessClientclient = HarnessClient(base_url="http://127.0.0.1:3080")
session = client.create_session(profile="standard", workspace="/path/to/workspace")
def on_event(event):
    print(f"事件类型: {event.type}, 内容: {event.payload}")
task = session.run_task(
    "读取项目 README.md，总结项目架构",
    stream_callback=on_event
)
task.wait()

六、会话 Fork（分叉调试）

和 Web UI 的 Fork 功能一致，可以基于历史会话的某个节点新建分支任务，做A/B测试：

# 在已有会话的指定事件节点分叉
fork_session = client.fork_session(
    session_id=session.id,
    event_index=10
)
new_task = fork_session.run_task("换一种思路重新完成任务")

七、获取轨迹数据用于实验/评测

Python SDK 可以批量导出完整轨迹，非常适合 Agent 学术实验、自动化评测：

trajectory = session.get_trajectory()# 导出为 json，用于后续分析
import json
with open("trajectory_result.json", "w", encoding="utf-8") as f:
    json.dump(trajectory, f, ensure_ascii=False, indent=2)

八、远程服务器使用

Harness 服务部署在远程服务器时，修改 base_url，注意防火墙开放端口：

client = HarnessClient(base_url="http://your-server-ip:3080")

⚠️ 安全提醒：公网暴露 Harness 端口存在风险，建议增加鉴权、VPN 或者内网访问。

九、常见参数说明

  • base_url：Harness 服务地址
  • profile：指定运行模式
  • workspace：工作目录，Agent 文件操作被限制在此目录
  • timeout：任务超时时间
  • stream_callback：流式事件回调函数

十、常见问题

  1. 连接失败，无法连接到 127.0.0.1:3080
    Harness 服务没有启动；端口被占用；确认 Web UI 浏览器可以正常打开。
  2. 模型调用报错
    SDK 不负责管理 API Key，模型配置需要在 Harness WebUI/配置文件提前配置好，SDK 直接复用 Harness 的模型配置。
  3. 文件操作无权限
    检查传入的 workspace 路径是否存在，Harness 沙箱会拦截工作目录以外的文件访问。
  4. 长时间任务中断
    调大任务超时参数，或者使用流式回调持续监听事件。

十一、适用场景

  • 自动化批量评测 Agent 任务，批量跑基准测试；
  • 在Python项目中嵌入智能体能力，如代码批量处理、文档分析；
  • 自动采集、导出轨迹数据，用于实验分析；
  • 结合CI流水线自动执行项目检查、代码重构任务。
标签：

0 条笔记