DeepSeek Superagentチュートリアル：CIを監視し、修正を許可する

DeepSeek Superagentとは？

DeepSeek Superagentは、DeepSeek Harnessを通じて1つのGitHubリポジトリを監視します。チームのルールが、イベントに対応すべきかどうかを判断し、承認された作業は個別のセッションに進みます。本チュートリアルは公開されたプロトタイプを扱い、設計のみのアイデアは対象外です。

Harnessがランタイムを提供し、Superagentがイベント監視と認可を追加します。弊社のエージェントハーネス解説では、ツール、メモリ、制御について説明しています。

DeepSeek Superagentはどのように動作しますか？

新しいGitHubイベントは4つの段階を経ます。これらの段階により、判断とコード変更が分離されます。

• SourceとTrigger：GitHubのポーリングは、各イベントをIssue、プルリクエスト、またはmain上のTriggerに変換します。

• Admission：ゲートは、それを明示的な依頼、推測された候補、または何でもないものとしてラベル付けします。

• EvalとDecision： 推測されたCIをルールに照らして判断します。明示的な依頼は、理由explicitRoutedでacceptのDecisionにルーティングされます。

• TicketとExecutor：承認された作業には認可、ワーカーセッション、ディレクトリが割り当てられます。

その後のコメントは、Ticket自身のThread上で新たなEvalなしにそのワーカーへ届きます。図は3つのGitHubパス（デフォルトブランチのCI、明示的なリクエスト、そのレビュー）を示します。CIパスの中では、観察と自動離脱が一致ルールの両端にあります。

CIは評価されます。依頼が作業を開始します。画像：筆者作。

観察モードと自動モードの違いは？

acceptモードは、Superagentがイベントから推測した作業にのみ適用されます。以下の3つから選択してください。

• off は推測された候補を破棄します。

• observe は評価を行い、肯定的な結果を「would accept」として記録します。

• auto は肯定的な評価の後に作業を開始します。

許可された人物からの依頼はどのモードでも動作し、独自のTicketを作成します。このチュートリアルではautoはオフにしてください。

観察モードでCI修正ワークフローを構築する

このパイプラインはpytestと2つのGitHub Actionsジョブを用いて、イベントを日次収益に変換します。Superagentは作業開始前に意思決定を挟みます。関連するイベント駆動型ワークフローは、弊社のClaude Code Routinesチュートリアルで扱っています。

日次収益のリプレイバグをトレースする

このバグは、リプレイされた支払いを二重に計上してしまいます。各行にはevent_id、order_id、タイムスタンプ、金額があります。1つの注文に複数の正当な支払いが含まれることがあります。

そのため、order_idで重複排除するとリプレイのテストは通っても、本来の支払いを削除してしまう可能性があります。正しいキーはevent_idです。エージェントを許可する前に、Pythonのcsvモジュールで期待値を計算しておき、エージェントの出力が答え合わせにならないようにします。

成功するCI修正を定義する

成功は、エージェントの発言ではなく、ワークフローの動作で決まります。リポジトリを変更する前に、次の条件を設定してください。

• ドキュメントのみの失敗は無視する。

• revenue-integrityに一致しても作業は開始しない。

• 明示的な依頼の後にのみプルリクエストを開く。

• アサーションを保持し、事前に用意したホールドアウトスイートに合格する。

Superagentにアクセス権を与える前にホールドアウトスイートを用意してください。これにより、期待される挙動はワーカーの開発用入力の外側に保たれます。

DeepSeek Superagentの前提条件と分離

DeepSeekのAPIキー、2つのGitHubアカウント、使い捨てのLinux環境が必要です。Harnessの基本は弊社の基本セットアップガイドを参照してください。

必要なソフトウェアとアカウント

ソフトウェアのバージョンを固定し、アップグレードでワークフローが変わらないようにします。最後の列は、この記事後半の結果で使用したセットアップを記録しています。

エージェントは自身のGitHubユーザーで書き込み権限が必要です。Superagentはそのアカウントの通知を読み取るためです。許可リストには、作業を認可できる人間のメンテナーだけを追加してください。

