> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# AI によるプロトコル作成
> バッテリー試験を英語で説明するだけで、検証済みの UCP プロトコルが返ってきます。実行にもテンプレート保存にも使えます
**AI プロトコル作成** は、バッテリー試験の英語の説明を、検証済みの
[Universal Cycler Protocol](/ja/simulate/universal-cycler-protocol) (UCP)
に変換します。実行したい内容を入力し（例：
`"1C/1C cycling for 200 cycles between 4.2 V and 2.5 V with 10-minute rests"`)、
**Generate** をクリックすると、生成された YAML がそのままプロトコルエディタに
入ります。
これはピッカー・アップロード・[インタラクティブビルダー](/ja/simulate/protocol-builder)
の行の上に、第 4 の作成手段として配置されています。実行したい試験は言葉で
分かっているが、YAML を手で書きたくない、あるいはビジュアルエディタを
クリックして進めたくない場合に使ってください。
ジェネレーターが返すプロトコルは、[`POST /protocols/validate`](/ja/simulate/api)
と同じ検証を通過しており、未解決の `input["..."]` プレースホルダーも
含みません。そのまま[実験テンプレート](/ja/simulate/experiment-templates)
として保存したり、[計画済み測定](/ja/operate/planned-measurements)に
紐付けたりできます。
## 表示される場所
プロンプトは **Test scheduler → Request test** フォーム
（[計画済み測定](/ja/operate/planned-measurements) を参照）の **Protocol**
セクションの先頭に表示されます。現時点で利用できるのはここだけです。
[プロトコル](/ja/simulate/protocols) 一覧、
[インタラクティブビルダー](/ja/simulate/protocol-builder)、および Studio の
他のプロトコルエディタには、まだプロンプトは表示されません。
プレースホルダーは状況に応じて変わります：
* **プロトコル未読み込み** — `Enter prompt to generate protocol using AI, e.g. "1C/1C cycling for 100 cycles between 4.2 V and 2.5 V"`
* **プロトコルが既に読み込まれている場合** — `Enter prompt to change protocol using AI, e.g. "make it 200 cycles"`
プロトコルが既に読み込まれている場合、プロンプトは新規作成ではなく
そのプロトコルに対する *編集*（`Update`）として扱われます。保存済み
テンプレートを微調整する最速の方法です。エディタで該当ステップを
探すのではなく、変更したい内容を言葉で伝えてください。
## 良いプロンプトの書き方
チャネル上で実際に何が動くかを変える値については、具体的に書いてください：
* **C レートまたは電流** — `1C`、`C/3`、`10 A`
* **電圧範囲** — `between 4.2 V and 2.5 V`
* **サイクル数**、**休止時間**、**温度**
* 電圧範囲以外の **終了条件**（容量劣化、時間上限など）
曖昧なままにした項目は、ジェネレーターが
[セル仕様](/ja/core-concepts/cells) から推測するか、
[明確化のための質問](#明確化のための質問)で問い返します。
### 例
```text 1C/1C サイクリング theme={null}
1C/1C cycling for 200 cycles between 4.2 V and 2.5 V with 10-minute rests
between charge and discharge.
```
```text 20 パルスの GITT theme={null}
GITT at C/10 with 20 discharge pulses, 30 minutes each, followed by 2 hours
of rest.
```
```text フォーメーション theme={null}
Formation: three CC-CV charge/discharge cycles at C/20 between 4.2 V and 3.0 V.
```
## セル仕様のコンテキスト
**セル仕様** を渡すと（Test scheduler のリクエストフォームは試験対象の
セルから自動的に選択します）、ジェネレーターにはそのセルの電圧上下限、
公称容量、電流定格が事実として与えられ、それらについて推測や質問を
しなくなります。プロンプト品質を上げる最大のレバーです。セルを添付
すれば `"cycle it at 1C"` だけで十分です。
セルが無い場合は、電圧範囲と容量をプロンプト内で明示してください。
## 明確化のための質問
説明の中に、チャネルで動く内容を大きく左右するのに未確定な値が
残っている場合、ジェネレーターはプロトコルを書く前に質問します。
各質問に答えて **Generate protocol** をクリックしてください。答えは
やり取りに追加され、モデルは再度作成を試みます。
候補の選択肢はチップとして表示され、クリックで選べます。あるいは
自分で入力することもできます。やり取りはステートレスで、再試行の
たびに回答履歴全体を再送するため、ページを更新しても失うのは
入力中の文字だけです。
ジェネレーターがコンテキストから判断できる質問には答える必要は
ありません。カットオフ電圧について議論するより、セル仕様を添付する方が
早いです。
## 保存済みプロトコルの提案
新しくプロトコルを書く前に、ジェネレーターはあなたの組織の保存済み
プロトコルから、要求内容を既に満たすものを探します。一致するものが
あれば、**Saved protocols that already do this** パネルに、各候補ごとに
**Use this** ボタン付きで表示されます。
再生成より再利用が優先されます。保存済みプロトコルは既にレビューと
命名が済んでいるためです。候補が合わない場合は、**Write a new one instead**
をクリックすると、その実行では再利用をスキップします。
## 説明と前提
プロトコルが書き上がると、プロンプトの下に短い確認が表示されます：
* **Explanation** — プロトコルが行う内容を 1 文で説明します。
* **Assumed:** — 明示していないのにジェネレーターが選んだ値
（標準的な休止時間、既定温度など）が列挙されます。実行前に必ず
確認してください。同意できない項目は、編集プロンプトを 1 回打てば
修正できます。
生成された YAML は下のソースエディタに、提案された名前は
**Protocol name** フィールドに入ります。どちらも保存前に編集可能です。
## AI で修正
プロトコルの解析に失敗した場合（壊れたファイルをアップロードしたり、
YAML を手で編集して壊した場合など）、**Request test** フォームの
解析エラーの警告に **Fix with AI**
ボタンが表示されます。プロンプト本体と同様、この操作も現時点では
テストスケジューラに限定されています。Studio の他のプロトコルエディタでは
解析エラーは表示されますが、修正ボタンはありません。クリックすると、壊れたプロトコルとエラー
メッセージがジェネレーターに送られ、「Fix it, changing as little as
possible.（可能な限り変更を抑えて修正して）」という指示で
呼び出されます。
ほぼ正しいプロトコルをやり直しではなく救済したい場合に使ってください。
## API
UI の背後にあるのは 1 つのエンドポイントだけです：
```bash cURL theme={null}
curl -X POST "https://api.ionworks.com/protocols/generate" \
-H "Authorization: Bearer $IONWORKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "1C/1C cycling for 200 cycles between 4.2 V and 2.5 V with 10-minute rests",
"cell_specification_id": "cell-spec-id"
}'
```
```python Python theme={null}
import httpx
response = httpx.post(
"https://api.ionworks.com/protocols/generate",
headers={"Authorization": f"Bearer {api_key}"},
json={
"prompt": (
"1C/1C cycling for 200 cycles between 4.2 V and 2.5 V "
"with 10-minute rests"
),
"cell_specification_id": "cell-spec-id",
},
timeout=120,
)
result = response.json()
```
### リクエスト
| フィールド | 型 | 説明 |
| ----------------------- | ----------------------------- | ------------------------------------------------------- |
| `prompt` | 文字列（必須） | 実行したい試験のプレーンイングリッシュの説明（最大 4000 文字）。 |
| `current_protocol` | 文字列（任意） | 既存プロトコルの UCP YAML。指定すると、プロンプトは新規作成ではなくその *編集* として扱われます。 |
| `clarifications` | `{question, answer}` のリスト（任意） | 前回の呼び出しで返された質問への回答。古い順に。呼び出しごとに履歴全体を送ってください（ステートレスです）。 |
| `cell_specification_id` | 文字列（任意） | 試験対象のセル。電圧上下限・容量・電流定格が事実としてジェネレーターに渡されます。 |
| `skip_existing` | 真偽値（既定 `false`） | 保存済みプロトコルの検索をスキップして新規に書きます。ユーザーが候補を拒否したときに設定します。 |
### レスポンス
3 つの分岐のうちちょうど 1 つだけが埋まります：
| フィールド | 埋まる条件 | 説明 |
| ----------------------------------------------------- | -------------------- | --------------------------------------------------------------------------- |
| `protocol_yaml`, `name`, `explanation`, `assumptions` | ジェネレーターがプロトコルを書いた場合。 | 検証済みの UCP YAML、提案名、1 文の説明、ジェネレーターが指示なく選んだ値の一覧。 |
| `questions` | ジェネレーターに追加情報が必要な場合。 | `{question, why, options}` のリスト。ユーザーに提示し、回答を `clarifications` に入れて再呼び出しします。 |
| `matches` | 保存済みプロトコルで要求を満たせる場合。 | `{template_ids, note}`。候補として提示するか、`skip_existing: true` で再呼び出しして新規に書き直します。 |
`protocol_yaml` を読む前に `questions` と `matches` を確認してください。
どちらかが埋まっているときは `protocol_yaml` は空です。
### エラー
* **422** — 不正なリクエスト（空プロンプト、フィールド過大、
clarifications が 20 件超など）。これらはリクエストモデルの検証エラーで
あり、`BAD_REQUEST` ではなく FastAPI 標準の検証レスポンスとして返ります。
* **502** — モデルが有効なプロトコルを生成できませんでした。試験内容を
言い換えるか、[プロトコルビルダー](/ja/simulate/protocol-builder) で
構築してください。
エンドポイントが返すプロトコルは、UCP 検証を通過し `input["..."]` の
未解決参照も含みません。ジェネレーターが内部的に再試行して両方を
満たすまで返さないため、呼び出し側で再検証する必要はありません。
## 制限とヒント
* `prompt` は **4000 文字**、任意の UCP ペイロードは **100,000 文字**、
回答は 1 セッションあたり **20 ラウンド**が上限です。それを超える場合は
リクエストを分割するか、値をご自身で確定してください。
* ジェネレーターは呼び出しごとにフロンティアモデルを使用します。良い
プロトコルができたら[実験テンプレート](/ja/simulate/experiment-templates)
として保存してください。再利用は無料です。
* 完全に決定論的に作成したい場合（モデルを介したくない場合）は、
[プロトコルビルダー](/ja/simulate/protocol-builder) を使うか、UCP
YAML を直接記述してください。
## 次のステップ
UCP プロトコルをステップごとに視覚的に構築します。
ジェネレーターが出力する UCP YAML 形式の完全なリファレンス。
生成されたプロトコルを保存、複製、設定します。
生成されたプロトコルを予約された試験に紐付けます。