agentforce-generate

Agent Script スキル

このスキルの用途

このスキルは、主に AI エージェント向けの Salesforce のスクリプト言語である Agent Script を使用して、Agentforce エージェントを開発するためのものです。

組織に接続するワークフローには、Agentforce ライセンス、API v66.0 以降、Einstein Agent User が必要です。静的な作成とレビューは、組織にアクセスできなくても実施できます。

重要： Agent Script は AppleScript、JavaScript、Python、その他の言語ではありません。Agent Script の構文や意味を、学習した他の言語と混同しないでください。

Agent Script エージェントは AiAuthoringBundle メタデータで定義されます。これには、<ApiName>.agent ファイル（エージェントの動作）と、同じ階層にある <ApiName>.bundle-meta.xml ファイル（バンドルのメタデータ）が含まれます。ディレクトリと両方のファイル名には、大文字と小文字を区別した同じ API 名を使用する必要があります。bundle-meta.xml というファイル名そのものはデプロイできません。アクションは、invocable Apex、autolaunched Flows、Prompt Templates、その他のサポートされているタイプを使って実装できます。

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

このスキルの使い方

このファイルは、ユーザーの意図をタスク領域と references/ 内の関連するリファレンスファイルに対応付けます。このファイルをエージェント開発全体の実行ルーターとして扱い、詳細についてはリファレンスを参照してください。

タスクの説明からユーザーの意図を特定します。現在のステップで明示的に必要なリファレンス、または現在の判断に必要なリファレンスのみを読み込んでください。各 Reference Files セクションは検索用のインデックスであり、事前読み込みリストではありません。後続のステップや該当しないステップのファイルは読み込まないでください。

既存のエージェントの包括的なヘルスチェック、よくある落とし穴の監査、または監査・修正・評価のサイクルを行う場合は、同じ作成ライフサイクルの一部として、以下の 既存のエージェントを監査して修復する タスク領域を使用してください。

常に適用されるルール

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. 変更の規模に応じて診断します。 構文上またはローカルの静的な不具合には、まずサポートされているローカルパーサー／コンパイラーを実行し、利用可能であればその後に対象組織での検証を追加してください。 動作上の不具合には、ベースラインを保持し、プレビューとトレースを使用してください。 Surface の修復では、承認済みの編集リストを正確に固定してから最終差分を確認し、ブロックスカラーやメタデータの正規化も含め、それ以外のすべての差分を元に戻してください。最小限の変更による修復では、ユーザーが明示的にクリーンアップを対象範囲に含めない限り、任意の見た目上の指摘は参考情報にとどめてください。有効な構文で、診断もユースケースへの影響もないものは、追加修正の対象ではありません。 シミュレーションではルーティングとアクションの選択を確認できます。--use-live-actions を使用するのは、明示的な承認があり、非本番環境であることを確認し、安全なテストデータがある場合に限ってください。シミュレーションや応答テキストを根拠に、外部への影響があったと主張しないでください。検証とデバッグを参照してください。

4. 仕様の承認ゲートを適切な範囲で適用します。 新規エージェントと構造変更または書き換えには、Agent Spec の明示的な承認を得てください。ユーザーが許可した、仕様が明確なローカル修復では、仕様全体を作り直したり、再承認を求めたりする必要はありません。影響を受けるユースケースを記録し、既存の設計を維持してください。ユーザーが十分に詳細な設計を提示し、すでに承認済みであると明示している場合は、それを承認済みの仕様として扱ってください。要件が不足している場合、または大幅に変更される場合を除き、仕様を作り直したり、追加の承認を求めて作業を止めたりしないでください。

5. 停滞しないでください。 ステップが正常に完了したら、次のステップを伝えて開始してください。ユーザーが「次は何ですか」や「はい、続けて」と言うのを待たないでください。明示的なユーザー承認が必要なチェックポイントには、（a）Rule 4 で必要となる Agent Spec の承認、（b）公開前の CHECKPOINT、（c）破壊的な操作や重大な影響を及ぼす外部操作、（d）スキルが明示的に提示する A/B 分岐（例：ADL のセットアップ中に Data Cloud がプロビジョニングされていない場合）が含まれます。ADL のインデックス作成など、時間のかかる非同期処理はバックグラウンドで実行し、結果に依存しない作業をスキルで続けてください。

