DeepSeek Harness AI Agent開発ガイド

DeepSeek Harnessを初めて使う開発者向けに、最小タスクの設計からAI Agentの起動、ツール登録、状態管理、継続運用までを時間軸で解説します。複雑なマルチエージェント構成へ進む前に、何を確認すべきか、どの段階でリモート環境へ移すべきかも判断できます。

症状：Agentは起動するのに、ツール呼び出し後に停止しない、状態を復元できない、同じタスクを再実行すると結果が変わる。

最短解決策：最初は1つのモデル、1つのツール、1つの終了条件だけで最小ループを検証し、成功後にプラグイン、記憶、並列実行を追加します。

対象は、DeepSeek Harnessを初めて触る個人開発者、ローカルのAI Agentを継続運用へ移したい小規模チーム、ツール呼び出しの信頼性を評価する技術責任者です。 本稿では、2026年8月17日時点の公式リポジトリ、公式ドキュメント、DeepSeek API仕様を確認し、準備からデプロイ前の受け入れ確認までを実装順に整理します。

注意： DeepSeek Harnessは公式リポジトリ上でDeveloper Previewと明記されています。互換性を壊す変更が予定されているため、固定バージョン、実行ログ、再現手順を最初から残してください。 (github.com)

Last updated

最終更新：2026年8月17日。情報は同日時点の DeepSeek Harness公式リポジトリ、公式アーキテクチャ文書、DeepSeek APIドキュメント を確認しています。

公式リポジトリには、npmから npx @deepseek-ai/dsh web で起動する方法と、ソースから pnpm install、pnpm run build、pnpm dsh web で起動する方法が掲載されています。既成のReleaseは2026年8月17日時点で確認できないため、記事内では未確認のバージョン番号や性能値を断定しません。2026年9月、公式リポジトリ deepseek-ai/deepseek-harness と CLI dsh が公開されています。公式ランタイムを入れ、Web / headless を回すなら DeepSeek Harness dsh インストール：Web起動・Headless・AI Coding実測 を読んでください。本稿は自作ループとツール確認だけを扱い、公式 CLI 文書の代わりにはなりません。

事前設計：最小タスクの境界

DeepSeek Harnessで最初に作るべきものは、何でも答える汎用アシスタントではありません。入力、許可されたツール、期待する出力、停止条件を1枚に書ける小さなタスクです。

例えば、最初の検証対象を「指定されたディレクトリ内のファイル一覧を取得し、JSONで返す」にします。この場合、入力はディレクトリ、ツールは読み取り専用のファイル一覧取得、出力はファイル名の配列、終了条件はJSONを返した時点です。

この境界を決めないまま、検索、ファイル編集、シェル実行、サブエージェントを同時に追加すると、失敗原因が分かりません。モデルの判断ミスなのか、ツールの権限なのか、履歴の組み立てなのかを切り分けられなくなります。

DeepSeek Harnessの公式設計では、モデルアダプター、ツール登録、セッションログ、Agent Loopもプラグインとして扱われます。つまり拡張性は高い一方、最初から構成要素が多くなりやすい設計です。

最初に確認する項目

• APIキーをどこから注入するか
• 使用するモデル経路と互換API
• Agentの入力を受ける入口
• 呼び出してよいツールの一覧
• ツールが失敗した時の返却形式
• 成功、失敗、要確認の終了条件
• セッションを再開する単位

DeepSeek Harnessで最初のAI Agentを作る場合、何から始めるべきでしょうか。 まず公式のWeb UIまたはヘッドレス実行を起動し、ワークスペースを1つ選び、読み取り中心の単一タスクを実行します。公式ガイドでも、モデル設定、ワークスペース選択、リポジトリ要約という順番で最初のタスクを試す構成になっています。 (github.com)

初回起動：1時間で閉じる最小ループ

最小ループは、次の4要素に分けて考えると理解しやすくなります。

公式ドキュメントでは、1つのStepを「1回のモデル要求と、その要求に関連するツール呼び出し」と説明しています。また、Turnは未処理の作業がなくなった時に終了します。したがって、検証では「モデル応答があるか」だけでなく、「ツール結果を受け取った後に、次の要求が不要と判断して停止できるか」を確認します。

公式の起動例では、Web UIは標準で http://127.0.0.1:3080 に提供されます。実行ディレクトリが標準のファイルシステム位置になるため、プロジェクト用の作業ディレクトリを明示し、秘密情報を置いたディレクトリから起動しないことが重要です。 (github.com)

