エージェントのリファレンス

カスタムエージェントを作成する際は、この記事でインストラクションや出力スキーマなどの主要な設定について詳しく確認してください。ステップバイステップのセットアップについては、カスタムエージェントの作成を参照してください。概要については、Braze Agentsおよびよくある質問を参照してください。

モデル

エージェントを設定する際に、応答の生成に使用するモデルを選択できます。選択肢は 2 つあります。Braze が提供するモデルを使用するか、独自の API キーを使用するかです。

重要

Braze が提供する Auto モデルは、ナレッジソースの検索やセグメントメンバーシップの確認などのタスクを処理できるように調整されています。独自のモデルを使用する場合は、これらのタスクを重点的にテストしてください。低コストのモデルで思考レベルが低い場合、ツール呼び出しを省略したり、データを取得する前に回答したりすることがあります。速度や性能が異なるモデルに合わせて、詳しさや段階的な思考の度合いを変えるように指示を調整する必要がある場合があります。

オプション 1:Braze が提供するモデルを使用する

最もシンプルなオプションで、追加の設定は必要ありません。Braze が大規模言語モデル (LLM) へのアクセスを直接提供します。このオプションを使用するには、Gemini モデルを使用する Auto を選択します。

オプション 2:独自の API キーを使用する

このオプションでは、Braze アカウントを OpenAI、Anthropic、Google Gemini などのプロバイダーと接続できます。サポートされているプロバイダーの一覧については、AI モデルプロバイダーを参照してください。LLM プロバイダーの独自の API キーを使用する場合、トークンコストは Braze ではなくプロバイダーから直接請求されます。

従来のモデルは数か月後に提供終了または非推奨となる可能性があるため、最新のモデルを定期的にテストすることをお勧めします。エージェントを大規模に実行できるだけのクレジットがプロバイダー側にあることを確認してください。また、通知設定でエージェントコンソールの通知に登録すると、モデルが利用できなくなったことや LLM プロバイダーとの請求に関する問題を Braze が検出した際にアラートを受け取れます。

設定するには、次の手順に従います。

1. パートナー連携 > テクノロジーパートナーに移動し、使用するプロバイダーを見つけます。
2. プロバイダーの API キーを入力します。
3. 保存を選択します。

その後、エージェントに戻ってモデルを選択できます。

Braze が提供する LLM を使用する場合、そのモデルのプロバイダーは Braze の再委託先 (Sub-processor) として機能し、お客様と Braze との間のデータ処理補遺 (DPA) の条件に従います。独自の API キーを使用することを選択した場合、LLM サブスクリプションのプロバイダーは、お客様と Braze との間の契約に基づく第三者プロバイダーとみなされます。

思考レベル

LLM プロバイダーによっては、選択したモデルの思考レベルを調整できる場合があります。思考レベルは、モデルが回答する前に行う思考の範囲を定義するもので、すばやく直接的な応答から、より長い推論の連鎖まであります。これは応答の品質、レイテンシー、トークン使用量に影響します。

利用可能なレベルはモデルによって異なります。一部のモデルでは最小の代わりになしが提供され、すべてのモデルで高が提供されるわけではありません。

まずは最小 (またはなし) から始めて、エージェントの応答をテストすることをお勧めします。エージェントがナレッジソースを使用する場合は、低から始めてください。最も低いレベルでは、一部のモデルが検索を実行せずに回答することがあります。エージェントが正確な回答を出すのに苦労している場合は、1 レベルずつ上げてください。まれに高の思考レベルが必要になる場合もありますが、このレベルを使用するとトークンコストが高くなり、応答時間が長くなったり、タイムアウトエラーのリスクが高まったりする可能性があります。エージェントが複数ステップの推論と妥当な応答時間の両立に苦労している場合は、ユースケースを複数のエージェントに分割し、キャンバスやカタログ内で連携させることを検討してください。

Braze は、LLM へのアウトバウンド呼び出しに Connected Content と同じ IP 範囲を使用します。範囲は Connected Content の IP 許可リストに記載されています。プロバイダーが IP 許可リストに対応している場合は、キーをそれらの範囲に制限して、Braze のみが使用できるようにすることができます。

重要

