developing-agentforce

Agent Script スキル

このスキルの用途

Agent Script は、Atlas Reasoning Engine 上で次世代の AI エージェントを作成するための Salesforce のスクリプト言語です。2025 年に導入され、どの AI モデルにもトレーニングデータはありません。Agent Script エージェントの作成、変更、診断、デプロイに必要なすべての情報は、このスキルのリファレンスファイルに記載されています。

⚠️CRITICAL: Agent Script は AppleScript、JavaScript、Python、またはその他の言語ではありません。Agent Script の構文やセマンティクスを、トレーニングで学習した他の言語と混同しないでください。

Agent Script エージェントは AiAuthoringBundle メタデータで定義されます。これは、アクション、指示、サブエージェント、フロー制御、設定を記述する Agent Script ソースを含む .agent ファイルと、バンドルのメタデータを含む bundle-meta.xml ファイルで構成されるディレクトリです。エージェントは、サブエージェントを経由して発話を処理します。各サブエージェントには指示と、Apex、Flows、Prompt Templates、その他の種類のバックエンドロジックに基づくアクションがあります。

このスキルでは、エージェントの設計、Agent Script コードの作成、検証とデバッグ、デプロイと公開、テストという、Agent Script のライフサイクル全体を扱います。

このスキルの使い方

このファイルでは、ユーザーの意図をタスク領域と references/ 内の関連リファレンスファイルに対応付けています。詳細な知識には、構文規則、設計パターン、CLI コマンド、デバッグのワークフローなどが含まれます。

タスクの説明からユーザーの意図を特定してください。作業を始める前に、必ず指定されたリファレンスファイルを読んでください。

常に適用されるルール

1. 常に --json を指定します。 すべての sf CLI コマンドに、必ず --json を指定してください。CLI の出力を jq や 2>/dev/null にパイプしないでください。LLM は JSON をネイティブに解析できるため、JSON レスポンス全体を直接読み取ってください。

2. 対象の組織を確認します。 組織とやり取りする前に、sf config get target-org --json を実行して、対象の組織が設定されていることを確認してください。設定されていない場合は、sf config set target-org <alias> を使って設定するようユーザーに依頼してください。

3. 修正する前に診断します。 エージェントの動作を検証またはデバッグする際は、オーサリングバンドルをプレビューするために、必ず --use-live-actions を指定してください。発話を送信した後、結果のセッショントレースを読み、エージェントの動作を把握してください。トレースファイルには、サブエージェントの選択、アクションの入出力、LLM の推論が記録されています。この情報に基づく把握をせずに、.agent ファイルやバックエンドロジックを変更しないでください。トレースファイルの場所と診断パターンについては、検証とデバッグを参照してください。

4. 仕様の承認は必須のゲートです。 ユーザーから明示的な承認を得る前に、Agent Spec の作成より先へ進まないでください。

タスク領域

以下の各タスク領域には、必須の手順があります。記載された順序で、そのまま実行してください。独自の手順に置き換えたり、省略したりしないでください。

エージェントの作成

ユーザーがエージェントを一から作成しようとしています。必ず Agent Script を使用してください。Salesforce 固有の用語を使わず、平易な言葉でエージェントの目的、サブエージェント、アクションについてユーザーと確認してください。

必須の手順

正確なコマンド構文については、エージェント向け CLIを読んでください。

1. 設計 — 設計とエージェント仕様を読み、エージェント仕様を作成します。既存のバックエンドロジックを検索するか、必ず確認してください。特に指示がない限り、sfdx-project.jsonを読んでパッケージディレクトリを特定し、各ディレクトリでclasses/内の@InvocableMethod、flows/内のAutoLaunchedFlow、promptTemplates/内のテンプレートメタデータを検索します。一致したものにはEXISTS、一致しないアクションにはNEEDS STUBと記載します。また、objects/内の.object-meta.xmlも検索し、カスタムオブジェクトを見つけます。関連オブジェクトには、プロンプトで言及されていなくてもエージェントが公開すべきデータが含まれていることがよくあります。エージェント仕様は必ずファイルとして保存してください。
2. エージェント仕様についてユーザーの承認を得るまで停止します。 ユーザーに提示し、承認またはフィードバックを求めてください。承認を得るまでは先に進まないでください。承認後は、手順が失敗しない限り停止せずに進めます。
3. 環境の前提条件を検証する — 設計とエージェント仕様のセクション3（環境の前提条件）を読みます。設計に基づいてエージェントの種類を判断し、組織の環境を検証します。
   • 従業員エージェント：設定ブロックにdefault_agent_user、connection messaging:、MessagingSessionにリンクされた変数が含まれていないことを確認します。含まれている場合は削除します。従業員エージェントの完全な例については、例を参照してください。
   • サービスエージェント：組織にEinstein Agent Userがあるかどうかをクエリします。存在する場合は、ユーザーにユーザー名を確認します。存在しない場合は、作成手順をユーザーに案内します。作成手順についてはエージェント用CLIのセクション12を、必要な権限についてはエージェントユーザーの設定を参照してください。 環境の検証が完了するまで、コード生成に進まないでください。
