docker-agent-deploy

Docker Agent：サービング、共有、評価

概要

このスキルは、Docker Agent の統合インターフェースを担います。エージェントを他のソフトウェアから利用可能にすること（docker agent serve）、コンテナイメージと同じ方法で OCI レジストリを通じて配布すること（docker agent share）、変更後も引き続き正しく動作することを確認すること（docker agent eval）が対象です。 エージェントの設定はすでに存在することを前提としています。設定の作成方法については docker-agent-config を、対話形式またはローカルでの呼び出しについては docker-agent-run を参照してください。

このスキルを使用する場合

次の場合に、このスキルを有効にしてください。

• エージェントを MCP、OpenAI 互換のチャットエンドポイント、プレーンな HTTP API、または A2A/ACP 経由で利用可能にしたい場合。
• エージェントを Docker Hub（または任意の OCI レジストリ）に公開したい場合、または他の人が公開したエージェントをプルしたい場合。
• エージェントの自動評価（回帰テスト）を実施したい場合、または CI を評価結果に基づいて制御したい場合。

このスキルを使用しない場合

次の場合は、このスキルを使用しないでください。

• agent.yaml 自体（モデル、ツールセット、サブエージェント）を作成する場合は、docker-agent-config を使用してください。
• 開発者のマシンでエージェントを対話形式で実行する場合、--safety／--sandbox を選択する場合、またはエイリアスを扱う場合は、docker-agent-run を使用してください。

基本的なガイダンス

エージェントのサービング

• 5 つのサーバーモードには、それぞれ既定のループバックリッスンアドレスがあります。認証なしでループバックの外部に公開してはいけません。

  モード	既定のリッスンアドレス	認証フラグ	--safety はありますか？
  serve mcp	127.0.0.1:8081	--auth-token（--http 使用時のみ）	はい（--http 使用時のみ）
  serve api	127.0.0.1:8080	--auth-token	いいえ
  serve chat	127.0.0.1:8083	--api-key／--api-key-env	はい
  serve a2a	127.0.0.1:8082	--auth-token	はい
  serve acp	（stdio のみ）	該当なし	いいえ

  docker agent serve mcp ./agent.yaml --http --listen 127.0.0.1:9090 --auth-token "$TOKEN"
  

• serve mcp は既定で stdio トランスポートを使用します（Claude Desktop などのローカルクライアント向け）。ネットワーク経由でアクセス可能な MCP エンドポイントが必要な場合にのみ --http を指定し、その場合は必ず --auth-token を設定してください。

• 認証トークン／キーなしで、サーバーのいずれかのフラグをループバック以外のアドレスにバインドすることは拒否されます。--insecure-no-auth を使えば強制できますが、意図的に選択し、例外として文書化すべきものであり、既定の設定にしてはいけません。

• serve mcp（--http を指定）、serve chat、serve a2a では --safety（strict／balanced／restricted／autonomous）を指定できます。Docker のドキュメントによると、これらのモードでは未指定の場合、既定値は restricted です。serve api と serve acp には --safety フラグがありません。ネットワーク経由でアクセス可能なリスナーで --safety を autonomous に引き上げてはいけません。サービング中のエージェントにより多くの操作を許可する必要がある場合は、balanced を優先し、認証を有効にしてください。

• serve api では単一のファイルの代わりにディレクトリを指定できます。ディレクトリ内のすべての .yaml／.yml／.hcl が /api/agents の下に公開されます。複数のユーザーからサーバーにアクセスできる場合は、--session-workingdir-root を使ってセッションの作業ディレクトリを制限してください。

OCI レジストリ経由でのエージェントの共有

• イメージと同じ方法でエージェント設定をプッシュ、プルします。同じレジストリを使い、認証には同じ docker login を使用します。

  docker agent share push ./agent.yaml docker.io/username/my-agent:latest
  docker agent share pull docker.io/username/my-agent:latest
  

• instruction_file の内容はプッシュされたアーティファクトに自動的にインライン化されます。そのため、公開されたエージェントは自己完結型になり、参照先のファイルを別途バンドルする必要はありません。
• プッシュしたアーティファクトを参照する sub_agents は、公開後にダイジェスト（name@sha256:...）で固定してください。これにより、実行ごとのレジストリ検索を避け、利用者が受け取る設定が確実に同一になります。
• share pull で --force を使うのは、すでに存在するローカルコピーを上書きする場合に限ってください。--force を指定しなければ、既存のローカル設定はそのまま残ります。

エージェントの評価

• 評価データはデフォルトでエージェント設定の隣にある evals/ ディレクトリに保存されます。各評価データは、ユーザーメッセージ、記録されたツール呼び出し、採点基準を含む evals オブジェクトを記録した 1 つの JSON セッションファイルです。
• JSON を手書きするのではなく、実際の会話から評価セッションを作成してください。エージェントを対話形式で実行してから、TUI で /eval スラッシュコマンドを使ってセッションを保存し、その後に relevance／size／assertions の基準を編集します。
• 採点の観点は 4 つです。ツール呼び出し（記録されたシーケンスに対する F1）、関連性（LLM による判定、--judge-model、デフォルトは anthropic/claude-opus-5）、サイズ（応答の長さを S／M／L／XL に分類）、アサーション（決定論的なチェック。アサーションタイプの完全な一覧は references/eval-format.md を参照してください）。チェックを厳密に行える場合は、relevance よりアサーションを優先してください。アサーションには判定モデルが不要で、近似による誤りがなく、決定論的です。
• 評価は分離のためにコンテナ内で実行されます。Docker 互換のランタイムが必要です。プロバイダー専用の API キー（ANTHROPIC_API_KEY／OPENAI_API_KEY）は自動的に転送されます。GITHUB_TOKEN／GH_TOKEN は自動的には転送されません（モデルキーではなく、ホスト全体で使える認証情報であるためです）。エージェントのプロバイダーが必要とする場合（例：github-copilot）は、-e GITHUB_TOKEN を使って明示的に渡してください。
• --baseline を使い、絶対スコアではなくリグレッションを CI のゲート条件にしてください。

  docker agent eval ./agent.yaml --baseline results/2026-08-01-run.json --regression-tolerance 0.05
  

  以前は合格していた評価が今回失敗した場合、許容差にかかわらず、常にゲート条件に達します。コストの変化は報告されますが、ゲート条件にはなりません。ベースラインまたは評価が 0 件の実行（例：何にも一致しない --only パターン）は、合格として報告されるのではなく、拒否されます。
• --keep-containers と使用中のランタイムの exec を使うと、失敗した評価のコンテナを調査できます。評価の .db セッションファイルには、オフラインでのデバッグに使える会話全体が保存されています。

検証

• 提供中のエージェントの設定を変更した後は、リスナーを再起動する前に、デプロイ時と同じ --safety 値を明示して評価を再実行してください。これにより、承認ポリシーのリグレッションをトラフィックに影響する前に検出できます。ロールアウトをロールバックする場合は、以前の設定と safety フラグを復元してください。ロールバックの手段として、認証されていないリスナーを復元してはいけません。

関連スキル

• 基盤となる agent.yaml の作成や変更には、docker-agent-config を使用してください。
• ローカル／対話型の実行、安全モードの選択、サンドボックス化には、docker-agent-run を使用してください。

参考資料

• references/eval-format.md — 評価セッションの JSON スキーマと CLI フラグの一覧。
• references/sources.md — このスキルの各ルールの出典。

アセット

• assets/eval-session-example.json — コピーして調整できる、最小構成の評価セッションファイル。

チェック

• checks/verification.md — エージェントの提供、共有、評価に関する検証手順。