Braze が提供する LLM を使用する場合、そのモデルのプロバイダーは Braze の再委託先 (Sub-processor) として機能し、お客様と Braze との間のデータ処理補遺 (DPA) の条件に従います。独自の API キーを使用することを選択した場合、LLM サブスクリプションのプロバイダーは、お客様と Braze との間の契約に基づく第三者プロバイダーとみなされます。

使用するモデルを決める

LLM プロバイダーごとに、モデルの性能、コスト、思考レベルの組み合わせは少しずつ異なります。一般的なガイドラインとベストプラクティスを以下に示します。

• コスト効率を重視する場合は、トークンコストの高いモデルよりも低いモデルを優先してテストしてください。低コストのモデルがユースケースに対応できない場合や、出力に一貫性がない、または不正確な場合にのみ、高コストのモデルに切り替えてください。
• 速度とパフォーマンスの効率を重視する場合は、高い思考レベルよりも低い思考レベルを優先してテストしてください。低い思考レベルでユースケースに対応できない場合や、出力に一貫性がない、または不正確な場合にのみ、高い思考レベルに切り替えてください。
• 低コストのモデルや低い思考レベルでユースケースに対応できない場合や、出力に一貫性がない、または不正確な場合は、高コストのモデルや高い思考レベルへの切り替えを検討してください。
• テスト中は、信頼性と正確性、トークン使用量と呼び出し時間のバランスを取るようにしてください。
• ユースケースごとに最適なモデルと思考レベルは異なる場合があります。タイムアウトなしで一貫した品質が得られるか、十分にテストすることをお勧めします。

呼び出しフロー制御

以下の呼び出しフロー制御は、ワークスペースごとに適用されます。

• Braze が提供するモデル: 1 分あたり 5,000 回の呼び出し
• 独自の API キーを使用する場合: 1 分あたり 5,000 回の呼び出し

多くのユーザーが同時にエージェントステップに入ると、Braze はこれらの上限に従って呼び出しをキューに入れるため、大量送信時には処理に時間がかかる場合があります。

1 日あたりの呼び出し上限とクレジット上限

各エージェントの 1 日あたりの呼び出し上限はデフォルトで 250,000 回で、最大 1 日 1,000,000 回まで設定できます。1,000,000 回を超えて上限を引き上げたい場合は、カスタマーサクセスマネージャーにお問い合わせください。エージェントコンソールのプレビューや、応答をシミュレートを使用するキャンバスのテスト実行を含め、すべての呼び出しがこの上限にカウントされます。

エージェントコンソールでは、1 日あたりのアクションクレジットコスト上限により、エージェントが 1 日に消費できるクレジットの最大量が見積もられます。Braze は、選択したモデルに対するワークスペースの呼び出し 1 回あたりのクレジット比率に、1 日あたりの呼び出し上限を掛けて算出します。

クレジットが消費されるタイミング

Braze は、処理が完了した呼び出しに対してのみクレジットを請求します。次の理由で呼び出しが失敗した場合、クレジットは消費されません。

• LLM プロバイダーからのレート制限エラー (最終的に失敗したリトライを含む)
• 選択したモデルが利用できない
• エージェントが 1 日あたりの呼び出し上限に達した

呼び出しがタイムアウトした場合は、エージェントが使用可能な出力を返さなくてもクレジットが消費されます。

クレジット使用量を監視する

設定 > 請求 > クレジット使用量 > エージェントコンソールに移動すると、クレジット消費量、呼び出し回数、エージェントごとのクレジット比率を確認できます。

クレジット比率は契約に基づいて決まり、クレジット使用量ダッシュボード (クレジット比率タブとエージェントコンソールタブ) に表示されます。見積もりは、モデルや呼び出し上限を変更すると更新されます。

支出を管理するには、1 日あたりの呼び出し上限を下げてください。独自のキーを使用する (BYO) モデルの場合は、低コストのモデルを選択したり、思考レベルを下げたりして、プロバイダーのトークンコストを抑えることもできます。Braze Auto では思考レベルの調整はサポートされていません。

レート制限エラー

キャンバスのエージェントステップまたはカタログエージェントの呼び出し中に LLM プロバイダーがレート制限エラーを返した場合、Braze は呼び出しが成功するか、完了できないと判断するまで、指数バックオフを使用してリクエストを継続的にリトライします。