4. オーサリングバンドルを生成する — sf agent generate authoring-bundle --json --no-spec --name "<Label>" --api-name <Developer_Name>
5. コードを記述する — 構文、ブロック構造、アンチパターンについてはコア言語を読みます。参照ファイルとテンプレートを使って、生成された.agentファイルを編集します。.agentファイルやbundle-meta.xmlファイルを手動で作成しないでください。
6. コンパイルを検証する — sf agent validate authoring-bundle --json --api-name <Developer_Name> 検証に失敗した場合は、検証とデバッグを読んで原因を特定し、修正してから再検証します。バックエンドロジックを生成する前に、構文エラーと構造エラーを必ず修正してください。
7. バックエンドロジックを生成する — NEEDS STUBと記載された各アクションについて、次を実行します。 sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes クラス本体を設計とエージェント仕様にある呼び出し可能なパターンに置き換えます。必ずデプロイしてください。 sf project deploy start --json --metadata ApexClass:<ClassName> 次のスタブの生成とデプロイに進む前に、デプロイエラーを必ず修正してください。
8. 動作を検証する — プレビューのワークフローとセッショントレースの分析については、検証とデバッグを読みます。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> アクションがデータをクエリする場合は、次を使ってテスト発話の根拠となるデータを取得します。 sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100" 次のコマンドでテスト発話を送信します。 sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" サブエージェントへのルーティング、ゲーティング、アクションの呼び出しがエージェント仕様と一致していることを確認します。動作が異なる場合は、動作上の問題の診断ワークフローに切り替えます。問題を修正した後に戻ってください。 チェックポイント — 次のすべてを満たすまで公開に進まないでください。
   • validate authoring-bundleがエラー0件で成功している
   • サブエージェントごとに代表的な発話を使い、ライブプレビュー（--use-live-actions）でテスト済みである
   • トレースで正しいサブエージェントへのルーティングとアクション呼び出しが確認できている
   • ユーザーがデプロイを明示的に承認している
9. 公開する — 公開ではエージェントの動作ではなく、メタデータ構造が検証されます。公開するたびに、取り消せないバージョン番号が作成されます。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 公開に失敗した場合は、再試行する前にメタデータとライフサイクルのセクション5にあるトラブルシューティングチェックリストに従ってください。
10. 有効化する — 新しいバージョンをユーザーが利用できるようにします。 sf agent activate --json --api-name <Developer_Name>
11. 公開済みのエージェントを検証する — 有効化した後、次を使ってユーザー向けの動作をプレビューします。 sf agent preview start --json --api-name <Developer_Name> --authoring-bundleではなく、--api-nameを使用してください。
12. エンドユーザーアクセスを設定する — 従業員エージェントの場合にのみ実施します。権限の設定とアクセス権の割り当てについては、エージェントアクセスガイドを読みます。

参照ファイル

1. エージェント向け CLI — generate、validate、deploy、publish、activate の正確な コマンド構文。Einstein Agent User の作成についてはセクション 12 を参照
2. コア言語 — 実行 モデル、構文、ブロック構造、アンチパターン
3. 設計とエージェント仕様 — サブエージェントのグラフ設計、フロー制御パターン、エージェント仕様の作成、 バッキングロジックの分析。環境の前提条件についてはセクション 3 を参照
4. サブエージェントマップ図 — エージェントのサブエージェントグラフを視覚化するための Mermaid 図の規約
5. エージェントユーザーの設定と権限 — 権限セットの割り当て、オブジェクト権限、サブエージェント間の検証
6. メタデータとライフサイクル — ディレクトリ構造、バンドルメタデータ。公開時のトラブルシューティング
7. 検証とデバッグ — エージェントがコンパイルできることを検証し、プレビューで動作を確認
8. エージェントアクセスガイド — エンドユーザーの アクセス権限、表示に関するトラブルシューティング
9. 既知の問題 — コードを修正しても エラーが解消しない場合にのみ読み込む
10. アーキテクチャパターン — ハブアンドスポーク、検証ゲート、アクション後ループ
11. 複合データ型 — 型マッピングの判断ツリー
12. 安全性レビュー — 7 項目の安全性レビュー
13. Discover リファレンス — ターゲット検出 CLI
14. Scaffold リファレンス — スタブ生成 CLI
15. Deploy リファレンス — デプロイのライフサイクル、エラー復旧

既存のエージェントを理解する

ユーザーは、自分で作成していない、または内容を再確認する必要がある Agent Script エージェントを理解したいと考えています。AiAuthoringBundle ディレクトリを指定する場合や、「このエージェントは何をするのですか？」または「このエージェントを修正する必要がありますが、仕組みがわかりません」と尋ねる場合があります。