個人ファイルからエージェントを分離する

両プリセットはOSユーザーにフルアクセスを与え、ghラッパーもプロセスを分離しません。自動マウントとインターオプをオフにした新しいWSLディストリビューションを使ってください。

すでに使い捨てのLinux仮想マシンがある場合はWSLの手順を飛ばしてそれを使い、無関係な認証情報やファイルは置かないでください。

# /etc/wsl.conf inside the disposable distribution
[automount]
enabled = false
mountFsTab = false
[interop]
enabled = false
appendWindowsPath = false
[user]
default = superagent提供：

専用のsuperagentユーザーにはDeepSeekキーとエージェントトークンのみを保持させてください。これは偶発的なアクセスを減らす措置であり、セキュリティ境界ではありません。MicrosoftのWSLセキュリティモデルでは、信頼できないコードにはWSL外の別管理の仮想マシンを推奨しています。

GitHubではmainを保護し、必須のプルリクエスト、少なくとも1名の独立した承認、両方のCIチェックを要求してください。エージェントには管理者バイパスなしで書き込み権限を与えます。Issue本文を通じたプロンプトインジェクションは、これらでは防げません。

ステップ1：Python収益パイプラインとCIベースラインを構築

公開されているチュートリアルリポジトリは現在、修正がmainにマージ済みです。現在のブランチを初期状態として使わないでください。以下のコミットで3段階を分けます。

以下のパイプラインとテストは、現在のmainではなく、グリーンのベースライン（a6d2036）から簡略化したものです。CIの手順に従う前に、そのコミットから使い捨てのリポジトリを作成してください。

git clone https://github.com/KhalidAbdelaty/superagent-revenue-lab.git revenue-lab
cd revenue-lab
git switch -C main a6d2036
git remote remove origin

export EXPERIMENT_REPO="YOUR_LOGIN/superagent-revenue-lab"
gh repo create "$EXPERIMENT_REPO" --private --source=. --remote=origin --push提供：

制御された失敗とエージェントのブランチには、この新しいリポジトリを使用してください。公開リポジトリは変更せず、インシデントと解決のコミットは比較用の参照として残します。

"""Daily revenue report built from payment events."""
import pandas as pd


def load_events(path):
    """Read payment events; amounts are integer cents."""
    return pd.read_csv(path, parse_dates=["occurred_at", "received_at"])


def daily_revenue(events):
    """Return one row per UTC day with total revenue in cents."""
    days = events["occurred_at"].dt.strftime("%Y-%m-%d")
    report = (
        events.assign(day=days)
        .groupby("day", as_index=False)["amount_cents"]
        .sum()
        .rename(columns={"amount_cents": "revenue_cents"})
    )
    return report提供：

ベースラインのデータセットは2日分にわたり、1つの注文に複数の正当な支払いが含まれます。Pytestは既知の合計値とその共有注文のケースを確認し、まだリプレイはテストしていません。

import pandas as pd


def test_daily_totals_match_known_values():
    report = daily_revenue(load_events(DATA))
    assert report["revenue_cents"].tolist() == [20398, 27550]


def test_events_on_the_same_order_are_all_counted():
    t = pd.Timestamp(0, unit="s", tz="UTC")
    events = pd.DataFrame({
        "event_id": ["evt_a", "evt_b"],
        "order_id": ["ord_1", "ord_1"],
        "occurred_at": [t, t],
        "received_at": [t, t + pd.Timedelta(seconds=1)],
        "amount_cents": [1000, 250],
    })
    assert daily_revenue(events)["revenue_cents"].tolist() == [1250]提供：

各ジョブには、検証する振る舞いにちなんだ名前を付けてください。同じ名前がGitHubやSuperagentのTriggerテキストにも現れます。

name: ci
on:
  push:
    branches: [main]
  pull_request:

jobs:
  revenue-integrity:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt   # pandas==2.3.3, pytest==8.4.2
      - run: pytest -v

  docs-check:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python scripts/check_docs.py      # fails if README links a missing file提供：

