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、フロー、Prompt Template、およびその他の種類のバッキング ロジックでサポートされている、それぞれの命令とアクションを持つサブエージェントを通じてルーティングすることで、発話を処理します。

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

このスキルの使用方法

このファイルは、ユーザーの意図をタスク ドメインにマップし、references/ 内の関連するリファレンス ファイルにマップします。詳細な知識には、構文ルール、設計パターン、CLI コマンド、デバッグ ワークフロー、およびその他が含まれます。

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

常に適用されるルール

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

2. ターゲット組織を確認。 組織と相互作用する前に、sf config get target-org --json を実行してターゲット組織が設定されていることを確認します。設定されていない場合は、ユーザーに sf config set target-org <alias> を使用して設定するよう依頼します。

3. 修正の前に診断。 エージェントの動作を検証/デバッグする場合、常に --use-live-actions を使用してオーサリング バンドルをプレビューします。発話を送信してから、結果のセッション トレースを読み取り、エージェントの動作の理解を根拠付けます。トレース ファイルは、サブエージェント選択、アクション I/O、および LLM の推論を明らかにします。このグラウンディング なしで .agent ファイルまたはバッキング ロジックを修正しないでください。トレース ファイルの場所と診断パターンについては、検証とデバッグ を参照してください。

4. Spec 承認は確定的なゲート。 Agent Spec の作成を明示的なユーザー承認なしで進めることはできません。

タスク ドメイン

以下のすべてのタスク ドメインには 必須ステップ があります。順番に逐語的に従ってください。独自の計画を代わりにしたり、ステップをスキップしたりしないでください。

エージェントの作成

ユーザーはスクラッチからの新しいエージェントをビルドしたいと考えています。常に Agent Script を使用します。ユーザーと協力してエージェントの目的、サブエージェント、およびアクションを Salesforce 固有の用語を使用せずに平文で理解します。

必須ステップ

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

1. 設計 — 設計と Agent Spec を読んで Agent Spec をドラフトします。既存のバッキング ロジックをスキャンすべきかどうかを常に質問します。特に指示がない限り、sfdx-project.json を読むことでスキャンを開始してパッケージ ディレクトリを特定してから、各ディレクトリで classes/ 内の @InvocableMethod、flows/ 内の AutoLaunchedFlow、および promptTemplates/ 内のテンプレート メタデータを検索します。マッチを EXISTS としてマーク。マッチしないアクションを NEEDS STUB としてマーク。また、objects/ で .object-meta.xml をスキャンしてカスタム オブジェクトを発見します。関連オブジェクトは、プロンプトで言及されていなくても、エージェントが公開する必要があるデータを含むことが多いです。常に Agent Spec をファイルとして保存します。
2. Agent Spec ユーザー承認のため停止。 ユーザーに提示します。承認またはフィードバックを求めます。承認なしで進まないでください。 承認されたら、ステップが失敗しない限り停止せずに進みます。
3. 環境前提条件を検証 — 設計と Agent Spec、セクション 3 (環境前提条件) を読みます。設計のエージェント タイプに基づいて、組織環境を検証します:
   • 従業員エージェント: config ブロックに default_agent_user、connection messaging:、または MessagingSession リンク変数が含まれていないことを確認します。存在する場合は削除します。完全な従業員エージェント例については、例 を参照してください。
   • サービス エージェント: org で Einstein Agent User をクエリします。存在する場合は、ユーザー名をユーザーに確認します。存在しない場合は、ユーザーの作成をガイドします。作成ステップについては エージェント用 CLI のセクション 12 を参照し、必要なアクセス許可については Agent ユーザー セットアップ を参照してください。 環境が検証されるまでコード生成に進まないでください。