キャンバスまたはカタログのリトライが上限に達すると、ログの詳細パネルの出力にエラーとプロバイダーのメッセージ (Rate limit exceeded など) が表示されます。リトライはログに表示され、最終的な成否にかかわらず最初の呼び出しも含まれます。たとえば、あるユーザーで成功するまでに 4 回のリトライが必要だった場合、ユーザー ID で検索するとログに 5 件すべて (元の呼び出しと 4 回のリトライ) が表示され、元の呼び出しと最初の 3 回のリトライには Rate limit exceeded とともにエラーが表示されます。

ログに表示される失敗したリトライを含め、レート制限エラーで Braze のクレジットが消費されることはありません。

指示の作成

指示とは、エージェントに与えるルールやガイドライン（システムプロンプト）です。エージェントが実行されるたびにどのように動作するかを定義します。システム指示は最大 25 KB まで指定できます。

BrazeAI Operatorで開始テンプレートを使用してエージェントを作成した場合は、あらかじめ入力された指示を確認し、必要に応じて編集してください。

プロンプト作成を始めるにあたって、一般的なベストプラクティスを紹介します。

1. 最終的な目標を念頭に置き、まずゴールを明示します。
2. モデルに役割やペルソナを与えます（「あなたは…です」）。
3. 明確なコンテキストと制約（対象者、長さ、トーン、形式）を設定します。
4. 構造を指定します（「JSON/箇条書き/表で返してください…」）。
5. 説明するのではなく、見せます。質の高い例をいくつか含めます。
6. 複雑なタスクは順序立てたステップに分割します（「ステップ1… ステップ2…」）。
7. 推論を促します（「内部でステップを考えてから、簡潔な最終回答を出してください」または「判断の理由を簡単に説明してください」）。
8. 試行、検証、反復を行います。小さな調整で品質が大きく向上することがあります。
9. エッジケースは肯定的で明示的なルールで扱い、必要に応じて拒否に関する指示を追加します。
10. 効果があった内容を測定して社内で文書化し、再利用やスケーリングに役立てます。

できる限り、肯定的で明示的な指示を書いてください。エージェントに何をすべきかを伝え、制限事項は具体的な言葉で記述します。エージェントがルールを無視する場合は、エージェントが指示やルールに従わなかったのはなぜですか？を参照してください。

Markdown による指示の書式設定

指示では、見出し、箇条書きや番号付きリスト、太字、リンク、表などの Markdown 書式を使用できます。# Role、## Goal、## Rules などの見出しを使って長い指示をセクションに分けると、自分やチームが内容を把握しやすくなります。書式設定は Braze での指示の表示方法を変えるだけです。エージェントは常に、あなたが書いた元のテキストを受け取ります。

• 指示ステップでプレビューを選択すると、指示が書式設定されたテキストとして表示されます。編集を選択するとエディターに戻ります。
• エージェントの表示ページでは、指示が Markdown の書式設定付きで表示されます。
• 書式設定された指示内のリンクは新しいタブで開きます。
• 生の HTML や XML 形式のタグ（<role> など）は、プレビューではプレーンテキストとして表示されます。エージェントは記述どおりにそれらを受け取ります。

例

エージェントコンソールでの開始構成については、Operator で作成されたエージェントテンプレートを参照してください。

コピーまたは応用できる完全な指示の例については、Braze Agents のユースケースライブラリを参照してください。

Liquid の使用

エージェントの指示に Liquid を含めると、応答にさらにパーソナライゼーションを加えることができます。エージェントが受け取る Liquid 変数を正確に指定し、プロンプトのコンテキストに含めることができます。たとえば、「名」と明示的に書く代わりに、Liquid スニペット {{${first_name}}} を使用できます。

1

Tell a one-paragraph short story about this user, integrating their {{${first_name}}}, {{${last_name}}}, and {{${city}}}. Also integrate any context you receive about how they are currently thinking, feeling, or doing. For example, you may receive {{context.${current_emotion}}}, which is the user's current emotion. You should work that into the story.