素のpytestがrevenueをインポートできない場合は、pytest.iniにpythonpath = .を追加してください。Superagentを導入する前に、mainで両ジョブがパスすることを確認します。

公開されているexperiment/holdoutディレクトリは元の実行を記録していますが、公開クローンから見えます。新しい実験では、ワーカーが読めるあらゆるチェックアウトやファイルシステムの外に新しいスイートを作成してください。

依頼を送る前にそのスイートにハッシュを付け、以下をカバーしてください。

• 1つのイベントの繰り返し配信。
• 同じ注文IDを持つ異なるイベント。
• 変更してはならない入力DataFrame。
• 期待される出力列とソート順。

レビューまでこのスイートは非公開にします。ステップ6では、ワーカーの終了後に別の人間環境からこれを実行します。

次の図は、ワーカーの開発用入力とメンテナーの最終チェックを分離しています。

ホールドアウトデータはワーカーの外に保持。画像：筆者作。

ステップ2：DeepSeek SuperagentをインストールしてGitHubに接続

日常業務で使うプロファイルとは別の専用Harnessプロファイルにバンドルをインストールします。エージェントアカウントのトークンはAGENT_GH_TOKENにロードし、リポジトリには書き込まないでください。その上でsuperagentユーザーとして以下を実行します。

npm install -g @deepseek-ai/[email protected] [email protected]

git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git ~/dsh-superagent
cd ~/dsh-superagent
git checkout --detach 8c32a9dc5d72c033816c6a8110b37f40cf94fba4
pnpm install && pnpm build

# A gh wrapper that only ever sees the agent account
mkdir -p "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"
cat > ~/.local/bin/gh-agent <<'W'
#!/bin/sh
GH_CONFIG_DIR="$HOME/.config/gh-agent" exec gh "$@"
W
chmod +x ~/.local/bin/gh-agent
printf '%s' "$AGENT_GH_TOKEN" | gh-agent auth login --hostname github.com --with-token
gh-agent api user --jq .login            # your dedicated agent account

# Dedicated profile, then the bundle
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"提供：

注：本チュートリアルの実行ではコミット6337fc8を使用しましたが、後にDeepSeekが8c32a9dにスクワッシュしました。

クローンしたリポジトリのプロファイル例を用い、ステートディレクトリを設定し、パネルを127.0.0.1:3082にバインドしてください。その後、tmuxでサービスを起動します。

scripts/dsh-superagent start
scripts/dsh-superagent status提供：

このプロファイルは、サービスの再起動を個人のHarnessセッションから切り離します。また、プラグインのPATHやGit設定を通常のプロファイルから分離します。

statusは、GitHub Sourceをステップ3で保存するまでセットアップ保留やrepositoryUnsetを報告するかもしれません。現時点ではランタイムが応答し、Superagentパネルが開くことだけ確認してください。SourceやCIベースラインはまだ不要です。

専用プロファイルのSettings → Modelsを開き、deepseek-flashを選択します。Superagent → Settings → EvalとExecutionでも、両ロールがそのプロファイルのモデルを継承しているか、deepseek-flashを明示的に指定していることを確認してください。

ステップ3：観察モードでGitHub Actionsの監視を構成

Source、ポリシー、ルール、エグゼキュータ設定を保存する間は、デフォルトブランチのCI観察をオフにしておきます。新しいリポジトリのmainがグリーンになってからオンにし、最初の読み取りがクリーンなベースラインを記録するようにします。

GitHub Sourceを構成する

専用のSettings → Sourcesで、リポジトリをEXPERIMENT_REPOに設定し、CLIフィールドを専用のgh-agentラッパーに向け、デフォルトブランチのCI観察はオフのままにします。Sourceを保存し、ポリシーを変更する前に再起動の完了を待ってください。

CIのAdmissionポリシーを構成する

CI結果には送信者がいません。そのAdmission行には1つのセルがあり、デフォルトはignoreです。そのままでは、EvalはCIを一切見ません。