4. オーサリング バンドルを生成 — sf agent generate authoring-bundle --json --no-spec --name "<Label>" --api-name <Developer_Name>
5. コードを作成 — Core Language を読んで、構文、ブロック構造、およびアンチパターンを学習します。生成された .agent ファイルをリファレンス ファイルとテンプレートを使用して編集します。.agent または bundle-meta.xml ファイルを手動で作成しないでください。
6. コンパイルを検証 — sf agent validate authoring-bundle --json --api-name <Developer_Name> 検証に失敗した場合は、検証とデバッグ を読んで診断して修正してから、再検証します。バッキング ロジックを生成する前に、常に構文とstructuralエラーを修正します。
7. バッキング ロジックを生成 — NEEDS STUB とマークされた各アクションについて: sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes 設計と Agent Spec からクラス本体を invocable パターンで置き換えます。常にデプロイします: 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>" サブエージェント ルーティング、ゲーティング、およびアクション呼び出しが Agent Spec と一致することを確認します。動作が異なる場合は、動作上の問題を診断 ワークフローに切り替えます。問題を修正した後に戻ります。 チェックポイント — 以下のすべてが当てはまる場合を除き、公開に進まないでください:
   • validate authoring-bundle はエラーゼロで合格
   • Live preview (--use-live-actions) は各サブエージェントごとに代表的な発話でテスト済み
   • トレースは正しいサブエージェント ルーティングと action invoke を確認
   • ユーザーが明示的にデプロイを承認
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. エンドユーザー アクセスを設定 — 従業員エージェント のみ 対象。Agent Access Guide を読んでアクセス許可を設定してアクセスを割り当てます。

リファレンス ファイル

1. エージェント用 CLI — generate、validate、deploy、publish、activate の正確なコマンド構文。 セクション 12 は Einstein Agent User 作成向け
2. Core Language — 実行モデル、構文、ブロック構造、アンチパターン
3. 設計と Agent Spec — サブエージェント グラフ設計、フロー制御パターン、Agent Spec 作成、バッキング ロジック分析。環境前提条件向けセクション 3
4. Subagent Map ダイアグラム — エージェントのサブエージェント グラフを視覚化するための Mermaid ダイアグラム規約
5. Agent ユーザー セットアップと アクセス許可 — パーミッション セット割り当て、オブジェクト アクセス許可、クロスサブエージェント検証
6. メタデータとライフサイクル — ディレクトリ構造、バンドル メタデータ。公開トラブルシューティング
7. 検証とデバッグ — エージェントがコンパイルすることを検証、動作を確認するプレビュー
8. Agent Access Guide — エンドユーザー アクセス アクセス許可、表示トラブルシューティング
9. 既知の問題 — エラーがコード修正後も持続する場合のみ読み込む
10. アーキテクチャ パターン — hub-and-spoke、検証ゲート、post-action ループ
11. 複雑なデータ型 — 型マッピング判定木
12. Safety Review — 7 カテゴリ safety review
13. Discover リファレンス — ターゲット検出 CLI
14. Scaffold リファレンス — スタブ生成 CLI
15. デプロイ リファレンス — デプロイ ライフサイクル、エラー復旧

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

ユーザーは、作成していない Agent Script エージェント、または再度確認する必要があるエージェントを理解したいと考えています。AiAuthoringBundle ディレクトリを指すか、「このエージェントは何をしますか?」または「このエージェントを修正する必要があるが、どのように動作するのかわかりません」と尋ねる可能性があります。

必須ステップ

1. エージェントの場所を特定 — sfdx-project.json を読んでパッケージ ディレクトリを特定します。ディレクトリ内で AiAuthoringBundle ディレクトリを探します。.agent ファイルと bundle-meta.xml を読みます。
2. コードを読む — .agent ファイルを解析する 前に Core Language を読んで、構文と実行モデルを学習します。
3. バッキング ロジックをマップ — target を持つ各アクションについて、プロジェクト内のバッキング実装 (Apex クラス、Flow、Prompt Template) を探します。入出力コントラクトに注釈を付けます。
4. Agent Spec をリバース エンジニア — 設計と Agent Spec を読んで Agent Spec 構造を理解します。コードから Agent Spec を生成してファイルとして保存します。
5. Subagent Map ダイアグラムを作成 — Subagent Map ダイアグラム を読んで Mermaid 規約を確認します。遷移、ゲート、およびアクション関連付けを示すサブエージェント グラフのフローチャートを生成します。
6. ソースに注釈を付ける — ユーザーが Agent Script ソースに注釈を付けてほしいかどうかを尋ねます。リクエストされた場合、フロー制御の決定、ゲーティング根拠、およびサブエージェント関係を説明するインライン コメントを .agent ファイルに追加します。
7. ユーザーに提示 — Agent Spec、Subagent Map、および生成した注釈付きソースを共有します。Core Language リファレンスの Anti-Patterns セクションをチェックしてコード内で見つかったマッチングをフラグします。

