DeepSeek Harness Python SDK

将 DeepSeek Harness Python SDK 接入 DeepSeek API

官方 deepseek-harness-sdk 把 DeepSeek Harness 封装成 Python API。它是 Web UI 的程序化替代方案：应用选择 Agent 组合、工作区、模型和 Session，发送任务并获取最终回答，同时保留 Harness 原有的工具循环与事件日志。

本指南依据当前开发者预览版的官方 Python SDK 文档。

环境要求

  • Python 3.10 或更高版本
  • Linux x64、Linux arm64，或 Apple Silicon macOS 14+
  • DeepSeek 兼容接口与凭证
  • 一个允许 Agent 修改的独立工作区

Python wheel 内置匹配版本的 Harness runtime，因此使用 SDK 的目标机器不需要单独安装系统 Node.js。

安装

建议使用虚拟环境隔离 SDK 与内置运行时：

python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

如果要使用官方仓库内的示例和组合配置，再克隆 Harness：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

最小运行示例

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("./agent-workspace").resolve()
sessions = Path("./agent-sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "检查这个项目并总结其架构。",
        session_id="demo-001",
    )

print(result.final_response)

在进程环境中提供 DEEPSEEK_API_KEY。如果使用兼容网关而非默认地址，再设置 DEEPSEEK_BASE_URL。

四个关键参数

参数作用
cordis决定 Agent 组合和模型可见工具面
cwd工具能够读取或修改的工作区
session_root持久化 JSONL Session 记录
session_id创建或继续某段对话的身份

这些路径应该显式设置并彼此分离。不要让实验性 Agent 直接操作整个用户主目录。

继续同一个 Session

后续提示需要延续先前对话时，复用相同的 session_root 与 session_id。复用同一个 Harness 进程还会保留 Session 所有的 Shell 状态，包括工作目录、环境变量与 Shell 函数。

无关任务必须使用新的 Session ID。错误复用会把前一个任务的上下文、假设甚至终端状态带入新任务。

应该选择哪种调用方式

入口适用场景
Web UI人工交互和可视化查看 Trajectory
Headless CLIShell 或 CI 中执行一个任务
Python SDK产品集成、评测器和受控自动化
JSON-RPC SDK非 Python 进程接入相同 Host 协议
ACP ServerAgent 客户端互操作

运行注意事项

  • 生产集成应固定 SDK 版本，项目仍处于开发者预览阶段。
  • 不同租户或任务应隔离工作区和 Session Root。
  • Cordis 组合具有执行权限，不能当成无害配置文件。
  • 调用服务应限制任务时长和最大输出。
  • 凭证放在环境变量或密钥管理器中，不能写入 Prompt 或测试 Session。

常见问题

Python SDK 需要安装 Node.js 吗？

受支持平台的 wheel 不需要单独安装系统 Node.js，包内已经携带匹配运行时。

复用 Session ID 会保留上下文吗？

会，前提是继续使用同一个 Session Root；持久对话和 Session Shell 状态都会延续。

可以使用 OpenAI 兼容网关吗？

可以。设置兼容 Base URL，并选择组合配置所需的 Provider 与模型。