範囲の狭いrevenue-integrityルールを定義する

例のルールを、チェック名にちなんだ1つのルールに置き換えてください。評価器には原因を推測しないよう指示します。

{
  "rules": [{
    "id": "revenue-integrity",
    "name": "Revenue integrity CI failures",
    "enabled": true,
    "instruction": "A default-branch CI result in which the check named revenue-integrity newly fails. That check executes the pytest suite guarding the daily revenue totals. Judge only from the check names and results you can read for that commit; do not guess a root cause. Failures limited to other checks, such as docs-check (README links), do not match. A recovery where every check passes does not match. Work, if accepted: investigate the failing revenue-integrity tests, fix the pipeline without weakening or deleting any assertion, add a regression test, and open a pull request for human review. Never merge."
  }],
  "sources": {"github": {
    "allowed": [{"id": "<human-login>"}],
    "bots": [],
    "admission": {"ci": {"unlistedUnaddressed": "inferred"}}
  }}
}提供：

各Ticket用にGitのワークツリーを作成するprepareコマンドを追加します。各ワーカーはリポジトリのチェックアウトから開始します。

C=/home/superagent/src/superagent-revenue-lab
git -C $C fetch --no-tags "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" \
  "${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/$DSH_SUPERAGENT_TICKET" &&
git -C $C worktree add -b "agent/$DSH_SUPERAGENT_NAME" "$DSH_SUPERAGENT_DIR" "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"提供：

Superagentは各Ticketに対してこれらの変数を埋め込みます。認可する前に、生成されたディレクトリに想定どおりのチェックアウトが含まれているか確認してください。

任意の構成ヘルパーは、同じSource、ポリシー、Eval、エグゼキュータのブロックを書き出します。初回のパスでは常にCI観察をオフのままにします。実験用リポジトリと許可された依頼者は必ず明示設定してください。

export REPO="$EXPERIMENT_REPO"
export ALLOWED="YOUR_GITHUB_LOGIN"
bash /path/to/configure.sh all提供：

プロアクティブ実行を無効のままにする

Evalはobserveのまま、プロファイルのデフォルトモデルを使います。各イベント後にEvalタブでDecisionを、ExecutionタブでTicketの有無を確認します。

CI観察をオンにしてベースラインを記録する

mainで両GitHub Actionsジョブが合格したら、デフォルトブランチのCI観察をオンにします。ヘルパースクリプトでは2回目のパスを使用します。

OBSERVE_CI=true bash /path/to/configure.sh source
bash /path/to/configure.sh show提供：

最初の読み取りは、作業を作らずに状態を記録します。次の4点を確認してください。

• セットアップに未解決の要件がない。

• GitHub Sourceがreadyと報告する。

• SourceがクリーンなCIベースラインを記録している。

• TriggerタブとExecutionタブに、ベースラインのTriggerやTicketが表示されない。

いずれかが満たされない場合は、ドキュメントの失敗を作る前に中止してください。以下のスクリーンショットは最終構成を示しています。

CI観察を有効にしたGitHub Sourceカード。画像：筆者作。

Eval設定：ルールは1つ、観察モード。画像：筆者作。

ステップ4：無関係なGitHub Actionsの失敗をテストする

無関係な失敗として、壊れたREADMEリンクを使用します。保護ブランチは失敗したチェックを拒否するため、この使い捨てリポジトリでのみ人間の管理者バイパスを使用してください。エージェントにそのバイパスを与えてはなりません。

sed -i 's|^- Tests: .*|&\n- Data dictionary: [docs/data-dictionary.md](docs/data-dictionary.md)|' README.md
git commit -am "docs: link the data dictionary from the README" && git push提供：

GitHub Actionsの完了後、docs-checkは失敗し、revenue-integrityは合格しました。設定したルールに一致し、Superagentは収益ルールに一致しなかったため候補を無視しました。

DecisionにはignoredFromCardが使われました。これはアクティブなルールに触れない候補向けのショートカットです。したがって、これはルール自体ではなくルーティングの確認です。

