ROBOT PAYMENT TECH-BLOG

株式会社ROBOT PAYMENTのテックブログです

Agentforce 2GPパッケージ作成でハマった “つまずきポイント”

Salesforce関連

　こんにちは！株式会社ROBOT PAYMENTで請求管理ロボ for Salesforce開発を担当している木村です。
　最近盛り上がっているAgentforceですが、パッケージ化に関する技術的なナレッジは社内外ともに少ない印象です… 。
　この記事では、Agentforceパッケージング作業（2GP）の過程で発生したエラーと解決策を共有します。
　同じようにAgentforceのパッケージ化で苦労している方の助けになれば幸いです。

つまずきポイント1：BotTemplate に不正なタグが残るパースエラー

現象：Error parsing file: Element agentTemplate invalid

　Agentforceをパッケージ化する際のsf package createコマンド実行にあたっては、　BotTemplate とGenAiPlannerBundle 配下に作成されるエージェントテンプレートが必要になります。
　エージェントテンプレートを構成するメタデータについて詳細は公式ヘルプご参考ください。
　そこで、sf agent generate templateを実行し生成された BotTemplate にてsf package create コマンドを実行したところ、以下のXMLのパースエラーが発生しました。BotTemplate 型のファイル内に、不正な要素として <agentTemplate> がある、という内容です。

Error (MultipleErrorsError): Multiple errors occurred:
(1) AiAgent_fugahogeAgent_v1_Template: Error parsing file: Element {http://soap.sforce.com/2006/04/metadata}agentTemplate invalid at this location in type BotTemplate

原因：Botテンプレート生成時に不要なタグが残存

　これは、Bot メタデータには存在する <agentTemplate> タグが、BotTemplate のメタデータに変換される際に自動で削除されず、そのまま残ってしまうことが原因でした。
　Salesforceサポートにも問い合わせたところ、他社でも同様の事例が報告されているとのことでした。対象のKnown Issuesはこちらになります。

解決策：BotTemplate のXMLファイルから手動でタグを削除

　解決策はシンプルで、対象の BotTemplate メタデータファイルを開き、<agentTemplate> タグとその中身を丸ごと手動で削除します。

つまずきポイント2：スクラッチ組織でBotが有効化されていないエラー

現象：Not available for deploy for this organization

　パッケージバージョンを作成するためにsf package version createコマンドを実行すると、以下のエラーが発生しました。BotTemplate が組織にデプロイできない内容です。

AiAgent_fugahogeAgent_v1_Template: Not available for deploy for this organization

原因：スクラッチ組織定義の不備

　原因は、パッケージングに使用するスクラッチ組織の定義ファイルのproject-scratch-def.jsonで、Botを利用するための機能が有効化されていなかったことでした。
　Salesforceの公式ドキュメントにも記載がある通り、BotTemplate を利用するには Chat と Einstein Bots の有効化が必要です。

Special Access Rules
BotTemplate is available only if Chat and Einstein Bots are enabled in your org. （引用元）

解決策：project-scratch-def.json に設定を追加

project-scratch-def.json ファイルに以下の設定を追加し、スクラッチ組織作成時にBot関連の機能が有効になるようにします。

{
  "orgName": "Your Org Name",
  "edition": "Developer",
  "features": [
    "Einstein1AIPlatform",
    "Chatbot"
  ],
  "settings": {
    "botSettings": {
      "enableBots": true
    }
  }
}

つまずきポイント3：プロンプトテンプレートの権限不足エラー

現象：insufficient access rights on entity: GenAiPromptTemplate

　パッケージバージョンを作成するためにsf package version createコマンドを再度実行しますが、またもや次のエラーが発生です。
　今回我々のAgentforceパッケージではプロンプトテンプレートを利用しているAgentアクションがありますが、　GenAiPromptTemplate というエンティティへのアクセス権が不十分というエラーです。

AiAction_GetfugahogePt: insufficient access rights on entity: GenAiPromptTemplate

原因：パッケージ作成時の権限セットの不足

　プロンプトテンプレートを2GPパッケージに含めるには、パッケージバージョンを作成するプロセス自体にプロンプトテンプレートを管理するための権限セットを割り当てる必要がありました。

解決策：sfdx-project.json に権限セットを指定

　プロジェクト定義ファイル sfdx-project.json に、packageMetadataAccess という設定を追加し、EinsteinGPTPromptTemplateManager 権限セットを指定します。
　詳細については、公式ヘルプをご参考ください。

{
  "packageDirectories": [
    {
      "path": "force-app",
      "default": true,
      "package": "YourPackageName",
      "versionName": "ver 0.1.0",
      "versionNumber": "0.1.0.NEXT",
      "packageMetadataAccess": {
        "permissionSets": [
          "EinsteinGPTPromptTemplateManager"
        ]
      }
    }
  ],
  "namespace": "YourNamespace",
  "sfdcLoginUrl": "https://login.salesforce.com",
  "sourceApiVersion": "60.0"
}

つまずきポイント4：BotTemplate の<description> は255文字制限

　エージェントをUI上で作成する際の説明文には比較的長い説明文を記述できます。もちろん、必然的にBot メタデータの <description> としても相応の記述がされます。
　しかしBotTemplate に変換すると、この<description> タグの文字数上限が255文字になります。
　この状態で、パッケージバージョンの作成でsf package version createを実行すると以下エラーが発生します。

AiAgent_fugahogeAgent_v1_Template: Value too long for field: Description maximum length is:255

対処

　パッケージバージョン作成前に、BotTemplateの<description>が255文字より多い記述であれば、それ以内に収めるように修正する必要があります…。

まとめ

　今回は、Agentforce (Einstein Bot) を2GPでパッケージ化する際に直面した4つのつまずきポイントと、その解決策をまとめました。

  1. BotTemplate に不要なタグが残ってしまう → XMLファイルから手動で削除
  2. スクラッチ組織のBot有効化 → project-scratch-def.json を修正
  3. プロンプトテンプレートの権限不足 → プロジェクトファイル sfdx-project.json の修正
  4. BotTemplate の<description>文字数制限 → 255文字以内に収める

　Agentforceはまだ新しく、パッケージング周りの情報は社内外ともにまだ少ないため試行錯誤が続く状況かと思いますが、皆様の一助となれば嬉しいです！！！