デプロイガイド

カスタムエージェントを 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）」を参照してください。

前提条件

• 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]==0.5.40
openai>=1.60.0
qdrant-client>=1.13.0

run_marketplace_agent のデフォルト構成（data_access 省略時の DB 接続フォールバック）は 0.5.30 以降を使用してください。0.5.29 には接続構築のバグがあり、data_access= を明示しない限り起動時に AttributeError で停止します。

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

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

Azure Container Registry

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

Amazon ECR

curl

# ビルド
docker build --platform linux/amd64 \
  -t 123456789.dkr.ecr.ap-northeast-1.amazonaws.com/my-agent:v1.0.0 .

# ECR にログイン
aws ecr get-login-password --region ap-northeast-1 | \
  docker login --username AWS --password-stdin 123456789.dkr.ecr.ap-northeast-1.amazonaws.com

# プッシュ
docker push 123456789.dkr.ecr.ap-northeast-1.amazonaws.com/my-agent:v1.0.0

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

config.toml は、SDK の各モジュール（DB / RAG / メモリ）が接続情報を組み立てるために読み込む設定ファイルです。PostgreSQLConfig.from_toml() などがこのファイルを読んで設定を構築するため、エージェントには config.toml が必要です（ビルドしたコンテナイメージに同梱してください）。作成方法の基本は クイックスタート — ステップ 2: 設定ファイルの作成 を参照してください。

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_* 等）は ［エージェント設定 → 環境変数］ に登録してください。 自動注入されるのはコンテキスト変数（EXECUTION_ID、USER_ID 等）のみです。

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

1. 管理画面にログイン — AGENTIC STAR Console にアクセス
2. エージェント管理画面 — 「エージェント」→「新規登録」
3. 基本情報の入力（設定ガイド — エージェント設定）:

フィールド	値	説明
エージェント名	my-custom-agent	一意の識別子（英数字・ハイフン）
表示名	マイカスタムエージェント	UI に表示される名前
コンテナイメージ	your-acr.azurecr.io/my-agent:v1.0.0	レジストリ・イメージ名・タグ
環境変数	DB_HOST / DB_PASSWORD / WEBHOOK_URL など	DB 接続（PostgreSQLConfig.from_env() 契約）と Webhook 通知先。コンテキスト変数（EXECUTION_ID 等）は自動注入のため登録不可（同名登録はエラー）

4. LLM 設定 — 使用する Azure OpenAI モデルとエンドポイントを設定（設定ガイド — LLM 設定）
5. リソース設定 — CPU / メモリのリクエスト・リミットを設定（設定ガイド — リソース）
6. 保存 & デプロイ

ステップ 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> の取得手順は、マーケットプレイス版クイックスタート — Step 2: トークンの取得 を参照してください。

Chat Web App での確認

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

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

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

• 実行状態（execution_pods テーブル）の記録は Marketplace executor が行います。エージェントが SDK の PodRuntime を呼ぶ必要はありません（executor の記録と二重管理になります。また marketplace-agents namespace の Pod には ServiceAccount トークンが割り当てられないため、Pod 内から Kubernetes API を呼ぶコードは動作しません）
• 終端イベント（COMPLETION_SUCCESS / COMPLETION_FAILURE）は run_marketplace_agent() が正確に 1 回配信します。agent 関数が例外を投げた場合も、runner が COMPLETION_FAILURE を配信した上でプロセスを正常終了します
• 処理完了後はプロセスが exit 0 で終了し、Pod の後片付けはプラットフォームが行います

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

トラブルシューティング

症状	原因	対処
Pod が再起動を繰り返す	プロセスが非 0 で終了している（restartPolicy: OnFailure のため再起動される）	ログでエラーを確認。run_marketplace_agent で処理後 exit 0 で終了する構成にする（常駐サーバとして起動しない）
Pod が CrashLoopBackOff	config.toml の読み込み失敗	環境変数が正しく注入されているか確認
MarketplaceRunnerConfigError で停止	WEBHOOK_URL またはコンテキスト変数（EXECUTION_ID 等）の欠落	［エージェント設定 → 環境変数］に WEBHOOK_URL が登録されているか確認（DB_* の欠落はこのエラーではなく接続エラーになる）
DB 接続タイムアウト	PostgreSQL へのネットワーク到達不可	NetworkPolicy と Service の設定を確認
応答が Chat に表示されない	WEBHOOK_URL の未設定または誤り	環境変数 WEBHOOK_URL の値を確認
イメージプルエラー	レジストリ認証失敗	imagePullSecrets の設定を確認

次のステップ

アーキテクチャガイド

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

ガイドを見る

SDK API リファレンス

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

ガイドを見る