入門編を読んだ後、「Agent Scriptが必要だ」と思っていただけたでしょうか？
本編ではその危機感を行動へ変えるために、以下の視点で学習を進めます。
理解ではなく実装：概念解説は必要最小限に抑え、とにかく動くコードを提示します。
・ユースケースごとに分割：1つのトピック＝1つの用途として切り出し、それぞれ独立してコピーできるようにします。
・失敗例→正解例：最初にありがちな失敗例を示し、次に正しい書き方を示すことで、なぜその記述が必要なのか理解できます。
・Salesforce文脈への寄せ：Permission Setの設定やFlow呼び出しなど、Salesforce特有の要素を扱うことで現場の再現性を高めます。
- 1. ユースケース1：本人確認と注文確認
- 2. ユースケース2：アクション順序の保証
- 3. ユースケース3：トピックルーティングの制御
- 4. ベータ版の制約と開発ベストプラクティス（概要）
- 5. ベータ版の制約を考慮した条件分岐
- 6. available whenでツール公開条件を制御する
- 7. Setup with Agentforceと権限設定の実装
- 8. GraphQL・Flow連携の活用
- 9. 開発フローとベストプラクティス
- 10. アンチパターンと回避策
- 11. ユースケース: 返品処理フローの実装
- 12. まとめと実践へのアクションプラン
- 13. ユースケース: 権限付与フロー
- 14. おわりに
- 15. お問い合わせ
この記事で使う環境
- Salesforce Org：Spring ’26 以降を想定（Agent Script Beta対応）
- Agentforce Builder：CanvasビューとScriptビューの両方が利用可能。Scriptを直接編集する場合はローカル環境でYAMLファイルを編集しデプロイします。
- 権限設定：Permission Setで“Agentforce User”、“Einstein Agent Script User”などの権限を付与しておくと、実装とテストがスムーズに行えます。
これら前提が整っていない場合でもサンプルコードはそのまま理解できるので、読み進めながら環境を準備してください。
ユースケース1：本人確認と注文確認
概要と手順
ユーザーからの問い合わせで最も多いのは注文情報の確認です。ここでは本人確認を行わずに情報を提供してしまう失敗例を示し、その後で必ず本人確認を実施する正解例を紹介します。以下の手順で設計します。
- ユーザー入力を受け取り「注文確認」かどうかを判定する（
start_agent）。 - 「注文確認」であれば
OrderInfoトピックに遷移し、初めに本人確認を行う。 - 本人確認が成功したら
get_ordersアクションで注文情報を取得し、適切な文言で応答する。 - 本人確認に失敗した場合はエラーメッセージを返し、処理を終了する。
失敗例（本人確認を忘れる）
以下は注文情報を取得する際に本人確認をしない失敗例です。LLMにプロンプトだけで指示しているため、文脈によっては本人確認を省略してしまい、個人情報を漏らす危険があります。
system:
instructions: "You are an agent that provides order information."
variables:
orderId:
type: string
topics:
start_agent:
-> transition to OrderInfo
OrderInfo:
-> run @actions.get_orders
| Here is your order information: {!orders}
このスクリプトではユーザーの本人確認をせずにget_ordersアクションを実行しています。そのため、LLMが意図的に本人確認を行わなければ、誰でも注文情報を取得できてしまう状態です。
正解例（本人確認を必須にする）
次のコードでは、変数isVerifiedを用いて本人確認を実施します。本人確認用のアクションverify_userを最初に実行し、確認が成功した場合のみ注文情報を取得します。
system:
instructions: "You are an agent that provides order information only after verifying the user."
variables:
isVerified:
type: boolean
default: false
orderId:
type: string
topics:
start_agent:
-> if @system_variables.user_input contains "注文"
-> transition to OrderInfo
OrderInfo:
-> if not variables.isVerified
-> run @actions.verify_user
-> variables.isVerified = true
-> run @actions.get_orders
| ご本人確認が完了しました。こちらがご注文の情報です：{!orders}
この正解例ではvariables.isVerifiedがfalseの場合のみverify_userアクションを実行し、確認が完了するとtrueに更新します。その後にget_ordersを呼び出すことで、必ず本人確認を通過したユーザーだけが情報を閲覧できます。状態変数で検証結果を管理する点がポイントです。
解説
失敗例ではLLMの挙動に依存しており、プロンプトを変更したり会話が長引くと本人確認を飛ばしてしまうことがあります。正解例では変数を使って状態を保持し、if文とtransitionによってフローを明示的に制御しています。これにより、決定論的な制御とLLMによる自然言語応答のハイブリッドを実現しています。また、アクションはrun命令で実行されるため、順序通りに処理されます。
Salesforce Tips:
verify_userアクションは認証サービス（例：Salesforce AuthenticatorやSMS認証）と連携していることを想定します。組織で既にユーザー認証フローが存在する場合は、FlowやApexを呼び出すアクションに置き換えることでセキュアな本人確認が行えます。Permission Setでユーザーに必要な権限が付与されているかも必ず確認してください。
ユースケース2：アクション順序の保証
概要と手順
LLMに指示を与えるだけでは、複数のアクションが必ずしも意図した順番で実行されないことがあります。本ユースケースでは、アクションの順序が入れ替わる失敗例を示し、run命令を使って順序を保証する方法を示します。
- ユーザーから「返品したい」と入力された場合に返品フローへ遷移する。
- フロー内で「キャンセル」「返金」「確認メール送信」の3つのアクションを順番に実行する。
- 各アクションの結果をチェックしながら次のアクションに進むように記述する。
失敗例（順序が保証されない）
topics:
start_agent:
-> transition to Return
Return:
| 注文をキャンセルし、返金処理を行い、確認メールを送ってください。
-> run @actions.cancel_order
-> run @actions.refund
-> run @actions.send_confirmation
このコードでは、プロンプトとアクションを混在させているため、LLMが文脈を誤解し、send_confirmationを先に実行してしまう場合があります。また、run命令を連続して書いているものの、プロンプト行の先頭に|があるため、LLMが指示を優先してしまうケースもあります。
正解例（順序を強制する）
順序を保証するには、アクションをすべてrunで明示し、プロンプトを最後に記述します。加えて、各アクションの完了を次のアクションのトリガーとして明示できます。
topics:
start_agent:
-> transition to Return
Return:
-> run @actions.cancel_order
-> run @actions.refund
-> run @actions.send_confirmation
| ご注文のキャンセルと返金が完了し、確認メールを送信しました。
この構造ではアクションが上から順番に確実に実行されます。|で始まるプロンプト行はすべてのアクションが終了した後に実行され、ユーザーに結果を通知します。Beta版ではrunで複数のアクションを並べると順次実行されることが保証されており、アクションが戻り値を返す場合は変数に格納して次のロジックで利用することもできます。
解説
失敗例のようにプロンプトとアクションを混在させると、LLMは「自然言語の指示」を優先しがちです。run命令はあくまでプログラム的に実行されますが、プロンプトに列挙されているタスクをAIが独自に解釈して順序を変えてしまうことがあります。正解例ではプロンプトを後ろに移動し、アクションをrunで連続して並べることでLLMの介入を最小化しています。
Salesforce Tips:
cancel_orderやrefundアクションはそれぞれApexやFlowで実装されることが多いです。Apexクラスでは同名のメソッドを作成し、@invocableMethodアノテーションを付けてFlowから呼び出せるようにするのが一般的です。また、返金処理には適切な権限が必要なので、関連するPermission Setを利用者に付与しておきましょう。
ユースケース3：トピックルーティングの制御
概要と手順
Agent Scriptでは複数のトピックを定義し、ユーザーの要求に応じて遷移させます。このユースケースでは、ユーザーの意図に合わないトピックに遷移してしまう失敗例を示し、available whenやtransitionを使って適切に制御する方法を学びます。
start_agentでユーザー入力を解析し、注文確認、返品、サポートの3つのトピックに分岐する。- 各トピックにはそれぞれ専用のアクションと応答を定義する。
- 特定の状況下ではトピックを無効化したり、遷移を制御するために
available whenを使用する。
失敗例（意図しないトピックに遷移）
topics:
start_agent:
-> if @system_variables.user_input contains "キャンセル"
-> transition to Cancel
-> transition to Support
Cancel:
| キャンセルの手続きをします。
Support:
| ご質問ありがとうございます。サポート担当者がお手伝いします。
このスクリプトでは「注文確認」に関する問い合わせがSupportに流れてしまいます。ユーザー入力の解析が不十分で、すべてのリクエストがSupportにフォールバックしているためです。さらに、「キャンセル」という文字列に部分一致する他の単語（例：キャンセルポリシー）が含まれると誤ってCancelトピックに遷移する可能性があります。
正解例（available whenで条件制御）
正しくルーティングするには条件を厳密に定義し、必要に応じてavailable whenでツールやトピックの有効・無効を切り替えます。
topics:
start_agent:
-> if @system_variables.user_input contains "注文"
-> transition to OrderView
-> if @system_variables.user_input contains "キャンセル"
-> transition to Cancel
-> transition to Support
OrderView:
available when: variables.isVerified == true
-> run @actions.get_orders
| ご注文内容はこちらです：{!orders}
Cancel:
-> run @actions.cancel_order
| キャンセル処理が完了しました。
Support:
| ご質問ありがとうございます。何をお手伝いできますか？
この例では、OrderViewトピックにavailable whenを付与し、本人確認が完了している場合のみ利用可能にしています。start_agentでは3つの条件を順に評価し、一致した場合のみ遷移します。これにより、誤ったトピックへのフォールバックを防止できます。
解説
失敗例ではフォールバック条件が曖昧で、ユーザーの意図を正しく解釈できませんでした。正解例ではstart_agentに複数のif文を配置し、順序と条件を明確に定義しています。また、available whenによってトピックの有効条件を指定することで、内部状態に依存したルーティングが可能になります。これにより、ユーザーの権限や操作状況に応じたトピック選択が実現できます。
Salesforce Tips: トピック毎に異なるPermissionを要求する場合、
available whenで参照する変数にユーザーのPermission情報を格納すると便利です。たとえば、権限オブジェクトを取得するApexアクションを用意し、結果を真偽値で保存しておくと、特定のトピックだけを許可する条件が簡潔に書けます。
ベータ版の制約と開発ベストプラクティス（概要）
ここまでで主要なユースケースを3つ紹介しました。後半ではさらに複雑なシナリオやメンテナンスのベストプラクティスを解説しますが、その前にベータ版の制約と開発時の注意点をまとめます。
else ifは未対応：条件分岐は単純なifを連続で使用する必要があります。- 演算は
+と-のみ：Beta版では乗算や割り算がサポートされていません。複雑な計算はApexやFlowに委譲しましょう。 - インデントと空行に厳格：YAMLライクな構文はインデントの深さが意味を持ちます。余分な空白行やコメントはエラーの原因になりやすいため、フォーマットを厳守しましょう。
- コメント記法：行コメントは
#で書きますが、ブロックコメントはサポートされていません。
開発フローのコツ: 最初はCanvasビューでフローを視覚的に作成し、動作を確認したらScriptビューへ切り替えてコードを編集するのがおすすめです。Agentforce Builderにはテストパネルがあり、ユースケースごとにテストデータを入力して動作を検証できます。また、変更をGitにコミットしてCI/CDパイプラインに統合することで、コードレビューや自動テストとの親和性が高まります。
ベータ版の制約を考慮した条件分岐
手順
- Agent Scriptはまだβ版であり、
else ifや複雑な演算はサポートされていません。条件分岐を設計する際は、単純なif命令の組み合わせと+/-のみの演算でロジックを組み立てます。- まず必要な条件を列挙し、優先順位を決めます。複数条件がある場合は順番にif命令を配置し、すべての条件が偽だった場合に備えて最後に
else命令でデフォルトの処理を定義します。- 演算が必要な場合はApexやFlowに処理を委任し、その結果を変数に格納します。Agent Script内ではその変数を参照して条件判断を行います。
失敗例: else ifを使ってしまう
# 条件Aが真なら処理1、条件Bが真なら処理2…を意図したが、else ifはβ版では使えない
-> if variables.score > 80
| 合格です
-> else if variables.score > 60
| 追試が必要です
-> else
| 不合格です正解例: ifを連続して使う
# 条件を順番に評価し、適切なプロンプトを出し分ける例
-> if variables.score > 80
| 合格です
-> if variables.score > 60 and variables.score <= 80
| 追試が必要です
-> else
| 不合格です解説
β版では
else ifが使えないため、条件を順に評価し、複雑な演算はApexやFlowに任せます。available whenでツール公開条件を制御する
手順
reasoning.actionsで宣言したツールは、available when条件で公開タイミングを制御できます。- まず変数やユーザー属性を使って利用条件を定義し、必要に応じてアクションやツールを呼び出します。
- Setupの権限やライセンス情報を変数に読み込み、条件判定に利用します。
失敗例: 条件なしでツールを公開してしまう
reasoning.actions:
grantDiscount:
description: "割引を適用する"# どのユーザーでも割引が適用できてしまい、権限が無視されている
-> run grantDiscount正解例: 条件付きでツールを公開する
variables:
isPremiumUser: { type: boolean, default: false }reasoning.actions:
grantDiscount:
description: "割引を適用する"
available when: variables.isPremiumUser == true# isPremiumUserがtrueの時のみツールが呼び出される
-> if variables.isPremiumUser == true
-> run grantDiscount
| 割引を適用しました。
-> else
| プレミアム会員のみ割引を適用できます。解説
available whenを使えば条件を満たした場合のみツールを公開できます。変数に基づいて判定することで不適切な実行を防ぎ、安全に運用できます。Setup with Agentforceと権限設定の実装
手順
- Setup with Agentforce (Beta) を利用すると、ユーザー管理やオブジェクト作成などの管理タスクをエージェントに委任できます。
- 事前にEinstein Agent Userに必要な権限セットを付与し、Setupタスクが実行できるようにします。
- Agent Script内でSetupタスクを実行する際は必ずユーザーからの確認を求めるプロンプトを追加し、信頼レイヤーによるガードレールを強化します。
失敗例: 権限不足でタスクが失敗する
# ユーザー作成アクションを呼び出そうとしているが、Einstein Agent Userに必要な権限がない
-> run @actions.createUser(username="new.user@example.com")
| ユーザーを作成しました！正解例: 権限付与と確認を行う
# ApexクラスやSetupタスクの実行権限を事前に付与しておきます
# Agent Scriptでは、操作前に確認を求める
CreateUser:
-> | 新しいユーザーを作成します。続行してもよろしいですか？（はい / いいえ）
-> if @system_variables.user_input contains "はい"
-> run @actions.createUser(username="new.user@example.com", permissionSet="Standard User")
| ユーザーを作成しました。
-> else
| 処理をキャンセルしました。解説
Setupタスクはエージェントで実行できますが、事前に本人確認を挟み、必要な権限を付与して安全に実行します。
GraphQL・Flow連携の活用
手順
- Spring ’26リリースではGraphQL APIでmutation操作がサポートされ、LWCやAgent Scriptからレコード作成・更新ができるようになりました。
- GraphQLアクションを作成し、必要な入力パラメータを渡します。返り値を変数に格納し、会話に反映させます。
- Flow連携では、複雑なロジックや長時間処理をFlowに委任し、結果をAgent Scriptに返します。
失敗例: GraphQLの戻り値を変数に保存しない
-> run @actions.get_account_data_via_graphql(accountId=variables.accountId)
| アカウント名は{!variables.accountName}です。正解例: 戻り値を変数に保存して利用する
AccountLookup:
-> run @actions.get_account_data_via_graphql(accountId=variables.accountId)
-> variables.accountName = @actions.get_account_data_via_graphql.name
-> variables.oppCount = @actions.get_account_data_via_graphql.opportunityCount
| アカウント{!variables.accountName}には{!variables.oppCount}件の商談があります。解説
GraphQLで必要なデータを取得・更新でき、mutationを使えばレコード作成や更新も可能です。戻り値は変数に格納し、複雑な処理はFlowに任せましょう。
開発フローとベストプラクティス
手順
- 要件整理と変数設計: フローチャートを描き、目的や分岐条件、必要な変数と初期値を整理します。
- トピックとアクション設計: 1トピック1責務を守り、ApexやFlow、GraphQLをアクションとして定義します。
- 実装とテスト: CanvasとScript viewでスクリプトを作成し、Previewモードで正常系と異常系のテストを行います。
- 本番反映と監視: 検証後に本番へデプロイし、ログやモニタリングで挙動を監視します。
失敗例: テストせず本番投入する
# スクリプトを書いたらすぐに本番環境へデプロイしてしまう例
# エッジケースやエラー入力が検証されておらず、ユーザーが実行時にエラーに遭遇する正解例: Previewモードで徹底検証する
# StudioのPreviewで会話をシミュレーションし、変数の値や遷移ロジックを確認する。
# テストケース: 正常な入力、異常な入力、タイムアウト、権限不足など。
# 検証後に本番へデプロイする。解説
開発フローの順守とPreviewテストは高品質な実装の鍵です。テストしてから本番へ展開しましょう。
アンチパターンと回避策
手順
- プロンプト肥大化を避け、制御ロジックはロジック命令に切り出します。LLM依存を減らすことで挙動を安定させます。
- トピックを適切に分割し、1トピック1責務とエラー処理の追加を徹底します。
失敗例: 巨大なトピックに全処理を書き込む
OrderProcess:
-> if ...
-> run @actions.verify_user
-> run @actions.get_orders
-> run @actions.check_cancellable
| 遅延・キャンセル・問い合わせなど全ての文をここに書いている
# このトピックが肥大化し、条件分岐が読みづらくなっている正解例: トピックを細分化する
topics:
Identity:
# 本人確認
OrderView:
# 注文表示
CancelCheck:
# キャンセル可否の確認
Error:
# エラー応答
# 各トピックは明確な責務を持ち、遷移でつなぐ解説
プロンプトやトピックの肥大化を避け、処理を分割し変数で状態を管理しましょう。
ユースケース: 返品処理フローの実装
手順
- ユーザーが注文IDを入力し、返品理由を提供するステップを設計します。
- 返品可否をチェックするApexアクションを作成し、結果に応じて処理を分岐させます。
- 失敗パターンとして、本人確認を飛ばして返金を行おうとするケースを示し、正しいフローを提示します。
失敗例: 本人確認を省略する
ReturnRequest:
-> run @actions.check_returnable(orderId=variables.orderId)
-> if @actions.check_returnable.canReturn == true
-> run @actions.process_return(orderId=variables.orderId)
| 返金処理が完了しました。正解例: 本人確認を必須とする
ReturnFlow:
-> if not variables.isVerified
-> transition to Identity
-> run @actions.check_returnable(orderId=variables.orderId)
-> if @actions.check_returnable.canReturn == true
-> | 返品理由を入力してください。
-> variables.reason = @system_variables.user_input
-> run @actions.process_return(orderId=variables.orderId, reason=variables.reason)
| 返品処理が完了しました。
-> else
| 返品できない商品です。解説
返品フローでは本人確認と返品可否の判定が鍵です。変数で状態を管理し安全に実行します。
まとめと実践へのアクションプラン
Agent Script実装編の後半では、β版の制約を踏まえた条件分岐、ツール公開条件の制御、Setupタスクの扱い、GraphQL/Flow連携、開発フロー、アンチパターンの回避、返品フローなど高度なトピックを解説しました。ここまでの内容を踏まえ、以下のステップで実践に移してみてください。
- **β制約を適用**: else if非対応を考慮し、単純なif命令でロジックを組み立てる。
- **条件付きツール実装**: available whenでユーザー属性に応じた公開を制御する。
- **権限と確認の整備**: 権限セット付与とユーザー確認を徹底する。
- **GraphQL/Flow連携活用**: Mutationやフロー連携でデータ操作を効率化する。
- **開発と運用の徹底**: 設計・実装・テスト・デプロイを順守する。Agent Scriptはまだβ版ですが、適切な設計と実装により企業のAI活用を加速させる強力なツールです。この記事の手順とコードを参考に、自身のエージェントで実践し、より安定したAIエージェントの構築に役立ててください。
ユースケース: 権限付与フロー
IT 部門でよく行われる新入社員への Permission Set 付与をエージェントで自動化する例です。本人確認後に対象ユーザーのIDと付与する権限セット名を取得し、最終確認を経て権限付与を実行します。
手順
新入社員への Permission Set 付与作業をエージェントで自動化するユースケースです。本人確認後にユーザー名からIDを取得し、権限セット名を入力させ、最終確認後に付与します。
手順
- 本人確認を行い、ユーザー名からIDを取得する
- 権限セット名を入力させ、最終確認後に付与する
簡易コード
PermissionGrant:
-> if not variables.isVerified
-> transition to Identity
-> variables.userId = @actions.get_user_id(username=@system_variables.user_input).id
-> variables.permissionSet = @system_variables.user_input
-> | ユーザー{!variables.userId}に権限{!variables.permissionSet}を付与しますか？（はい / いいえ）
-> if @system_variables.user_input contains "はい"
-> run @actions.grant_permission(userId=variables.userId, permissionSet=variables.permissionSet)
| 付与しました。
-> else
| キャンセルしました。解説
本人確認と最終確認を挟むことで誤操作を防ぎます。Setup with Agentforceの権限管理と組み合わせることで、ガバナンスを保ちつつ自動化できます。
おわりに
Agent Scriptの実装は継続的な改善が必須です。SpringリリースやEinstein Trust Layerの更新を追いながらガイドラインを見直し、セキュリティと運用を向上させましょう。CanvasとScript viewを往復し、自社ユースケースに合わせてスクリプトを調整することが成功の鍵です。公式ドキュメントやコミュニティ事例を参考に、小さな実験を重ねて理解を深めてください。
お問い合わせ
現在Salesforceを効果的に活用できていない企業様や、これからSalesforceの導入を検討している企業様で、設定や運用、保守に関するサポートが必要な場合は、ぜひお気軽にご相談くださいませ！