必須の手順

1. エージェントを特定する — sfdx-project.json を読み込み、パッケージディレクトリを確認します。その中から AiAuthoringBundle ディレクトリを探します。.agent ファイルと bundle-meta.xml を読み込みます。
2. コードを読む — .agent ファイルを解析する前に、構文と実行モデルについて コア言語 を読み込みます。
3. バッキングロジックをマッピングする — target を含む各アクションについて、プロジェクト内でバッキング実装（Apex クラス、Flow、Prompt Template）を探します。入力／出力の契約を記録します。
4. エージェント仕様をリバースエンジニアリングする — エージェント仕様の構造について 設計とエージェント仕様 を読み込みます。コードからエージェント仕様を作成し、ファイルとして保存します。
5. サブエージェントマップ図を作成する — Mermaid の規約について サブエージェントマップ図 を読み込みます。遷移、ゲート、アクションとの関連を示すサブエージェントグラフのフローチャートを生成します。
6. ソースに注釈を付ける — Agent Script のソースに説明を付けるかどうか、ユーザーに確認します。依頼された場合は、フロー制御の判断、ゲートを設ける理由、サブエージェント間の関係を説明するインラインコメントを .agent ファイルに追加します。
7. ユーザーに提示する — エージェント仕様、サブエージェントマップ、作成した場合は注釈付きソースを共有します。コア言語リファレンスのアンチパターンのセクションを確認し、コード内に該当するパターンがあれば指摘します。

参照ファイル

1. コア言語 — 構文、 実行モデル、アンチパターン
2. 設計とエージェント仕様 — エージェント仕様の構造、フロー制御パターンの認識
3. サブエージェントマップ図 — サブエージェントのグラフを可視化する Mermaid の規約
4. メタデータとライフサイクル — ディレクトリの規約、バンドルのメタデータ
5. 既知の問題 — 説明のない回避策のパターンが コードに含まれている場合にのみ読み込みます

既存のエージェントを変更する

既存のエージェントのサブエージェント、アクション、指示、またはフロー制御の追加、削除、変更をユーザーが希望しています。変更を平易な言葉（「請求サブエージェントを追加する」など）で説明する場合もあれば、特定の Agent Script の構成要素を参照する場合もあります。

必須手順

正確なコマンド構文については、CLI for Agents をお読みください。

1. 把握 — Agent Spec が存在しない場合は、まず上記の「既存のエージェントを把握する」ワークフローに従ってリバースエンジニアリングを行います。
2. Agent Spec を更新 — フロー制御パターンとバックエンドロジックの分析については、Design & Agent Spec をお読みください。意図する変更が反映されるように Agent Spec を修正します。新しいアクションについては、既存のバックエンドロジックをスキャンするか、必ず確認してください。特に指示がない限り、sfdx-project.json を読んでパッケージディレクトリを特定し、各ディレクトリの classes/ で @InvocableMethod、flows/ で AutoLaunchedFlow、promptTemplates/ でテンプレートのメタデータを検索します。一致したものには EXISTS、一致しなかったアクションには NEEDS STUB のマークを付けます。更新した Agent Spec は必ずファイルとして保存してください。
3. 更新した Agent Spec のユーザー承認を得るまで停止します。 ユーザーに提示し、承認またはフィードバックを求めます。承認なしに先へ進んではいけません。承認されたら、手順が失敗しない限り停止せずに続行します。
4. コードを編集 — 構文とアンチパターンについては、Core Language をお読みください。承認された変更を実装するために .agent ファイルを編集します。
5. コンパイルを検証 — sf agent validate authoring-bundle --json --api-name <Developer_Name> 検証に失敗した場合は、Validation & Debugging を読んで原因を特定して修正し、再検証します。
6. 新しいバックエンドロジックを生成 — NEEDS STUB のマークが付いた新しいアクションごとに、次を実行します。 sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes クラス本体を Design & Agent Spec の呼び出し可能パターンに置き換えます。必ずデプロイします。 sf project deploy start --json --metadata ApexClass:<ClassName> 次のスタブを生成してデプロイする前に、デプロイエラーを必ず修正します。新しいアクションが追加されていない場合はスキップします。
7. 動作を検証 — プレビューのワークフローとセッショントレースの分析については、Validation & Debugging をお読みください。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> アクションがデータをクエリする場合は、次を使ってテスト用発話の根拠となるデータを取得します。 sf data query --json -q "SELECT <Relevant_Fields> FROM <SObject> LIMIT 100" 次を使ってテスト用発話を送信します。 sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" まず変更したパスをテストし、次に既存の動作におけるリグレッションを検出するため、隣接するパスもテストします。 チェックポイント — 以下のすべてを満たすまで、公開に進んではいけません。
   • validate authoring-bundle がエラー 0 件で成功している
   • サブエージェントごとに代表的な発話を使い、ライブプレビュー（--use-live-actions）をテスト済みである
   • トレースで、正しいサブエージェントへのルーティングとアクションの呼び出しを確認できる
   • ユーザーがデプロイを明示的に承認している