エージェントコンソールのログセクションでは、エージェントの入力と出力の詳細を確認し、Liquid からどの値がレンダリングされたかを把握できます。

エージェントが受け取るデータ

エージェントのコンテキストは、制限のない会話メモリではありません。チャットアシスタントとは異なり、エージェントは呼び出し時に明示的に渡されたデータのみを参照します。ユーザープロファイルを閲覧したり、欠落しているフィールドを推測したり、必要な情報が不足していることを知らせたりはしません。

各エージェントは、意図的な入力から出力へのパイプラインとして設計してください。エージェントに必要なすべてのデータポイントを、次のいずれか 1 つ以上の方法で連携します。

1. 指示内の Liquid: ユーザー属性（{{${first_name}}}）とキャンバスコンテキスト変数（{{context.${variable_name}}}）をエージェントのプロンプトに直接テンプレート化します。
2. + エージェントコンテキスト: エージェントコンソールで、ナレッジソース、セグメントのメンバーシップ、ブランドガイドライン、すべてのキャンバスコンテキスト、またはユーザーのインタラクションデータを選択します。
3. コンテキストステップ: エージェントステップが実行される前に、キャンバスの上流で context.* 変数を設定または更新します。
4. エージェントステップの追加コンテキスト: 他の方法でまだ指定されていない Liquid テンプレート化された値を、送信時にステップの設定からエージェントに渡します。

これらのコンテキスト変数は、エージェントの指示内で Liquid テンプレート化するか、エージェントが参照すべきコンテキストファイルを添付するか、すべてのキャンバスコンテキストを追加を選択してください。これらのいずれのチャネルでも値が渡されない場合、エージェントはその値を受け取りません。必要な入力は指示内またはユースケースの前提条件に記載し、テスト後にエージェントコンソール > ログで入力を確認してください。

カタログエージェントでは、JSON スキーマではなく、出力セクションのフィールドを使用してください。その場合でも、それらのフィールド名に一致するキーと値の出力をモデルに求める指示を書くことができます。

プロンプト作成のベストプラクティスの詳細については、以下のモデルプロバイダーのガイドを参照してください。

• OpenAI
• Anthropic
• Gemini

出力

スターターテンプレートを使ってBrazeAI Operatorでエージェントを構築した場合は、あらかじめ入力されている出力スキーマを確認し、必要に応じて編集してください。

基本スキーマ

基本スキーマは、エージェントが返すシンプルな出力です。文字列、数値、ブール値、文字列の配列、数値の配列のいずれかを指定できます。

たとえば、商品を受け取った顧客の満足度を把握するために、シンプルなフィードバックアンケートからユーザーのセンチメントスコアを収集したい場合は、基本スキーマとして数値を選択して出力形式を構造化できます。

重要

配列はキャンバスステップエージェントでのみ使用でき、カタログエージェントでは使用できません。

高度なスキーマ

高度なスキーマのオプションには、フィールドを手動で構造化する方法と、JSON を使用する方法があります。

• フィールド: 一貫して使用できるエージェント出力を、コーディング不要で適用する方法です。
• JSON: 正確な出力形式を作成するためのコードによる方法で、JSON スキーマ内に変数やオブジェクトをネストできます。キャンバスステップエージェントでのみ使用でき、カタログエージェントでは使用できません。

単一の値を出力するのではなく、複数の値を構造化して定義したデータ構造をエージェントに返させたい場合は、高度なスキーマの使用をお勧めします。これにより、出力を一貫したコンテキスト変数としてより適切にフォーマットできます。

フォールバック出力

フォールバック値はキャンバスステップエージェントでのみ使用できます。キャンバスステップエージェントのエージェントコンソールの出力セクションで、呼び出しが失敗したときに Braze が使用する値を定義できます。

JSON スキーマの場合、Braze はスキーマを読み取り、各プロパティの入力フィールドを生成するため、キーごとにフォールバック値を設定できます。フィールドスキーマの場合は、フィールドごとにフォールバック値を入力します。基本スキーマの場合は、1つのフォールバック値を入力します。キャンバスステップエージェントでは、フォールバック値に Liquid を使用できます。

設定手順については、フォールバック値を設定するを参照してください。キャンバスでの実行時の動作については、エラー処理とフォールバック動作を参照してください。

