# デプロイガイド

カスタムエージェントを 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/develop/quickstart/quickstart-sdk.md) の「Marketplace 互換で実行する（runner）」を参照してください。

> **ワークフローの工程で動くエージェント**
>
> プロジェクトのワークフローで使うエージェント（マーケットプレイス版 3.2.0 以降）は、`run_marketplace_agent` ではなく `agenticstar_platform.workflow.run()` を起動コマンドから呼びます。管理画面の登録では「ワークフローで使う」を有効にして契約を登録し、イメージの digest などの認定情報が登録されるまでワークフローでは起動できません。詳しくは [ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md) を参照してください。

## 前提条件

- 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]==3.3.0
openai>=1.60.0
qdrant-client>=1.13.0
```

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()` などがこのファイルを読んで設定を構築するため、**SDK のメモリ・RAG などのモジュールを使うエージェントには config.toml が必要**です（ビルドしたコンテナイメージに同梱してください）。`run_marketplace_agent` だけを使うエージェントは、config.toml を使わず、DB の接続情報を環境変数 `DB_HOST`・`DB_DATABASE`・`DB_USER`・`DB_PASSWORD` で渡すこともできます（`db_config` を省くと、SDK がこれらの環境変数から接続情報を組み立てます）。作成方法の基本は [クイックスタート — ステップ 2: 設定ファイルの作成](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/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) を参照してください。

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

```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_*` 等）は ［マーケットプレイスのAIエージェント → 環境変数］ に登録してください。** 自動注入されるのはコンテキスト変数（`EXECUTION_ID`、`USER_ID` 等。一覧は[設定ガイド — 環境変数](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/settings-guide.md#%E7%92%B0%E5%A2%83%E5%A4%89%E6%95%B0)）と、完了の知らせ用のトークン `ASTER_NOTIFY_TOKEN` のみです。

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

1. **管理画面にログイン** — AGENTIC STAR Console にアクセス
2. **AIエージェント作成画面** — 「AIエージェント」→「マーケットプレイスのAIエージェント」から作成
3. **基本情報の入力**（[設定ガイド — マーケットプレイスのAIエージェント](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/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)）:

| フィールド              | 値                                                      | 説明                                                                                                                         |
| ------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| AIエージェントID         | `my-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 イメージの欄の「**イメージを確認する**」で、このクラスターでイメージを取得できるかを確かめられます（[設定ガイド — イメージを確認する](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/settings-guide.md#%E3%82%A4%E3%83%A1%E3%83%BC%E3%82%B8%E3%82%92%E7%A2%BA%E8%AA%8D%E3%81%99%E3%82%8B)）。

4. **生成モデルの接続** — エージェントの登録とは別のメニュー「生成モデルの接続」で、使う LLM のプロバイダーとモデルを登録（[設定ガイド — 生成モデルの接続](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/settings-guide.md#llm-%E8%A8%AD%E5%AE%9A)）
5. **リソース設定** — CPU / メモリのリクエスト・リミットを設定（[設定ガイド — リソース](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/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/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 のライフサイクル管理（起動・実行状態の記録・終了・後片付け）は**プラットフォーム側の責務**です。エージェント側での実装は不要です。

- 実行状態の記録は 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+。[クイックスタート](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/quickstart/quickstart-sdk.md#report-completion)）
- 起動の後に異常終了を繰り返す実行と、管理画面の「実行時間の上限」に 10 分を足した時間を過ぎても終わらない実行（上限を設けていないときは、実行の寿命の 10 分前を過ぎた実行）は、プラットフォームが失敗として閉じ、チャットに停止したことを知らせる文を出します（`WEBHOOK_URL` がプラットフォームの通知先のとき）

`PodRuntime` クラス（[SDK API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/reference/sdk-ref.md)）は、マーケットプレイス外で Pod を自前管理するデプロイ形態向けのビルディングブロックであり、マーケットプレイスのカスタムエージェントでは使用しません。

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

| 症状                                          | 原因                                                                       | 対処                                                                                                        |
| ------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `Pod が再起動を繰り返す`                             | プロセスが非 0 で終了している（restartPolicy: OnFailure のため再起動される）                     | 実行履歴の「Pod の状態」と「ログを見る」でエラーを確認（下記）。run\_marketplace\_agent で処理後 exit 0 で終了する構成にする（常駐サーバとして起動しない）           |
| `Pod が CrashLoopBackOff`                    | config.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エージェントの「イメージを確認する」で理由を確かめられます（[設定ガイド — イメージを確認する](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/settings-guide.md#%E3%82%A4%E3%83%A1%E3%83%BC%E3%82%B8%E3%82%92%E7%A2%BA%E8%AA%8D%E3%81%99%E3%82%8B)）。

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

## 次のステップ

アーキテクチャガイド

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

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

SDK API リファレンス

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

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