sf-ai-agentscript

SF-AI-AgentScript スキル

Agent Script は、決定性の高い Agentforce エージェントを実現するためのコードファーストな方法です。ユーザーが .agent ファイルを作成している場合、有限状態のトピックフローを構築している場合、またはルーティング、変数、アクション、公開動作を再現可能な形で制御する必要がある場合に、このスキルを使います。

まず、最も短いガイドから始めてください：references/activation-checklist.md

Builder UI から移行しますか？references/migration-guide.md を使ってください。

このスキルが担当するタスク

次の作業には sf-ai-agentscript を使います。

• .agent ファイルの作成または編集
• 決定性の高いトピックルーティング、ガード、遷移
• Agent Script CLI のワークフロー（sf agent generate authoring-bundle、sf agent validate authoring-bundle、sf agent preview、sf agent publish authoring-bundle、sf agent activate）
• スロットの入力、指示の解決、アクション後のループ、または FSM の設計

ユーザーが次の作業をしている場合は、ほかに引き継ぎます。

• Builder メタデータエージェント（GenAiFunction、GenAiPlugin、GenAiPromptTemplate、Models API、カスタム Lightning タイプ）の保守 → sf-ai-agentforce
• ペルソナ／トーン／声の設計 → sf-ai-agentforce-persona
• 正式なテスト計画やカバレッジループの作成 → sf-ai-agentforce-testing

ユーザーが Builder Script／Canvas ビューを使っていても、成果物が .agent オーサリングバンドルであれば、作業は sf-ai-agentscript で続けてください。

---

適切な決定性の設定

• 決定性は目的地ではなく、調整するものです。
• 「おおむね正しい」では許容されない場合、つまりゲート、必須の順序、明示的な状態遷移、コンプライアンス、またはドリフト制御が必要な場合は、Agent Script を使います。
• ワークフローが完全に静的で直線的な場合は、会話をスクリプト化するのではなく Flow または Apex を使います。
• 決定性のある枠組みを優先してください。決定性のある開始／ゲート → 柔軟な中盤 → 決定性のある終了処理とします。
• 決定性を高めれば自動的に良くなるわけではありません。まず最小限から始め、ルーティングのドリフト、順序の失敗、またはコンプライアンスリスクが見られる部分だけを強化してください。

---

最初に確認する必須コンテキスト

次の点を確認するか、推測してください。

• エージェントの目的と、Agent Script が本当に適切かどうか
• Service Agent と Employee Agent のどちらか
• 対象組織と公開の意図
• 想定するアクション／対象（Flow、Apex、PromptTemplate など）
• 依頼がオーサリング、検証、プレビュー、または公開のトラブルシューティングのどれに当たるか

---

有効化チェックリスト

.agent ファイルを作成または修正する前に、まず次の点を確認してください。

1. start_agent ブロックがちょうど 1 つである
2. タブとスペースを混在させない
3. ブール値は True／False にする
4. else if とネストした if を使わない
5. トップレベルの actions: ブロックを使わない
6. set 式で @inputs を使わない
7. linked 変数にデフォルト値を設定しない
8. linked 変数に object／list 型を使わない
9. 明示的な agent_type を使う
10. @actions. プレフィックスを一貫して使う
11. run @actions.X を使うのは、target: を持つトピックレベルのアクション定義が X の場合に限る
12. インテントのルーティングに、@system_variables.user_input contains/startswith/endswith の生の値を直接使って分岐しない
13. プロンプトテンプレートの出力では、is_displayable: False と is_used_by_planner: True の組み合わせを優先する
14. @outputs.X がスカラー値だと決めつけない。分岐や代入の前に出力スキーマを確認する

詳細版は references/activation-checklist.md を使ってください。

---

絶対に守るべきルール

1) Service Agent と Employee Agent

エージェントタイプ	必須事項	禁止事項／注意事項
AgentforceServiceAgent	有効な default_agent_user、適切な権限、対象組織の確認、sf org create agent-user を優先する	実在する Einstein Agent User がいない状態で公開しない
AgentforceEmployeeAgent	明示的な agent_type	default_agent_user を指定しない

詳細：references/agent-user-setup.md

