sf-agentforce

Name: sf-agentforce
Author: clientell-ai

github.com/clientell-aiエージェントワークフロー2091 回インストール32 週間前に更新

リポジトリ

sf-agentforce について

sf-agentforceは、Salesforce Agentforceの開発・運用ガイドです。トピックやアクションの設計、決定論的なAgent Scripts、テスト、デプロイ、可観測性を扱います。

主な機能

01トピック設計とリクエストの振り分け
02Flow、Apex、プロンプトアクションの設定
03Agent Scriptsによる決定論的なエージェント構築
04エージェントの検証、公開、有効化、テスト
05セッションとエージェントイベントの監視

活用シーン

01トピックの範囲とアクションの境界を設計
02規制対象の業務向けに再現可能なエージェントを構築
03複数ターンの会話とルーティングをテスト
04セッションデータから本番環境の動作を調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/clientell-ai/salesforce-skills --skill sf-agentforce

インストール後、Claude Code で/sf-agentforceを入力して読み込まれたか確認します。

同梱ファイルreferences/agentforce-reference.md

詳細

Agentforce 開発ガイド

Salesforce Agentforce のスペシャリストとして、Salesforce のベストプラクティスに従って、本番環境に対応した自律型および決定論型のエージェントを構築します。すべての Agentforce 機能で API バージョン 66.0 を使用します。

エージェントの設定

エージェントの作成

エージェントは 設定 > Agentforce > エージェント またはメタデータのデプロイを通じて作成します。

エージェントの種類は 2 つあります。

エージェントの種類	API 名	用途
サービスエージェント	`AgentforceServiceAgent`	顧客向け。Agent User として実行され、チャネルにデプロイされます
従業員エージェント	`AgentforceEmployeeAgent`	社内向け。ログインユーザーとして実行され、アプリに組み込まれます

エージェントユーザーの設定（サービスエージェントのみ）

サービスエージェントには、専用の Einstein エージェントユーザーが必要です。

Salesforce Integration ライセンスを持つユーザーを作成します
AgentforceServiceAgent 権限セットを割り当てます
エージェントに必要なオブジェクトおよび項目の権限を、権限セットを通じて付与します
エージェント設定で default_agent_user として設定します

従業員エージェントはログインユーザーとして実行されるため、専用のエージェントユーザーは必要ありません。

チャネルの設定

エージェントは次のチャネルにデプロイできます。

メッセージングチャネル（Web チャット、SMS、WhatsApp）
Embedded Service デプロイメント（Lightning Web Runtime）
Slack（従業員エージェント）
API（プログラムからアクセスするための Agent Runtime API）

チャネルは 設定 > メッセージング設定 または Embedded Service デプロイメントで設定します。

トピック

トピックは、エージェントが対応できる範囲を定義します。各トピックは、独自の指示、アクション、範囲の境界を持つ論理ドメインです。

トピック設計の原則

具体的な範囲：各トピックには、明確で重複しないドメインを設定します
自然言語による説明：説明はルーティングのシグナルです。プランナーはこれを使ってユーザーの発話を照合します
焦点を絞った指示：このトピック内でのエージェントの振る舞いを指定します
範囲を限定したアクション：トピックに関連するアクションのみを割り当てます

トピックの構成

トピックは次の要素で構成されます。

ラベルと API 名：人が理解しやすい名前と開発者向けの参照名
説明：このトピックが扱う内容を自然言語で説明します（ルーティングを左右します）
範囲：対象範囲と対象外の範囲を明示的に定義します
指示：このトピック内でのエージェントの振る舞いを、段階的に案内します
アクション：このトピックが有効なときにエージェントが利用できるツール

トピックのルーティング

プランナーは、次の要素に基づいてユーザーの発話をトピックに照合します。

トピックの説明と発話の類似度
範囲の定義（対象範囲と対象外の範囲）
指示のコンテキスト

兄弟トピック間で範囲が重複しないようにしてください。2 つのトピックが同じ発話に一致する可能性がある場合、プランナーが誤ったルーティングを行うことがあります。範囲の境界を明示してください。

In scope: Order status inquiries, order tracking, delivery estimates
Out of scope: Order creation, order cancellation (handled by Order Management topic)

エージェントアクション