リファレンス ファイル

1. Core Language — 構文、実行モデル、アンチパターン
2. 設計と Agent Spec — Agent Spec 構造、フロー制御パターン認識
3. Subagent Map ダイアグラム — サブエージェント グラフ視覚化の Mermaid 規約
4. メタデータとライフサイクル — ディレクトリ規約、バンドル メタデータ
5. 既知の問題 — コード内に説明のつかないワークアラウンド パターンがある場合のみ読み込む

既存のエージェントを修正する

ユーザーは、既存エージェント上でサブエージェント、アクション、命令、またはフロー制御を追加、削除、または変更したいと考えています。平文で変更を記述する場合もあります (「billing サブエージェントを追加」など) または特定の Agent Script コンストラクトを参照する場合もあります。

必須ステップ

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

1. 理解 — Agent Spec が存在しない場合は、上記の「既存のエージェントを理解する」ワークフローに従ってリバース エンジニアリングを最初に実施してから、続行します。
2. Agent Spec を更新 — 設計と 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> 検証に失敗した場合は、検証とデバッグ を読んで診断して修正してから、再検証します。
6. 新しいバッキング ロジックを生成 — NEEDS STUB とマークされた新しいアクションそれぞれについて: sf template generate apex class --name <ClassName> --output-dir <PACKAGE_DIR>/main/default/classes 設計と Agent Spec からクラス本体を invocable パターンで置き換えます。常にデプロイします: sf project deploy start --json --metadata ApexClass:<ClassName> 次のスタブを生成してデプロイする前に、常にデプロイ エラーを修正します。新しいアクションが追加されない場合はスキップします。
7. 動作を検証 — 検証とデバッグ を読んで、プレビュー ワークフローとセッション トレース分析を確認します。 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 はエラーゼロで合格
   • Live preview (--use-live-actions) は各サブエージェントごとに代表的な発話でテスト済み
   • トレースは正しいサブエージェント ルーティングと action invoke を確認
   • ユーザーが明示的にデプロイを承認
8. 公開 — 公開はメタデータ構造を検証し、エージェント動作は検証しません。すべての公開は永続的なバージョン番号を作成します。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 公開に失敗した場合は、再試行する前に メタデータとライフサイクル のセクション 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. Core Language — 構文、アンチパターン
3. 設計と Agent Spec — 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. 障害を特定 — Core Language を読んで正しい構文を理解します。各エラーを引き起こす .agent ファイルの特定の行を探します。
4. コードを修正 — ターゲット付き修正を適用します。Core Language リファレンスの Anti-Patterns セクションを確認して、既知の悪いパターンを導入していないことを確認します。
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. 修正を説明 — ユーザーに何が間違っていて、何を変更したかを伝えます。Core Language エージェント実行モデルの観点からルート原因を説明します。

リファレンス ファイル

1. Core Language — 構文、ブロック構造、アンチパターン
2. 検証とデバッグ — エラー分類法、エラーからルート原因へのマッピング
3. 既知の問題 — エラーがユーザー コードと一致しない場合のみ読み込む。プラットフォーム バグの可能性がある
4. Production Gotchas — エラーが予約キーワードまたはライフサイクル フック構文を含む場合のみ読み込む

動作上の問題を診断する