実装手順

1. 専用ディレクトリを作成する

ソースコード、設定、ログ、生成物を分けます。最初から本番リポジトリ全体を無制限に渡しません。

1. 公式リポジトリの起動方法を確認する

npm経由か、ソースビルドかを決めます。Developer Previewのため、後から同じ状態を作れるよう、実行時のコミット情報も保存します。

1. APIキーを環境変数または設定画面から注入する

ソースコードに直接書きません。ログにもキーが出ないことを確認します。

1. ワークスペースを1つだけ選択する

まずは読み取り専用のプロジェクトを使います。書き込み権限やシェル実行は後で追加します。

1. 単一ツールのタスクを送る

例として、ファイル一覧、JSONの形式検証、テスト結果の読み取りなどを使います。外部サービスへの更新処理は避けます。

1. 4種類の証拠を保存する

入力、モデルが生成したツール引数、ツールの戻り値、処理時間と失敗理由を保存します。

1. 停止条件を確認する

成功後に同じツールを繰り返さないか、空の入力で無限ループにならないかを確認します。

ツール登録：説明、引数、権限

DeepSeek Harnessのツールは、単に関数を登録すれば安全に動くわけではありません。モデルがツールを選ぶための説明、引数のJSON Schema、実行権限、エラー時の戻り値が一体で設計されます。

DeepSeek APIでは、ツールとして現在サポートされる型はfunctionで、1回のリクエストに指定できる関数は最大128個です。ただし、最大数まで登録することが良い設計ではありません。候補が増えるほど、似た名前のツールを誤選択する余地が広がります。 (api-docs.deepseek.com)

ツールの説明には「何をするか」だけでなく、「何をしないか」も書きます。例えば、read_file なら対象ディレクトリ外を拒否し、run_test ならネットワーク接続や本番データの変更を行わない、と明示します。

DeepSeek Harnessに自作ツールを接続するにはどうすればよいでしょうか。 まずツールの入力と出力を固定し、次に ctx.tools の登録経路、実行前後のイベント、失敗時の結果形式を確認します。公式アーキテクチャでは、ツール登録はスコープ付きレジストリと保護された実行パイプラインを通り、tools/pre-execute、tools/execute、tools/post-execute の流れで観測できます。

ツール呼び出しの最低限の記録項目は次のとおりです。

• tool_name
• 生成された引数
• Schema検証結果
• 実行開始時刻と終了時刻
• 権限判定
• 標準出力と標準エラー
• 失敗分類
• 再試行回数
• 対応するセッションID

DeepSeek APIの仕様でも、モデルが生成した引数は常に有効なJSONや定義済みパラメーターになるとは限らないため、実行前にアプリケーション側で検証する必要があります。Betaのstrictモードを使う場合でも、権限確認や業務上の妥当性確認は別に実装します。 (api-docs.deepseek.com)

複雑化：状態を3種類に分ける

長いタスクでは、すべてを会話履歴に詰め込む設計が最初に破綻します。状態は、短期会話、タスク成果物、長期知識に分けます。

短期会話は、現在の指示や直前のツール結果です。タスク成果物は、編集済みファイル、テスト結果、差分、チェックポイントです。長期知識は、プロジェクト規約や再利用する設計情報です。

Agentがタスクを実行している間、状態を保存するにはどうすればよいでしょうか。 モデルに見せる履歴と、復旧のための実行ログを分けず、セッションイベントを中心に記録します。公式設計では、セッションログがモデルに見えるコンテキストの基礎になり、再開、フォーク、トランスクリプト、テレメトリーもこのストリームから派生します。

実務では、次の段階を明示します。

1. 目的と入力の確定
2. 作業計画の生成
3. 情報収集
4. 変更または生成
5. 検証
6. 人による確認
7. 完了または復旧

各段階に、成功条件と中断条件を設定します。APIの一時障害なら再試行、引数不備ならモデルへ修正要求、権限不足なら停止して人へ確認、と分けます。すべてを自動再試行にすると、同じ副作用を何度も実行する危険があります。

判断分岐

• 読み取りだけで、処理時間も短い

ローカル環境で検証します。

• ファイル変更があるが、失敗時に破棄できる

専用ワークスペースとリセット手順を用意します。

• 長時間実行、複数人共有、定期実行がある