6. まずはドラフトで進めるライフサイクル。 通常の作成作業では、ドラフトの反復を続けてください。.agent とアクションの実装を編集し、必要に応じて何度でも検証、デプロイ、プレビューを行います。デフォルトでは公開／有効化しないでください。公開と有効化は明示的なリリース操作であり、現在のドラフトをメタデータに反映し、エンドユーザーに公開する準備ができたことをユーザーに確認してから実行します。

7. 最初は実行ブロックを1つにし、可変状態を持たせないでください。 焦点を絞ったエージェントでは、推論とアクションを start_agent に直接記述します。サブエージェントは、実際の目的、指示、アクション、権限、またはエスカレーションの境界がある場合にのみ追加します。永続状態は、名前の付いた決定論的なコンシューマーがある場合にのみ追加し、完全なライフサイクルを定義します。通常の継続性は、保持される履歴で対応します。The Zen of AgentScript と Posture & Determinism に記載された具体的なチェックを適用してください。

8. サポートされている制御フローを使用してください。 正規の条件構文を使用し、Agentforce の lint で拒否されるネストした if は生成しないでください。Conditional Control Flow Syntax を参照し、続けてバンドル全体を検証してください。

9. アクションの実装方法はユーザーが決めます。 計画／仕様の作業では、新しいアクションはデフォルトで NEEDS STUB のプレースホルダーにします。既存の実装を組織／プロジェクト内で検索するか、新しい Apex／Flow／Prompt の実装を生成するかについて、どちらかの方法に進む前に必ずユーザーに確認してください。

10. 到達可能な各分岐には、次の結果を1つだけ割り当ててください。 主な結果は、回答、質問、アクションの呼び出し、遷移、拒否、エスカレーションから、正確に1つ選びます。コンパイラーはグローバル値ではなく、サブエージェントの system.instructions オーバーライドを選択します。また、現在のランタイムは、モデル向けの有効なシステムテキストと解決済みの推論テキストを組み立てます。作成時の構文をモデル向けのテキストに含めないでください。Instruction Resolution を参照してください。

11. 移植性のある構造的なインデントを使用してください。 新しい .agent ファイルは、レベルごとに4つのスペースで生成します。既存ファイルを限定的に編集する場合は、一貫したインデントを維持するか、ファイル全体の正規化を独立した検証済みの変更として行ってください。

12. プロンプトの書式を制御フローと誤認させないでください。 | テキスト内のインデント、番号付き手順、「Show」、「Ask」、「Call」、「Set」、「STOP」などの語句は、モデルへの指示であり、実行可能なスコープではありません。アクションは個別に制御してください。連続するプロンプトブロックごとに | を1つだけ使用します。隣接して | を繰り返しても、段階や優先順位は設定されません。ターンの区切りや別の推論の繰り返しを強制するために @utils.setVariables を使用しないでください。Common Control-Flow Pitfalls のチェックリストを適用してください。

13. 各判断の担当者を決めます。 結果を一貫して維持する必要があり、厳密な機械判定可能な事実を扱う場合は、実行時述語を使用します。意味的な意図、曖昧さへの対応、復旧、状況に応じた判断では、柔軟性を優先してモデルへの指示を使用します。プロンプトテキストに {[email protected]} を挿入しない限り、モデルは保存された変数の値を読み取れません。値を展開しても、モデルによる比較が決定論的になるわけではありません。姿勢と決定性のトレードオフテストを適用してください。

