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

デプロイガイド

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

概要​

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

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

前提条件​

  • Docker 24.0 以上
  • Azure Container Registry（ACR）または互換レジストリへのアクセス
  • 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 . .

# ヘルスチェック
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"

# ポート公開
EXPOSE 8000

# エントリポイント
CMD ["python", "start_api_server.py"]
requirements.txt
agenticstar-platform[all]==0.5.3
fastapi>=0.115.0
uvicorn>=0.34.0
openai>=1.60.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 に以下の構成を含めてください。

config.tomlToml
[agent]
name = "my-custom-agent"
version = "1.0.0"
description = "カスタムエージェント"
port = 8000

[postgresql]
host = "${POSTGRESQL_HOST}"
port = 5432
database = "${POSTGRESQL_DATABASE}"
user = "${POSTGRESQL_USER}"
password = "${POSTGRESQL_PASSWORD}"

[postgresql.azure_ad]
enabled = true
tenant_id = "${AZURE_TENANT_ID}"

プラットフォームが PostgreSQL 接続情報や Azure AD 設定などの環境変数を Pod 起動時に自動注入します。config.toml 内で ${VAR_NAME} 形式のプレースホルダーを使用してください。

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

  1. 管理画面にログイン — AGENTIC STAR Console にアクセス
  2. エージェント管理画面 — 「エージェント」→「新規登録」
  3. 基本情報の入力:
フィールド値説明
エージェント名my-custom-agent一意の識別子（英数字・ハイフン）
表示名マイカスタムエージェントUI に表示される名前
コンテナイメージyour-acr.azurecr.io/my-agent:v1.0.0レジストリのフルパス
ポート8000コンテナが公開するポート
ヘルスチェックパス/healthKubernetes がチェックするエンドポイント
  1. LLM 設定 — 使用する Azure OpenAI モデルとエンドポイントを設定
  2. リソース設定 — CPU / メモリのリクエスト・リミットを設定
  3. 保存 & デプロイ

ステップ 5: 動作確認​

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

curl
# ヘルスチェック
curl https://your-platform.example.com/agents/my-custom-agent/health

# チャットリクエスト
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
  }'

Chat Web App での確認​

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

Pod ライフサイクル​

SDK の PodRuntime クラスを使うと、Pod の起動・終了時にプラットフォームへ状態を通知できます。

start_api_server.pyPython
from agenticstar_platform.db.pod_runtime import PodRuntime

runtime = PodRuntime(db_manager)

# Pod 起動を通知
await runtime.report_pod_start(
    conversation_id=conversation_id,
    pod_name=os.environ.get("HOSTNAME", "unknown"),
)

# --- エージェント処理 ---

# Pod 終了を通知（自動スケールダウン）
await runtime.report_pod_final(
    conversation_id=conversation_id,
    status="completed",
)

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

症状原因対処
Pod が CrashLoopBackOffconfig.toml の読み込み失敗環境変数が正しく注入されているか確認
DB 接続タイムアウトPostgreSQL へのネットワーク到達不可NetworkPolicy と Service の設定を確認
ヘルスチェック失敗/health エンドポイント未実装FastAPI に /health ルートを追加
イメージプルエラーレジストリ認証失敗imagePullSecrets の設定を確認

次のステップ​

アーキテクチャガイド

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

ガイドを見る

SDK API リファレンス

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

ガイドを見る