8. 公開 — 公開で検証されるのはメタデータの構造であり、エージェントの動作ではありません。公開するたびに永続的なバージョン番号が作成されます。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 公開に失敗した場合は、再試行する前に Metadata & Lifecycle のセクション 5 にあるトラブルシューティングチェックリストに従います。
9. 有効化 — 新しいバージョンをユーザーが利用できるようにします。 sf agent activate --json --api-name <Developer_Name>
10. 公開済みエージェントを確認 — 有効化後、次を使ってユーザー向けの動作をプレビューします。 sf agent preview start --json --api-name <Developer_Name> --authoring-bundle ではなく、--api-name を使用してください。

参照ファイル

1. エージェント向け CLI — validate、deploy、preview、publish、activate の正確なコマンド構文
2. コア言語 — 構文、 アンチパターン
3. 設計とエージェント仕様 — Agent Spec の更新、バックエンドロジックの分析
4. 検証とデバッグ — コンパイル診断、プレビューワークフロー、セッショントレース分析
5. 既知の問題 — コードを修正してもエラーが解消されない場合にのみ読み込みます

コンパイルエラーを診断する

ユーザーの Agent Script がコンパイルできません。エラーは sf agent validate または sf agent preview start から発生するほか、「検証エラーが発生しています」のような症状をユーザーが説明する場合もあります。

必須手順

正確なコマンド構文については、エージェント向け CLI を読んでください。

1. エラーを再現する — 次を実行して、基本的なコンパイルエラーを取得します。 sf agent validate authoring-bundle --json --api-name <Developer_Name> エラーがなければ、次を実行して複雑なコンパイルエラーを取得します。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> ユーザーが特定のエラー出力を提示した場合は、必ず再現して確認してください。
2. エラーを分類する — エラーの分類については、検証とデバッグを読んでください。各エラーメッセージを根本原因のカテゴリに対応付けます。
3. 問題箇所を特定する — 正しい構文を理解するため、コア言語を読んでください。各エラーの原因となっている .agent ファイル内の具体的な行を見つけます。
4. コードを修正する — 対象を絞って修正します。既知の不適切なパターンを導入していないことを確認するため、コア言語リファレンスのアンチパターンのセクションを確認してください。
5. 再検証する — 次を実行します。 sf agent validate authoring-bundle --json --api-name <Developer_Name> 続けて、次を実行します。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> エラーが残る場合は、手順 2～5 を繰り返します。
6. 修正内容を説明する — 何が問題で、何を変更したかをユーザーに伝えます。コア言語のエージェント実行モデルに基づいて、根本原因を説明します。

参照ファイル

1. コア言語 — 構文、 ブロック構造、アンチパターン
2. 検証とデバッグ — エラーの分類、エラーと根本原因の対応付け
3. 既知の問題 — エラーがユーザーのコードに該当しない場合にのみ読み込みます。プラットフォームのバグの可能性があります
4. 本番環境での注意点 — エラーが予約語またはライフサイクルフックの構文に関係する場合にのみ読み込みます

動作上の問題を診断する

エージェントはコンパイルでき、プレビューを開始でき、--use-live-actions も使用できますが、期待どおりに動作しません。「エージェントがいつも間違ったサブエージェントに進む」や「アクションが呼び出されない」のような症状をユーザーが説明する場合です。validate や preview start のエラーとは根本的に異なり、コードは有効でも動作に問題があります。

必須の手順

正確なコマンド構文については、CLI for Agents をお読みください。

1. ベースラインを確立する — Agent Spec を読みます。Agent Spec が存在しない場合は、既存のエージェントを把握するワークフローに従ってリバースエンジニアリングし、Agent Spec を作成してから続行します。
2. 仮説を立てる — 実行モデルについては、Core Language をお読みください。ユーザーの説明に基づいて、考えられる根本原因を列挙します。サブエージェントへのルーティング、ゲーティング条件、アクションの利用可否、指示の明確さ、変数の状態、遷移のタイミングについて検討します。
3. プレビューで再現する — プレビューのワークフローとセッショントレースの分析については、Validation & Debugging をお読みください。次のコマンドでプレビューセッションを開始します。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> 続いて、sf agent preview send を使って、各サブエージェントを網羅するテストメッセージを送信します。メッセージは1つでは不十分です。先に進む前に、サブエージェントごとに動作を確認してください。
4. セッショントレースを分析する — トレース出力を調べ、サブエージェントの選択、アクションの利用可否と実行、LLM の推論、動作が Agent Spec と異なる箇所を確認します。この手順を省略しないでください。プレビュー出力だけでは、原因を診断するには不十分です。
5. 根本原因を特定する — トレースの証拠と仮説を照合します。Design & Agent Spec リファレンスの Core Language リファレンスとゲーティングパターンを参照し、アンチパターンがないことを確認します。
6. コードを修正する — 対象を絞った修正を適用します。修正にフロー制御の変更が含まれる場合は、Agent Spec も一致するように更新します。
7. 再検証して再プレビューする — 動作が Agent Spec と一致するか、プラットフォームの制限を確認できるまで、手順3〜6を繰り返します。validate authoring-bundle を実行してから、preview start --use-live-actions を実行し、同じ発話を使って修正を検証します。その後、変更の影響を受ける可能性のある隣接パスもテストします。
8. 修正内容を説明する — 何が問題で、何を変更したかをユーザーに伝えます。Core Language のエージェント実行モデルに基づいて根本原因を説明します。