14. AgentScript はまずローカルで、手早く、結果を明示してコンパイルします。 既存の .agent ファイルを対象とする作成、修正、監査のタスクでは、組織側での検証や完了報告の前に、付属のローカルインデックス／コンパイラーを必ず実行してください。次を実行します。 node <skill-directory>/scripts/index-agent.mjs <agent-file>。SDK を読み込めない場合は、AgentScript コンパイラーのセットアップに従って再試行し、範囲を限定した npm／ソースの代替手段を使用します。重大度 1 の診断をすべて修正し、問題がなくなるまで再実行してください。プロバイダーと正確なバージョンまたはコミットを報告します。組織へのアクセスを、手早く済むローカルチェックの代わりにしてはいけません。ローカルでの 2 つのセットアップ方法がどちらも失敗した場合は、対象組織での検証、または範囲を限定した静的レビューを続け、原因とともに コンパイラー未使用 と明記します。タスクを停滞させたり、今後実行するよう提案したコマンドを検証済みであるかのように示したりしてはいけません。オフライン モードや 非対話型 モードでも、この手順は省略できません。禁止されるのはネットワーク操作と組織への操作であり、付属のローカルコンパイラーの使用ではありません。

15. 作成バンドルの構成をデプロイ可能な状態に保ちます。 aiAuthoringBundles/<ApiName>/ 配下には、対応する <ApiName>.agent と <ApiName>.bundle-meta.xml のペアを必ず揃えます。メタデータのファイル名を bundle-meta.xml に短縮してはいけません。スキャフォールドまたは取得したメタデータは、スキーマを書き換えずに維持します。新たに CLI でスキャフォールドしたバンドルでは通常 <bundleType>AGENT</bundleType> を使用します。既存のディスクリプターでは、代わりに確立済みの fullName／type／status 形式を使用でき、label と description は任意です。不完全なハイブリッドを作成したり、フィールドを独自に追加したりしてはいけません。.agent ファイルのローカルコンパイルでは、メタデータのファイル名や XML は検証されないため、検証が成功したと報告する前に、両方を確認してください。

タスクの領域

ユーザーの現在の目的に合った領域を選択します。作業を始める前に、指定された参照資料を読んでください。リンクは読み込み手順であり、任意の参考文献ではありません。該当するワークフローだけに従い、満たされている前提条件はそのまま維持します。通常のライフサイクルは、設計 -> ドラフト作成 -> 検証／プレビュー -> 明示的な承認を得たリリースです。

エージェントを作成する

新しいエージェントまたはオーサリングバンドルに使用します。

1. 設計とエージェント仕様を読み、すでに承認されている十分に詳細な設計が提供されている場合は、それをビルド契約として使用し、再生成や再承認は行いません。それ以外の場合は、要件を保存済みのエージェント仕様にまとめ、明示的な承認を得ます。ユーザーが実装の再利用、生成、またはプレースホルダーのままにするかを選択するまでは、新しいアクションの実装をNEEDS STUBのままにします。
2. エージェント向け CLIの該当するセクションを読み、組織で作業する前に対象組織の前提条件を確認します。ドキュメントを根拠とする場合は、データライブラリを読みます。音声エージェントの場合は、音声モダリティと音声レイテンシを読みます。
3. Salesforce CLI でオーサリングバンドルを生成します。スキャフォールドされた<ApiName>.agentを編集し、対応する<ApiName>.bundle-meta.xmlを保持します。作成を始める前に、コア言語、指示の解決、および該当するテンプレートを読みます。
4. ルール 14 で必要とされるローカルコンパイラーを実行します。認証済みの対象組織を利用できる場合は、組織内でもオーサリングバンドルを検証します。アクションの依存関係を実装またはデプロイする前に、作業を妨げる診断結果を修正します。
5. アクションの実装を生成するのは、ユーザーがその方法を選択した場合に限ります。依存関係を1つずつ検証してデプロイします。
6. ドラフトをプレビューし、検証とデバッグを使用してトレースを調べます。現実的な正常系、隣接ケース、復旧、およびキャンセルの各パスを網羅します。
7. ドラフトのループを続けます。デプロイ、公開、アクティベートのリリースゲートを通過し、ユーザーが明示的に承認した後にのみ、公開してアクティベートします。

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

既存のバンドルについてユーザーが理解したい場合に使用します。