アクションは、エージェントが呼び出せるツールです。各アクションは、対象となる実装をラップします。

アクションの種類

アクションの種類	対象	最適な用途	登録方法
Flow アクション	Screen Flow または Autolaunched Flow	宣言型ロジック、ガイド付きインタラクション、複数ステップのプロセス	`GenAiFunction`
Apex アクション	`@InvocableMethod` クラス	複雑なビジネスロジック、コールアウト、計算	`GenAiFunction`
PromptTemplate アクション	PromptTemplate メタデータ	生成テキスト、要約、推奨事項、下書き	`GenAiFunction`
外部サービスアクション	外部サービスの登録	OpenAPI 仕様を介したサードパーティ API 呼び出し	`GenAiFunction`

各アクションの使いどころ

Flow：デフォルトの選択肢です。最も安全で保守しやすく、ガイド付きのユーザーインタラクションをサポートします
Apex：複雑なロジック、外部コールアウト、カスタムのデータ処理が必要な場合に使用します
PromptTemplate：出力が生成テキスト（要約、メール、推奨事項）の場合に使用します
外部サービス：外部サービスを通じて登録された外部 API を呼び出す場合に使用します

アクションの設定

各アクションには次の項目が必要です。

機能の説明：エージェントがこのアクションを実行するタイミングを自然言語で説明します
入力パラメーター：会話のコンテキストまたはユーザー入力からマッピングします
出力パラメーター：応答の生成に使用するため、エージェントに返されます

入力／出力パラメーター名は、対象のコントラクトと完全に一致する必要があります。

Flows の場合：Flow の入出力変数の API 名と一致させます
Apex の場合：@InvocableVariable フィールド名と一致させます
PromptTemplates の場合：テンプレートの入出力変数名と一致させます

GenAiPlugin を使ったアクションのグループ化

関連する GenAiFunction エントリを GenAiPlugin にまとめ、論理的に整理します。プラグインは機能ドメインを表します（たとえば、「注文管理」に検索、ステータス確認、キャンセルの各アクションを含めます）。

PromptTemplate

PromptTemplate のメタデータでは、エージェントのグラウンディング、テキスト生成、構造化された応答のために再利用可能なプロンプト設定を定義します。

テンプレートの種類

種類	使用例
`einstein_gpt__fieldCompletion`	単一フィールドの生成
`einstein_gpt__salesEmail`	メールの下書き
`einstein_gpt__flex`	汎用のフレックステンプレート
`einstein_gpt__chat`	会話型エージェントのグラウンディング

テンプレートの構成要素

入力変数：テンプレートに渡されるデータ（レコードのフィールド、ユーザー入力、コンテキスト）
出力変数：生成された結果
解決ステップ：順序付けされたプロンプトの断片、グラウンディングデータ、指示
モデル設定：使用するモデルとパラメーター

エージェントアクションとしての PromptTemplate

エージェントアクションとして使用する場合：

PromptTemplate のメタデータを作成します
テンプレートを有効化します（ドラフト状態のテンプレートは公開エラーの原因になります）
GenAiFunction として登録します
トピックに追加します
会話のコンテキストから入力をマッピングします

Models API との統合

PromptTemplates 以外でカスタムモデルルーティングを行うには、Apex から Models API を使用します。

public with sharing class ModelService {
    @InvocableMethod(label='Generate Summary')
    public static List<String> generateSummary(List<String> inputs) {
        ConnectApi.EinsteinLlmGenerateParams params =
            new ConnectApi.EinsteinLlmGenerateParams();
        params.promptTextorId = 'Summarize: ' + inputs[0];
        ConnectApi.EinsteinLlmGenerationOutput output =
            ConnectApi.EinsteinAI.generateMessages(params);
        return new List<String>{ output.generatedMessages[0].text };
    }
}

エージェントスクリプト（決定論的エージェント）

エージェントスクリプトは、決定論的エージェントを構築するためのコードファーストで FSM ベースのアプローチを提供します。宣言型 DSL を使用する .agent ファイルを使用します。

エージェントスクリプトと設定 UI の使い分け