リファレンスファイル

1. Core Language — 実行モデル、アンチパターン
2. Design & Agent Spec — Agent Spec を動作のベースラインとして使用する方法、ゲーティングパターン
3. Validation & Debugging — プレビューのワークフロー、セッショントレースの分析
4. Known Issues — 動作に問題があるものの、コードのロジックが正しい場合にのみ読み込みます

デプロイ、公開、有効化

ユーザーは、ローカル開発中の動作するエージェントを、Salesforce 組織で実行できる状態にしたいと考えています。AiAuthoringBundle とその依存関係をデプロイし、バージョンを確定するために公開してから、有効化してライブ状態にします。

必須手順

正確なコマンド構文については、CLI for Agentsをお読みください。

1. コンパイルを検証する — sf agent validate authoring-bundle --json --api-name <Developer_Name> 検証に失敗した場合は、先に進まないでください。
2. バンドルと依存関係をデプロイする — 依存関係の管理とデプロイコマンドについては、Metadata & Lifecycleをお読みください。AiAuthoringBundleと、すべての関連ロジック（Apex クラス、Flows、Prompt Templates）および依存関係を組織にデプロイします。
3. ライブプレビュー — プレビューのワークフローとセッショントレースの分析については、Validation & Debuggingをお読みください。 sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> 次に、以下を使ってテスト用の発話を送信します。 sf agent preview send --json --authoring-bundle <Developer_Name> --session-id <ID> -u "<message>" ライブアクションを使用した場合のエージェントの動作を検証するため、主要な会話経路をテストします。 チェックポイント — 以下のすべてを満たすまで、公開に進まないでください。
   • validate authoring-bundleがエラーなしで成功する
   • ライブプレビュー（--use-live-actions）で、各サブエージェントについて代表的な発話をテスト済みである
   • トレースで、サブエージェントへのルーティングとアクションの呼び出しが正しいことを確認できる
   • ユーザーがデプロイを明示的に承認している
4. 公開する — 公開で検証されるのはメタデータの構造であり、エージェントの動作ではありません。開発／テストの反復作業の一環として公開しないでください。エージェントを有効化してエンドユーザーに公開する前の最終手順としてのみ公開してください。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 公開に失敗した場合は、再試行する前に、Metadata & Lifecycleの公開に関するトラブルシューティングに従ってください。
5. 有効化する — 新しいバージョンをユーザーが利用できるようにします。 sf agent activate --json --api-name <Developer_Name>
6. 公開済みエージェントを確認する — 有効化後、以下を使ってユーザー向けの動作をプレビューします。 sf agent preview start --json --api-name <Developer_Name> --authoring-bundleではなく、--api-nameを使用してください。
7. エンドユーザーのアクセスを設定する — 従業員向けエージェントの場合のみ実施します。権限を設定してアクセスを割り当てる方法については、Agent Access Guideをお読みください。

参照ファイル

1. CLI for Agents — デプロイ、公開、有効化、無効化に関する正確なコマンド構文
2. Validation & Debugging — コンパイル検証、プレビューのワークフロー
3. Metadata & Lifecycle — 依存関係の管理、デプロイコマンド、公開に関するトラブルシューティング
4. Agent Access Guide — エンドユーザーのアクセス権限、公開範囲に関するトラブルシューティング
5. Known Issues — デプロイが停止する、公開に失敗する、または有効化が予期せず失敗する場合にのみ読み込みます

本番環境の問題を診断する

エージェントは公開済みで有効化されていますが、プレビューでは検出されなかった問題が発生しています。クレジットの過剰消費、トークンまたはサイズの上限による失敗、ループガードレールによる中断、予約語が原因の実行時エラー、VS Code の同期失敗、またはプレビューと本番環境での予期しない動作の違いが含まれます。

必須の手順

正確なコマンド構文については、エージェント向け CLIをお読みください。