エージェントはコンパイルされ、プレビュー開始でき、--use-live-actions ですが、エージェントは予期されたように動作しません。ユーザーは「エージェントは常に間違ったサブエージェントに進む」または「アクションが呼び出されていない」のような症状を述べています。validate または preview start エラーから根本的に異なります — コードは有効ですが、動作が間違っています。

必須ステップ

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

1. ベースラインを確立 — Agent Spec を読みます。Agent Spec が存在しない場合は、既存のエージェントを理解する ワークフローに従ってリバース エンジニアリングを実施してから、続行します。
2. 仮説を形成 — Core Language を読んで実行モデルを確認します。ユーザーの説明に基づいて、候補ルート原因をリストします。次の項目について考えます: サブエージェント ルーティング、ゲーティング条件、アクション可用性、命令の明確さ、変数の状態、および遷移のタイミング。
3. プレビューで再現 — 検証とデバッグ を読んで、プレビュー ワークフローとセッション トレース分析を確認します。プレビュー セッションを開始: sf agent preview start --json --use-live-actions --authoring-bundle <Developer_Name> その後、sf agent preview send でそれぞれのサブエージェントをカバーするテスト メッセージを送信します。1 つのメッセージで十分ではありません — 続行する前に、サブエージェントごとに動作を確認します。
4. セッション トレースを分析 — トレース出力を調べてサブエージェント選択、アクション可用性/実行、LLM 推論、および動作が Agent Spec から逸脱した箇所を確認します。このステップをスキップしないでください — プレビュー出力だけは診断に不十分です。
5. ルート原因を特定 — トレース証拠を仮説にマッチさせます。Core Language リファレンスと 設計と Agent Spec リファレンスのゲーティング パターン を参照してアンチパターンがないことを確認します。
6. コードを修正 — ターゲット付き修正を適用します。修正がフロー制御の変更を含む場合、Agent Spec を更新して一致させます。
7. 再検証と再プレビュー — ステップ 3-6 を動作が Agent Spec と一致するか、プラットフォーム制限を確認するまで繰り返します。validate authoring-bundle を実行してから、preview start --use-live-actions を実行して同じ発話を使用して修正を検証します。その後、変更の影響を受ける可能性のある隣接パスをテストします。
8. 修正を説明 — ユーザーに何が間違っていて、何を変更したかを伝えます。Core Language エージェント実行モデルの観点からルート原因を説明します。

リファレンス ファイル

1. Core Language — 実行モデル、アンチパターン
2. 設計と Agent Spec — 動作ベースラインとしての Agent Spec、ゲーティング パターン
3. 検証とデバッグ — プレビュー ワークフロー、セッション トレース分析
4. 既知の問題 — 動作が間違っていてもコード ロジックが正しい場合のみ読み込む

デプロイ、公開、およびアクティベート

ユーザーは、ローカル開発から Salesforce org の実行中の状態に機能するエージェントを取得したいと考えています。AiAuthoringBundle とその依存関係を org にデプロイし、バージョンをコミットするために公開してから、アクティベートしてライブにすることが関わります。

必須ステップ

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

1. コンパイルを検証 — sf agent validate authoring-bundle --json --api-name <Developer_Name> 検証に失敗した場合は進まないでください。
2. バンドルと依存関係をデプロイ — メタデータとライフサイクル を読んで依存関係の管理とデプロイ コマンドを確認します。AiAuthoringBundle と、すべてのバッキング ロジック (Apex クラス、Flow、Prompt Template) および依存関係を org にデプロイします。
3. Live プレビュー — 検証とデバッグ を読んで、プレビュー ワークフローとセッション トレース分析を確認します。 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 はエラーゼロで合格
   • Live preview (--use-live-actions) は各サブエージェントごとに代表的な発話でテスト済み
   • トレースは正しいサブエージェント ルーティングと action invoke を確認
   • ユーザーが明示的にデプロイを承認