基準	エージェントスクリプト	設定 UI ／ Agent Builder
ルーティング制御	決定論的（状態マシン）	LLM による制御（プランナー）
バージョン管理	ソース内の `.agent` ファイル	組織から取得したメタデータ XML
再現性	毎回同一の動作	プランナーの解釈によって変わる場合があります
複雑さの上限	高い（FSM ＋ガード＋遷移）	中程度（トピック＋アクション）
最適な用途	厳格なコンプライアンスフロー、規制対象のプロセス	一般的なカスタマーサービス、柔軟な質疑応答

エージェントスクリプトの DSL 構造

config:
  developer_name: MyServiceAgent
  master_label: My Service Agent
  agent_description: Handles customer service inquiries
  agent_type: AgentforceServiceAgent
  default_agent_user: [email protected]

variables:
  caseNumber:
    type: string
    description: The case number provided by the customer
  customerVerified:
    type: boolean
    description: Whether the customer has been verified
    default: False

system:
  greeting: Hello! I am your service agent. How can I help you today?

start_agent:
  topic: Greeting

topic: Greeting
  description: Initial greeting and intent identification
  instructions: ->
    Greet the customer and ask how you can help.
    Identify their intent and route to the appropriate topic.
  actions:
    identifyIntent:
      target: flow://Identify_Customer_Intent
      inputs:
        utterance: $input
      outputs:
        detectedIntent: intent
  transitions:
    - when: detectedIntent == "case_status"
      go_to: CaseStatus
    - when: detectedIntent == "new_case"
      go_to: NewCase

DSL の主なルール

ファイルごとに start_agent ブロックを必ず 1 つだけ記述します
タブとスペースを混在させないでください。どちらかを選び、一貫して使用します
ブール値：True ／ False（先頭を大文字にします）
else if は使用できません。個別の条件または遷移を使用します
if ブロックをネストできません
linked 変数にはデフォルト値を設定できず、object ／ list 型も使用できません
指示内でアクションを参照する場合は、@actions. プレフィックスを使用します
run @actions.X を使用できるのは、target: 定義のあるトピックレベルのアクションだけです

エージェントスクリプト CLI

# Validate an agent script
sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Publish an agent script
sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Activate the agent
sf agent activate --api-name MyAgent -o TARGET_ORG

公開しても有効化されません。必ず別途 sf agent activate を実行してください。

メタデータ構造

Agentforce の主なメタデータ型は次のとおりです。

メタデータ型	ファイル拡張子	用途
Bot	`.agent-meta.xml`	エージェントの定義、バージョン、コンテキスト変数
GenAiTopic	`.agentTopic-meta.xml`	説明、範囲、指示、アクションを含むトピック
GenAiFunction	`.genAiFunction-meta.xml`	Flow、Apex、または PromptTemplate のターゲットをラップする単一のアクション
GenAiPlugin	`.genAiPlugin-meta.xml`	関連する GenAiFunction を論理的にグループ化
PromptTemplate	`.promptTemplate-meta.xml`	入力、出力、モデル設定を含むプロンプト構成

各 GenAiFunction では、次の項目を指定する必要があります。

targetType（Flow、Apex、PromptTemplate、ExternalService）
targetName（ターゲットの API 名）
capabilityDescription（エージェントがこのアクションを使用すべき状況）
inputs と outputs（ターゲットのコントラクトと完全に一致する名前）

すべてのメタデータ型の完全な XML テンプレート：references/agentforce-reference.md

エージェントのテスト

Agentforce Testing Center

Testing Center（Setup > Agentforce > Testing Center）では、複数ターンの会話を検証する UI ベースのテストを実施できます。

CLI テストコマンド

sf agent test run --api-name MyAgent -o TARGET_ORG --json
sf agent test run --spec-file tests/order-status.yaml -o TARGET_ORG --json
sf agent test results --test-run-id 0Atxx0000000001 -o TARGET_ORG --json

テスト仕様の YAML 形式と複数ターンの例：references/agentforce-reference.md

テストカバレッジのカテゴリ

テストで次の項目を網羅してください。

トピックのルーティング：各発話に対して正しいトピックが一致すること
アクションの呼び出し：期待されるアクションが正しいパラメーターで呼び出されること
コンテキストの保持：複数ターンの会話で状態が維持されること
ガードレール：範囲外、有害、または対象範囲外の入力が適切に処理されること
エスカレーション：適切な場合にエージェントが人間に引き継ぐこと
表現のバリエーション：同じ質問を複数の方法で尋ねること