1. 問題を分類する — 請求／コストに関する懸念、実行時の制限、名前の競合、ツールの問題、プレビューと本番環境の動作の違いのいずれに該当するかを判断します。
2. 本番環境で既知の注意点を確認する — クレジット消費量、トークン制限、ループのガードレール、予約語、ライフサイクルフック、VS Code の回避策について、本番環境での注意点をお読みください。
3. プレビューと本番環境の動作を比較する — 問題が動作に関するものであれば、次のコマンドで公開済みエージェントをプレビューします。 sf agent preview start --json --api-name <Developer_Name> （--authoring-bundleではなく）。ライブアクションを使ったオーサリングバンドルのプレビュー--authoring-bundle <Developer_Name> --use-live-actionsと比較し、プレビューと本番環境の違いを特定します。
4. 既知の問題を確認する — 本番環境でのみ発生する失敗の原因となっている可能性があるプラットフォームのバグについて、既知の問題をお読みください。
5. 修正して再公開する — 修正を適用し、検証し、再度プレビューしてから公開、有効化し、確認します。デプロイ、公開、有効化の手順に従ってください。
6. 診断結果を説明する — 何が起きていたのか、何を変更したのかをユーザーに伝えます。根本原因を説明してください。

参照ファイル

1. 本番環境での注意点 — クレジット消費量、トークン制限、ループのガードレール、予約語、ライフサイクルフック、VS Code の回避策
2. エージェント向け CLI — プレビュー、公開、有効化のコマンド構文
3. 検証とデバッグ — プレビューのワークフロー、セッショントレースの分析
4. 既知の問題 — 問題がプラットフォームのバグである可能性がある場合にのみ読み込みます

エージェントの削除または名前の変更

ユーザーがエージェントの削除または名前の変更を希望しています。AiAuthoringBundleのバージョン管理と公開済みバージョンへの依存関係があるため、メンテナンス作業は複雑です。

必須の手順

正確なコマンド構文については、エージェント向け CLIをお読みください。

1. 現在の状態を把握する — バージョン管理、削除の仕組み、名前変更の仕組みについて、メタデータとライフサイクルをお読みください。エージェントが公開済みか、バージョンがいくつあるか、現在有効かどうかを確認します。
2. 有効な場合は無効化する — sf agent deactivate --json --api-name <Developer_Name> 有効なエージェントは削除または名前変更できません。
3. 操作を実行する — 削除する場合は、「メタデータとライフサイクル」のリファレンスに記載された削除の仕組みに従います。名前を変更する場合は、同じリファレンスに記載された名前変更の仕組みに従います。
4. 孤立したメタデータをクリーンアップする — 孤立したメタデータ（Bot、BotVersion、GenAiPlannerBundle、GenAiPlugin、GenAiFunction）がないか確認し、あれば削除します。確認対象については、「メタデータとライフサイクル」のリファレンスに詳しく記載されています。
5. 検証する — 操作が問題なく完了したことを確認します。名前を変更した場合は、新しいバンドルがコンパイルできることを検証し、プレビューして動作を確認します。

参照ファイル

1. エージェント向け CLI — 削除、無効化、取得の正確なコマンド構文
2. 検証とデバッグ — コンパイルの検証、プレビューのワークフロー
3. メタデータとライフサイクル — 削除の仕組み、名前変更の仕組み、孤立したメタデータのクリーンアップ

エージェントのテスト

ユーザーは Agent Script エージェントの自動テストを作成したいと考えています。テストシナリオ、期待される動作、品質指標を定義するYAML形式のAiEvaluationDefinitionテスト仕様を作成します。

必須の手順

正確なコマンド構文については、CLI for Agents をお読みください。

1. カバレッジのベースラインを確立する — Agent Spec を読みます。Agent Spec がない場合は、Comprehend の手順に従って、まずリバースエンジニアリングを行います。すべてのサブエージェント、アクション、フロー制御パスをマッピングし、テストカバレッジが必要な箇所を特定します。
2. テストシナリオを設計する — テスト設計の方法論、期待値、メトリクス、テスト仕様 YAML の形式、テンプレートについては、testing-agentforce スキルを使用します。テストに関する内容はすべてこのスキルが担います。カバレッジ対象ごとに、ユーザーの発話、期待するサブエージェントへのルーティング、期待するアクションの呼び出し、期待するエージェントの応答を含むテストシナリオを 1 つ以上作成します。正常系とエッジケースの両方を含めます。
3. テスト仕様 YAML を作成する — testing-agentforce スキルのテンプレートと参照ファイルを使用します。SFDX プロジェクトの specs/<Agent_API_Name>-testSpec.yaml に保存します。
4. テストメタデータを作成する — CLI を使用して、テスト仕様から AiEvaluationDefinition を生成します。
5. テストをデプロイする — AiEvaluationDefinition を org にデプロイします。
6. テストを実行する — CLI を使用してテストを実行し、結果を記録します。
7. 結果を分析する — 実際の結果を期待値と比較します。失敗した場合は、エージェントのコード、バックエンドのロジック、テスト仕様のいずれに問題があるかを特定します。
8. 反復する — 必要に応じてエージェントのコードまたはテスト仕様を修正し、再デプロイして、カバレッジ目標を達成するまで再実行します。