4. 公開 — 公開はメタデータ構造を検証し、エージェント動作は検証しません。公開を dev/test インナー ループの一部として実施しないでください。エージェントをアクティベートしてエンドユーザーに表示する直前の最終ステップとしてのみ公開してください。 sf agent publish authoring-bundle --json --api-name <Developer_Name> 公開に失敗した場合は、再試行する前に メタデータとライフサイクル の 公開エラーのトラブルシューティング を確認します。
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 — deploy、publish、activate、deactivate の正確なコマンド構文
2. 検証とデバッグ — コンパイル検証、プレビュー ワークフロー
3. メタデータとライフサイクル — 依存関係管理、デプロイ コマンド。公開トラブルシューティング
4. Agent Access Guide — エンドユーザー アクセス アクセス許可、表示トラブルシューティング
5. 既知の問題 — デプロイがハングしたり、公開に失敗したり、アクティベートが予期せず失敗した場合のみ読み込む

Production の問題を診断する

ユーザーのエージェントは公開されてアクティブですが、プレビュー中に検出されなかった問題が発生しています。クレジット過剰消費、トークンまたはサイズ制限エラー、ループ ガードレール割り込み、予約キーワード ランタイム エラー、VS Code 同期失敗、またはプレビューと本番間の予期しない動作の違いが含まれます。

必須ステップ

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

1. 問題を分類 — これが請求/コスト懸念、ランタイム制限、命名の競合、ツール問題、またはプレビューと本番間の動作の違いであるかを判断します。
2. 既知の production gotchas をチェック — Production Gotchas を読んでクレジット消費、トークン制限、ループ ガードレール、予約キーワード、ライフサイクル フック、および VS Code ワークアラウンドを確認します。
3. プレビュー vs 本番動作を比較 — 問題が動作的である場合、公開されたエージェントをプレビュー: sf agent preview start --json --api-name <Developer_Name> (--authoring-bundle ではなく)。live-actions authoring bundle プレビュー --authoring-bundle <Developer_Name> --use-live-actions と比較してプレビュー vs 本番の違いを分離します。
4. 既知の問題をチェック — 既知の問題 を読んで本番のみの失敗を説明するプラットフォーム バグを確認します。
5. 修正と再公開 — 修正を適用し、検証、再プレビュー、公開、アクティベート、検証します。デプロイ、公開、アクティベート ステップに従ってください。
6. 診断を説明 — ユーザーに何が起きていて、何を変更したかを伝えます。ルート原因を説明します。

リファレンス ファイル

1. Production Gotchas — クレジット消費、トークン制限、ループ ガードレール、予約キーワード、ライフサイクル フック、VS Code ワークアラウンド
2. エージェント用 CLI — preview、publish、activate のコマンド構文
3. 検証とデバッグ — プレビュー ワークフロー、セッション トレース分析
4. 既知の問題 — 問題がプラットフォーム バグの可能性がある場合のみ読み込む

エージェントを削除またはリネームする

ユーザーはエージェントを削除したい、またはその名前を変更したいと考えています。AiAuthoringBundle のバージョン管理と公開バージョン依存関係によって複雑化されるメンテナンス タスク。

必須ステップ

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

1. 現在の状態を理解 — メタデータとライフサイクル を読んでバージョン管理、削除メカニクス、およびリネーム メカニクスを確認します。エージェントが公開されているかどうか、どのくらいのバージョンが存在するか、および現在アクティブであるかどうかを特定します。
2. アクティブであれば非アクティベート — sf agent deactivate --json --api-name <Developer_Name> アクティブなエージェントは削除またはリネームできません。
3. 操作を実行 — 削除の場合: Metadata & Lifecycle リファレンスで削除メカニクスに従います。リネームの場合: 同じリファレンスのリネーム メカニクスに従います。
4. 孤立したものをクリーンアップ — 孤立したメタデータを検索して削除します: Bot、BotVersion、GenAiPlannerBundle、GenAiPlugin、GenAiFunction。Metadata & Lifecycle リファレンスで何を探すかについて詳細があります。
5. 検証 — 操作が正常に完了したことを確認します。リネームの場合、新しいバンドルがコンパイルされること、およびプレビューして動作を確認すること検証します。

リファレンス ファイル

