DeepSeek Harness 入門ガイド：ゼロから最初のAIエージェントまで

このチュートリアルで学べること

DeepSeek Harness（dsh）は、Cordis プラグインシステム上に構築された DeepSeek のオープンソース AI エージェントプラットフォームです。簡単に言うと、あなたの指示で、コンピュータ上のファイルの読み書きやコマンド実行を行う AI を動かせるようにするものです。

このチュートリアルは何も知らない前提で書かれています。ターミナルも Node.js も AI エージェントも初めてでも大丈夫です。概念は使う前に必ず説明します。最後には Web UI の起動、モデルの設定、最初のエージェントタスクの実行まで到達します。上級者向けに CLI モードと Python SDK も紹介します。

対象バージョン？ 2026 年 8 月にリリースされた公開開発者プレビュー（0.1.0-rc.5）です。deepseek.com/harness や @deepseek-ai/dsh npm パッケージと同じコードです。

所要時間： 30–45 分   難易度： 入門

始める前に

費用は？ ソフトウェア自体は無料・オープンソース（MIT ライセンス）。あなたが支払うのはモデル提供者への AI 利用料のみで、トークン単位（トークンはおおよそ単語の一部）で課金されます。

「AI エージェント」とは？

普通のチャットボットは、質問したら答えが返るだけです。エージェントはさらに先まで行けます。ファイルの読み書き、コマンド実行、Web 検索など、小さなステップを連鎖させて、あなたが自然言語で示したゴールを達成します。DeepSeek Harness はモデルに「手」を与える体、モデルは頭脳です。

「モデル」とは？

AI の「頭脳」をモデルと呼びます。DeepSeek のモデルは、この Harness を作ったのと同じ会社が作っています。モデルを使うにはAPI エンドポイント（ソフトウェアが話しかける「住所」）とAPI キー（その住所に入るための「暗証番号」。請求アカウントに紐づきます）の 2 つが必要です。

「ターミナル」とは？

ターミナル（Windows では PowerShell、macOS では ターミナル、Linux では Konsole/GNOME ターミナル など）は、クリックではなく命令を打ち込む窓です。このチュートリアルのインストール手順はすべてここで実行します。次のセクションで開き方を解説します。

ターミナルの開き方（手順付き）

ステップ 1：Node.js を確認し、なければインストール

DeepSeek Harness の最も簡単なインストール方法は、Node.js に付属する npx コマンドを使います。まず Node.js が入っているか確認しましょう。

ターミナルで以下を入力し、Enter を押します：

node --version

• v20.x.x や v22.x.x のような表示 → インストール済み。ステップ 2 へ。
• command not found（Windows では node is not recognized）→ 未インストール。以下を続けてください。

Node.js のインストール

nodejs.org にアクセスし、LTS 版（「長期サポート版」。安定・推奨）をダウンロード。普通のアプリと同じように、ダウンロードしたファイルを開いてデフォルトのまますすめてください。インストール後、ターミナルを閉じて開き直し、node --version でもう一度確認します。

Node.js とは？ JavaScript プログラムをコンピュータ上で実行するための無料ランタイムです。Harness のような開発ツールの多くは、そのパッケージマネージャ npm で配布されます。このチュートリアルで JavaScript を学ぶ必要はありません。Node.js は裏方としてツールを支えているだけです。

ステップ 2：Web UI をインストールして起動

本命の一行です。ターミナルで実行：

npx @deepseek-ai/dsh web

`npx` とは？ npx <パッケージ名> を実行すると、そのパッケージをダウンロードして（初回は 1〜2 分かかります）実行します。つまりこの 1 行で DeepSeek Harness のダウンロードと起動が完了します。

何が起きるか： ログの文字列が流れ、その中に次のような行が出ます：

DeepSeek Harness is running at: http://127.0.0.1:3080

この http://127.0.0.1:3080 が、Harness の Web UI が自分のコンピュータ上で動いているアドレスです。このターミナルのウィンドウは閉じないでください。 ウィンドウが開いている限り、サーバーは動き続けます。

ブラウザ（Chrome、Edge、Safari…）で http://127.0.0.1:3080 を開くと、DeepSeek Harness のウェルカム画面が表示されます。