参照ファイル

1. CLI for Agents — テストの作成、実行、結果取得に使用する正確なコマンド構文
2. Core Language — 意義のあるテストを設計するためのエージェントの構造
3. Design & Agent Spec — テストカバレッジのベースラインとなる Agent Spec
4. testing-agentforce スキル — テスト仕様 YAML の形式、期待値、メトリクス、テスト設計の方法論、テスト仕様のテンプレート

Agent Spec

Agent Spec は、このスキルが作成および使用する中心的な成果物です。エージェントの目的、サブエージェントのグラフ、バックエンドのロジックを含むアクション、変数、ゲーティングロジック、動作の意図を表す構造化された設計ドキュメントです。

Agent Spec はエージェントとともに進化します。エージェントの作成時は簡潔で（目的、トピック、方向性を示すメモ）、エージェントの構築中に詳細化されます（フローチャート、バックエンドのロジックのマッピング、ゲーティングの記録）。既存のエージェントを理解する際には、リバースエンジニアリングされます。高度なトラブルシューティングには欠かせず、期待される動作と実際の動作を比較するための参照資料となります。テスト時には、これを基準にテストカバレッジをマッピングします。

エージェントを変更または分析する操作では、必ず最初の手順として Agent Spec を作成または更新してください。Agent Spec は、作業の一貫した基盤となり、開発者が確認できる永続的な成果物です。

Agent Spec の構造と作成方法については、Design & Agent Spec をお読みください。

アセット

assets/ ディレクトリにはテンプレートとサンプルが含まれています。作成の出発点や成果物、ソースファイルの具体的な参考例が必要なときに参照してください。

• assets/agent-spec-template.md — すべてのセクションとプレースホルダーの内容を含む Agent Spec テンプレートです。プロジェクトディレクトリに <AgentName>-AgentSpec.md としてコピーし、設計時に内容を記入してください。Agent Spec はファイルとして保存してください。特に Mermaid の Subagent Map 図など、適切にレンダリングすると見やすくなる重要な設計成果物です。

• assets/local-info-agent-annotated.agent — Local Info Agent をベースにした、注釈付きの完全なサンプルです。主要な Agent Script 構文をすべて実際の文脈で示し、各構文を使用する理由をインラインコメントで説明しています。概念を組み合わせて動作するエージェントを作る方法の具体例が必要な場合や、リファレンスファイルの個別のサンプルだけでは不十分な場合の代替資料として参照してください。

• assets/template-single-subagent.agent — サブエージェントが1つの最小限のエージェントです。シンプルなエージェントを作る場合にコピーして変更してください。

• assets/template-multi-subagent.agent — 複数のサブエージェントと遷移を含む最小限のエージェントです。複雑なエージェントを作る場合にコピーして変更してください。

• assets/invocable-apex-template.cls — 呼び出し可能な Apex クラスのリファレンスです。複雑な Apex のバックエンドロジックが必要な場合にコピーして変更してください。

重要な制約

• Salesforce CLI と Salesforce 組織のみを使用してください。 他のスキル、MCP サーバー、外部ツールには言及したり、依存したりしないでください。すべてのコマンドで sf（Salesforce CLI）を使用します。

• アクションのバックエンドロジックとして有効な型は限られています。 たとえば、アクションのバックエンドにできるのは呼び出し可能な Apex のみであり、任意の Apex クラスは使用できません。Flow や Prompt Template にも同様の制約が適用される場合があります。アクションをバックエンドロジックに接続する場合は、有効な型とスタブの作成方法について Design & Agent Spec のリファレンスファイルを参照してください。

• sf agent generate test-spec はエージェント向けではありません。 人間向けに設計された、対話型の REPL 形式のコマンドです。テストスペックを作成する場合は、代わりに assets 内のボイラープレートテンプレートを使用してください。

よくある問題のクイックリファレンス

公開中に Internal Error, try again later が発生する場合： default_agent_user が無効か、設定されていません。Design & Agent Spec のセクション3にあるクエリを再実行してください。ユーザー名を推測してはいけません。

プレビュー中に Unable to access Salesforce Agent APIs... が発生する場合： default_agent_user に権限がありません。Agent User Setup & Permissions を参照してください。解決策として公開してはいけません。--use-live-actions ではエージェントを公開する必要はありません。

権限エラーに設定したものとは異なるユーザー名が表示される場合： 上記と同じ方法で解決します。エラーには組織のデフォルトの実行ユーザーが表示されていますが、根本原因は Einstein Agent User の権限です。

