メインコンテンツまでスキップ

デプロイガイド

カスタムエージェントを Docker コンテナとしてビルドし、AGENTIC STAR プラットフォームに登録・実行する手順を解説します。

概要​

デプロイフローは以下の 4 ステップです。

  1. Dockerfile 作成 — エージェントをコンテナ化
  2. Docker ビルド & プッシュ — コンテナレジストリに登録
  3. プラットフォーム登録 — 管理画面でエージェントを登録
  4. 動作確認 — Chat Web App でテスト

実行モデル​

マーケットプレイスのカスタムエージェントは、常駐 HTTP サーバではなく「1 実行 = 1 プロセス」のバッチとして動きます。

  1. ユーザーがメッセージを送信すると、プラットフォームがエージェントの Pod を起動し、コンテキスト変数(EXECUTION_ID / CONVERSATION_ID / USER_ID / MESSAGE_ID 等)を環境変数として注入します
  2. コンテナの CMD で起動したプロセスが run_marketplace_agent() を呼びます。入力メッセージの取得 → エージェント処理 → 結果の DB 保存・Webhook 通知(終端イベントを正確に 1 回)は SDK の runner が担います
  3. 処理が終わるとプロセスは exit 0 で終了します(Pod は常駐しません)

このため、ポートの公開・/health エンドポイントの実装・FastAPI 等の Web フレームワークは不要です。エージェント関数の書き方は SDK クイックスタート の「Marketplace 互換で実行する(runner)」を参照してください。

ワークフローの工程で動くエージェント

プロジェクトのワークフローで使うエージェント(マーケットプレイス版 3.2.0 以降)は、run_marketplace_agent ではなく agenticstar_platform.workflow.run() を起動コマンドから呼びます。管理画面の登録では「ワークフローで使う」を有効にして契約を登録し、イメージの digest などの認定情報が登録されるまでワークフローでは起動できません。詳しくは ワークフローガイド を参照してください。

前提条件​

  • Docker 24.0 以上
  • Azure Container Registry(ACR)または互換レジストリへのアクセス(イメージのプッシュ権限。Azure では AcrPush ロール)
  • AGENTIC STAR 管理画面へのアクセス権限

ステップ 1: Dockerfile の作成​

DockerfileDockerfile
FROM python:3.12-slim

WORKDIR /app

# 依存関係のインストール
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# アプリケーションコードのコピー
COPY . .

# 非root実行ユーザー(runAsNonRoot 強制 namespace では「数値 UID」が必須。
# 名前のみの USER だと kubelet が非root判定できず起動拒否される)
RUN useradd -u 1000 -m -s /usr/sbin/nologin appuser \
&& chown -R 1000:1000 /app
USER 1000

# エントリポイント(run_marketplace_agent を呼ぶワンショットプロセス。
# 常駐サーバではないため、ポート公開やヘルスチェックエンドポイントは不要)
CMD ["python", "marketplace_agent.py"]
runAsNonRoot / readOnlyRootFilesystem 前提

マーケットプレイス実行環境は runAsNonRoot: true を強制します。USER 指定が無い(root実行)、 または USER appuser のように名前で指定した Dockerfile は container has runAsNonRoot and image will run as root で起動拒否されます。必ず数値 UID (例 USER 1000)を指定してください。あわせて readOnlyRootFilesystem: true 環境では 一時書き込み(例: ファイル共有のための /tmp)が失敗するため、/tmp を emptyDir で マウントするか書き込み先を可変ボリュームに向けてください。

requirements.txt
agenticstar-platform[all]==3.3.0
openai>=1.60.0
qdrant-client>=1.13.0

Kubernetes クラスタが AMD64 アーキテクチャの場合、必ず --platform linux/amd64 を指定してビルドしてください。

ステップ 2: Docker ビルド & プッシュ​

curl
# ビルド
docker build --platform linux/amd64 \
-t your-acr.azurecr.io/my-agent:v1.0.0 .

# ACR にログイン
az acr login --name your-acr

# プッシュ
docker push your-acr.azurecr.io/my-agent:v1.0.0

ステップ 3: エージェント設定ファイル​

config.toml は、SDK の各モジュール(DB / RAG / メモリ)が接続情報を組み立てるために読み込む設定ファイルです。PostgreSQLConfig.from_toml() などがこのファイルを読んで設定を構築するため、SDK のメモリ・RAG などのモジュールを使うエージェントには config.toml が必要です(ビルドしたコンテナイメージに同梱してください)。run_marketplace_agent だけを使うエージェントは、config.toml を使わず、DB の接続情報を環境変数 DB_HOST・DB_DATABASE・DB_USER・DB_PASSWORD で渡すこともできます(db_config を省くと、SDK がこれらの環境変数から接続情報を組み立てます)。作成方法の基本は クイックスタート — ステップ 2: 設定ファイルの作成 を参照してください。

