SF-AI-AgentScript スキル

Agent Script は決定論的 Agentforce エージェント向けのコードファーストパスです。ユーザーが .agent ファイルを作成している、有限状態トピックフローを構築している、またはルーティング、変数、アクション、および公開動作に対する反復可能な制御が必要な場合に、このスキルを使用してください。

最初に最短ガイドから始めてください: references/activation-checklist.md

ビルダー 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 設計

ユーザーが以下を行っている場合は他の場所に委譲してください:

• ビルダーメタデータエージェントのメンテナンス (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. 正確に 1 つの start_agent ブロック
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 は、X が target: を持つトピックレベルアクション定義の場合のみ使用
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) 重要な config フィールド

フィールド	ルール
developer_name	フォルダ / バンドル名と一致する必要がある
description	パブリック ドキュメント / 例はこの config フィールドを使用する必要がある
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 を使用
• 生のインテント / 検証シグナルをブール値またはEnum に正規化してから分岐。重要な制御フローのために生のユーザー発話で直接部分文字列チェックを避ける
• アクション後のチェックを instructions: -> の トップ に保持

デフォルト作成スタンス

• デフォルトで直接 .agent 作成とソース管理でのEdits に デフォルト化
• ユーザーがローカルバンドルスキャフォルディングを望む場合のみ sf agent generate authoring-bundle --no-spec を使用
• sf agent generate agent-spec をオプションの ideation / トピックブートストラップとして扱い、デフォルトワークフローではない
• 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 個のスモークユーターナンスを導出
• ベアレ sf agent preview ではなく start / send / end サブコマンドでプレビューを開始
• --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

# 手動アクティベーション
sf agent activate --api-name MyAgent -o TARGET_ORG

# CI / 既知の 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、および {!@actions.X} 命令参照など)

現在 reasoning レベルのユーティリティとしてモデル化されている何かに対して決定論的な動作が必要な場合は、以下のいずれかを実行してください:

• 直接 set / transition to として書き直す、または
• トピックレベルのターゲット支持アクションに昇格させ、そのアクションを run する

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

---

クロススキル統合

クロススキル オーケストレーション

タスク	委譲先	理由
flow:// ターゲットを構築	sf-flow	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	ターゲットテンプレートはドラフトステータス — 最初にアクティベートしてください	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
プレビューと実行時が一致しない	リンク済みVars / コンテキスト / 既知のプラットフォーム問題	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

例 / スキャフォルド

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

プロジェクト ドキュメント

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

---

スコアガイド

スコア	意味
90+	自信を持ってデプロイ
75–89	良好、警告を確認
60–74	重点的な見直しが必要
< 60	公開をブロック

完全なルーブリック: references/scoring-rubric.md

---

公式リソース

• Agent Script ドキュメント
• Agent Script レシピ
• Agentforce DX ガイド
• references/official-sources.md