現在のサブエージェントのアクションは動作するのに、エージェントが権限エラーで失敗する場合： Planner は起動時に、すべてのサブエージェントに含まれるすべてのアクションを検証します。権限が1つでも不足すると、エージェント全体が失敗します。

Apex アクションがシミュレーションでは動作するのに、ライブプレビューでは結果が空になる場合： WITH USER_MODE とオブジェクト権限の不足が組み合わさると、エラーが表示されず、結果が0行になります。Agent User Setup & Permissions のセクション6.2を参照してください。

構文のクイックリファレンス

• ブロックの順序：system: → config: → variables: → connection: → knowledge: → language: → start_agent agent_router: → subagent: ブロック
• インデント：インデントレベルごとに4つのスペースを使用します。タブは使用しないでください。スペースとタブを混在させると、パーサーが正しく動作しません。
• ブール値：True／False（先頭を大文字にします）
• 文字列：常に二重引用符で囲みます
• 数値のアクション入出力：変数では裸の number を使用できますが、アクションの入出力では公開時に失敗します。数値のアクションパラメーターには object と complex_data_type_name を使用してください。判断手順の全体については、複合データ型を参照してください。
• after_reasoning: に instructions: のラッパーは不要です
• else if は使用できません。複合条件の if x and y: または、フラットな if を順に記述してください
• 予約済みの @InvocableVariable 名：model、description、label は Apex のパラメーター名に使用できません
• @inputs と @outputs は一時的な値です。@inputs は with 内でのみ、@outputs はアクション直後の set／if 内でのみ使用できます。set 内の @inputs は、エラーが表示されずに失敗します。

Lightning の型マッピングに関する判断手順の全体については、複合データ型を参照してください。3 フェーズのランタイムモデルについては、命令の解決を参照してください。

アーキテクチャパターン

主な FSM パターンは 3 つあります。コードを含む詳細については、アーキテクチャパターンを参照してください。

• ハブ・アンド・スポーク（最も一般的）：start_agent から特化型サブエージェントにルーティングします。各サブエージェントには「ハブに戻る」遷移を設けます。別個のルーティング用サブエージェントは作成しないでください。
• 検証ゲート：保護されたサブエージェントの前に本人確認を行います。保護された遷移には available when ガードを設定します。
• アクション後ループ：アクション完了後の再解決時に実行されるよう、instructions: -> の先頭にアクション後のチェックを配置します。

スコアリング基準

生成したすべてのエージェントを 7 つのカテゴリ、合計 100 点で評価します：構造（15 点）、安全性（15 点）、決定論的ロジック（20 点）、命令の解決（20 点）、FSM アーキテクチャ（10 点）、アクション設定（10 点）、デプロイ準備状況（10 点）。

評価基準の全体については、スコアリング基準を参照してください。

レビューモード

ユーザーから既存の .agent ファイル（例：review path/to/file.agent）が提供された場合：

1. ファイルを読み取ります
2. 100 点満点の評価基準に照らして採点します
3. カテゴリごとに問題をすべて列挙します
4. 修正後のコードスニペットを提示します
5. 修正を適用するかどうかを確認します

安全性レビュー

.agent ファイルを対象とした、LLM による 7 カテゴリの安全性レビューです。作成とデプロイのフェーズ 0 に組み込まれています。カテゴリ：アイデンティティと透明性、ユーザーの安全、データの取り扱い、コンテンツの安全、公平性、欺瞞、スコープと境界。

フレームワーク全体、深刻度レベル、誤検知に関するガイダンス、敵対的テスト用プロンプトについては、安全性レビューを参照してください。

検出とスキャフォールド生成

アクションのターゲットが組織内に存在するか検証し、存在しない場合はスタブを生成します。

検出リファレンスとスキャフォールド生成リファレンスを参照してください。

重要： スタブは 'TODO' ではなく、現実的なデータを返す必要があります。プレースホルダーの応答を使用すると、LLM がトレーニングデータにフォールバックするため、SMALL_TALK によるグラウンディングが発生します。

デプロイのライフサイクル

検証 → メタデータのデプロイ → バンドルの公開 → 有効化。各フェーズ、エラーからの復旧、CI/CD、ロールバックについては、デプロイリファレンスを参照してください。

テンプレートアセット

すぐに使用できる .agent テンプレートが assets/agents/ にあります（hello-world、simple-qa、multi-subagent、production-faq、order-service、verification-gate）。再利用可能な 11 個以上のデザインパターンについては assets/patterns/ を、コードを使った解説については例も参照してください。

追加の参考資料

トピック	ファイル
アーキテクチャパターン	architecture-patterns.md
型マッピングの決定木	complex-data-types.md
コンテキスト別の機能の有効性	feature-validity.md
指示の解決モデル	instruction-resolution.md
エージェントの完全な例	examples.md