> ## Documentation Index
> Fetch the complete documentation index at: https://e2e.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# エージェントステップの仕組み

> モデルが見る情報、実行できる操作、ステップの終了条件、コストを説明します。

エージェントステップは、`agent.act`、`agent.assert`、`agent.waitFor`、`agent.extract` のいずれかを 1 回呼び出す処理です。モデルが画面を読み取り、操作を要求し、判定を返してステップを終えます。各ステップには制限時間とモデル呼び出し回数の上限があります。

## 役割の分担

エグゼキューターは操作を選び、判定を返します。ランナーは画面内の機密情報をマスキングし、各操作の許可と実行、予算の適用、シークレットの入力、レポートの作成を担当します。`agents` のエントリーで[独自のエグゼキューター](https://e2e.com/docs/ja/executors)を指定しない限り、組み込みエージェントがエグゼキューターになります。

## モデルに渡される情報

`act` の最初のプロンプトには、指示、パラメーター、完了済みのステップ、機密情報をマスキングした画面のテキストスナップショットが含まれます。スナップショットの内容は、ロール、名前、テキスト、状態です。生の HTML、Cookie、ヘッダー、環境変数の値は含まれません。パスワードフィールドはマスキングされ、設定済みのシークレットが画面に現れると `<secret:name>` に置き換わります。

操作の後、モデルには画面の差分が渡されます。画面の大部分が変わった場合は、新しい全体スナップショットが渡されます。ノード ID は、その要素が存在する間は変わりません。操作が失敗した場合にも現在の画面が返るため、モデルは次の操作を選べます。

`assert`、`waitFor`、`extract` の標準の判定には、指示、現在の画面とその場所、エージェントの `context` が渡されます。完了済みのステップや、操作を担当するエージェントの要約は渡されません。別の[ジャッジモデル](https://e2e.com/docs/ja/models#a-judge-of-its-own)も使用できます。組み込みの探索付きアサーションは、`judge` が設定されていても `agents.<name>.model` を使用します。

`vision: true` を指定するとマスキング済みのスクリーンショットが加わり、`vision: 'only'` ではスクリーンショットだけで判定します。モードについては[エージェントリファレンス](https://e2e.com/docs/ja/reference/agent#vision)を参照してください。スクリーンショットでマスキングされるのはセキュアなフィールドだけです（[シークレット入力後のスクリーンショット](https://e2e.com/docs/ja/reference/security#screenshots-after-a-secret-fill)）。

## モデルが実行できる操作

エージェントには、`tap`、`type`、`press`、`select`、`scroll`、`navigate` など、ターゲットのエンジンが対応するツールが渡されます。キーボードに対応したエンジンでは、フォーカス中のコントロールに文字やキーを入力できます。テキストスナップショットではコントロールを表現できない場合、ピクセル操作ツールでスクリーンショットを撮り、座標を指定して操作できます。[ツールリファレンス](https://e2e.com/docs/ja/reference/agent#pixel-tools-screenshot-and-the-point-verbs)を参照してください。

`Secret` パラメーターを入力するとき、モデルは `type_secret` を呼び出します。モデルに見えるのはシークレットの名前と用途だけです。ランナーはモデルが選んだフィールドを確認し、値を直接入力します。値がプロンプト、トランスクリプト、レポート、AI トレースに含まれることはありません。

対象を指定する操作は、最長 15 秒でタイムアウトします。[プロジェクトツール](https://e2e.com/docs/ja/tools)では、予算と対応プラットフォームを宣言した独自の操作を追加できます。

ループは、同じ呼び出しの繰り返しや循環を検出します。操作が 3 回連続で失敗すると、モデルに方法を変えるよう伝えます。5 回連続で失敗すると判定を求めます。予算や制限時間の上限が近づいた場合にも判定を求めます。

## アサーションで画面を探索する

`explore: true` を指定すると、`agent.assert` は読み取り専用ツールでスクロールし、複数の表示領域から得た根拠を組み合わせられます。表示領域は探索を終えた位置に残ります。現在の画面の別の場所にある内容にはこの機能を使い、時間とともに起きる変化には `waitFor` を使います。ツール、予算、判定については[アサーションの探索](https://e2e.com/docs/ja/reference/agent#agent-assert)を参照してください。

## ステップの終了条件

ステップは次の 3 つの判定のいずれかで終了します。

- `passed`: ステップが成功したことを画面で確認できました。
- `failed`: 必要な条件を満たしていないか、満たしていると確認できません。根拠が足りない場合は `ASSERTION_INCONCLUSIVE` になります。
- `blocked`: 前提条件、環境、制限のいずれかにより、製品の動作を判定する前にステップが停止しました。終了コードはエラーコードによって決まります。

エラーコードを持つのは `failed` と `blocked` だけです。

| 停止の原因 | コード | 終了コード |
| --- | --- | ---: |
| アプリが認証情報を拒否した、または認証情報が未設定 | `AUTH_CREDENTIAL_INVALID`, `AUTH_CREDENTIAL_UNAVAILABLE` | 2 |
| 環境が停止している | `ENVIRONMENT_UNAVAILABLE` | 3 |
| シードデータ、または製品外の前提条件が不足している | `SEED_DATA_MISSING`, `TEST_SETUP_FAILED` | 2 |
| 予算または制限時間に達した | `STEP_BUDGET_EXHAUSTED`, `STEP_TIMEOUT` | 1 |
| ツールで実行できない操作が必要 | `AUTOMATION_UNSUPPORTED` | 1 |

判定に付くすべてのコードは[エラーリファレンス](https://e2e.com/docs/ja/reference/errors#agenterror)に記載しています。

## ステップにかかるコスト

各呼び出しには、モデル呼び出し回数の上限とデフォルトのタイムアウトがあります。[予算](https://e2e.com/docs/ja/reference/agent#budgets)を参照してください。

- 探索なしの `assert` と `extract` は 1 回判定し、応答の形式が不正な場合に限り、修復のためにもう 1 回呼び出します。データが画面にない場合、`extract` は `ASSERTION_INCONCLUSIVE` で失敗し、代わりの仮の値は返しません。
- `waitFor` は、画面とその場所が変わらない間はモデルを呼び出しません。
- スクリーンショットを含む呼び出しには、その分の入力トークンが加わります。`act` はテキストスナップショットだけでは不十分なときにのみスクリーンショットを要求します。
- [リプレイキャッシュ](https://e2e.com/docs/ja/cache)は、成功した `act` ステップをモデルの呼び出しなしで再実行します。
- [独自のエグゼキューター](https://e2e.com/docs/ja/executors#what-the-executor-handles)では、`assert` に `act` の予算が適用されます。

厳密な確認には `expect` を使い、各 `act` には[ひとつの明確な目標](https://e2e.com/docs/ja/core-concepts#goals)を与えます。プロバイダーがプロンプトをキャッシュする場合、`--debug` でステップごとの入力トークンに占めるキャッシュの割合を確認できます。

## 次のステップ

<CardGroup cols={2}>
  <Card title="プロジェクトツール" icon="wrench" href="/tools">
    エージェントに独自のツールを追加します。
  </Card>
  <Card title="独自のエグゼキューター" icon="gears" href="/executors">
    既存のループで独自のプロンプトを使うか、ループごと置き換えます。
  </Card>
</CardGroup>
