コンテンツにスキップ

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

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

モデル

エージェントを設定する際に、レスポンスの生成に使用するモデルを選択できます。Brazeが提供するモデルを使用する方法と、独自のAPIキーを持ち込む方法の2つのオプションがあります。

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

これは最もシンプルなオプションで、追加のセットアップは不要です。Brazeは大規模言語モデル(LLM)への直接アクセスを提供します。このオプションを使用するには、Geminiモデルを使用するAutoを選択してください。

オプション2:独自のAPIキーを持ち込む

このオプションでは、BrazeアカウントをOpenAI、Anthropic、またはGoogle Geminiなどのプロバイダーと接続できます。LLMプロバイダーから独自のAPIキーを持ち込む場合、トークンコストはBrazeを通じてではなく、プロバイダーから直接請求されます。

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

設定方法:

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

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

Brazeが提供するLLMを使用する場合、そのモデルのプロバイダーはBrazeのサブプロセッサーとして機能し、お客様とBraze間のデータ処理追加条項(DPA)の条件に従います。独自のAPIキーを持ち込む場合、LLMサブスクリプションのプロバイダーは、お客様とBraze間の契約に基づくサードパーティプロバイダーとみなされます。

思考レベル

一部のLLMプロバイダーでは、選択したモデルの思考レベルを調整できます。思考レベルは、モデルが回答する前に使用する思考の範囲を定義します。素早く直接的なレスポンスから、より長い推論の連鎖までさまざまです。これはレスポンスの品質、レイテンシー、トークン使用量に影響します。

レベル 使用場面
最小 シンプルで明確なタスク(カタログ検索、直接的な分類など)。最速のレスポンスと最低コストです。
低 もう少し推論が必要だが、深い分析は不要なタスク。
中 マルチステップまたは微妙なニュアンスのあるタスク(アクションを推奨するために複数の入力を分析するなど)。
高 複雑な推論、エッジケース、またはモデルが回答前にステップを踏んで考える必要がある場合。

まず最小から始めて、エージェントのレスポンスをテストすることをお勧めします。エージェントが正確な回答を提供するのに苦労している場合は、思考レベルを低または中に調整できます。まれに高の思考レベルが必要になることがありますが、このレベルを使用すると、高いトークンコストやレスポンス時間の延長、タイムアウトエラーのリスクが高くなる可能性があります。エージェントがマルチステップの推論と適切なレスポンス時間のバランスに苦労している場合は、ユースケースを複数のエージェントに分割して、キャンバスやカタログ内で連携させることを検討してください。

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

使用するモデルの判断

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

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

呼び出しフロー制御

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

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

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

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

各エージェントには1日あたりの呼び出し制限があります(デフォルトは250,000、契約で許可されない限り最大1,000,000)。すべての呼び出し(エージェントコンソールのプレビューやレスポンスをシミュレートを使用するテストキャンバスの実行を含む)がこの制限にカウントされます。

エージェントコンソールの1日あたりのアクションクレジットコスト上限は、エージェントが1日に消費できる最大クレジットを推定します。Brazeは、選択したモデルのワークスペースごとの呼び出しあたりのクレジット比率に1日あたりの呼び出し制限を掛けて計算します。

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

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

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

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

クレジット使用量の監視

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

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

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

レート制限エラー

キャンバスステップエージェントまたはカタログエージェントの呼び出し中にLLMプロバイダーがレート制限エラーを返した場合、Brazeは指数バックオフを使用して、コールが成功するか完了できないと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. 社内での再利用とスケーリングのために、効果的だった方法を測定し文書化します。

可能な限り、肯定的で明確なインストラクションを作成してください。エージェントに何をすべきかを伝え、制限事項は具体的な表現で記述します。エージェントがルールに従わない場合は、エージェントがインストラクションやルールに従わないのはなぜですか?を参照してください。

例

エージェントコンソールでの初期設定については、Operatorで構築されたエージェントテンプレートを参照してください。

コピーまたはアレンジできるインストラクションの完全な例については、Brazeエージェントのユースケースライブラリを参照してください。