1. パッケージと対応するオーサリングバンドルファイルを見つけます。
2. コア言語を読み、サブエージェントのグラフ、決定論的なブロック、モデルへの指示、アクション、変数、およびアクションの実装を整理します。
3. 設計とエージェント仕様を読み、保存済みのエージェント仕様をリバースエンジニアリングします。グラフにはサブエージェントマップ図を使用します。ユーザーから依頼された場合にのみ、ソースに注釈を付けます。
4. サポート対象のアンチパターンを指摘し、観察された動作と静的な推論を区別します。他に説明のつかない回避策がある場合に限り、既知の問題を読み込みます。

既存のエージェントを監査して修復する

「AgentScript を修正して」、ヘルスチェック、よくある落とし穴のレビュー、ベースラインと候補の修復ループに使用します。

1. 監査と修復を読み、リンク先のスコープ／パスレビューと修復／レポートのワークフローに順番どおり従います。
2. 診断カタログと、対象アーティファクトに該当するカテゴリのみに対応する個別の診断リファレンスを使用します。疑われるプロンプト／制御フローの問題には、よくある制御フローの落とし穴とその個別のリファレンスを使用します。
3. アーティファクトを変更する前に、受け入れ済みの Surface 編集を確定します。Structural または Rewrite の作業では、ルール 4 で必要とされる承認を得ます。
4. ローカルでコンパイルし、変更していないベースラインと候補を同じユースケースで比較して、監査評価ループに従います。
5. Surface、Structural、Rewrite の評価を個別に報告します。ユーザーから別途リリース操作を依頼されない限り、ドラフトのままにします。

監査リファレンスファイル

• 監査スコープとパスのレビュー
• 監査の修復とレポート
• 監査候補の検証
• 命令とルーティングの診断
• アクションと状態の診断
• アーキテクチャと評価の診断
• アクションと順序に関する落とし穴
• ライフサイクルと副作用に関する落とし穴
• AgentScript コンパイラのセットアップ

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

既存のレスポンス、ルート、アクション、サブエージェント、状態フロー、グラウンディングソース、またはモダリティに対する承認済みの変更に使用します。

1. まず影響を受けるパスを把握します。重要な設計変更の場合は、Agent Spec を更新して承認を得ます。範囲の限定された指定された修復の場合は、完全なスペックの書き直しを強いることなく、影響を受けるユースケースを記録します。
2. コア言語と、変更に必要な機能リファレンスのみを読みます。無関係なメタデータ、コントラクト、フォーマット、および動作は維持します。
3. 既存のバンドルをその場で編集します。アクションの実装は、明示的に要求された場合にのみ生成します。
4. ローカルでコンパイルし、可能な場合はターゲット組織に対して検証します。変更されたすべてのパスと隣接するパスをプレビューし、トレースを検査します。ドラフトで反復します。
5. リリースワークフローは、ユーザーが別途リリースを要求した場合にのみ使用します。

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

1. 報告された正確なエラーをキャプチャし、ルール 14 のローカルコンパイラを実行します。
2. 認証済みのターゲット組織が利用可能な場合は、組織の検証を実行します。ライブプレビューは、コンパイルが成功したもののランタイムの準備がまだ失敗する場合にのみ使用します。
3. 検証とデバッグおよびコア言語を使用して、各具体的なエラーを分類して修復します。
4. エラーを露呈したサーフェスを再実行します。実行された正確なチェック、残っている制限事項、および実行されていないコマンドを検証証跡として報告しないでください。

動作または本番の問題を診断する

ローカルの動作上の問題については、ベースラインを保持し、現実的な発話でプレビューし、検証とデバッグを使用してトレースを検査します。編集する前に、どのサブエージェント、アクション呼び出し、アクション結果、状態変更、および最終レスポンスが実際に発生したかを確認します。

本番のセッションまたはトレース ID については、agentforce-observe を使用して取得と再構築を行います。証拠が AgentScript の変更を特定した場合にのみ、ここに戻ります。利用できないアクションの入力、出力、またはモデルの推論を決してでっち上げないでください。

デプロイ、公開、有効化

