sf-ai-agentforce

sf-ai-agentforce：標準的な Agentforce プラットフォーム開発

Setup UI／Agent Builder の経路では、このスキルを使用します。宣言型トピック、Builder 管理のアクション、GenAiFunction／GenAiPlugin メタデータ、GenAiPromptTemplate メタデータとして保存される Prompt Builder テンプレート、Apex からの Models API の使用、カスタム Lightning タイプが対象です。

新しいコードファーストのエージェント開発には、sf-ai-agentscript を優先してください。

Builder Script／Canvas の作業を含め、作成または編集の結果として .agent ファイルが生成される場合は、sf-ai-agentscript を使用してください。

このスキルの対象となるタスク

次の作業には sf-ai-agentforce を使用します。

• 既存の Builder ベースのエージェントを保守する
• Setup → Agentforce → Agents で作業する
• GenAiFunction、GenAiPlugin、または GenAiPromptTemplate メタデータを作成または修正する
• Builder のトピックを Flow／Apex／Prompt Builder アクションに接続する
• Builder ベースのエージェントに関連して Models API または LightningTypeBundle を使用する

次の作業には使用しないでください。

• .agent ファイルや決定論的 FSM の設計 → sf-ai-agentscript
• エージェントのテストスイートやカバレッジの反復作業 → sf-ai-agentforce-testing
• ペルソナ／音声の設計 → sf-ai-agentforce-persona

---

最初に収集する必要のあるコンテキスト

次の内容を質問するか、状況から判断してください。

• これは Builder／Setup UI のプロジェクトか、コードファーストの Agent Script プロジェクトか
• ユーザーが編集しているのは Builder メタデータか、.agent オーサリングバンドルか
• エージェントの種類：Service Agent または Employee Agent
• 作業の対象はトピック、アクション、Prompt Builder テンプレート、Models API、カスタム Lightning タイプのどれか
• 既存の Flow／Apex／メタデータの依存関係
• ユーザーが必要としているのはオーサリング、公開、トラブルシューティングのどれか

---

Agentforce の 2 つの経路

経路	スキル	最適な用途
Builder メタデータの経路	sf-ai-agentforce	宣言型の保守、既存の Builder エージェント、メタデータ駆動のアクション登録
Agent Script オーサリングバンドルの経路	sf-ai-agentscript	コードファーストの .agent オーサリング、決定論的なルーティング、バージョン管理されたエージェントロジック

新規作成でフロー／状態を強力に制御したい場合は、Agent Script に誘導してください。

---

Builder ワークフローの概要

1. Builder／Setup UI プロジェクトであることを確認する
2. Service Agent と Employee Agent のどちらかを選ぶ
3. Service Agent の場合、実行ユーザーをプロビジョニングする（sf org create agent-user を推奨）
4. Employee Agent の場合、<agentAccesses> を含む Permission Set で可視性を計画する
5. 明確な説明、範囲、指示を設定してトピックを定義する
6. 関連するアクション（Flow、Apex、Prompt Builder テンプレート）を準備する
7. 入出力を慎重に設定する
8. 依存関係とテンプレートのステータスを検証する
9. 公開してから有効化する

ワークフローの詳細：references/builder-workflow.md

---

プラットフォームの主なルール

トピックの品質は重要です

トピックの説明はプランナーへのルーティング指示です。次の条件を満たす必要があります。

• 具体的である
• シナリオに基づいている
• 同じ階層の他のトピックと重複しない

アクションは実際のターゲットをラップするものです

ターゲットの種類	代表的な用途	登録方法
Flow	Builder アクションの最も安全なデフォルト	GenAiFunction
Apex	@InvocableMethod を介した複雑なビジネスロジック	GenAiFunction
Prompt Builder テンプレート	生成された要約／下書き／推奨事項	GenAiFunction

Prompt Template と GenAiPromptTemplate の比較