1. エージェント用 CLI — delete、deactivate、retrieve の正確なコマンド構文
2. 検証とデバッグ — コンパイル検証、プレビュー ワークフロー
3. メタデータとライフサイクル — 削除メカニクス、リネーム メカニクス、孤立したクリーンアップ

エージェントをテストする

ユーザーは Agent Script エージェント向けの自動テストを作成したいと考えています。テスト シナリオ、予期される動作、および品質メトリクスを定義する YAML 形式の AiEvaluationDefinition テスト仕様の作成が関わります。

必須ステップ

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

1. カバレッジベースラインを確立 — Agent Spec を読みます。Agent Spec が存在しない場合は、理解 ステップに従ってリバース エンジニアリングを最初に実施します。すべてのサブエージェント、アクション、およびフロー制御パスを Agent Spec にマップしてテスト カバレッジが必要なものを特定します。
2. テスト シナリオを設計 — テスト設計方法論、予期、メトリクス、テスト仕様 YAML 形式、およびテンプレートについては、testing-agentforce スキルを使用してください。そのスキルはすべてのテスト コンテンツを所有しています。各カバレッジ ターゲットについて、1 つ以上のテスト シナリオを作成します: ユーザー発話、予期されるサブエージェント ルーティング、予期されるアクション呼び出し、および予期されるエージェント応答。happy paths とエッジ ケースの両方を含めます。
3. テスト仕様 YAML を作成 — testing-agentforce スキルのテンプレートとリファレンス ファイルを使用します。SFDX プロジェクトの specs/<Agent_API_Name>-testSpec.yaml に保存します。
4. テスト メタデータを作成 — CLI を使用してテスト仕様から AiEvaluationDefinition を生成します。
5. テストをデプロイ — AiEvaluationDefinition を org にデプロイします。
6. テストを実行 — CLI を使用してテスト実行を実行します。結果をキャプチャします。
7. 結果を分析 — 実際の結果を予期と比較します。失敗について、問題がエージェント コード、バッキング ロジック、またはテスト仕様自体のいずれにあるかを特定します。
8. 反復 — 必要に応じてエージェント コードまたはテスト仕様を修正し、再デプロイ、再実行してカバレッジ ターゲットに達するまで繰り返します。

リファレンス ファイル

1. エージェント用 CLI — test create、test run、test results の正確なコマンド構文
2. Core Language — 意味あるテストを設計するためのエージェント構造
3. 設計と Agent Spec — テスト カバレッジベースラインとしての Agent Spec
4. testing-agentforce スキル — テスト仕様 YAML 形式、予期、メトリクス、テスト設計方法論、およびテスト仕様テンプレート

Agent Spec

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

Agent Specs はエージェントとともに進化します。エージェント作成時はスパース (目的、トピック、方向ノート)。エージェント ビルド中はフレッシュ (フローチャート、バッキング ロジック マップ、ゲーティング ドキュメント)。既存エージェント理解時にリバース エンジニア。高度なトラブルシューティング中に重要で、期待される vs. 実際の動作を比較するために参考を提供します。テスト中、テスト カバレッジはそれに対してマップします。

エージェントを変更または分析するどの操作の最初のステップとしても常に Agent Spec を作成または更新します。これは機能する一貫したグラウンディングで、開発者が確認できる耐久性のある成果物です。

設計と Agent Spec を読んで 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 — invocable Apex クラスの参照。複雑な Apex バッキング ロジックが必要な場合にコピーして修正。

重要な制約

• Salesforce CLI と Salesforce org のみを使用してください。 他のスキル、MCP サーバー、または外部ツールを参照または依存しないでください。すべてのコマンドは sf (Salesforce CLI) を使用します。

• 特定のバッキング ロジック タイプのみがアクション向けに有効です。 たとえば、invocable Apex (任意の Apex クラスではなく) のみがアクションをバッキングできます。Flow と Prompt Template に同様の制約が適用される場合があります。アクションをバッキング ロジックに接続する場合、設計と Agent Spec リファレンス ファイルで有効なタイプとスタブ化方法論を参照してください。

