# エージェントガイド

マーケットプレイス版のプロジェクトで工程に置くのは、**管理者が管理コンソールで登録した Agent**（登録 Agent）です。登録 Agent は、SDK で作ったコンテナのイメージです。何をするかはイメージと、管理者が登録した契約で決まります。

**SaaS 版と違い、プロジェクトの画面では Agent を作れず、中身も変えられません。** ゴール (指示)・ガードレール・Playbook・Skill を付けることもありません。プロジェクトで決めるのは、どの工程に置くかと、工程ごとの設定だけです。

|              | SaaS 版                         | マーケットプレイス版                            |
| ------------ | ------------------------------ | ------------------------------------- |
| Agent を用意する人 | 利用者がプロジェクトの編集画面で作る             | 管理者が管理コンソールの「マーケットプレイスのAIエージェント」で登録する |
| 動き方を決めるもの    | ゴール (指示)・ガードレール・Playbook・Skill | コンテナのイメージと契約                          |
| 工程ごとに変えられるもの | （Agent を直すと、置いた全工程に効く）         | 工程の設定（ワークフロー）・環境変数（サイクル）              |

## 置ける Agent

編集画面の左の「**Agent を追加**」を押すと、一覧が登録 Agent の一覧に切り替わります。SaaS 版の「新しい Agent」「Schedule・Claw から作る」はありません。一覧には、型ごとに次の登録 Agent が並びます。

| 型          | 並ぶ Agent                                                            |
| ---------- | ------------------------------------------------------------------- |
| **ワークフロー** | 管理者が「ワークフローで使う」をオンにして契約を登録した、有効な登録 Agent。**認定済みの Agent だけを工程に置けます** |
| **サイクル**   | 管理者が有効にした登録 Agent（会話で使う Agent）。契約も認定も要りません                          |

ワークフローの一覧では、Agent ごとに「**認定済み**」か「**利用不可 (未認定)**」が付きます。未認定の Agent は置けません。未認定のままの理由は、契約の誤り、認定の情報（SDK 版・adapter 版・image digest・試験結果の参照・使える実行ルール）の不足や形式の誤り、または認定の情報の実行の効果と契約の実行の効果の食い違いです。**管理者に、契約と認定の登録を頼んでください**（[設定ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/guide/settings-guide.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC%E3%81%A7%E4%BD%BF%E3%81%86)）。

「ワークフローで使用できる Agent がありません。管理画面の『マーケットプレイスのAIエージェント』で『ワークフローで使う』を登録してください」と出るときは、契約を登録した有効な登録 Agent が 1 つもありません。

**1 つのプロジェクトに置けるのは登録 Agent だけです。** 登録 Agent とそれ以外の Agent を同じプロジェクトに置くことはできません。

## 工程に置く

一覧で Agent を選び、右の「Agent の内容」の「**工程に配置する**」で置き先の工程を押します。工程の「基本設定」の「Agent を追加」からも置けます。

登録 Agent を**初めて**工程に置くと、**その場でプロジェクトに保存されます**（「Agent を配置しました」と出ます）。SaaS 版のように下書きには載りません。定義の変更に承認が要る環境では、初めての配置も承認待ちのバージョンになり、承認されるまで実行には使われません。置いた Agent を、ほかの工程にも置いたり外したりする操作は、下書きに載ります。反映の操作は SaaS 版と同じです（[設計ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/project/guide/design-guide.md)）。

ワークフローに置いた Agent の設定には、「顧客が登録した Agent です。内容は管理画面の『マーケットプレイスのAIエージェント』の『ワークフローで使う』で決定され、ここでは工程ごとの設定だけ変更できます」と出ます。

**ワークフローで同じ工程に複数置くと、配置順に 1 体ずつ動きます。** 「同時に実行」はありません。**サイクルでは、同じ工程の配置どうしも互いを待たず、それぞれの周期や Webhook で動きます。**

## 工程の設定（ワークフロー）

ワークフローの工程に置いた登録 Agent を選ぶと、「工程の Agent」の「**基本設定**」に「**工程の設定**」が出ます。契約で決まった範囲のうち、この工程で変えたい値を入れます。入れた値は**下書き**に入り、「**変更を反映**」で保存されます。

| 欄               | 入れるもの                                                                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **設定値**         | 契約の設定項目の値。文字列・整数・数値・はい／いいえ・選択肢の項目を変えられます。**保存されるのは値を入れた項目だけで、空欄の項目は Agent の標準値のままです。** 画面で変えられない型の項目は「○ 件の項目は画面で編集できません（管理画面の『ワークフローで使う』で定義）」と出ます |
| **連携先**         | 契約の接続 slot ごとに、このプロジェクトの連携先から選びます。選べるのは、管理者が slot に許可した連携先だけです。許可された連携先がこのプロジェクトに無いときは、先に設定の連携先で追加します                                             |
| **入力ファイルの受け渡し** | 先行する工程の Agent の出力を、この Agent の入力ファイルとしてつなぎます。「案件の設定で渡す」を選んだファイルは、案件を始めるときに入れます                                                                     |

**前の工程の出力は、自動では次の工程に渡りません。** SaaS 版では次の工程の Agent に前の工程の出力が渡りますが、マーケットプレイス版では、ここでつないだファイルだけが渡ります。工程をまたいで受け渡したい出力は、必ず「入力ファイルの受け渡し」でつないでください。