再接続可能なリモート環境へ移します。

• 外部サービスの更新や課金処理を含む

人による確認を必須にし、承認前後のログを分けます。

• 複数Agent、並列ツール、バックグラウンド処理が必要

単一Agentの成功ログを基準にし、1機能ずつ追加します。

継続運用：ローカルから分離環境へ

DeepSeek Harnessは、短い動作確認ならローカルマシンで十分です。しかし、ノートパソコンのスリープ、ネットワーク切断、作業ディレクトリの混在、他の開発者との共有不足が発生すると、Agentの不具合と環境の不具合を区別しにくくなります。

移行時には、次の5点を固定します。

• 依存パッケージとロックファイル
• APIキーの注入方法
• Agentごとの作業ディレクトリ
• セッションログと成果物の保存先
• 同時実行数と停止方法

公式アーキテクチャでは、ファイルシステム、サブプロセス、サンドボックス、ターミナルも交換可能な能力として整理されています。これは、ローカル実行をそのまま別の実行基盤へ移せる可能性を示しますが、実際のプラグイン互換性や運用安定性は、利用する構成ごとに検証が必要です。

特にコーディングAgentでは、作業ディレクトリの分離が重要です。同じディレクトリを複数セッションで共有すると、片方の変更をもう片方が前提にしてしまいます。実行前にスナップショット、実行後に差分、失敗時にリセットという3段階を用意します。

Macを遠隔の開発環境として使う場合は、クラウドMacレンタルの選び方を確認し、接続方式、作業領域、再起動方法、利用期間を先に決めます。地域要件があるチームは、日本国内のクラウドMac環境のように、接続先の条件から比較すると判断しやすくなります。

デプロイ前：実タスクで受け入れ確認

デモが1回成功しても、AI Agentを運用へ移す根拠にはなりません。最低でも、成功、ツール引数の誤り、権限拒否、API障害、途中停止、同一入力の再実行を含むタスク群で確認します。

評価項目は次のように分けます。

• 完了率：指定した終了条件まで到達したか
• 引数正確性：必須項目、型、対象パスが正しいか
• 異常復旧：再試行、停止、人への引き継ぎが想定通りか
• 再実行一貫性：同一入力で危険な差分が増えないか
• 資源使用量：CPU、メモリ、ストレージ、API利用量を追跡できるか
• 監査可能性：誰が、いつ、どのツールを許可したか確認できるか

評価表は、成功数だけでなく失敗理由を残します。「ツールを呼べなかった」と「正しいツールを呼んだが権限で拒否された」は、修正方法が異なるためです。

DeepSeek APIのTool Calls仕様では、tool_choice によって自動選択、ツール呼び出し必須、特定ツールの指定を切り替えられます。最小検証では自動選択だけに頼らず、特定ツールを強制するケースも用意すると、モデル判断と実行経路を分離して確認できます。

最後に、公式リポジトリのデフォルトブランチ、最新コミット、インストール文書、サンプルコードを再確認します。Developer Previewでは、昨日動いた設定が今日も同じとは限りません。更新前後のログを比較し、プラグインの読み込み順、設定パッチ、権限ポリシーを再検証してください。

まとめ：先に小さく動かし、必要な時だけ移す

DeepSeek Harness AI Agentの開発では、最初から多機能な自律システムを目指すより、モデル応答、ツール登録、状態保存、終了条件を含む最小閉ループを先に通す方が安全です。その後に、書き込み、シェル、長時間処理、並列実行、複数Agentを加えます。

ローカル環境は初期検証に向いていますが、スリープ、作業領域の混在、共有権限、復旧手順の不足が長時間タスクの弱点になります。自前マシンを常時稼働させる方法は、電源管理、接続維持、環境の再構築、チーム共有を別途管理しなければなりません。

短期の検証、チーム共有、リセット可能な作業領域が必要なら、ZekVPSのMac環境を候補に入れる価値があります。自分のMacを使い続けるより、作業環境を分離しやすく、終了後に状態を戻しやすいからです。反対に、物理デバイス接続が必須、長期にわたる固定負荷、特定のローカル周辺機器が必要な場合は、自前環境の方が適しています。

最小タスクの成功ログを残した後で、実行時間、同時利用者数、隔離要件を基準に環境を選んでください。判断材料を整理したい場合は、ZekVPSのクラウドMac環境で、必要な期間と作業内容に合う構成を確認できます。