• Prompt Templateは、Prompt Builder で使用される平易な英語／UI 上の用語です。
• **GenAiPromptTemplate**は、ソース主導のテンプレート作業で現在使用されている Metadata API の型です。
• 現在のソース形式を優先してください：genAiPromptTemplates/*.genAiPromptTemplate-meta.xml。
• 柔軟な Prompt Builder テンプレートでは、入力は最大5個という制約を考慮し、必要に応じて入力を統合してください。
• プロンプトの内容では、現在の差し込み項目の形式（例：{!$Input:TargetRecord} または {!$Input:AdditionalContext}）で入力を参照してください。

先にサポートメタデータをデプロイする

エージェント自体を公開する前に、サポートスタックをデプロイしてください：

1. 必要に応じてメタデータ／項目
2. 必要に応じて Apex
3. 必要に応じて Flow
4. GenAiPromptTemplate / GenAiFunction / GenAiPlugin
5. その後、エージェントを公開

Service Agent の実行ユーザー

Service Agent では、ネイティブ GA コマンドを優先してください： sf org create agent-user --target-org <alias> --json 返されたユーザー名を実行ユーザー設定で使用してください。

Employee Agent の表示

Employee Agent では、エンドユーザーに <agentAccesses> を含む Permission Set が付与されていることを確認してください。これがないと、エージェントが有効でも Lightning Experience に表示されない場合があります。 ../sf-permissions/references/agent-access-guide.md を参照してください。

公開しても有効化されない

公開後に、別途 sf agent activate を実行してください。 自動化では、ロールアウトを確実かつ機械可読にするため、sf agent activate --api-name <AgentName> --version <n> --target-org <alias> --json を優先してください。

---

メタデータのガイダンス

GenAiFunction

単一の呼び出し可能なアクションを登録する場合に使用します。以下を検証してください：

• ターゲットが存在する
• ターゲットが有効／デプロイ可能である
• 入力名がターゲットの仕様と一致する
• 出力名がターゲットの仕様と一致する
• アクションを使用する場面が、機能の説明に明確に記載されている

GenAiPlugin

関連する関数を1つの論理的なパッケージにまとめる場合に使用します。

GenAiPromptTemplate

生成コンテンツに使用し、決定論的なビジネスルールには使用しません。

現在のメタデータ形式を優先してください：

• メタデータ型：GenAiPromptTemplate
• フォルダー：genAiPromptTemplates/
• ファイルの拡張子：.genAiPromptTemplate-meta.xml
• コンテンツは templateVersions の下に格納
• 依存するアクションを接続する前に、公開済みのテンプレートバージョンを使用

詳細なリファレンス：

• references/metadata-reference.md
• references/genaiprompttemplate.md

---

スキル間の連携

推奨されるオーケストレーションの順序

sf-metadata → sf-apex → sf-flow → sf-ai-agentforce → sf-deploy

必須の委任先

要件	委任先	理由
Flow の作成／修正	sf-flow	アクションターゲットの作成と Flow の検証
Apex アクションの作成／修正	sf-apex	@InvocableMethod と Apex の正確性
デプロイ／公開	sf-deploy	デプロイのオーケストレーション
エージェントのテスト	sf-ai-agentforce-testing	正式なテスト実行とアサーション
Employee Agent の表示／アクセス	sf-permissions	Permission Set の <agentAccesses> 設定

---

発生率の高い失敗パターン

症状	考えられる原因	次に読む項目
Builder でアクションを使用できない	ターゲットのメタデータがない、またはデプロイされていない	references/metadata-reference.md
公開中または有効化中にプロンプトアクションが失敗する	テンプレートが Draft である、入力項目がない、または古い形式のメタデータが使われている	references/genaiprompttemplate.md
テンプレートの入力項目が 5 個を超える	フレックステンプレートの入力項目数の上限に達している	references/genaiprompttemplate.md
Apex の AI ロジックがタイムアウトする	Models API の処理を誤ったコンテキストに配置している	references/models-api.md
リッチな入出力 UI が表示されない	Lightning の型設定または前提条件が不完全である	references/custom-lightning-types.md
エージェントは公開されたが使用できない	明示的な有効化を忘れている	references/cli-commands.md
Service Agent の公開／実行時に失敗する	実行ユーザーがない、または無効である	../sf-ai-agentscript/references/agent-user-setup.md
Employee Agent は有効だが、ユーザーに表示されない	<agentAccesses> 権限セットがない	../sf-permissions/references/agent-access-guide.md

---

リファレンスマップ

まずはこちら

• references/builder-workflow.md
• references/metadata-reference.md
• references/genaiprompttemplate.md
• references/cli-commands.md

用語とテンプレートの計画

• references/prompt-templates.md
• references/models-api.md
• references/custom-lightning-types.md

評価基準

• references/scoring-rubric.md

関連スキル

• sf-ai-agentscript
• sf-ai-agentforce-testing
• sf-flow
• sf-apex
• sf-permissions
• sf-deploy

---

スコアガイド

スコア	意味
90+	デプロイの準備完了
80–89	良好。軽微な整理のみ必要
70–79	デプロイ前にレビューが必要
60–69	改善が必要
< 60	デプロイをブロック

評価基準の全文：references/scoring-rubric.md