例 カテゴリ エージェントタイプ 概要
ユーザーのコンテキストに基づいてパーソナライズされたメッセージを作成する コンテンツ生成 キャンバスステップエージェント 検索したが予約しなかったユーザー向けに、メール件名/プリヘッダーとプッシュタイトル/本文を協調的に生成します。
ユーザーフィードバックを分析して次のステップを決定する データ標準化 キャンバスステップエージェント 旅行後のアンケートの感情とトピックを分類し、CRMの次のステップを推奨します。
既存の属性からユーザーを興味バケットに分類する アフィニティエージェント キャンバスステップエージェント 属性と高インテントシグナルからユーザーを興味バケットに分類し、最適な次のエクスペリエンスやアイテムを推奨します。
最近の行動から最も関連性の高いキャンバスパスにユーザーをルーティングする アフィニティエージェント キャンバスステップエージェント 最近の行動からモチベーションを推測し、ユーザーの次のキャンバスステップに最適なルートキーを返します。
リアルタイムの高インテントアクションからユーザーを興味カテゴリに割り当てる アフィニティエージェント キャンバスステップエージェント 高インテントアクションから興味カテゴリを割り当て、最適な次のエクスペリエンスやアイテムを推奨します。
インバウンドメッセージをオプトアウトの意図で分類する 分類とルーティング キャンバスステップエージェント メッセージがオプトアウトリクエストかどうかを示す厳密なブール値を返します。
インバウンドメッセージをオートメーション用の構造化データに標準化する データ標準化 キャンバスステップエージェント インバウンドSMSやチャットを構造化されたインテント、エンティティ、コンプライアンスフラグに正規化し、ダウンストリームのオートメーションに使用します。
ブランドガイドラインに沿った高コンバージョンの説明文を作成する コンテンツ生成 カタログエージェント カタログの各行に対して、ブランドに合った短い説明文を生成します。
地域で使用される言語に基づいた翻訳を提供する カタログエンリッチメント カタログエージェント ロケールと文字数制限に応じてUIおよびマーケティング文字列をローカライズします。
カタログアイテムに説明、カテゴリ、タグを追加して充実させる カタログエンリッチメント カタログエージェント 既存のカタログアイテムデータから、拡張された説明文、カテゴリ、タグを生成します。

Liquidの使用

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

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

インストラクションにLiquidを含むエージェントの詳細。

カタログエージェントの場合は、JSONスキーマの代わりに出力セクションのフィールドを使用してください。ただし、それらのフィールド名に一致するキーバリュー出力をモデルに求めるインストラクションを記述することは可能です。

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

出力

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

基本スキーマ

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

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

基本スキーマとして「Number」が選択されたエージェントコンソール。

高度なスキーマ

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

  • Fields: エージェントの出力を一貫して使用できるように強制するノーコードの方法です。
  • JSON: 正確な出力形式を作成するためのコードアプローチで、JSONスキーマ内に変数やオブジェクトをネストできます。キャンバスステップエージェントでのみ利用可能で、カタログエージェントでは利用できません。

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

フォールバック出力

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

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

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

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

レストランの最新アイスクリームフレーバーをおすすめする可能性がどのくらいあるかを判断するために、シンプルなフィードバック調査の回答をフォーマットしたい場合は、以下のフィールドを設定して出力形式を構造化できます。

フィールド名 値
likelihood_score Number
explanation String
confidence_score Number

likelihood score、explanation、confidence scoreの3つの出力フィールドを表示するエージェントコンソール。

レストランチェーンでの直近のダイニング体験に対するユーザーフィードバックを収集したい場合は、出力形式としてJSON Schemaを選択し、以下のJSONを挿入して、センチメント変数と理由変数を含むデータオブジェクトを返すことができます。

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

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

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

カタログ「nyc_restaurants」を参照するナレッジソース「nyc_restaurants」

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

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

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

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

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

エージェントのメンバーシップアクセスに選択された「Loyalty Users」セグメント

ブランド・ガイドライン

エージェントの応答で遵守するブランド・ガイドラインを選択できます。例えば、ジムの会員登録を促す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 フィールドに貼り付けてください。

エージェントの複製

エージェントを複製して、改善やイテレーションをオリジナルと並べてテストできます。以前の設定を確認または復元するには、バージョン履歴を使用してください。エージェントを複製するには:

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

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

カスタムエージェントが増えてきたら、アクティブに使用されていないエージェントをアーカイブしてエージェント管理ページを整理できます。エージェントをアーカイブするには:

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