1. CLI for Agents、 Metadata & Lifecycle、および Deployを読んでください。
2. ローカルでコンパイルし、対象の組織に対して検証します。バンドルと 依存関係をデプロイしてから、現実的なカバレッジでライブプレビューを実行し、 トレースを確認してください。ブロッキング結果が出た場合は先に進まないでください。
3. 対象の組織とバージョンの状態を正確に提示します。公開または有効化の前に、 ユーザーから明示的な承認を得てください。
4. 承認を得てから、ユーザー向けエージェントを公開、有効化し、検証してください。
5. 音声エージェント — テレフォニーチャネルの接続は別途オプトインが必要な手順です。自動で接続してはいけません。 電話番号を接続すると、実際のルーティングインフラストラクチャ（フロー、キュー、有効な MessagingChannel）が作成され、プロビジョニング済みの番号が消費されます。そのため、ユーザーが明示的に依頼し、プロビジョニング済みの電話番号を提示した場合に限り実行してください（その番号が実在することを確認し、推測や捏造はしないでください）。どちらかが不足している場合は停止し、必要なものを伝えてください。両方が揃っている場合は、CLI を使用してヘッドレスで接続してください。ユーザーを Agent Builder に誘導しないでください。 Headless Telephony CLIに従ってください。

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

CLI for Agentsと Metadata & Lifecycleの削除および名前変更のセクションを読んでください。参照と依存関係をすべて列挙し、影響を受けるバンドルを正確に示してから、削除前に明示的な確認を得てください。名前を変更する場合は、元のエージェントを削除する前に置き換えを作成して検証し、その後、孤立したメタデータがないか確認してください。

エージェントのテスト

テスト仕様の設計、セキュリティカバレッジ、メタデータの作成、実行、結果分析にはagentforce-testを使用してください。まず Agent Spec と、到達可能なすべてのルート／アクションをカバレッジ対象に対応付けてください。セキュリティテストの追加や、ライブアクションを呼び出す可能性のあるテストの実行前に確認を得てください。

レガシーエージェントを Agent Script に移行する

ユーザーがレガシーな GenAiPlannerBundle エージェントを NGA の AiAuthoringBundle（Agent Script）エージェントにアップグレードしたい場合です。「レガシーエージェントを移行して」「新しいビルダーにアップグレードして」「エージェントを変換して」「移行を開始して」などの表現や、genAiPlannerBundle／aiAuthoringBundle の移行について言及する場合があります。（Einstein Bot のアップグレードとは異なります。既存の Agentforce エージェントが対象です。Einstein Bot を新しいエージェントに変換する場合は、代わりに agentforce-bot-upgrade スキルを使用してください。）

必須手順

全体のワークフロー、正確なコマンド、NGA とレガシーの識別方法については、Upgrade a Legacy Agent to Agent Scriptを読んでください。概要は次のとおりです。

1. プロジェクトを設定する — 選択可能なメニューを使って対象の組織を確認してください。デフォルトの組織を決めつけてはいけません（sf org list を表示し、デフォルトを示したうえで、明示的に選択してもらいます）。DX プロジェクトを確認し（必要であれば作成し）、すべての取得処理をそのプロジェクト内から実行してください。
2. レガシーエージェントのバージョンを選択する — 2画面で選択します。まずエージェントを選び、次にNGA ではないバージョンを選びます。プランナーの PlannerType が Atlas__ConcurrentMultiAgentOrchestration のバージョンは、すでに NGA であるため除外してください。
3. Connect API で移行する — 選択した botVersionId を migrateAgentToNga に POST します。これは変更を伴う呼び出しです。最初に組織と ID を確認してください。大きなレスポンス（インラインの agentScript）でコンテキストが肥大化しないよう、サブエージェントで実行し、bundleVersionApiName（および conversionWarnings、agentResponse）のみを返してください。
4. 新しいバンドルを取得する — bundleVersionApiName を使用して AiAuthoringBundle をプロジェクトに取り込みます。フォールバックとして、bundleVersionId → fullName に対応付けることもできます。
5. 分析、最適化、反復 — この移行は Agent Script のプリミティブを考慮しない機械的な変換です。Comprehend an Existing Agentに引き継ぎ、次にOptimize an Agentを実行してから、検証／プレビューを行ってください。

参考ファイル

1. レガシーエージェントを Agent Script にアップグレードする — 詳細な手順、コマンド、判別ロジック
2. コア言語 — 移行後の .agent 構造を確認します