たとえば、ユーザーが送信したフォームをもとにサンプルの旅行日程を作成することを目的としたエージェントで、出力形式を使用するとします。出力形式を使うと、すべてのエージェントの応答が tripStartDate、tripEndDate、destination の値を含んで返されるように定義できます。これらの各値はコンテキスト変数から抽出し、Liquid を使ったパーソナライゼーションのためにメッセージステップに配置できます。

• フィールド
• json スキーマ

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "string"
    },
    "reasoning": {
      "type": "string"
    }
  },
  "required": [
    "sentiment",
    "reasoning"
  ]
}

カタログコンテキストとフィールド

キャンバスステップエージェントにカタログデータへのアクセス権を付与するには、カタログからナレッジソースを作成し、+ エージェントコンテキストとして追加します。エージェントはナレッジソースをクエリして一致する行を取得し、関連するカタログデータのみをLLMに送信します。これにより、トークンの使用量を最小限に抑え、検索精度を向上させます。カタログをエージェントコンテキストとして直接添付することはできません。ナレッジソースが利用可能になる前にレガシーのカタログフィールドを追加オプションで設定されたエージェントは、移行するまでそのコンテキストを引き続き使用できます。

カタログエージェントをカタログフィールドにデプロイする際は、必須入力コントロールを有効にし、エージェントが呼び出される前に、選択した列のうちどの列の入力を必須にするかを選択します。エージェントが行をスキップするのは、必須列のいずれかが空白または欠落している場合のみです。たとえば、まだ入力されていないgenderフィールドなどが該当します。選択した列はデフォルトで必須に設定されますが、空の可能性がある列は、実行をブロックしないように必須から外すことができます。これにより、不完全なデータによるトークンの無駄を防げます。

また、カタログエージェントは、入力フィールドが相互に依存している場合に列の順序も考慮します。列Dを列Bと列Cから生成する場合、エージェントはその行の列Bと列Cに値が入るまで列Dに対して実行されません。

デプロイのシナリオと例については、カタログエージェントを使用するとカタログエージェントのベストプラクティスを参照してください。

セグメントメンバーシップのコンテキスト

エージェントをキャンバスで使用する場合、各ユーザーのセグメントメンバーシップを照合する対象として、最大5つのセグメントを選択できます。たとえば、エージェントで「Loyalty Users」セグメントのセグメントメンバーシップを選択しており、そのエージェントをキャンバスで使用するとします。ユーザーがエージェントステップに入ると、エージェントはエージェントコンソールで指定した各セグメントに各ユーザーが属しているかどうかを照合し、各ユーザーのメンバーシップ (または非メンバーシップ) を LLM のコンテキストとして使用できます。

ブランド・ガイドライン

エージェントが応答で従うブランド・ガイドラインを選択できます。たとえば、ジムの会員登録をユーザーに促すSMSコピーをエージェントに生成させたい場合は、このフィールドを使用して、あらかじめ定義した大胆でモチベーションを高めるガイドラインを参照できます。

コンテキストファイル

エージェントが毎回の呼び出しで静的な資料を参照できるように、リファレンスドキュメントをアップロードします。たとえば、トーンガイド、ポリシードキュメント、製品仕様書などです。コンテキストファイルは、キャンバスステップエージェントとカタログエージェントで利用できます。

ファイルを添付するには、以下の手順に従います。

1. Instructions ステップで、+ Agent context > Upload files を選択します。
2. 1つまたは複数のファイルを追加します。サポートされるファイル形式は、PDF、TXT、MD、CSVです。
3. エージェントを保存します。保存時にファイルがアップロードされます。ファイルはブラウザにステージングされた状態で残り、エージェントをプレビューする際に含まれます。

1つのエージェントにつき最大10ファイルまで添付できます。添付ファイル全体の合計サイズは15 MBまでです。コンテキストファイルを添付する場合は、インストラクション内でエージェントにファイルの使い方を指示してください。たとえば、「添付されたスタイルガイドのトーンと用語に従ってください。」のように記載できます。Files セクションが空の場合、少なくとも1つのファイルを添付するまで needs setup の警告が表示されます。