2) 推奨されるトップレベルブロックの規約

このスキルの例やレビューでは、一貫性を保つために次の順序を使用してください。

config:
variables:
system:
connection:
knowledge:
language:
start_agent:
topic:

Salesforce の公式資料ではトップレベルブロックの順序が異なっており、ローカルでの検証結果からも複数の順序でコンパイルできることが示されています。これはスタイル上の規約として扱い、単独で正誤を判断したり、公開を妨げたりするものではありません。

3) 重要な設定フィールド

フィールド	ルール
developer_name	フォルダー名／バンドル名と一致させる必要があります
description	公開ドキュメント／例では、この設定フィールドを使用してください
agent_type	毎回明示的に設定してください
default_agent_user	Service Agents のみ

ローカルのツールでは互換性のために agent_description: も使用できますが、このスキルの公開ドキュメントや例では description: を優先してください。

4) 即時エラーとして扱うべき構文上のブロッカー

• else if
• ネストされた if
• コメントのみの if 本体
• トップレベルの actions:
• 呼び出しレベルの inputs:／outputs: ブロック
• description や label などの予約済み変数／フィールド名

標準ルールセット：references/syntax-reference.md および references/validator-rule-catalog.md

---

推奨ワークフロー

推奨される作成ワークフロー

フェーズ 1 — エージェントを設計する

• 問題が Agent Script にとって本当に十分な決定性を備えているか判断します
• トピックを状態、遷移をエッジとしてモデル化します
• 本当に必要な変数のみを定義します

フェーズ 2 — .agent を作成する

• まず config、system、start_agent、トピックを作成します
• 完全な inputs: と outputs: を含む、ターゲットに紐づいたアクションを追加します
• 決定論的なツールの表示には available when を使用します
• 分岐の前に、生の意図／検証シグナルをブール値または列挙型に正規化します。重要な制御フローで、ユーザーの生の発話に対する直接的な部分文字列チェックは避けてください
• アクション後のチェックは instructions: -> の 先頭 に配置します

デフォルトの作成方針

• ソース管理で .agent を直接作成、編集する方法をデフォルトにします。
• ユーザーがローカルでのバンドルのひな形作成を希望する場合にのみ、sf agent generate authoring-bundle --no-spec を使用します。
• sf agent generate agent-spec は、デフォルトのワークフローではなく、任意のアイデア出し／トピックのひな形作成として扱います。
• Agent Script のユーザーを sf agent create や sf agent generate template に誘導しないでください。

フェーズ 3 — 継続的に検証する

検証は書き込み／編集時にすでに自動実行されます。公開前に CLI を使用してください。

sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json

バリデーターは、構造、実行時の注意点、ターゲットの準備状況、組織を考慮した Service Agent のチェックをカバーします。ルール ID は references/validator-rule-catalog.md にあります。

フェーズ 4 — プレビューのスモークテスト

公開前にプレビューのループを使用してください。

• スモークテスト用の発話を 3～5 個導き出します
• start／send／end サブコマンドを使用してプレビューを開始します。sf agent preview のみで実行しないでください
• --authoring-bundle を使用する場合は、必ずモードを明示的に選択します。--simulate-actions または --use-live-actions を指定してください
• トピックのルーティング／アクション呼び出し／安全性／グラウンディングを確認します
• 修正して、最大 3 回まで再実行します

ループの全体：references/preview-test-loop.md

フェーズ 5 — 公開して有効化する

sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Manual activation
sf agent activate --api-name MyAgent -o TARGET_ORG

# CI / deterministic activation of a known BotVersion
sf agent activate --api-name MyAgent --version <n> -o TARGET_ORG --json

公開しても、エージェントは有効化されません。 自動化では、決定論的で機械可読な有効化を実現するために、--version <n> --json を優先してください。

決定論的な構成要素

これらは提案ではなく、コードとして実行されます。

• 条件分岐
• available when ガード
• 変数チェック
• 直接の set ／ transition to
• run @actions.X：X がトピックレベルの target: を持つアクション定義である場合のみ
• LLM 向けテキストへの変数の挿入

重要な違い：