`127.0.0.1` とは？ 「このコンピュータ自身」を指す共通の住所です。:3080 はポート番号（内線番号のようなもの）。このアドレスは自分のマシンでしか動かず、他者は到達できません。

別の方法：ソースから実行

最新コードが必要なら GitHub リポジトリをクローンしてビルドします（pnpm が必要。npm の高速版です）：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

ステップ 3：DeepSeek API キーを取得（まだの場合）

Harness が実際のモデルと話すにはキーが必要です。キーは長い秘密の文字列——AI 利用のためのパスワードだと考えてください。

1. 1platform.deepseek.com を開き、ログインまたはアカウント作成。
2. 2アカウント内の API Keys ページを開く。
3. 3Create API key をクリックし、キーをコピーして安全な場所に保存。ページを離れると完全なキーは二度と見られません。

キーは誰にも渡さないでください。他人がキーを持てば、あなたの枠（多くの場合、あなたのお金）を消費できます。

ステップ 4：Web UI でモデルを設定

Web UI は起動時、モデル未設定の状態です。モデル変更は次のリクエストで反映され、サーバーの再起動は不要です。

1. 1Harness の Web UI（http://127.0.0.1:3080）で設定 → モデルを開く。
2. 2DeepSeek カードに DeepSeek API キーを貼り付ける。
3. 3保存をクリック。

DeepSeek ルートは即座に使えるようになります。

安全性のためキーは書き込み専用です。保存後、UI にはマスクされた形しか表示されず、本当のシークレットは $DSH_HOME/.credentials.yaml（ホームディレクトリ内のプライベートファイル）に保存されます。

他のプロバイダを追加

他の会社のモデル（Anthropic、OpenAI など）も使えます：

• カタログプロバイダ — プロバイダを追加をクリックし、インストール済みカタログから Anthropic や OpenAI などを選択。エンドポイント、プロトコル、モデルリストはプリセット済み。
• カスタムプロバイダ — カスタムプロバイダを追加で、企業ゲートウェイ、セルフホスト、OpenAI 互換エンドポイントを追加。小文字の Provider ID（永続的）、ベース URL、API プロトコル、資格情報、少なくとも 1 つのモデルを指定。保存前に利用可能なモデルを取得でエンドポイントを検査できます。

ネイティブ認証プロバイダ — Bedrock、Vertex、Azure、Codex はそれぞれ独自のネイティブ資格情報（AWS キー＋リージョン、ADC プロジェクト、api-version、OAuth）が必要です。API キーフィールドに入力するだけでは設定されません。

カスタムプロバイダのビジョンモデル

手入力したモデルは、明示するまでテキストのみとして扱われます。画像対応を宣言するには $DSH_HOME/settings.yaml を編集：

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

input は text と image を受け付け、そのモデルにのみ適用。ルート全体のフォールバックは defaultInput: [text, image]（プロバイダレベル）。DeepSeek 自身の chat-completions ルートはテキストのみです。

ステップ 5：ワークスペースを選択

新規 Web UI はワークスペース未選択の状態です。選択するまで、タスクを入力するメッセージ欄は無効です。

「ワークスペース」とは？ エージェントが触れていいコンピュータ上のフォルダです。中のファイル、コード、ドキュメントをエージェントは読み取り・編集・実行できます。コンピュータ全体ではなく、信頼できるプロジェクトフォルダにしましょう。

1. 1UI でワークスペースを選択をクリック。
2. 2dsh を起動したプロジェクトディレクトリを追加。
3. 3選択。

入力欄が活性化され、準備完了です。

ステップ 6：最初のエージェントタスクを実行

1. 1セッションを開始をクリック（またはメッセージ欄を直接使用）。
2. 2プロンプトを送信。新しいプロジェクトフォルダには次のようなタスクがおすすめ：

> Summarize this repository and identify its main packages.

（空フォルダの場合は：*hello.txt というファイルを作り、中に "Hello from DeepSeek Harness!" と書いて*）

1. 1エージェントの動作を観察。以下のことが可能です：

• ワークスペース内ファイルの読み書き
• Shell コマンドの実行（永続 Bash プロセス）
• サブエージェントへの作業委任
• プランの維持

現在の権限ポリシーでは、承認が必要な操作（ファイル削除、パッケージインストールなど）の前に Web UI が確認を求めます。設計どおりの動作なので、1 つずつ許可していきましょう。

