このページの翻訳は LLM によって生成されています。誤りに気づいた場合は GitHub で issue を開いてお知らせください。

エージェントに Herdr 対応を追加する

コーディングエージェントを開発しているなら、自分のコードだけでそのエージェントを Herdr の第一級の存在にできます。Herdr へのプルリクエストも、Herdr のリリースを待つ必要もありません。

エージェントが Herdr に報告すると、ユーザーは次のものを得られます:

サイドバーと herdr agent list に表示されるエージェント名と idle、working、blocked の状態
完了したときや判断が必要になったときの通知
herdr agent wait など、エージェントの状態を待つ自動化
Herdr サーバーの再起動後、同じペインで同じセッションが戻ること

ベンダーがインテグレーションを提供していないエージェントについては、Herdr がインテグレーションを管理します。エージェントのメンテナーが自分でインテグレーションを持てば、自分のリリーススケジュールで修正できます。

仕組み

Herdr ペイン内のすべてのプロセスは、次の環境変数を継承します:

変数	意味
`HERDR_ENV`	Herdr 内では `1`
`HERDR_PANE_ID`	エージェントが動いているペイン
`HERDR_BIN_PATH`	このペインを管理する Herdr バイナリ
`HERDR_SOCKET_PATH`	Herdr の API ソケット

エージェントは "$HERDR_BIN_PATH" を通じて 3 種類の報告をします:

状態。 idle、working、blocked が変わるたびに報告します。
resume コマンド。 現在のセッションを開き直すコマンドを報告します。
解放。 エージェントの終了時にペインを解放します。

HERDR_ENV=1 で他の変数も設定されているときだけ報告してください。Herdr の外では、インテグレーションは何もしないようにします。

状態を報告する

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --state working \
  --seq 1

ターンの開始時に working、入力を受け付けられるときに idle、ユーザーの判断が必要なときに blocked を報告します。ブロックの理由は --message で説明できます。
--agent はユーザーに表示される名前です。Herdr がすでに対応しているエージェントの名前ではなく、自分のエージェントの名前を使ってください。
--source はインテグレーションを識別します。固定かつ一意にしてください。herdr: で始めないでください。この接頭辞は Herdr 自身のインテグレーションが使います。
--seq は省略できますが、付けることを推奨します。source からの報告ごとに増加する必要があり、エージェントのセッションや再起動をまたいでも増加し続ける必要があります。タイムスタンプが適しています。Herdr は最後に受け付けた番号より大きくない報告を無視するので、遅れて届いた報告や順不同の報告が新しい状態を上書きすることはありません。

resume コマンドを報告する

現在のセッションを再開するコマンドを -- の後に置きます。モデルや権限モードなど、そのセッションに必要なオプションも含めると、再開したセッションが同じように動きます:

"$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --state idle \
  --seq 2 \
  --agent-session-id "$SESSION_ID" \
  -- my-agent --resume "$SESSION_ID" --model my-model

コマンドはどの状態報告に付けてもかまいません。セッションだけが変わったときは pane report-agent-session で送れます。エージェントがセッションを切り替えるたびに、もう一度報告してください。

Herdr サーバーの再起動後、Herdr は同じディレクトリでペインを開き、そこでそのコマンドを実行します。コマンドは次のルールに従う必要があります:

最初の語は、my-agent のようにユーザーの PATH 上にある単純なコマンド名にします。パスは使えません。
どの引数にもアポストロフィや制御文字を含めません。
引数は最大 64 個、合計 8 KiB までです。
先に source がペインを保持している必要があります。コマンドより前か同時に、report-agent で状態を報告してください。そうしないと Herdr は resume_not_accepted を返します。

最初の 3 つのルールに違反するコマンドは、Herdr が invalid_resume_argv で拒否し、その報告は適用されません。ユーザーは [session] resume_agents_on_restore = false で resume を無効にできます。

終了時に解放する

"$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \
  --source my-agent \
  --agent my-agent \
  --seq 3

解放すると、エージェントの名前、状態、resume コマンドがすぐにペインから消えます。解放するのはユーザーが実際に終了したときだけにしてください。同じプロセス内でセッションを別のセッションに置き換える場合は、解放せずに新しいセッションを報告します。

エージェントが解放せずに終了した場合、Herdr はペインがアイドルなシェルプロンプトに戻ったことに気づき、エージェントと resume コマンドを消去します。通常は 1〜2 秒かかります。これは安全網であり、解放の代わりにはなりません。

エージェントの邪魔をしない

Herdr のせいでエージェントを遅くしないでください。報告はバックグラウンドか短いタイムアウトで送り、失敗は無視します。
最新の状態だけを送ります。報告の送信中に複数の変化がたまったら、古いものは捨てます。
resume コマンドには Herdr 0.9.2 以降が必要です。古いバージョンはこれを無視するので、状態の報告と解放はそのまま動きます。

ソケットを直接使う

HERDR_BIN_PATH と CLI は Windows を含めて移植性のある選択肢です。エージェントに直接の IPC が必要な場合は、Socket API に記載された同等の pane.report_agent、pane.report_agent_session、pane.release_agent リクエストを送信します。resume コマンドは resume_argv 配列に入れます。

インテグレーションを確認する

Herdr のペインでエージェントを起動し、Herdr から見える内容を確認します:

herdr pane get "$HERDR_PANE_ID"
herdr agent list

普段のセッションに影響を与えずに復元をテストするには、別の名前付きセッションを使います:

herdr --session my-agent-test を起動し、ペインでエージェントを実行します。
herdr session stop my-agent-test でそのセッションを停止します。
herdr --session my-agent-test をもう一度起動します。ペインで resume コマンドが実行され、エージェントが再び報告するはずです。

例

Prime Agent の組み込み Herdr レポーターは実際のインテグレーションです。Herdr 内でのみ有効になり、エージェントイベントを working、idle、blocked に対応付け、セッションをまたいで報告順序を維持し、終了時にペインを解放します。

タイトルやカスタムのステータス文言など、状態を変えずにエージェントの見た目を変えるには、カスタムステータスラベルを参照してください。