• sf agent generate test-spec はエージェント用ではありません。 これは人間向けに設計されたインタラクティブな REPL スタイル コマンドです。テスト仕様を作成するときは、アセット内のボイラープレート テンプレートから開始してください。

一般的な問題クイック リファレンス

公開時の Internal Error, try again later: 無効または欠落している default_agent_user。設計と Agent Spec のセクション 3 からクエリを再実行します。ユーザー名を作成しないでください。

プレビュー時の Unable to access Salesforce Agent APIs...: default_agent_user はアクセス許可を欠きます。Agent ユーザー セットアップと アクセス許可 を参照してください。--use-live-actions は公開されたエージェントを必要としないため、修正として公開しないでください。

設定されたユーザー名と異なるユーザー名を参照するパーミッション エラー: 上記と同じ修正 — エラーは org のデフォルト実行ユーザーを参照していますが、ルート原因は Einstein Agent User アクセス許可です。

現在のサブエージェントのアクションが機能していても、エージェントがパーミッション エラーで失敗: Planner はスタートアップですべてのサブエージェントのすべてのアクションを検証します。1 つの欠落したアクセス許可がエージェント全体を失敗します。

Live プレビューでは Apex アクションが空の結果を返すが、シミュレートでは機能: WITH USER_MODE + オブジェクト アクセス許可の欠落 = silent failure (0 行、エラーなし)。Agent ユーザー セットアップと アクセス許可、セクション 6.2 を参照してください。

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

• ブロック順序: system: → config: → variables: → connection: → knowledge: → language: → start_agent agent_router: → subagent: ブロック
• インデント: インデント レベルごとに 4 スペース。タブを使用しないでください。スペースとタブの混合はパーサーを破壊します。
• ブール値: True/False (大文字)
• 文字列: 常にダブル クォート
• 数値 action I/O: 変数では number が機能しますが、公開で失敗します。数値 action パラメータに object + complex_data_type_name を使用してください。複雑なデータ型 で完全な判定木を参照してください。
• after_reasoning: は NO instructions: ラッパーを持つ
• else if なし — if x and y: の複合またはシーケンシャル フラット ifs を使用
• 予約された @InvocableVariable 名: model、description、label — Apex パラメータ名として使用できません
• @inputs と @outputs はエフェメラル: @inputs は with でのみ; @outputs はアクション直後の set/if でのみ。set の @inputs = silent failure。

複雑なデータ型向けの完全な Lightning 型マッピング判定木については 複雑なデータ型 を参照してください。3 フェーズ ランタイム モデルについては Instruction Resolution を参照してください。

アーキテクチャ パターン

3 つの主要な FSM パターン。コード付きの詳細は アーキテクチャ パターン にあります。

• Hub-and-Spoke (最も一般的): start_agent が専門サブエージェントにルーティング。各サブエージェントは「ハブに戻る」遷移を持つ。個別ルーティング サブエージェントを作成しないでください。
• Verification Gate: 保護されたサブエージェントの前のアイデンティティ検証。保護された遷移の available when ガード。
• Post-Action Loop: アクション完了後の再解決でトリガーする instructions: -> トップの post-action チェック。

スコーリング ルーブリック

7 つのカテゴリに対して 100 ポイントで生成されたすべてのエージェントをスコアリング: Structure (15)、Safety (15)、Deterministic Logic (20)、Instruction Resolution (20)、FSM Architecture (10)、Action Configuration (10)、Deployment Readiness (10)。

完全なルーブリックについては スコーリング ルーブリック を参照してください。

Review Mode

ユーザーが既存の .agent ファイルを提供するとき (例えば、review path/to/file.agent):

1. ファイルを読む
2. 100 ポイント ルーブリックに対してスコアリング
3. カテゴリごとにグループ化されたすべての問題をリスト
4. 修正されたコード スニペットを提供
5. 修正を適用することを提案

Safety Review

.agent ファイル向けの 7 カテゴリ LLM 駆動型 safety review