# デプロイガイド

カスタムエージェントを 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 クイックスタート](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/quickstart/quickstart-sdk.md) の「Marketplace 互換で実行する（runner）」を参照してください。

## 前提条件

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

## ステップ 1: Dockerfile の作成

```dockerfile
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` で マウントするか書き込み先を可変ボリュームに向けてください。

```text
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**

```bash
# ビルド
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**

```bash
# ビルド
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: 設定ファイルの作成](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/quickstart/quickstart-sdk.md#%E3%82%B9%E3%83%86%E3%83%83%E3%83%97-2-%E8%A8%AD%E5%AE%9A%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%81%AE%E4%BD%9C%E6%88%90) を参照してください。

```toml
# [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. **基本情報の入力**（[設定ガイド — エージェント設定](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/build/guide/settings-guide.md#%E3%82%A8%E3%83%BC%E3%82%B8%E3%82%A7%E3%83%B3%E3%83%88%E8%A8%AD%E5%AE%9A)）:

| フィールド    | 値                                        | 説明                                                                                                  |
| -------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
| エージェント名  | `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 設定](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/build/guide/settings-guide.md#llm-%E8%A8%AD%E5%AE%9A)）
5. **リソース設定** — CPU / メモリのリクエスト・リミットを設定（[設定ガイド — リソース](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/build/guide/settings-guide.md#%E3%83%AA%E3%82%BD%E3%83%BC%E3%82%B9)）
6. **保存 & デプロイ**

## ステップ 5: 動作確認

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

```bash
# チャットリクエスト
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: トークンの取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/api/quickstart/call-api.md#step-2-%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%81%AE%E5%8F%96%E5%BE%97) を参照してください。

### 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 リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/reference/sdk-ref.md)）は、マーケットプレイス外で 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 のモジュール構成と設計思想

[ガイドを見る](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/guide/architecture.md)

SDK API リファレンス

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

[ガイドを見る](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/reference/sdk-ref.md)