テストと修正のループ

テストを実行し、失敗を記録します
失敗を分類します（トピックの不一致、アクションの失敗、コンテキストの喪失、ガードレールの失敗）
エージェントを修正します（トピックの説明、アクション設定、指示）
再公開して、再度有効化します
全体の回帰テストを行う前に、対象を絞ったテストを再実行します

エージェントのオブザーバビリティ

Session Tracing Data Model（STDM）と EventLogFile を使用して、本番環境でのエージェントの動作を監視します。

Session Tracing Data Model（STDM）

STDM は、すべてのエージェントセッションについて、セッション、インタラクション（ターン）、インタラクションステップ、モーメント、メッセージからなる構造化テレメトリを取得します。Setup > Einstein AI > Session Tracing でトレースを有効にします。データは分析のために Data Cloud に送られます。

主な STDM エンティティは Session、Interaction、InteractionStep、Moment、Message です。各インタラクションは、1 回のユーザーターンと、エージェントによる応答の流れ（トピックの一致、アクションの呼び出し、LLM の呼び出し）に対応します。

セッションのトランスクリプト

Agent Runtime API または Data Cloud を通じてセッションのトランスクリプトをクエリします。トランスクリプトを使用して、トピックのルーティング失敗をデバッグし、アクションのパラメーターを調べ、ターンをまたいでコンテキストが保持されていることを確認します。

エージェントイベントの EventLogFile

EventLogFile は、エージェント関連のプラットフォームイベントを取得します。次の方法でクエリします。

SELECT Id, EventType, LogDate, LogFileLength
FROM EventLogFile
WHERE EventType IN ('AIInteraction', 'AIInsightAction')
ORDER BY LogDate DESC

EventLogFile のデータを使用して、呼び出し回数、エラー率、レイテンシの傾向を集計し、監視します。

エージェントのペルソナ設計

声の属性を定義し、エージェントの設定に組み込むことで、一貫したエージェントの個性を設計します。

声の属性

文体（フォーマルからカジュアル）、親しみやすさ（中立から共感的）、簡潔さ（簡潔から詳細）、ユーモア（なしから控えめ）を定義します。これらをブランドガイドラインと対象ユーザーの期待に合わせます。

ペルソナのシステム指示

エージェントのシステム指示、またはトピックレベルの指示にペルソナを組み込みます。アイデンティティの宣言、口調の指示、フレーズ集（推奨する表現）、使用禁止リスト（禁止する表現やトピック）を含めます。指示は具体的で、テスト可能なものにします。

ペルソナのガードレール

トーンの境界を定義します。ユーザーが不満を感じている場合と、順調に進んでいる会話の場合で、エージェントがどのようにトーンを調整するかを定めます。厳格な制限（スラングを使わない、予定時期を約束しない）と、緩やかなガイドライン（能動態を優先する、顧客の名前を使う）を設定します。

GenAI Models API

Models API は、ConnectApi.EinsteinAI.generateMessages() を介して Apex から LLM にプログラムでアクセスできるようにします。すべての呼び出しは、Einstein Trust Layer（プロンプト防御、有害性の検出、PII のマスキング、監査証跡、データグラウンディング、データのゼロ保持）によって自動的に保護されます。

Setup > Einstein AI > Model Management でモデルのルーティングを設定します。テンプレートごとにモデルを選択するには、PromptTemplate レベルで上書きします。

Apex の使用例と Trust Layer の詳細については、references/agentforce-reference.md を参照してください。

注意事項

Agent User ライセンス

Service Agents には Einstein Agent User ライセンスが必要です。このライセンスがなくても公開は成功しますが、エージェントは実行時にアクションを実行できません。ユーザーに AgentforceServiceAgent 権限セットがあることを確認してください。

トピックのスコープの重複

トピックの説明が重複していると、ルーティングが曖昧になります。プランナーが誤ったトピックに一致させたり、トピック間を行き来したりする可能性があります。スコープの境界を明確にし、重複しないようにして解決します。

アクションのパラメーターのマッピング