Brazeは、エージェントコンソールのプレビューを含め、エージェントの呼び出しごとに添付ファイルを送信します。ファイルは毎回の実行時に含まれるため、添付ファイルが大きいほどトークン使用量とレイテンシーが増加する可能性があります。

コンテキストファイルはブランド・ガイドラインとは異なります。ブランド・ガイドラインは統合されたワークスペース設定ですが、コンテキストファイルは個々のエージェントに直接アップロードするドキュメントです。設定手順については、コンテキストの追加を参照してください。

ユーザー固有のインタラクション履歴

ユーザーのインタラクションデータには、チャネルごとに最近受信したキャンペーンおよびキャンバスのメッセージ、各メッセージの内容、およびユーザーが各メッセージに対してインタラクションを行ったかどうかが含まれます。キャンバスでユーザーに対してエージェントが呼び出される際に参照するユーザー固有のコンテキストとしてこのデータを含めることができます。ユーザー固有のインタラクション履歴は、エージェントの役割がパーソナライズされたメッセージコピーの作成である場合に、各ユーザーに響くコピーを書くようエージェントに影響を与えるのに役立ちます。

バージョン履歴

エージェントコンソールは、エージェントの変更を保存するたびに新しいバージョンを記録します。バージョン履歴タブには、保存されたすべてのバージョンと保存間の編集内容が一覧表示されます。

1. エージェントコンソールでエージェントを開きます。
2. バージョン履歴タブを選択します。
3. バージョンを選択して設定を確認します。

バージョンの変更内容を確認するには、View を選択します。Brazeは、追加と削除をハイライトするコードスタイルのインライン差分を表示します。削除されたコンテンツは赤い取り消し線スタイルで表示されます。コンテキストファイルを追加または削除した場合、差分には添付されたファイル名が表示されます。

以前のバージョンからインストラクションを復元する必要がある場合は、そのバージョンの View を開き、インストラクションテキストをコピーして、現在の Instructions フィールドに貼り付けてください。

ヒント

インライン差分ビューで、⌘ + A（macOS）またはCtrl + A（Windows）を押すと、赤い削除マークアップなしですべてのインストラクションを選択でき、クリーンなテキストをコピーして復元できます。

エージェントを複製する

エージェントを複製すると、改善や反復を元のエージェントと並べてテストできます。以前の設定を確認または復元するには、バージョン履歴を使用します。エージェントを複製するには、次の手順に従います。

1. エージェントの行にカーソルを合わせ、 メニューを選択します。
2. 複製を選択します。

エージェントを別のワークスペースにコピーする

キャンバスステップエージェントまたは Agentic Standard を社内の別のワークスペースにコピーすると、一から作り直さずにその設定を再利用できます。Braze はコピーを下書きとして保存し、名前は「Copy of」の後に元の名前が続く形になります。エージェントをコピーするには、次の手順に従います。

1. エージェントの行にカーソルを合わせ、 メニューを選択します。
2. ワークスペースにコピーを選択します。
3. 宛先ワークスペースを選択し、下書きとしてコピーを選択します。
4. 宛先ワークスペースでコピーを確認し、コピーされなかった設定を再接続します。

コピーには、エージェントの指示、説明、出力形式、フォールバック値、ルール、コンテキストファイル、1日あたりの呼び出し上限が引き継がれます。上限が宛先ワークスペースで許可されている値を超える場合、Braze はそのワークスペースの最大値まで引き下げます。次の設定はコピー元のワークスペースに属するため、コピーされません。

• セグメント
• チーム
• タグ
• カタログフィールド
• ブランド・ガイドライン
• ナレッジソース

宛先ワークスペースでエージェントのモデルを実行できない場合、コピーでは Braze Auto が使用されます。

次の制限事項に注意してください。

• カタログエージェントやアーカイブ済みのエージェントはコピーできません。
• 宛先ワークスペース全体で、その種類のエージェントを編集する権限が必要です。

エージェントのアーカイブ

カスタムエージェントが増えてきたら、現在使用していないエージェントをアーカイブして、エージェント管理ページを整理できます。エージェントをアーカイブするには、次の手順に従います。

1. エージェントの行にカーソルを合わせ、 メニューを選択します。
2. アーカイブを選択します。