エージェントを最適化する

1. コア言語を読み、よくある制御フローの落とし穴を使って、到達可能なすべてのパスを調べます。
2. 該当する最適化リファレンスのみを読み込みます。対象は、データフロー、決定論的ロジック、参照構文、人間への引き継ぎ、音声対応です。
3. 根拠に基づく改善案を提示し、編集前に承認を得ます。
4. 承認された変更のみを適用し、ローカルでコンパイルし、可能な場合は組織に対して検証して、得られた根拠を報告します。

MCP サーバーを管理する

MCP に関する操作の前に、MCP サーバー管理をお読みください。対象の組織を確認し、--json を使用して、シークレットをコマンドラインに含めないでください。許可リストに追加する前にツールを確認し、破壊的または重大な変更については確認を求めてください。

Agent Spec

Agent Spec は、このスキルが生成し、使用する中心的な成果物です。エージェントの目的、ユーザーの成果、サブエージェントのグラフ、アクションと実装、変数、サブエージェントの姿勢、決定論的制御（必要な場合）、および振る舞いの意図を表す構造化された設計文書です。

Agent Spec はエージェントとともに進化します。エージェントの作成時は簡潔に記述し（目的、ユースケース、計画中のプレースホルダー）、エージェントの構築時に内容を充実させます（フローチャート、対応するアクションの実装、姿勢の選択の記録、正当な理由がある場合に限り決定論的制御を追加）。既存のエージェントを理解する際には、リバースエンジニアリングによって作成します。高度なトラブルシューティングでは、期待される動作と実際の動作を比較するための参照資料として重要です。テスト時には、テストカバレッジを Agent Spec に照らし合わせます。

新規開発、設計に大きな変更を加える場合、または文書化された契約に影響する分析結果が得られた場合は、Agent Spec を作成または更新してください。対象が限定された、すでに仕様化された修正では、仕様全体を書き直さず、影響を受けるユースケースと根拠を記録してください。

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

アセット

assets/ ディレクトリにはテンプレートと例が含まれています。アーティファクトやソースファイルの作成にあたり、出発点や具体的な参照例が必要な場合にご覧ください。

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

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

• assets/agents/template-single-subagent.agent — 互換性を考慮した名前の、焦点を絞ったスターターです。1つの start_agent 実行ブロックを含み、ルーターやサブエージェントのブロックはありません。

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

• assets/agents/router-first.agent — 遷移のみを使用するルーターの例です。 HyperClassifier と簡潔なルーター指示を使用しています。

• assets/agents/verification-gate.agent — 保護されたアクションの利用可否を制御する、ID／認可ゲートです。

• assets/agents/simple-qa.agent、production-faq.agent、order-service.agent — 振る舞いとアクションの複雑さが段階的に増す、完全な例です。

• assets/patterns/README.md — コールバック、入力バインディング、ライフサイクル、委譲、複数ステップのワークフローを扱う、個別の完全なパターンへの案内です。記載されたユースケースの前提条件に該当する場合のみ、そのパターンを使用してください。

• assets/invocable-apex-template.cls — 呼び出し可能な Apex クラスのリファレンスです。複雑な Apex アクションの実装が必要な場合は、コピーして変更してください。

重要な制約事項

• 必要な根拠に応じて、サポート対象のツールを使用してください。 組織を基盤とする検証とリリース操作には、Salesforce CLI と対象の組織を使用してください。ローカルでの解析／コンパイルチェックには公開済みの AgentScript SDK を使用し、関連スキルはそれぞれのドキュメントで定められた範囲内でのみ実行してください。

• アクションに使用できる実装の種類は限られています。 たとえば、アクションを実装できるのは呼び出し可能な Apex のみであり、任意の Apex クラスは使用できません。Flow と Prompt Template にも同様の制約が適用される場合があります。アクションを実装に接続する際は、有効な種類とスタブ化の方法について、Design & Agent Spec のリファレンスファイルを確認してください。

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

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

