DeepSeek Harness Python SDK 呼び出し

Web UI は人が見張るのに適していますが、プログラムから呼び出すdsh場合に必要なのは SDK です。

この章では Python SDK を紹介します:インストール方法、リポジトリ内蔵サンプルの実行方法、自分のプログラムでの呼び出し方法。


Python SDK はどのような問題を解決するのか

SDK は dsh をブラウザ上のページではなく、プログラム内の 1 行の呼び出しに変えます。

DeepSeekHarnessPython SDK のコアクラスであり、コンテキストマネージャーでランタイムのライフサイクルを管理します。

with ブロックに入ると組み込みランタイムを遅延起動し、退出時に自動で解放し、その間は run を繰り返し呼び出せます。

適したシーン:バッチ処理タスク、dsh を自社製品に統合する、テストで Agent を駆動する。

SDK をインストールすると、ランタイムはシステムに Node.js を要求せず、Python プロセス自体が同梱しています。


前提条件

SDK はシステムに対して明確な要件があるので、先に確認してください。

依存要件
Python3.10 以上
Gitインストール済み
オペレーティングシステムLinux x64、Linux arm64、または macOS 14+ の arm64
API エンドポイントDeepSeek 互換の API エンドポイントと認証情報
ワークスペースagent が変更できる分離された workspace

SDK のインストール

リポジトリをクローンして実行可能なサンプルを取得し、仮想環境を作成して、SDK と同バージョンの組み込みランタイムをインストールします。

$ git clone https://github.com/deepseek-ai/deepseek-harness.git
$ cd deepseek-harness
$ python -m venv .venv
$ . .venv/bin/activate
$ python -m pip install deepseek-harness-sdk

仮想環境は SDK をシステムの他の Python パッケージから分離するため、公式が推奨する方法です。

インストール後のランタイムはシステムに Node.js を要求しません。


リポジトリ内蔵サンプルの実行

リポジトリには minimal.py サンプルが含まれており、これを実行できれば SDK の一連の流れ全体を検証したことになります。

まず環境で認証情報を設定します。

$ export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

モデルがデフォルトの DeepSeek エンドポイントではなく、OpenAI 互換プロキシ経由で提供される場合は、DEEPSEEK_BASE_URL も設定する必要があります。

その後、分離された workspace とセッションディレクトリに対してタスクを実行します。

$ python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

スクリプトは assistant の最終的な応答を出力します。

セッションディレクトリには、組み立てられたモデルリクエストとツール呼び出しを含む JSONL ログが保存されます。


自分のプログラムで SDK を使う

リポジトリ内蔵サンプルは、実際には以下の SDK 呼び出しの軽量なラッパーであり、核心は 2 ステップだけです。

サンプル

# ファイルパス: examples/jsonrpc-agent/minimal.py の同等の書き方
from pathlib import Path

from deepseek_harness import DeepSeekHarness

# サンプル構成設定ファイルの絶対パス(.cordis.yml は起動するプラグインを記述)
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()

# agent がアクセスできる workspace。絶対パスである必要があります
workspace = Path("/absolute/path/to/workspace").resolve()

# セッションログと状態の保存ディレクトリ。絶対パスである必要があります
sessions = Path("/absolute/path/to/sessions").resolve()

# コンテキストマネージャー:入ると組み込みランタイムを遅延起動し、退出時に自動解放
with DeepSeekHarness(
    provider="deepseek-official",   # DeepSeek 公式プロバイダーを使用
    model="deepseek-v4-flash",      # モデル名。SDK のデフォルトでもあります
    max_tokens=49_152,              # 1 回の応答の最大トークン数
    cwd=str(workspace),             # workspace を agent の作業ディレクトリに設定
    session_root=str(sessions),     # セッションログの書き込み先
    cordis=str(config),             # どの構成で起動するか
) as harness:
    # タスクを送信; session_id はこの永続化された会話を識別するために使用
    result = harness.run(
        "Inspect the サンプル-demo repository and fix the failing tests.",
        session_id="example-001",
    )

# assistant の最終的な応答を出力
print(result.final_response)

DeepSeekHarness は組み込みランタイムを遅延起動し、コンテキストマネージャーを退出するまで継続して再利用します。

同じ harness は with ブロック内で run を複数回呼び出せますが、ランタイムが起動するのは 1 回だけです。


session id の再利用:Bash プロセスを保持する

これは SDK で最も見落とされがちであり、最も有用なルールです。

同じ harness と session id を再利用すると、そのセッションが持つ Bash プロセスが保持されます。

作業ディレクトリ、エクスポート済みの変数、シェル関数を含め、すべて次の呼び出しまで引き継がれます。

サンプル

# 1 回目の呼び出し:サンプル-workspace で変数をエクスポート
result = harness.run(
    "Run `cd /repo && export サンプル_MODE=dev` and confirm.",
    session_id="サンプル-session",
)
print(result.final_response)

# 2 回目の呼び出し:同じ session id を再利用すると、エクスポートした変数はそのまま残っている
result = harness.run(
    "Print the value of サンプル_MODE.",
    session_id="サンプル-session",
)
print(result.final_response)

独立したタスクには新しい session id を使用するべきです。次の呼び出しで同じ永続化された会話を引き継ぐ必要がある場合にのみ、元の id を再利用します。


サンプル構成の一覧

minimal.py の背後にあるサンプル構成は、意図的に簡素化された設定です。各項目が何をしているかを確認しましょう。

属性值
システムプロンプトDSH_SYSTEM_PROMPT; 未設定の場合は You are a helpful software engineer assistant. を使用
minimal.py が使用するモデル--model、次に DSH_MODEL、最後に deepseek-v4-flash
モデル向けのツール永続 bash と str_replace_editor のみ
Bash タイムアウト300 秒
エディタ出力の上限16,000 文字
コンテキスト圧縮無効
ファイルシステム素のローカルバックエンド; エディタは絶対パスを使用し、ランタイムプロセスから見える任意のパスにアクセスできます
セッションの永続化DSH_SESSION_ROOT 配下の非圧縮 JSONL

この構成は、harness アイデンティティ、workspace プロンプトテキスト、skill、使い捨て Bash、タスクツール、コンテキスト圧縮などのプラグインを省略しています。

全体の呼び出しフローは以下の通りです。

Python SDK 调用流程图


danger-full-access の境界

このサンプル構成は danger-full-access 権限プリセットを使用しているため、その境界を明確に理解する必要があります。

danger-full-access は、破棄可能な checkout またはコンテナ内でのみ実行できます。

Bash とエディタは、ランタイムプロセスがアクセス権を持つ任意のパスを変更でき、サンドボックスのフォールバックはありません。

永続 PTY バックエンドは POSIX ターミナル環境を必要とするため、この構成は Windows agent をサポートしません。

言い換えれば、それで本番プロジェクトを動かす前に、この環境が壊れても惜しくないことを確認してください。


まとめとセルフチェック

一言でまとめると:Python SDK は DeepSeekHarness コンテキストマネージャーでランタイムを包み、run(prompt, session_id) でタスクを送信します。

3 つの小さな質問で理解を確認します。

  1. 同じ session id を再利用すると何が保持されますか?
  2. どのような場合に新しい session id を使用すべきですか?
  3. minimal.py はデフォルトでモデルにどのツールを開放していますか?

参考回答:そのセッションの Bash プロセスが保持されます。作業ディレクトリ、エクスポート済みの変数、シェル関数も含みます。

独立したタスクには新しい id を使用; 同じ永続化された会話を引き継ぐ必要がある場合のみ再利用します。

永続 bash と str_replace_editor の 2 つのツールのみ。

その他の拡張