• 決定論的：set、transition to、およびトピックアクションを対象とする run @actions.X
• LLM による指示：reasoning.actions: のユーティリティ／委任（@utils.setVariables、@utils.transition、{[email protected]} の指示参照など）

現在、推論レベルのユーティリティとしてモデル化されているものに決定論的な動作が必要な場合は、次のいずれかを行います。

• 直接の set ／ transition to に書き換える、または
• トピックレベルの対象を持つアクションに昇格させ、そのアクションを run する

references/instruction-resolution.md と references/architecture-patterns.md を参照してください。

---

スキル間の統合

スキル間のオーケストレーション

タスク	委任先	理由
flow:// ターゲットを構築する	sf-flow	フローの作成／検証
Apex アクションターゲットを構築する	sf-apex	@InvocableMethod とビジネスロジック
トピックのルーティング／アクションをテストする	sf-ai-agentforce-testing	正式なテスト仕様と修正ループ
デプロイ／公開する	sf-deploy	デプロイのオーケストレーション

---

重要度の高い失敗パターン

症状	考えられる原因	次に読むドキュメント
公開中に Internal Error が発生する	Service Agent ユーザーが無効、またはアクションの I/O が不足している	references/agent-user-setup.md, references/actions-reference.md
プロンプトテンプレートアクションで invalid input/output parameters が発生する	対象テンプレートが Draft ステータスです — まず有効化してください	references/action-prompt-templates.md
パーサーが条件分岐を拒否する	else if、ネストされた if、空の if 本体	references/syntax-reference.md
アクションのターゲットに関する問題	Flow / Apex ターゲットがない、Flow が非アクティブ、スキーマが不正	references/actions-reference.md
プロンプトテンプレートは実行されるが、ユーザーには空の応答が表示される	プロンプト出力が is_displayable: True に設定されている	references/production-gotchas.md, references/action-prompt-templates.md
プロンプトアクションは実行されるが、プランナーが出力を未設定として扱う	出力は直接表示されないよう隠されているが、プランナーからは見える	references/production-gotchas.md, references/actions-reference.md
run @actions.X で ACTION_NOT_IN_SCOPE が発生する	run がトピックレベルのターゲット対応定義ではなく、ユーティリティ / 委任 / 未解決のアクションを参照している	references/syntax-reference.md, references/instruction-resolution.md
決定論的なキャンセル / 修正 / URL チェックの動作に一貫性がない	生の @system_variables.user_input マッチング、または文字列メソッドのガードを制御フロー上重要な検証に使用している	references/syntax-reference.md, references/production-gotchas.md
@outputs.X の比較や代入が予期しない動作をする	アクション出力が単純なスカラーではなく、構造化またはラップされている	references/actions-reference.md, references/syntax-reference.md
プレビューと実行時の結果が一致しない	リンクされた変数 / コンテキスト / 既知のプラットフォームの問題	references/known-issues.md
検証は通るが公開に失敗する	組織固有のユーザー / 権限 / 再取得に関する問題	references/production-gotchas.md, references/cli-guide.md

---

リファレンスマップ

まずはこちら

• references/activation-checklist.md
• references/syntax-reference.md
• references/actions-reference.md

公開 / 実行時の安全性

• references/agent-user-setup.md
• references/production-gotchas.md
• references/customer-web-client.md
• references/known-issues.md

アーキテクチャ / 推論

• references/architecture-patterns.md
• references/instruction-resolution.md
• references/fsm-architecture.md
• references/patterns-quick-ref.md

検証 / テスト / デバッグ

• references/preview-test-loop.md
• references/testing-guide.md
• references/debugging-guide.md
• references/validator-rule-catalog.md

Examples / scaffolds

• references/minimal-examples.md
• references/migration-guide.md
• assets/
• assets/agents/
• assets/patterns/

Project documentation

• references/version-history.md
• references/sources.md

---

Score Guide

Score	Meaning
90+	Deploy with confidence
75–89	Good, review warnings
60–74	Needs focused revision
< 60	Block publish

Full rubric: references/scoring-rubric.md

---

Official Resources

• Agent Script Documentation
• Agent Script Recipes
• Agentforce DX Guide
• references/official-sources.md