GenAiFunction の入力／出力パラメーター名は、対象のコントラクトと完全に一致させる必要があります。名前が一致しないと、アクションは呼び出されるものの、入力が null となるサイレントフェイラーが発生します。

PromptTemplate のドラフトステータス

PromptTemplate が Draft ステータスの場合、エージェントの公開時に invalid input/output parameters エラーが発生します。エージェントを公開する前に、必ずテンプレートを有効化してください。

API バージョン要件

Agentforce の機能には API バージョン 66.0 以降が必要です。それより低い API バージョンでデプロイされたメタデータは、拒否されるか無視されます。

公開と有効化

エージェントを公開しても、有効化はされません。sf agent publish の実行後、別途 sf agent activate を実行する必要があります。この手順を忘れると、エージェントはデプロイされてもアクセスできません。

Agent Script の構文上の注意点

else if はサポートされていません。個別の条件を使用してください
if ブロックのネストは許可されていません
linked 変数にデフォルト値を設定することはできません
ブール値は True／False（大文字と小文字を区別）でなければなりません
最上位の actions: ブロックは無効です。アクションはトピック内に配置してください

デプロイ順序が重要

エージェントより先に、サポート対象のメタデータをデプロイする必要があります。

カスタムオブジェクト／項目
Apex クラス（InvocableMethod）
Flow
PromptTemplate（有効化も行います）
GenAiFunction ／ GenAiPlugin
エージェントのメタデータ
公開してから有効化

テストカバレッジ

Apex とは異なり、エージェントにはテスト率の最低要件がありませんが、テストされていないエージェントにはリスクがあります。最低限、各トピック、各アクション、トピック外の入力への対応、エスカレーション経路をカバーしてください。

ワークフロー

エージェント開発のステップ

エージェントの目的を定義する：サービスエージェントと従業員エージェントのどちらに該当するかを特定します。チャネルとユースケースを決定します。
トピックを設計する：会話の領域を整理します。各トピックは明確な範囲を持つ、区別されたものにします。
作成方法を選択する：
- 設定 UI／Agent Builder：宣言型で、LLM の指示に従うエージェント向け
- Agent Script DSL：決定論的で、ステートマシン駆動型のエージェント向け
サポートコンポーネントを構築する：
- 宣言型アクション用にフローを作成します
- 複雑なロジック用に Apex @InvocableMethod クラスを作成します
- 生成コンテンツ用に PromptTemplates を作成します
- サードパーティ API 用に External Services を登録します
アクションを設定する：各アクションの GenAiFunction メタデータを作成します。入出力マッピングが対象と完全に一致していることを確認します。
トピックをアクションに接続する：アクションをトピックに紐付けます。プランナーが各アクションを呼び出すタイミングを把握できるよう、機能の説明を明確に記述します。
メタデータをデプロイする：依存関係の順序（オブジェクト、Apex、フロー、テンプレート、関数、エージェント）でデプロイします。

公開して有効化する：

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

テストする：トピックのルーティング、アクションの呼び出し、ガードレール、複数ターンにわたるコンテキストを網羅するテスト仕様を実行します。
反復する：失敗を修正し、再公開、再有効化、再テストします。

レビューチェックリスト

Agentforce エージェントをレビューする際は、以下を確認してください。

エージェントの種類がユースケースに適している（サービス向けか従業員向けか）
サービスエージェントに有効な Einstein Agent User が設定されている
トピックの説明が具体的で、互いに重複していない
各トピックの範囲が明示的に定義されている
アクションの機能の説明に、呼び出し条件が明確に記載されている
入出力パラメーター名が対象の契約と一致している
PromptTemplates のステータスが「Active」になっている
デプロイの順序が正しい（依存関係をエージェントより先にデプロイしている）
エージェントが公開済みで、有効化もされている
すべてのトピック、アクション、ガードレール、エスカレーション経路をテストで網羅している

参考資料

Agentforce リファレンス — メタデータテンプレート、Agent Script DSL、テスト仕様、パターン、Trust Layer、デバッグ

Markdown 対応

ログインしてコメント

基本情報

作者: clientell-ai
リポジトリ: clientell-ai/salesforce-skills
カテゴリ: エージェントワークフロー
インストール数: 91
GitHub スター: 20

問題を報告