AgentScriptでAgentforceを構築してみた

みなさんはAgentScriptをご存じでしょうか。AgentScriptとは、新たなAgentforceBuilderで使用できる、Agentforceを構築するためのプログラミング言語のようなものです。
以下の画面が実際のビルダーの画面となっています。

本稿では、AgentScriptについて、どのような構成となっているのかを説明したうえで、実際に簡単なAgentforceを構築し、使用するまでの流れをご説明します。

現状、従来のテキストベースのAgentforceBuilderと、AgentScriptを使用した新しいAgentforceBuilderは使用場所が異なります。
従来のテキストベースのビルダーは[設定]>[Agentforce エージェント]からAgentforceを新規作成する際に使用できます。
新しいAgentScriptを使用したビルダーはアプリケーションランチャーで[Agentforce スタジオ]を選択し、新規作成すると使用できます。

まず、AgentScriptがどのようなブロックで構成されているのか、そしてそれぞれのブロックがどのような役割を担っているのかをご紹介します。

systemブロックでは、Agentに対する包括的な役割の説明、そして会話の開始時とエラー時に出すためのメッセージを設定します。
systemブロックはAgentを新規作成される際に自動で作成されるため、指示文やメッセージ文を任意で修正すれば設定完了です。

configブロックでは、Agetforceのメタデータ定義を設定します。従来のビルダーとは異なり、「developer_name」という項目を書き換えることで、AgentのAPI参照名を変更できるようになっています。
configブロックも自動で作成されるため、API参照名や表示ラベルなどを変更したい場合のみ修正すれば設定の必要はありません。

variablesブロックでは、Agentが使用可能な変数を管理します。画像に記載されている変数は、Agentの新規作成時に全て自動生成される変数です。変数の定義には2種類あり、「mutable」とあるものはAgentが参照/編集できる変数、「linked」とあるものは参照のみの変数です。
variablesブロックも自動で作成されますが、新規で変数を作成したい場合は追加で変数の定義を設定する必要があります。

start_agentブロックは、Agentに対してユーザーの入力があった際にまず初めに実行されるブロックで、ユーザーの入力内容を理解し、どのサブエージェントを選択すれば良いかを決定するための重要なものです。
start_agentブロックも自動で作成されますが、このままではユーザーからどのような入力があった際に、どのサブエージェントへ移行すれば良いかの説明がなく、Agentの挙動が安定しません。

そのため、上記画像のように「go_to_～」という各サブエージェントへの移行アクションの下に、「description」という説明の項目を追加し、どのような場合に各サブエージェントへ移行するのかという説明を加える必要があります。また、自分でサブエージェントを作成した際には、「actions」の中に作成したサブエージェントへの移行アクションを新規作成する必要もあります。

subagentブロックでは、文字通りサブエージェントの定義と、サブエージェント内で使用するアクションなどを管理します。「label」、「description」という項目には、その名の通りサブエージェントの表示ラベルと、そのサブエージェントの役割の説明を入力します。その他の部分に関して、subagentブロックは自由度が高い分、書き方が少し複雑になるため、詳細に説明していきます。

reasoningブロックでは、実際にLLMに渡すためのプロンプト(「instructions」)と、LLMに公開し、使用するかの判断を任せるツール(「actions」)を入力します。「instructions」には、実際にAIに行わせたい内容を分かりやすく入力すれば問題ありません。「actions」には、行わせたい内容を実行するために、AIの判断で使用できるツールを作成し、設定します。具体的にどのようなツールを使用できるかについては「5-3.acitons」のセクションでご紹介します。
上記画像では、「@utils.setVariables」という、AgentScriptで使用可能な標準アクションのようなものを使用しており、Agentforce内の変数(ここでは「var_CaseNumber」)に、ユーザーが入力した文字列を格納させるようにしています。
ユーザーとの会話から、変数に設定したい値を抽出する際は、必ず「@utils.setVariables」を使用する必要があります。

after reasoningブロックでは、reasoningブロックでのAIによる処理が完了した後に必ず実行させたい行動を設定します。上記画像の例では、「getCaseInfo」という後続の「actions」ブロックで定義したフローのアクションを呼び出し、「summary_Case」というサブエージェントへそのまま移行するということを指示しています。
一つ目の、「run @actions.～」という構文は、強制的に「～」に当たるアクションを実行させることができます。「with」で、そのアクションの入力変数にAgentforceから値を渡すことができ、「set」でアクションの出力値をAgentforce内の変数に保存できます。
二つ目の、「transition to @subagent.～」という構文は、「～」に当たるサブエージェントに強制的に遷移させることができます。
after reasoningブロックは、サブエージェントを作成する際に必須のブロックではありませんが、必ず行いたい処理がある場合は使用すると便利です。