次の例は、Azure AD で接続する場合です。パスワードで接続する場合は、use_azure_ad と [database.azure_ad] を書かずに [database] の password を使うか、config.toml を使わずに環境変数 DB_HOST・DB_PORT・DB_DATABASE・DB_USER・DB_PASSWORD で渡します。

config.tomlToml
# [agent] は SDK が読み込まないメタ情報です(任意)
[agent]
name = "my-custom-agent"
version = "1.0.0"
description = "カスタムエージェント"

# [database] は PostgreSQLConfig.from_toml() が読み込みます(必須)
[database]
host = "${POSTGRESQL_HOST}"
port = 5432
database = "${POSTGRESQL_DATABASE}"
username = "${POSTGRESQL_USER}"
password = "${POSTGRESQL_PASSWORD}"
use_azure_ad = true

[database.azure_ad]
tenant_id = "${AZURE_TENANT_ID}"
client_id = "${AZURE_CLIENT_ID}"
client_secret = "${AZURE_CLIENT_SECRET}"

from_toml() が読み込むのは利用モジュールに対応するセクションのみです。既定は [database]([postgresql] ではなく、フィールドは username)、Azure AD 利用時は use_azure_ad = true + [database.azure_ad]、さらに利用時に [memory] / [rag.embedding] / [rag.qdrant]。[agent] は SDK が読まないメタ情報です(name 等は Console で設定)。

既定パスはありません。from_toml("config.toml") は渡したパスをそのまま読み込むため、config.toml はエージェントの作業ディレクトリに置いてイメージに同梱し、そのパスを渡してください。(認証設定 AgenticStarAuthConfig.from_config() は、パス省略時にカレントディレクトリ → プロジェクトルートの順で config.toml を自動検出します。)値は直書きせず ${VAR_NAME} プレースホルダーを使い、from_toml() が読み込み時に ${VAR} / ${VAR:-default} を os.environ から展開します(標準ライブラリ tomllib、外部 toml 不要)。

config.toml で参照する環境変数(POSTGRESQL_* / AZURE_* 等)は [マーケットプレイスのAIエージェント → 環境変数] に登録してください。 自動注入されるのはコンテキスト変数(EXECUTION_ID、USER_ID 等。一覧は設定ガイド — 環境変数)と、完了の知らせ用のトークン ASTER_NOTIFY_TOKEN のみです。

ステップ 4: プラットフォーム登録​

  1. 管理画面にログイン — AGENTIC STAR Console にアクセス
  2. AIエージェント作成画面 — 「AIエージェント」→「マーケットプレイスのAIエージェント」から作成
  3. 基本情報の入力(設定ガイド — マーケットプレイスのAIエージェント):
フィールド値説明
AIエージェントIDmy-custom-agent一意の識別子(小文字英数字とハイフン)
表示名マイカスタムエージェントUI に表示される名前
レジストリ / イメージ名 / タグyour-registry.example.com / my-org/my-agent / v1.0.0コンテナイメージを 3 つの欄に分けて入力(イメージ名にはレジストリを含めない)
環境変数DB_HOST / DB_PASSWORD / WEBHOOK_URL などDB 接続(PostgreSQLConfig.from_env() 契約)と Webhook 通知先。コンテキスト変数(EXECUTION_ID 等)と ASTER_NOTIFY_TOKEN は自動注入のため登録不可(同名登録はエラー)

入力したら、Docker イメージの欄の「イメージを確認する」で、このクラスターでイメージを取得できるかを確かめられます(設定ガイド — イメージを確認する)。

  1. 生成モデルの接続 — エージェントの登録とは別のメニュー「生成モデルの接続」で、使う LLM のプロバイダーとモデルを登録(設定ガイド — 生成モデルの接続)
  2. リソース設定 — CPU / メモリのリクエスト・リミットを設定(設定ガイド — リソース)
  3. 保存 & デプロイ

ステップ 5: 動作確認​

API エンドポイントでの確認​

curl
# チャットリクエスト
curl -X POST https://your-platform.example.com/conversation/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"model": "my-custom-agent",
"messages": [{"role": "user", "content": "こんにちは"}],
"stream": true
}'

<access_token> の取得手順は、API を呼び出す — Step 2: トークンの取得 を参照してください。

Chat Web App での確認​

  1. Chat Web App にアクセス
  2. エージェント選択ドロップダウンから「マイカスタムエージェント」を選択
  3. メッセージを送信して動作を確認

実行ライフサイクルと Pod 管理​

