Salesforce Agentforceカスタムアクション：ApexとFlowの使い分け実装ガイド

どんな取り組みか
使われた技術スタック
実装のポイント
得られた成果や学び
まとめ

どんな取り組みか

この記事では、SalesforceのAgentforceにおけるカスタムアクションの実装方法について、ApexとFlowのどちらを選択すべきか、そしてApexで実装する場合の具体的な手順と注意点を解説します。Agentforceのカスタムアクションは、主にFlowかApexのどちらかで実装されますが、どちらを選ぶかによってできることと設計の方向性が変わります。

使われた技術スタック

Salesforce
Apex
Flow
Agentforce
@InvocableMethod
@InvocableVariable

実装のポイント

FlowとApexの使い分け

Flowが向いているケース:

レコードの作成・更新・参照など、SOQL/DMLを組み合わせた標準的な業務処理
ノーコード・ローコードで管理者が維持できる設計が望ましい場合
既存の自動起動フローをそのまま転用したい場合

Apexが向いているケース:

複雑な業務ロジックや複数オブジェクトをまたぐ処理
外部APIとの連携（コールアウトが必要な処理）
バルク処理や条件分岐が多く、Flowだと管理しにくくなる場合
既存のApexコードベースを活用したい場合

実務的な判断基準としては、「Flowで表現できる範囲なら迷わずFlow、Flowでは難しい業務ロジックならApex」が合っていると考えられます。

Apexクラスの実装： @InvocableMethod アノテーション

Agentforceのカスタムアクションとして登録するには、Apexメソッドに @InvocableMethod アノテーションをつけます。これにより、Agentforce Builderのアクション設定画面からこのメソッドを参照できるようになります。

以下は基本的な実装パターンです。


public with sharing class GetAccountSummaryAction {
    public class Input {
        @InvocableVariable(label='取引先名' description='検索する取引先の名前を指定してください' required=true)
        public String accountName;
    }

    public class Output {
        @InvocableVariable(label='取引先サマリー' description='取引先の概要情報')
        public String summary;
        @InvocableVariable(label='エラーメッセージ' description='処理中にエラーが発生した場合のメッセージ')
        public String errorMessage;
    }

    @InvocableMethod( label='取引先サマリーを取得' description='指定した取引先名で取引先を検索し、業種・年間売上・所在地をサマリー形式で返します' )
    public static List getAccountSummary(List inputs) {
        List outputs = new List();
        for (Input input : inputs) {
            Output output = new Output();
            try {
                List accounts = [ SELECT Name, Industry, AnnualRevenue, BillingCity FROM Account WHERE Name LIKE :('%' + input.accountName + '%') WITH USER_MODE LIMIT 1 ];
                if (accounts.isEmpty()) {
                    output.summary = '該当する取引先が見つかりませんでした。';
                } else {
                    Account acc = accounts[0];
                    output.summary = acc.Name + ' / 業種：' + acc.Industry + ' / 年間売上：' + acc.AnnualRevenue + ' / 所在地：' + acc.BillingCity;
                }
            } catch (Exception e) {
                output.errorMessage = 'エラーが発生しました。管理者にお問い合わせください。詳細：' + e.getMessage();
            }
            outputs.add(output);
        }
        return outputs;
    }
}

コードのポイント:

@InvocableMethod の label と description は、Atlas Reasoning Engineがアクションを「いつ使うべきか」を判断する根拠となるため、具体的に記述することが重要です。
入力変数と出力変数はそれぞれ専用のクラス（Input・Output）を作り、@InvocableVariable アノテーションで定義します。label、description、required=true 属性が重要です。
セキュリティのため、SOQLには WITH USER_MODE を指定し、クラスには with sharing キーワードを使用します。
バルク処理設計（List<Input> と List<Output>）を意識します。

Agentforce Builderへの登録手順

Apexクラスが準備できたら、Agentforce Builderでカスタムアクション（ツール）として登録します。推奨される方法は、Agentforce Builderのサブエージェント内から作成する方法です。

設定のクイック検索で「Agentforce スタジオ」を検索して開く。
対象のエージェントを開き「Builderで開く」をクリック。
左パネル（エクスプローラー）から対象のサブエージェントを選択。
「ツール」横の「＋」ボタンをクリックし、「新しいツールを作成」を選択。
ツール名を入力し「作成して開く」をクリック。
「参照ツール種別」で「Apex」を選択。
「参照ツール」から作成したApexクラスを選択。
ラベル・手順・入出力変数の設定を確認して「保存」。

アセットライブラリから登録すると、複数のエージェントやサブエージェントで同じアクションを再利用でき、保守コストを下げることができます。

登録後の設定確認ポイント

手順（Instructions）：このツールをいつ実行すべきかをエージェントが理解するための説明文を記述します。
入力変数の「手順」：エージェントが各変数に何を渡せばいいかの説明を記述します。
入力変数の「入力が必要」チェックボックス：必須変数にはチェックを入れておきます。
出力変数の「会話に表示」チェックボックス：ユーザーに表示したい出力変数にはチェックを入れます。

つまずきポイント・注意事項

@InvocableMethod の label と description、およびアクション設定の label・手順 の同期を確認してください。
アクションがAgentforce Builderの選択肢に表示されない場合は、@InvocableMethod アノテーションの有無、クラスの public スコープ、Apexクラスのコンパイルエラー、エディション要件を確認してください。
サブエージェントの指示内でのツール名は、表示名ではなくAPI名（スペースをアンダースコアに置き換えた形）で記述すると認識されやすいです。
CPU時間制限・Governor Limitsに注意し、処理が重い場合はロジックの分割や非同期処理への移行を検討してください。

得られた成果や学び

@InvocableMethod アノテーションをつけたApexクラスを作成することで、Agentforceのカスタムアクション（ツール）として登録できます。label と description の記述は、Atlas Reasoning Engineのルーティング精度に直結します。入出力変数は @InvocableVariable で定義し、required=true と「会話に表示」チェックボックスの設定を忘れないようにします。セキュリティとパフォーマンスを考慮した実装が基本となります。ApexコードをAgentforceのアクションに繋げることで、既存のSalesforce開発スキルをAIエージェントの拡張に活かすことができます。

まとめ

AgentforceのカスタムアクションをApexで実装する際には、Flowとの使い分け基準を理解し、@InvocableMethod アノテーションを活用してApexクラスを作成します。Agentforce Builderへの登録手順や、label・description の重要性、入出力変数の設定、セキュリティ、パフォーマンスに関する注意点を把握することが、精度の高いアクション開発に繋がります。これにより、既存のSalesforce開発スキルをAIエージェントの拡張に効果的に活用することが可能になります。

出典: https://qiita.com/ubakichi_sr_mc_ai_06/items/e75531176c3c4b1a3620

Related Certifications