4 つのエージェントモード

セッションコンポーザーのモードセレクターで切り替えます：

Trajectory ビュー

システムプロンプト、思考、ツール呼び出し、結果、サブエージェントのディスパッチ、コンテキスト注入など、すべてのモデル相互作用はセッションログに追記専用イベントストリームとして記録されます。Trajectory ビューでソース別に確認でき、同じログが復元、フォーク、検索、完全リプレイを担います。エージェントが何を・なぜ行ったかを正確に把握するのに最適です。

ステップ 7：さらに進む — Headless CLI

Web UI のほかに、dsh はスクリプトや CI 向けの headless エントリモードを提供します。ブラウザなしでタスクを最初から最後まで実行し、最終回答を出力して終了するコマンドです：

dsh --profile headless "Inspect the repository and fix the failing tests."

headless プロファイルは初回使用時に付属テンプレートから自動初期化されます。

起動器は 4 つのエントリモード：

「プロファイル」とは？ 名前のついた設定一式（どのプラグイン・モデル・設定を使うか）です。プロファイルディレクトリには package.json（樹外プラグイン依存と dsh.profile マニフェスト）と cordis.patch.yml（自分用パッチ層）があります。合成木は次の順でマージされます：

1. 1dsh.profile.bundles 順に各バンドルのパッチ
2. 2プロファイルの cordis.patch.yml
3. 3ホームレベルの $DSH_HOME/cordis.patch.yml
4. 4--patch 上書き

--dump-default-config と --dump-config で起動せずに合成木を確認できます。

ステップ 8：Python SDK（プログラマ向け）

Python で自分のプログラムにエージェントを組み込みたい場合は、公式 Python SDK があります。

前提条件

• Python 3.10 以降
• Linux x64/arm64、または macOS 14+（arm64）
• Git（サンプル取得用）

インストール

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

インストールされたランタイムは Node.js を内蔵。システムレベルの Node.js は不要です。

資格情報の設定

export DEEPSEEK_API_KEY="sk-…"
# 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.'

チェックイン済みサンプルの実行

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."

最終アシスタント応答が出力されます。session-root にモデルリクエストとツール呼び出しを含む JSONL ログが生成されます。

自分のプログラムでの SDK 使用

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config    = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions  = Path("/absolute/path/to/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(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

DeepSeekHarness はバンドルランタイムを遅延起動し、コンテキストマネージャー終了まで再利用。同じ harness と同じ session id の再利用で、セッション専用 Bash プロセス、作業ディレクトリ、export 変数、Shell 関数が保持されます。独立タスクは新しい session id を。継続すべき会話のときだけ id を再利用します。

サンプル構成の理解

注意：このサンプル構成は、Harness の ID、ワークスペースプロンプト、スキル、ワンショット Bash、タスクツール、圧縮などすべてのモデル向けプラグインを省略しています。danger-full-access を使用しているため、使い捨てのクローンまたはコンテナ内でのみ実行してください。永続 PTY バックエンドは POSIX 端末基盤が必要なため、この構成はWindows エージェントをサポートしません。

トラブルシューティング

次のステップ

• プロバイダを増やす — 設定 → モデルから Bedrock、Vertex、Azure、Codex、OpenAI 互換ゲートウェイを追加
• プラグイン開発 — docs/user/develop/basic/ で Cordis プラグイン作成を学ぶ
• Python SDK リファレンス — python/sdk/README.md でライフサイクル、結果、通知、ランタイム選択、設定を確認
• Cordis Primer — docs/cordis-primer.md でハーネスの中核となる組み立て構文を学ぶ

まとめ

ゼロから自分専用の AI エージェントを立ち上げました。このチュートリアルでは：

1. 1ターミナル、Node.js、API キー、モデル、エージェントの意味を理解
2. 2npx（またはソース）で dsh をインストール
3. 3DeepSeek API キーを作成し、設定 → モデルで設定
4. 4エージェントのワークスペースを選択
5. 5セッションで最初のエージェントタスクを実行
6. 64 つのモードと Trajectory ビューを確認
7. 7CLI で headless セッションを実行
8. 8Python SDK をインストールして使用

DeepSeek Harness はすべてがプラグイン——そしてすべて MIT ライセンスで完全無料です。エージェントの世界へようこそ。