Pod のライフサイクル管理(起動・実行状態の記録・終了・後片付け)はプラットフォーム側の責務です。エージェント側での実装は不要です。

  • 実行状態の記録は Marketplace executor が行います。エージェントが SDK の PodRuntime を呼ぶ必要はありません(executor の記録と二重管理になります。またエージェントの Pod には ServiceAccount トークンが割り当てられないため、Pod 内から Kubernetes API を呼ぶコードは動作しません)
  • 終端イベント(COMPLETION_SUCCESS / COMPLETION_FAILURE)は run_marketplace_agent() が正確に 1 回配信します。agent 関数が例外を投げた場合も、runner が COMPLETION_FAILURE を配信した上でプロセスを正常終了します
  • 処理完了後はプロセスが exit 0 で終了し、Pod の後片付けはプラットフォームが行います
  • サイクル型の実行(プラットフォームが予定で起動する会話)は、exit 0 で終わっても完遂とは数えられません(「実行終了(完遂は未計測)」)。成功として数えるには、agent が report_completion で完遂を報告します(v3.0.14+。クイックスタート)
  • 起動の後に異常終了を繰り返す実行と、管理画面の「実行時間の上限」に 10 分を足した時間を過ぎても終わらない実行(上限を設けていないときは、実行の寿命の 10 分前を過ぎた実行)は、プラットフォームが失敗として閉じ、チャットに停止したことを知らせる文を出します(WEBHOOK_URL がプラットフォームの通知先のとき)

PodRuntime クラス(SDK API リファレンス)は、マーケットプレイス外で Pod を自前管理するデプロイ形態向けのビルディングブロックであり、マーケットプレイスのカスタムエージェントでは使用しません。

トラブルシューティング​

症状原因対処
Pod が再起動を繰り返すプロセスが非 0 で終了している(restartPolicy: OnFailure のため再起動される)実行履歴の「Pod の状態」と「ログを見る」でエラーを確認(下記)。run_marketplace_agent で処理後 exit 0 で終了する構成にする(常駐サーバとして起動しない)
Pod が CrashLoopBackOffconfig.toml の読み込み失敗環境変数が正しく注入されているか確認
サイクル型の実行が終わらず、次の発火が見送られる処理が終わってもプロセスが残っている(ヘルスチェックに応答し続けるサーバのまま)。プラットフォームはコンテナの終了コードで実行の終わりを判定する処理の完了後にサーバを閉じてプロセスを終了する([クイックスタート](/docs/marketplace/develop/quickstart/quickstart-sdk#exit-after-run))
MarketplaceRunnerFenceTaken で停止(v3.0.12+)サイクル型の実行で Pod が作り直され、前の runner が既に agent を起動していた対処は不要(同じ実行を二重に動かさないための停止)。実行はプラットフォームが効果不明の失敗として閉じます
サイクル型の実行が成功に数えられない(結果が「実行終了(完遂は未計測)」)agent が完遂を報告していない(プロセスの正常終了は完遂と見なされない)agent の最後で report_completion を呼んで完遂を報告する(v3.0.14+)。報告はコンテナが exit 0 で終わったときだけ採用される
MarketplaceRunnerConfigError で停止WEBHOOK_URL またはコンテキスト変数(EXECUTION_ID 等)の欠落[マーケットプレイスのAIエージェント → 環境変数]に WEBHOOK_URL が登録されているか確認(DB_* の欠落はこのエラーではなく接続エラーになる)
DB 接続タイムアウトPostgreSQL へのネットワーク到達不可NetworkPolicy と Service の設定を確認
応答が Chat に表示されないWEBHOOK_URL の未設定または誤り環境変数 WEBHOOK_URL の値を確認
イメージプルエラーレジストリ認証失敗・イメージの指定の誤り・レジストリに接続できないマーケットプレイスのAIエージェントの「イメージを確認する」で理由を確認(下記)

イメージを取得できないときは、マーケットプレイスのAIエージェントの「イメージを確認する」で理由を確かめられます(設定ガイド — イメージを確認する)。

実行ごとの Pod の状態とログは、管理画面の「プロジェクト管理」→「実行履歴」でその実行を開くと見られます。「Pod の状態」には「起動待ち」「実行中」「異常に終わりました」などの状態が出ます。終了コードは記録されていれば出て、止まった理由は分かるときに出ます。「ログを見る」で理由を入力すると、その実行のエージェントのログを取得します(出力が無いときや保持期間を過ぎたときは出ません)。ログを見られるのは対象の組織の組織管理者で、見た人と理由は記録されます。ログの保持期間は既定で 7 日です。

次のステップ​

アーキテクチャガイド

SDK のモジュール構成と設計思想

ガイドを見る

SDK API リファレンス

全モジュール・クラス・メソッドの完全仕様

ガイドを見る