READMEの変更を元に戻し、両ジョブがパスするのを待ちます。Superagentは復旧を無視し、何もしないはずです。

ステップ5：収益整合性のCI失敗をトリガーする

同じ人間のみの経路を使い、チュートリアルリポジトリからインシデントデータを追加します。以下の概要は、タイムスタンプ列を省略して、リプレイと同一注文での別支払いを示したものです。

event_id,order_id,amount_cents,delivery
evt_1009,ord_507,5000,first
evt_1010,ord_508,6400,first
evt_1011,ord_508,1600,first
evt_1009,ord_507,5000,replay
evt_1012,ord_509,2100,first提供：

リポジトリでは完全なタイムスタンプ列を保持しています。ここではイベント同一性の判定に影響しないため省略しています。先に用意した独立計算では15,100セントを期待値とするため、テストにその値を設定し、test_replayed_event_is_counted_once()を追加します。

E       actual daily total: 20100
E       expected daily total: 15100
E       replay total: 8000 != 4000
FAILED tests/test_revenue.py::test_daily_totals_match_known_values
FAILED tests/test_revenue.py::test_replayed_event_is_counted_once
2 failed, 1 passed提供：

余分な5,000セントは、1件の支払いが二重計上されたことを示します。15100を20100に書き換えたり、リプレイのテストを削除したりしてもCIは緑になりますが、いずれも修正ではありません。

失敗したGitHub Actionsのワークフローでは、revenue-integrityのみが失敗しています。Triggerはおよそ1回分のポーリング間隔後に到着しました。

Evalは候補を「would accept」とマークし、一方でExecutionタブは空のままでした。評価器はpytestのログではなくチェック名と結論だけを見ているため、どのガードが失敗したかは分かっても、原因は分かりません。

観察モードは「would accept」を記録するのみ。画像：筆者作。

ステップ6：修正を許可し、プルリクエストを検証する

先述の明示的依頼の経路が、ここで実行を許可します。GitHubの通知は遅延することがあります。

GitHub Issueのメンション見落としに対処する

Superagent 6337fc8では、GitHub Sourceが5秒重ねてポーリングし、後のカーソルから通知済みスレッドを読みます。メンション通知は21〜23秒後に到着するため、ポーリングがメッセージを追い越すことがあります。

このタイミングにより、新しいIssue本文や一部のコメントがTriggerにならなかった理由が説明できます。コミュニティの報告でも同様の失敗モードが記載されています。

GitHubコメントで修正を許可する

依頼を新規コメントとして再投稿し、そのTriggerが現れることを確認してください。Superagentはこれを明示的依頼として受け入れ、ワーカーを起動します。

コメントのメンションで許可済みのTicketを作成。画像：筆者作。

エージェントのイベント重複除去の修正を確認する

作成されたプルリクエストは、event_idをキーに修正しました。説明に頼らず、差分をレビューしてください。

 def daily_revenue(events):
     """Return one row per UTC day with total revenue in cents."""
+    # The payment webhook may deliver the same event more than once, with a
+    # different received_at but the same event_id. One event_id is one payment
+    # event, so keep only its first delivery before aggregating.
+    events = events.drop_duplicates(subset="event_id", keep="first")
     days = events["occurred_at"].dt.strftime("%Y-%m-%d")提供：

リプレイテストが追加され、削除はありません。最初のテストコマンドは依存関係不足で失敗しましたが、ワーカーが仮想環境を作成後、可視のテストスイートは合格しました。

同一注文に属する支払いをテストする

エージェントをメンションせずに変更を依頼します：event_id以外は同一の2件の支払いが両方計上され、片方のリプレイは1回だけ計上されることを証明してください。レビューは同じTicketに届き、新たなEvalは発生しないはずです。

ワーカーは、テストのみを追加してパイプラインに変更を加えないコミットで応答しました。承認前に、正確なHEADのSHAを確認し、そのリビジョンに対して独立スイートを再実行してください。

レビューのフィードバックは同じTicketに継続。画像：筆者作。

独立データで修正を確認する