actionsブロックでは、サブエージェント内で使用可能なツールを定義します。ツールとして呼び出せるのは、フロー、Apex、APIなどです。「reasoning」ブロックの中にも「actions」ブロックがありましたが、ツール自体の定義は「reasoning」ブロックの外側の「actions」ブロックで行い、それをAIの判断で呼び出させたい場合に、「reasoning」ブロック内の「actions」ブロックに記載するという形です。
尚、「5-1.reasoning」にて説明した「@utils.setVariables」については、標準搭載されているツールとなるため、「reasoning」ブロックの外側の「actions」ブロックでの定義の設定の必要はありません。

最後に、実際にケース要約を行ってくれるAgentforceの作成を行います。

ケースの情報をAgentforceに与えて要約させる際に、Agentforce内の変数にはフローのようなレコード型の変数は存在しないため、ケースを取得し、必要な情報をテキスト形式にまとめるためにApexを使用します。Agentforceがより内容を理解しやすいよう、今回はJSON形式のテキスト出力するApexクラスを作成します。

AgentforceからApexを呼び出す際は、フローと同じように@InvocableMethodを呼び出したいメインメソッドに付与することで呼び出し可能となります。

次に、実際のAgentforce構築を行います。

まず、Agentforceスタジオに移動し、「新しいエージェント」ボタンを押下します。

続いて、エージェントのテンプレートの選択画面に遷移します。
今回は、「Agentforce Employee Agent」を選択します。

表示ラベル、API参照名を入力すると、ビルダー画面に遷移します。
[system]>[instructions]には、どのような役割のエージェントなのかという説明を入力しています。
[system]>[messages]には、初めに表示するメッセージと、エラーメッセージを設定しています。
[config]ブロックはデフォルトから変更しておらず、[language]ブロックでは、[default_locale]を「ja(日本語)」に変更しています。

[variables]ブロックでは、ユーザーが入力したケース番号を保存するための変数「caseNumber」と、Apexから出力されるJSON文字列を保存するための変数「caseJSON」を新規作成しています。

「start_agent」ブロックでは、[reasoning]>[actions]に作成したサブエージェント「get_Case_Info」への移行アクションを追加しています。

サブエージェント「get_Case_Info」では上記画像のように設定しています。
ユーザーが入力した値を変数に格納する際は、「@utils.setVariables」を使用し、
「with caseNumber =...」と書くことで、Agentforceはユーザーが入力した値を変数caseNumberに格納してくれるようになります。
また、[after_reasoning]では、作成したApexを呼び出し、後続のサブエージェント「summary_Case」へ移行するように設定しています。

サブエージェント「summary_Case」では、Apexから取得したJSON文字列をもとに、出力フォーマットを指定して内容を表示させるように指示しています。
[reasoning]>[instructions]内で変数を参照する際は、{!@variables.変数名}とすることで変数の参照が可能です。

以上でAgentforceの構築は完了です。

最後に、今回作成したAgentを実際に動かしてみましょう。

Agentの挙動を試す際は、上記画像左上の「Preview」から行うのが便利であるため、今回は「Preview」で実際に動かしてみます。

プレビュー画面では、Agentと実際にやり取りする画面に加え、ユーザーの入力に対し、Agentがどのように思考し、内部的にどのようなアクションを取ったかというプロセスを見ることができるため、特に複雑なAgentを作成する際には挙動確認に効果的です。

ケース番号を入力し、送信すると上記画像のようにケースの情報が要約されて表示されました。また、「Preview Settings」という欄では、入力があってからのAgentの動きをすべてトレースしています。

また、「変数」という部分を押下すると、各変数に保存されている値を参照することができ、想定された値が変数に適切に保存されているかどうかのチェックも可能となっています。

本稿では、AgentScriptの概要説明と、簡単なAgentの構築を行いました。AgentScriptはまだインターネット上に書き方などに関する情報がそこまで多くなく、自分も実際に構築する際はいろいろ調べながら苦労したため、今回このようなAgentScriptの紹介記事を作成しました。「分かりにくいしこれなら従来のビルダーでいいや...」と思う方もいらっしゃるかもしれませんが、新規ビルダーはバージョン管理が可能であったり、作成後でもAgentのAPI参照名の変更ができるといった利点もあるため、実際に手を動かしながらAgentScriptに少しずつ慣れていくことをおすすめします。