**時間トリガー・Webhook トリガーや、`config` を渡さない外部 API で始めるなら、必須の設定値と連携先は工程の設定に入れておきます。** その始め方では、開始のときに値を渡さないためです。外部 API では、開始のときに `config` で値を渡すこともできます（[起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/trigger-guide.md#%E3%83%AF%E3%83%BC%E3%82%AF%E3%83%95%E3%83%AD%E3%83%BC%E3%82%92%E5%A7%8B%E3%82%81%E3%82%8B)）。

### 契約の要約を読む

置いた Agent の「**参照・ツール**」には、契約の要約が出ます。一覧で Agent を選んだときの「Agent の内容」にも、同じ要約が出ます。

| 項目         | 意味                                                                                                                                                                                                                                                                                        |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **外部への効果** | 「読み取りのみ」「書き込み (再送しても同じ結果)」「書き込み (再送で重複しうる)」のいずれか。失敗したときに自動でやり直すかが、これで決まります（[起動ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/project/guide/trigger-guide.md#%E3%81%86%E3%81%BE%E3%81%8F%E3%81%84%E3%81%8B%E3%81%AA%E3%81%8B%E3%81%A3%E3%81%9F%E3%81%A8%E3%81%8D)） |
| **実行上限**   | 1 回の実行の制限時間。「実行上限なし」は、配備の上限（既定 24 時間）まで                                                                                                                                                                                                                                                   |
| **ファイル**   | Agent が受け取る入力ファイル。「必須」「編集可」「設定値から生成」が付きます                                                                                                                                                                                                                                                 |
| **出力**     | Agent が作る成果物。次の工程の入力ファイルにつなげます                                                                                                                                                                                                                                                            |
| **連携先**    | 契約の接続 slot と、必須かどうか                                                                                                                                                                                                                                                                       |

## 環境変数（サイクル）

サイクルの工程に置いた登録 Agent には、「**環境変数**」があります。この工程で Agent を動かすときに渡す環境変数です。

- **新しい名前を足せます。** 名前は英大文字で始め、英大文字・数字・`_` の 64 文字までです
- **Agent に登録された値を上書きできます。** 秘密として登録された値は上書きできません（「秘密のため変更できません」）
- **管理者が変更を禁止した名前は使えません**（「管理者が変更を禁止」）。予約された名前（`ASTER_`・`MP_` で始まる名前など）も使えません
- 32 個まで、名前と値の合計 16 KiB までです

「保存済みの環境変数に、今の設定では使用できない名前があります」と出たときは、管理者があとから禁止した名前が残っています。**そのままでは起動できないので、その名前を削除して反映し直してください。** 「管理者の禁止設定の形が正しくないため、この工程では環境変数を使用できません」と出たときは、管理者に設定の確認を頼んでください。

## Agent に渡るもの

**プロジェクトから Agent に、指示の文章は渡りません。** 何をするかは Agent のイメージが決めます。プロジェクトから渡るのは次のものです。

### ワークフローで Agent に渡るもの

| 渡るもの     | 中身                                                        |
| -------- | --------------------------------------------------------- |
| 設定値      | 契約の標準値に、工程の設定と案件の設定を重ねた値                                  |
| 入力ファイル   | 案件の設定で入れた指示ファイルと、つないだ先行する工程の出力                            |
| 連携先のトークン | 工程の設定で選んだ連携先の、OAuth のトークン                                 |
| 確認の決定    | 直前の確認工程で、人が決めたか基盤が決めたか、進めたか差し戻したか、人が書いた差し戻しの理由や進めたときのコメント |

Agent の作り方は[ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md)にあります。

### サイクルで Agent に渡るもの

| 渡るもの     | 中身                                                                                                                                                                                 |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 本文       | 「このタスクはプロジェクト「（プロジェクト名）」の周期巡回 (sweep) です。担当工程: （工程名） (状態 id: …)。」という決まった 1 文。Webhook で起動したときは、受け付けた内容が続きます（外部からの入力として、データとして扱うよう添えて。8,000 文字まで）                                    |
| 環境変数     | Agent に登録された値と、工程の環境変数。加えて、実行・会話・プロジェクトの ID など、基盤が決める値                                                                                                                             |
| 連携先のトークン | このプロジェクトの連携先のうち、有効なもののトークン。接続が切れているものや、期限が過ぎていて更新できないものは渡りません（期限が過ぎていても、更新できれば渡ります。連携先を接続し直すと、次の実行から渡ります）。**有効な連携先が 8 件を超えるとき、同じ種類の連携先が 2 つ有効なとき、トークンの変数名がほかの環境変数とぶつかるときは、起動しません** |

**サイクルの Agent は、1 回の処理が終わったら終了する作りでなければなりません。** 終了しないと、その配置の次の起動が見送られ続けます。作り方は[はじめてのエージェント](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/quickstart/quickstart-sdk.md#exit-after-run)にあります。

## Agent の動きを変えたいとき

動きを変える場所は、変えたい内容で決まります。

| 変えたいこと                          | 頼む先                                                                          |
| ------------------------------- | ---------------------------------------------------------------------------- |
| この工程での値（設定値・連携先・入力ファイル・環境変数）    | オーナーが工程の設定・環境変数で変える                                                          |
| 変えられる項目そのもの、外部への効果、実行上限、接続 slot | 管理者が契約を変える                                                                   |
| Agent のする仕事、出力の中身               | Agent の開発者がイメージを作り直す。**イメージを変えたら、管理者が認定し直します**（認定した image digest のイメージで動くため） |