分離した人間の環境から、正確なプルリクエストのヘッドに対してホールドアウトを実行します。a43c541では、両スイートが5/5で合格し、アサーションの削除はありませんでした。62bac08でもツリーは同じでした。

エージェントだけで書かれたテストは、エージェントが選んだケースしかカバーしません。

ステップ7：修正をマージし、CIの復旧を測定する

マージ後に、mainがグリーンに戻り、復旧で新たな作業が開始されないことを確認します。その後、イベントのトレース、経過時間、プロバイダーの課金を確認します。

修正をマージし、CI復旧を確認する

手動承認とマージの後、デフォルトブランチの両チェックは合格しました。Superagentは復旧を無視し、追加の作業を開始せず、既存のTicketをmergedの結果でクローズしました。

イベントの取り込みと意思決定を評価する

弊社のAIエージェント評価ガイドが説明するように、各イベントを取り込みから結果まで追跡します。3回の繰り返しを通して、Evalに到達したイベントは期待どおりの経路を取り、取りこぼしはモデルのDecisionではなく取り込み段階で発生しました。

修正の正確性、時間、コストを測定する

同一のシナリオを、Superagent6337fc8、Harness0.2.1-rc.3、deepseek-flash、1つのポリシーで、3つの新しいリポジトリとWSLディストリビューションで実行しました。コストはDeepSeekのオフピークの低料金を使用しています。これらは再現であり、ベンチマークではありません。

3件すべての修正はevent_idを用い、すべてのホールドアウトテストに合格しました。取り込みはよりばらつきがあり、Issue本文のメンションは毎回見落とされ、3回目の再現では到着前にコメント2件も見落とされました。

2回目の再現ではコミットが書き換えられ、承認がホールドアウトの再実行より先に到着しました。後のチェックは合格しましたが、より安全な順序は「HEADのSHA確認→ホールドアウト→承認」です。

DeepSeek Superagentの制限とトラブルシューティング

本稿のいくつかの失敗は無反応のように見えるため、まずイベントがどこで止まったかを特定してください。Issueの見落としと正しい無視は、見た目が同じになり得るのが厄介です。

Triggerが発生しないCIの失敗

Superagentは失敗集合の変化を追跡します。そのため、ベースラインの読み取り、失敗が継続しているチェック、処理中のチェックは何も生成しません。DecisionのないTriggerは、たいていモデルではなくCIのAdmissionセルが原因です。

届かないGitHub依頼

送信者が許可されていない、Sourceがオフ、処理が一時停止中、GitHubの通知遅延などで失敗することがあります。これらを確認して問題ない場合は、新しいコメントを投稿してください。Issue本文の編集はイベントを発生させません。

自律的なCI修正の限界

このプロトタイプにはセキュリティ境界がありません。ワーカーはOSユーザーへのフルアクセスを持ち、情報開示ルールはプロンプト文面に過ぎません。エージェントアカウントを分離し、使い捨てリポジトリに限定してください。

autoへ切り替える前に、数週間分の観察されたDecisionを収集し、誤ったacceptだけでなく誤ったignoreも数え、ワーカーをWSLから独立した仮想マシンへ移行してください。

まとめ

冒頭の対比は維持されました。赤いCIが2件でも、同じアクションには至りません。Superagentはdocs-checkを無視し、revenue-integrityは「would accept」とマークしました。一方、観察モードは、人間が修正を依頼するまでコードを変更しませんでした。

event_idのパッチは素直でした。通知の取り込みはそれほど信頼できず、Issue本文のメンションはEvalに届かなかったため、正しいルールでも役に立ちませんでした。

この結果を自律的CI修正に一般化するつもりはありません。リポジトリは小さく、ルールは狭く、マージは人手で管理されました。他では、まずグリーンから始め、Decisionを点検し、明示的に許可し、ホールドアウトデータは分離し、独立した確認の後にマージしてください。

次のステップは、GitHubの通知経路を修正し、より多様な失敗タイプでワークフローを再実行することです。そのエビデンスが得られるまでは、autoモードはオフのままにします。