※本記事は2026年5月14日に米国で公開された The New Agentforce Metadata and Development Lifecycleの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。
新しいAgentforce Builder（Spring ’26正式リリース）では、AIエージェントの作成とテストのエクスペリエンスが刷新されます。スピーディで「失敗しても安全」な環境が提供され、試行錯誤しながら複雑なロジックを改良できます。本番環境で稼働しているAIエージェントへの影響を心配する必要はありません。
Salesforce開発者の皆さんなら、構築エクスペリエンスが新しくなると、たいていは内部の仕組みも変わることをご存じでしょう。今回、このスピード感がある、安全な作業環境をサポートするために、基盤となるメタデータも進化させる必要がありました。この記事では、新しい開発者ワークフロー、メタデータが変更された理由、デプロイ用にパッケージを構成する方法について、順を追って説明します。
新しい開発ワークフロー – スクリプトからメタデータへ
メタデータの変更については、AIエージェント構築の新しい考え方を理解しておくとわかりやすくなるでしょう。新しいAgentforce Builderでは、開発者の「意図」（AIエージェントに実行させたいこと）と、エンジンの「実行」（有効なメタデータ）が明確に分離されます。
AIエージェントの作成から公開までは、次のような流れで進みます。
- 記述と構築 – Agentforce BuilderのUIを使用するか、Agent Scriptを使って、AIエージェントを作成します。人間が読んで理解できるこのスクリプトは、AIエージェントの設定を示す単一の
.agentファイルとして、新しいAiAuthoringBundleメタデータ型内に保存されます。この段階では、作業内容はドラフトの状態です。 - 改良とプレビュー – プレビューモード（テストを組織のデータから安全に分離するシミュレーションモードなど）を使用して、ドラフトをテストします。
- 公開 – ドラフトの内容で問題ないと判断したら、そのバージョンをコミットします。ここが非常に重要なポイントです。コミットの段階で初めて、プラットフォームは
.agentスクリプトを、AIエージェントの実行に実際に使われる有効なBotメタデータとGenAiPlannerBundleメタデータに変換します。
メタデータ変更の理由 – ローカルアセットのバンドル化
新しいビルダーでGenAiPlannerBundleメタデータの構成を変更したのはなぜかというと、分離を確保し、デプロイの信頼性を高める必要があったからです。
これまで、Agentforceアセットはグローバルでした。あるAIエージェントのために共有サブエージェントを変更すると、それが全体に波及し、そのサブエージェントを使用しているすべてのエージェントに即座に影響していました。これを解決するために導入したのがローカルアセット（ローカルサブエージェントとローカルアクションを含む）です。ローカルアセットは、グローバルアセットを複製して作成され、特定のエージェントバージョンにひも付けられます。アセットがローカルになることで、他に影響を与えず安全に編集できます。
ローカルアセットは以前から利用可能でしたが、CI/CDパイプラインで完全にサポートするには、GenAiPlannerBundleメタデータを更新する必要がありました。これまで、エージェントメタデータは複数のメタデータ型に分散していました。新しいGenAiPlannerBundleで最も大きな変更は、「バンドル化」です。特定のバージョンに関連し、依存関係にあるすべてのエージェントアセットを、1つのフォルダー構造でデプロイして利用できるように、メタデータを再構成しました。これにより、デプロイエラーを防げるともに、エージェントがプレビュー時とまったく同じように動作するために必要なものを、すべて揃えられます。
内部の仕組み – 新しいメタデータ構造
従来のようにファイルが分散することなく、各エージェントバージョンに固有のすべての要素が、ディレク��リ構造の中にすっきりとまとめられています。
AiAuthoringBundleは、AIエージェントの設計時のアーティファクトをすべて含むディレクトリです。このバンドルでは、AgentName_1やAgentName_2のように複数のバージョン付きサブディレクトリを使用でき、それぞれが独自の.agentファイルと.bundle-meta.xml記述子を持ちます。これらのサブディレクトリは、AIエージェントのドラフトやコミット済みバージョンなど、異なるライフサイクル状態に対応します。各バージョンには、次のファイルが含まれます。
.agentファイルには、Agent Scriptで記述されたAIエージェントの設定が保持されます。これには、名前、ラベル、説明、システム指示、サブエージェント定義、推論指示、変数、条件分岐、ツール/アクション参照が含まれます。- メタデータ記述子（
.bundle-meta.xml）は、bundleType（例：AGENT）と、その記述子が参照するエージェントバージョンを宣言します。
Botには、AIエージェントの種類や、プライベートデータをログに記録するかどうかといった設定など、AIエージェントのすべてのバージョンに共通する情報が含まれます。また、Botはエージェントレベルのコンテキスト変数も保持します。これは、各BotVersion内に存在する会話変数とは異なります。BotVersionの詳細には、会話変数、ウェルカムメッセージ、会話転送時のメッセージが含まれます。
GenAiPlannerBundleは、AIエージェントの公開済みバージョンごとに関連するデータをすべて保持します。各バージョンには、次の要素が含まれます。
.genAiPlannerBundleは、AIエージェントの実行時設定（サブエージェント、指示、アクション、オーケストレーションロジック）を含む、中核となるメタデータファイルです。agentGraphは、サブエージェント間のすべての遷移と条件を記述した.jsonファイルです。agentScriptは、そのバージョンのAgent Scriptをエンコードしたコピーです。これは同期検出を目的として保持されるスナップショットです。このスナップショットにより、スクリプトが公開済みまたはコミット済みメタデータと同期していない場合に、Agentforce Builderがユーザーに通知できます。plannerActionsは、特定のサブエージェントにひも付かない、エージェントレベルのアクションです。localActionsは、サブエージェント単位でスコープが限定されたアクションで、それぞれのサブエージェントフォルダーの下にネストされます。input/schema.jsonファイルとoutput/schema.jsonファイルが、各アクションの型付きパラメーターを定義します。
注 – GenAiPlannerBundleのバージョンはコミットされた順に自動で番号が付けられるため、AiAuthoringBundleのバージョン番号と一致するとは限りません。
バージョンをコミットすると、BotメタデータとGenAiPlannerBundleメタデータはどちらも自動的に作成されます。また、AiAuthoringBundle、agentScript、agentGraphは、新しいAgentforce Builderで作成されたAIエージェントのメタデータにのみ含まれます。
GenAiPlannerBundle XMLの例
ローカル化されたサブエージェントとアクションをXMLの例で見てみましょう。
1<GenAiPlannerBundle>
2 <description>新しいAIエージェントの説明</description>
3 <localTopicLinks>
4 <genAiPluginName>Retrieve_data_from_the_Knowledge_Base_16jxx0000001234</genAiPluginName>
5 </localTopicLinks>
6 <localTopics>
7 <fullName>Retrieve_data_from_the_Knowledge_Base_16jxx0000001234</fullName>
8 <description>リトリーバーアクションを使用する</description>
9 <pluginType>Topic</pluginType>
10 <masterLabel>ナレッジベースからデータを取得</masterLabel>
11 <genAiPluginInstructions>
12 <description>あなたはAIエージェントです。</description>
13 <sortOrder>1</sortOrder>
14 </genAiPluginInstructions>
15 <localActionLinks>
16 <functionName>File_test_retriever_179xx0000001234</functionName>
17 </localActionLinks>
18 <localActions>
19 <fullName>File_test_retriever_179xx0000001234</fullName>
20 <invocationTarget>File_test_retriever_1234</invocationTarget>
21 <invocationTargetType>apex:testRetriever</invocationTargetType>
22 <source>File_test_retriever</source>
23 </localActions>
24 </localTopics>
25 <plannerType>AiCopilot__ReAct</plannerType>
26</GenAiPlannerBundle><localTopics>ブロックでは、サブエージェントのすべての設定を定義します。一意のAPI名、説明、プラグイン型、決定的な順序で並べられた指示、そのサブエージェントで利用可能なすべてのローカルアクションなどです。また、元のサブエージェントへのリファレンスが含まれる場合もあります。
<localActions>ブロックでは、アクション名、マスターラベル、呼び出し先とその種別を定義します。さらに、必要に応じて、クローン元のグローバルアクションへのsourceリファレンスを含める場合もあります。確認時の動作や読み込み中テキストの設定など、UX関連の追加設定が含まれる場合もあります。
新しいメタデータモデルに対応したpackage.xmlの例
新しいAgentforce Builderで構築したAIエージェントを正常に取得し、デプロイするには、package.xmlに新しいバンドル型を含める必要があります。以下は、Spring ’26のメタデータ構造を前提として作成されたマニフェストの例です。
1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3 <types>
4 <members>*</members>
5 <name>GenAiFunction</name>
6 </types>
7 <types>
8 <members>*</members>
9 <name>Bot</name>
10 </types>
11 <types>
12 <members>*</members>
13 <name>GenAiPlannerBundle</name>
14 </types>
15 <types>
16 <members>*</members>
17 <name>GenAiPlugin</name>
18 </types>
19 <types>
20 <members>*</members>
21 <name>AiAuthoringBundle</name>
22 </types>
23 <version>66.0</version>
24</Package>注 – このマニフェストではAPIバージョン66.0を使用しています。この例のGenAiPlannerBundleと新しいエージェントメタデータ型をサポートするには、このバージョンが必要です。
新しいAgentforce Builderで開発するためのヒント
この新しいアーキテクチャーによって改善された開発ライフサイクルを活用する方法を、2つ紹介します。
- 人間が読めるスクリプトファイルを使って、コードレビューを効率化する。従来のAgentforce Builderでは、AIエージェントの変更をレビューするには、プルリクエスト内に分散した複雑なXMLファイルを見比べる必要がありました。新しいアーキテクチャーでは、人が読んで理解できる
.agentスクリプトファイルを比較できます。これにより、ピアレビューが大幅にスピードアップし、内容も理解しやすくなります。 AiAuthoringBundleを使用して、CI/CDをシンプルにする。ほとんどのパイプラインでは、ソース管理にAiAuthoringBundleを保持するだけで済みます。新しい組織でそのAIエージェントが必要になったら、デプロイし、バージョンをコミットして実行時メタデータを生成し、最後に有効化します。これは、次のコマンドを使用して自動的に実行できます。
sf project deploy start --metadata AiAuthoringBundle --target-org my-org
sf agent publish authoring-bundle --api-name MyAuthoringBundle --target-org my-org
sf agent activate --api-name MyAuthoringBundle --version 2 --target-org my-org
���動のステップを必要としない、完全に自動のパイプラインを構築したい場合は、AiAuthoringBundleとGenAiPlannerBundleの両方をソース管理に保持し、同時にデプロイすることで、コミット済みの状態にできます。システムは、デプロイされるスクリプトと事前に生成されたメタデータをあわせて認識します。手動のコミット手順がすべてにスキップされ、エージェントはデプロイ直後に稼働状態になります。
sf project deploy start --metadata AiAuthoringBundle,GenAiPlannerBundle --target-org my-org
まとめ
新しいAgentforce Builderでは、メタデータ構造がバンドル化されたことで、影響範囲を分離し、バージョンを安全に維持しながらAIエージェントを作成できるようになりました。この構造により、メタデータが整理され、コードレビューが簡単になり、デプロイの信頼性も向上します。
さっそく、Agent Scriptと新しいAgentforce Builderを使ってみましょう。こちらのTrailheadモジュールでは、Agent Scriptを使用したエージェントの作成について学習できます。また、Agent Scriptの基本を解説したブログや、YouTubeのAgent Script Decodedシリーズ（英語）もご覧ください。Agentforce Builderのワークショップ（英語）も随時開催していますので、ぜひ参加してみてください。
関連情報
- リリースノート
- ヘルプドキュメント
- パッケージ
- メタデータの更新
Shreyasは、サンフランシスコのSalesforce AIでリードソフトウェアエンジニアを務めており、Institute of Analyticsのフェロー（FIoA）でもあります。Agentforce Core Platformチームの中心メンバーとして、AgentforceにエンタープライズレベルのALMを導入するため、Agentforceのバージョン管理システムとローカルアセット構成の変更を共同で設計し、主導しました。LinkedInのプロフィールはこちら。
Alba Rivasは、Salesforceのプリンシパルデベロッパーアドボケイトです。LinkedInのプロフィールはこちら。
