Apex アクションを作成する準備をしましょう。
学習の目的
この単元を完了すると、次のことができるようになります。
- アクションを構築できるように組織を準備する。
- Apex がアクションに対応していることを確認する。
予報: 晴天が続く見込み
よく旅行に行く人にとっては常識ですが、旅行を最大限に楽しむためには天候のチェックが不可欠です。Coral Cloud Resorts は、基本的にはいつも晴れていて暖かいのですが、悪天候に見舞われる日もあります。どんな天候でもゲストが休暇を満喫できるように、Coral Cloud チームは AI エージェントに天候の情報を収集する機能を追加したいと考えています。そのためには、外部 API を使用して Apex クラスから天候データを取得するアクションを作成する必要があります。
Agentforce 用の Developer Edition 組織にサインアップする
このモジュールを受講するためには、Agentforce とサンプルデータを搭載した特別な Developer Edition 組織が必要です。このバッジの Challenge を実行するには、Agentforce が組み込まれた無料のカスタマイズ済み Developer Edition 組織にサインアップし、組織を Trailhead に接続してください。リンクをクリックして始めましょう。この組織は、このバッジの Challenge 用に設計されているため、他のバッジでは機能しないことがあります。使用している Trailhead Playground や特別な Developer Edition 組織が推奨されているものであることを必ず確認してください。
-
Agentforce を搭載した無料の Developer Edition 組織にサインアップします。
- フォームに入力します。
- [Email (メール)] には、有効なメールアドレスを入力します。
- [Username (ユーザー名)] に、メールアドレス形式の一意のユーザー名 (例: yourname@example.com) を入力しますが、有効なメールアカウントである必要はありません。
- [Email (メール)] には、有効なメールアドレスを入力します。
- フォームに入力したら [Sign me up (サインアップ)] をクリックします。確認メッセージが表示されます。
- アクティベーションメールを受信したら (数分かかる場合があります)、そのメールを開いて [Verify Account (アカウントを確認)] をクリックします。
- パスワードと確認用の質問を設定して、登録を完了します。後でアクセスしやすいように、ユーザー名、パスワード、ログイン URL を安全な場所 (パスワードマネージャーなど) に保存しておくことをお勧めします。
- Developer Edition にログインした状態になります。
新しい Developer Edition 組織を Trailhead に接続します。
- Trailhead アカウントにログインしていることを確認します。
- このページの下部にある「Challenge」セクションで組織名をクリックして、[Connect Org (組織を接続)] をクリックします。
- ログイン画面で、先ほど設定した Developer Edition のユーザー名とパスワードを入力します。
- [Allow Access? (アクセスを許可しますか?)] 画面で [Allow (許可)] をクリックします。
- [Want to connect this org for hands-on challenges? (この組織をハンズオン Challenge 用に接続しますか?)] 画面で [Yes! Save it. (はい、保存します。)] をクリックします。Challenge ページにリダイレクトされたら、このバッジの獲得を目指して新しい Developer Edition を使用できます。
エージェント用に組織を準備する
エージェントをカスタマイズする前に、必要な組織の機能をすべて有効にします。
- 歯車アイコン
をクリックして、[Setup (設定)] を選択します。
- [Setup (設定)] の [Quick Find (クイック検索)] ボックスで [Einstein Setup (Einstein 設定)] を検索して選択します。
- [Turn on Einstein (Einstein を有効化)] 切り替えがオンになっていることを確認します。
- ブラウザーを更新して設定を再読み込みします。
- [Setup (設定)] の [Quick Find (クイック検索)] ボックスで [Agentforce Agents (Agentforce エージェント)] を検索して選択します。
-
[Agentforce] 切り替えをクリックし、オンになっていることを確認します。
-
[Enable the Agentforce (Default) Agent (Agentforce (デフォルト) エージェントを有効化)] 切り替えをクリックし、[On (オン)] に設定します。
すでにある機能を利用してエージェントアクションを構築する
さあ、いよいよエージェント用のカスタムアクションを構築する準備が整ってきました。Salesforce で AI エージェントを構築する大きな利点の 1 つは、組織にすでに備わっている機能を活用できることです。今回のケースでは、Coral Cloud Resort の天候情報を AI エージェントに追加しようとしています。すでに Coral Cloud には、外部 API からリゾート所在地の天候を取得するための WeatherService Apex クラスがあります。このクラスをアクションでどのように活用するのかを見ていきましょう。
public with sharing class WeatherService { /** * Gets the weather at Coral Cloud Resorts for the provided date */ public static Weather getResortWeather(Datetime dateToCheck) { Integer currentYear = Date.today().year(); Integer yearDelta = currentYear - dateToCheck.year(); dateToCheck = dateToCheck.addYears(yearDelta); String isoDate = dateToCheck.format('yyyy-MM-dd'); String dateString = dateToCheck.format('MMMM d'); // Prepare API request HttpRequest req = new HttpRequest(); req.setEndpoint( 'callout:Weather_Endpoint/weather?lat=37.789782764570425&lon=-122.39723702244089&date=' + isoDate ); req.setMethod('GET'); // Make callout Http http = new Http(); HttpResponse res = http.send(req); if (res.getStatusCode() != 200) { throw new CalloutException('Bad response: ' + res); } // The response contains a list of temperatures for different times of the day // We parse the response and find the min and max temperatures String body = res.getBody(); WeatherApiResponse weatherResponse = (WeatherApiResponse) JSON.deserialize( body, WeatherAPIResponse.class ); List<Decimal> temperatures = new List<Decimal>(); for (TemperatureWrapper item : weatherResponse.weather) { if (item.temperature != null) { temperatures.add(item.temperature); } } temperatures.sort(); // Prepare temperatures and description Decimal minTempC = temperatures[0]; Decimal maxTempC = temperatures[temperatures.size() - 1]; Decimal minTempF = toFahrenheit(minTempC); Decimal maxTempF = toFahrenheit(maxTempC); String description = 'On ' + dateString + ', temperature should be between ' + minTempC + '°C (' + minTempF + '°F) and ' + maxTempC + '°C (' + maxTempF + '°F) at Coral Cloud Resorts.'; // Return weather info Weather weather = new Weather(); weather.minTemperatureC = minTempC; weather.minTemperatureF = minTempF; weather.maxTemperatureC = maxTempC; weather.maxTemperatureF = maxTempF; weather.description = description; return weather; } private static Decimal toFahrenheit(Decimal celsius) { return (celsius * 9 / 5 + 32).setScale(1); } private class WeatherApiResponse { public List<TemperatureWrapper> weather; } private class TemperatureWrapper { public Decimal temperature; } public class Weather { public Decimal minTemperatureC; public Decimal minTemperatureF; public Decimal maxTemperatureC; public Decimal maxTemperatureF; public String description; } }
これは、指定された日付の天候情報を取得するために天気予報サービスに HTTP 要求を送信するシンプルな Apex クラスです。ただし、この Apex クラスは Agentforce ビルダーからは使用できません。このクラスを修正して呼び出し可能なメソッドにすることもできますが、ベストプラクティスとしては、元の WeatherService を呼び出すように設定された別の Apex クラスを作成し、それを呼び出し可能なメソッドとして定義するのことが推奨されます。@InvocableMethod アノテーションを使用すると、フローなどの宣言型ツール、REST 経由の外部アプリケーション、そして Agentforce からカスタム Apex コードを呼び出すことができます。
都合のよいことに、Coral Cloud チームはすでに WeatherService を呼び出す Apex クラスを用意しています。このクラスの中身を見て、WeatherService がどのように実装されているかを確認しましょう。
public with sharing class CheckWeather { @InvocableMethod( label='Check Weather' description='Check weather at Coral Cloud Resorts at a specific date' ) public static List<WeatherResponse> getWeather( List<WeatherRequest> requests ) { // Retrieve the date for which we want to check the weather Datetime dateToCheck = (Datetime) requests[0].dateToCheck; WeatherService.Weather weather = WeatherService.getResortWeather( dateToCheck ); // Create the response for Copilot WeatherResponse response = new WeatherResponse(); response.minTemperature = weather.minTemperatureC; response.maxTemperature = weather.maxTemperatureC; response.temperatureDescription = 'Temperatures will be between ' + weather.minTemperatureC + '°C (' + weather.minTemperatureF + '°F) and ' + weather.maxTemperatureC + '°C (' + weather.maxTemperatureF + '°F) at Coral Cloud.'; return new List<WeatherResponse>{ response }; } public class WeatherRequest { @InvocableVariable( required=true description='Date for which we want to check the temperature. The variable needs to be an Apex Date type with format yyyy-MM-dd.' ) public Date dateToCheck; } public class WeatherResponse { @InvocableVariable( description='Minimum temperature in Celsius at Coral Cloud Resorts location for the provided date' ) public Decimal minTemperature; @InvocableVariable( description='Maximum temperature in Celsius at Coral Cloud Resorts location for the provided date' ) public Decimal maxTemperature; @InvocableVariable( description='Description of temperatures at Coral Cloud Resorts location for the provided date' ) public String temperatureDescription; } }
まず注目すべきは、getWeather
メソッドに付けられている @InvocableMethod
アノテーションです。このメソッドには 2 つのパラメーターが渡されており、どちらもエージェントアクション作成プロセスで使用されます。label
パラメーターは、エージェントアクションの表示ラベルとして表示されます。description
パラメーターは、エージェントアクションの指示として表示されます。AI エージェントにとって説明は非常に重要で、メソッドの意味を正しく理解するために役立ちます。
また、WeatherRequest
クラスと WeatherResponse
クラスの 2 つの公開クラスには、それぞれ [Create an Agent Action (エージェントアクションを作成)] の入力と出力として使用される @InvocableVariable
アノテーションが付けられています。
WeatherRequest
では、dateToCheck
に @InvocableVariable
アノテーションが付いており、required
パラメーターが true
に設定されています。この設定により、[Create an Agent Action (エージェントアクションを作成)] の [Require Input (入力が必要)] チェックボックスがデフォルトでオンになります。description
パラメーターは入力指示として表示されます。また、dateToCheck
の変数の型を Date
に設定することで、入力データ型も自動的に Date に設定されます。
一方、WeatherResponse
では、minTemperature
、maxTemperature
、temperatureDescription
の 3 つの変数に @InvocableVariable
アノテーションが付けられています。これらにはそれぞれ description
パラメーターが設定されており、[Create an Agent Action (エージェントアクションを作成)] の出力指示として表示されます。また、各変数のデータ型 (Decimal
、Decimal
、String
) は出力表示で使用されます。String
型の変数は、出力表示で「テキスト」として扱われます。
権限を設定する
他の Apex 機能と同様に、Apex ファイルにアクセスするには適切な権限が必要です。このバッジで使用しているカスタム Developer 組織では、このステップはすでに完了しています。呼び出し可能なメソッドを含む Apex クラスへのアクセス権が、権限セットを通して AI エージェントに付与されています。この設定がなければ、アクションを作成してエージェントに追加しても、エージェントがその Apex クラスをプランの作成時に考慮することはできません。Apex アクションが Agentforce で期待どおりに動かない場合、よくある原因の 1 つが権限設定ミスです。
これで、Apex をアクションで使用するために何が必要かを理解できたことと思われます。少し情報量が多かったかもしれませんが、次の単元で実際にアクションを構築することで、より理解が深まるでしょう