公開時に発生するInternal Error, try again later： サーバー側のコンパイルエラーです。500 エラーではどのチェックが失敗したのかわかりません。ユーザーに問題の内容を尋ねる前に、4 つの原因を順番にすべて確認してください。原因 1 で確認を止めないでください。

1. access.default_agent_user のエージェントタイプが一致していません。 通常、従業員エージェントではaccess.default_agent_userを省略します。サービスエージェントでは必ず指定する必要があり、ユーザーには Einstein Agent ライセンスが必要です。設計とエージェントの仕様のセクション 3 を参照してください。クエリを再実行してください。ユーザー名を推測しないでください。
2. アクション定義にoutputs:ブロックがありません。 target:とinputs:があるアクションにoutputs:がない場合、サーバー側コンパイラは戻り値のバインディングを生成できません。CLI のvalidateと LSP はどちらも PASS しますが、公開時にのみ失敗します。既知の問題の Issue 15 を参照してください。
3. .agentファイルのその他の構造上のずれです。 同じ組織内にある正常に動作するバンドルと差分を比較してください。 sf project retrieve start --metadata "AiAuthoringBundle:<known-working-agent>" --output-dir /tmp/diff-bundle --json キーワードごとに比較します。必須でありながらドキュメントに記載されていないフィールドの欠落、ブロックの順序のずれ、バンドルで使われているものの正常に動作するバンドルにはない DSL キーワードを確認してください。
4. バックエンドで一時的に発生した本当のエラーです。 1～3 に問題がなく、再試行ごとにレスポンスのrequestIdが異なる場合は、60 秒待ってから 1 回再試行してください。

プレビュー時に発生するUnable to access Salesforce Agent APIs...： default_agent_userに権限がありません。エージェントユーザーの設定と権限を参照してください。修正のために公開しないでください。--use-live-actionsでは公開済みエージェントは不要です。

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

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

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

エージェントは公開済みで、ADL のインデックスも作成済み（retrieverIdが設定済み）なのに、グラウンディングされた質問がすべて空のknowledgeSummary／「その情報はありません」という結果になる： Einstein Agent User に Data Cloud へのアクセス権がありません。次の 2 点を順番に確認してください。

1. 権限セット／PSL が割り当てられていません。 エージェントユーザーの設定、手順 3b.3の検証クエリを実行してください。Data Cloud の権限セット／PSL が表示されない場合は、検出してから割り当てる手順を実行してください（優先順位：GenieDataPlatformStarterPsl PSL → GenieUserEnhancedSecurity PS → DataCloudUser PS → DataCloudArchitect PS）。
2. 権限セットでデータスペースのスコープが付与されていません。 現時点では API がありません。設定 → 権限セット → 割り当て済みの権限セットをクリック → アプリの「Data Cloud Data Space Management」→ 編集 → ADL のデータスペース（通常はdefault）を追加 → 保存。エージェントユーザーの設定、手順 3b.4を参照してください。

クイックリンク（詳細はリファレンスを参照）

• 構文と実行モデル：コア言語
• エージェントの設計／仕様策定プロセス：設計とエージェント仕様
• 振る舞いの調整（エージェント的か決定論的か）：振る舞いと決定性
• 具体的な作成時の不変条件：AgentScript の心得
• シナリオ別のパターン選択：要件別のパターン
• アーキテクチャの仕組み、HyperClassifier によるルーティング、移行：アーキテクチャパターン
• 検証、プレビュー、トレース：検証とデバッグ
• デプロイ／公開／有効化のライフサイクル：デプロイリファレンス
• メタデータのライフサイクルと公開時のトラブルシューティング：メタデータとライフサイクル
• ADL のプロビジョニングと接続：データライブラリリファレンス
• エージェントへのアクセスと権限：エージェントアクセスガイド、エージェントユーザーの設定
• 音声モダリティと電話対応エージェント：音声モダリティリファレンス
• 安全性レビューのフレームワーク：安全性レビュー
• 評価基準とレビューの採点：採点基準
• 最適化パターン：パターン 1 — データフロー、パターン 2 — 決定論的ロジック、パターン 3 — 参照構文、パターン 4 — エスカレーション
• MCP サーバーの登録とツールのホワイトリスト設定：MCP サーバー管理