17 エージェントの作成

この項では、ビジュアル・フロー・ビルダーまたはコードを介したAIエージェントの作成について説明します。

トピック:

マルチエージェント・システムとスーパーバイザ・パターン

マルチエージェント・システムは、1つの大規模な全目的エージェントではなく、複数の協力エージェントによってユーザー・リクエストが処理されるAIアプリケーション設計です。

各エージェントには、独自のロール、指示、モデル構成、メモリー・ポリシーおよび許可されたツールがあります。このフローは、リクエストがエージェント間でどのように移動するか、および最終回答がどのように生成されるかを定義します。

この設計は、ワークフローが専門的な職責に自然に分離される場合に役立ちます。たとえば、あるエージェントはデータを取得でき、別のエージェントはAPIをコールでき、別のエージェントは結果を要約でき、スーパーバイザは使用するスペシャリストを決定し、結果を単一のレスポンスに結合できます。

ノート:

設計原則として、要件を満たす最小のエージェント設計から始めるのが最善です。懸念事項の分離により、コストと複雑さが増すよりも信頼性、セキュリティ、メンテナンス性、可観測性が向上する場合は、複数のエージェントを追加します。

マルチエージェント・システムの利点

マルチエージェント・システムは、次の場合に最適です。
  • 専門: 1つの混雑した命令ブロックのかわりに、各エージェントにフォーカスされたジョブ、プロンプトおよびツール・セットを指定します。
  • ルーティングと分解:監督者が要求を解釈し、サブタスクに分割して、各サブタスクに適したスペシャリストを選択します。
  • ツールとデータの分離:機密または影響の大きいツールを、それらを使用するエージェントにのみ公開します。
  • ガバナンスとトラブルシューティング:ハンドオフ、ツールの所有権、メモリー設定、および障害点の検査が容易になります。

マルチエージェントまたは単一エージェントの設計を選択するタイミング

より多くのツールを備えた単一のエージェントは、多くの場合、適切な最初の設計です。テストが簡単で、実行コストが低く、タスクに1つの明確な目標と1つの権限モデルがあるかどうかを判断しやすくなります。ワークフローが明示的なロール、制限付きツール・アクセス、または複数のスペシャリスト出力を調整できるスーパーバイザからメリットを得られる場合は、マルチエージェント設計を使用します。

質問の設計 次の場合に単一のエージェントを使用します... 次の場合に複数エージェントを使用...
タスク・シェイプ リクエストには、1つの主な目的と1つのレスポンス・スタイルがあります。 リクエストは、専門間で分解、ルーティング、検証または合成する必要があります。
ツールとデータ 同じ命令セットとパーミッションモデルは、すべてのツールを安全に管理できます。 エージェントごとに異なるツール、データ・ソースまたはアクセス境界が必要です。
手順説明 すべてのビジネス・ルールとツール・ガイダンスが1箇所にあっても、プロンプトは明確です。 指示は、より小さいロール固有のプロンプトとして保守しやすくなります。
コストとレイテンシ ユーザー・メッセージから回答までの最短パスが必要です。 信頼性、ガバナンスまたはメンテナンス性の利点は、追加のオーケストレーションを正当化します。
トラブル・シューティング 障害は、1つのトレースで簡単にデバッグできます。 明示的なハンドオフ、状態分離、および各ステップの明確な所有権が必要です。

サポートされているパターン: Orchestrator/Supervisor

現在のキャンバス・エクスペリエンスでは、オーケストレータ/スーパーバイザ・パターンがサポートされます。このパターンでは、チャット・トリガーがユーザー・メッセージを受信し、オプションのガードレールが入力を評価し、スーパーバイザ・エージェントがフローの再開のオーケストレータとして機能します。

監督者は、プランニング、ルーティング、委任および最終応答合成に重点を置く必要があります。タスクを処理するエグゼキュータ・エージェントを決定し、そのエグゼキュータにスコープ指定命令を送信し、結果を確認してから、別のステップを委任するか、最終レスポンスを返します。エグゼキュータ・エージェントは、割り当てられた作業を行い、添付されたツールを使用し、役に立つ結果をスーパーバイザに返すという、より狭いスペシャリストである必要があります。

ビジュアル・フロー・キャンバスについて

エージェントは、ノードおよびツール・テンプレートを左パレットからキャンバスにドラッグし、リクエストが移動する順序でノードを接続することでアセンブルされます。

ノードを選択すると、画面の下部に構成パネルが開きます。


エージェント・ビジュアル・ビルダー・キャンバス。パレット、モード・セレクタおよびズーム・コントロールにラベルが付けられ、強調表示されます。

キャンバス要素 目 的
チャット・トリガー ユーザー・メッセージのエントリ・ポイント。スクリーンショットでは、このノードには「メッセージ」というラベルが付けられ、通常はフローの上部に配置されています。

chatトリガーノードは、エージェント、スーパーバイザエージェント、またはガードレールノードに接続できます。キャンバスごとに許可されるチャット・トリガーは1つのみです。

ガードレール モデル作業の前後に配置されるオプションのポリシーと安全層。ガードレール・ポリシーには、PII、コンテンツ・モデレーションおよびプロンプト・インジェクション検出が含まれます。

ガードレール・ノードは、チャット・トリガーとエージェント・ノード間、スーパーバイザとエグゼキュータ・エージェント間、またはエージェントとツール・ノード間のトラフィックをフィルタできます。chatトリガーとエージェントノードの間に1つのガードレールノードを推奨します。

監督者エージェント Orchestratorです。ユーザー・リクエストを受信し、各タスクを処理するエグゼキュータ・エージェントまたはツールを決定し、最終的な回答を調整します。

キャンバスでは、1つのスーパーバイザ・エージェントのみが許可されます。

エージェント エグゼキュータ・エージェント。各エグゼキュータには、データ取得、APIルックアップ、要約、ドキュメント質問の回答などの明確な専門性が必要です。

エージェント/エグゼキュータ・エージェントを単一のエージェント・システムに使用します。

ツール・テンプレート 個々のエグゼキュータまたはスーパーバイザ・エージェントにアタッチできる再利用可能な機能。ツールテンプレートには、SQL、RAG、Prompt、HTTP、Remote MCPサーバー、およびCustom Toolが含まれます。
開発/プレイグラウンド キャンバスの上のモード・セレクタ。開発は、エージェント・システムの編集中に使用されます。プレイグラウンドは、テスト・セッションの開始およびエージェントの動作の検査に使用されます。

プレイグラウンドでは、AIコンピュートがエージェントにアタッチされている必要があります。

ズーム・コントロール キャンバス・ズーム・セレクタスクリーンショットには、60%および90%のズーム・レベルが示されています。

エージェントの作成

管理権限を持つワークスペースにエージェントを作成できます。

  1. ホーム・ページで、ワークスペースに移動します。
  2. 左側のナビゲーション・ペインで「エージェント」をクリックします。
  3. 「エージェントの作成」アイコン 「エージェントの作成」をクリックするか、右上にある「作成」をクリックします。

    「エージェント」ページが表示されます。左側のナビゲーション・ペインのエージェントが強調表示されます。「エージェント・フローの作成」アイコンと「作成」ボタンが強調表示されています。

  4. エージェントの名前と説明を入力します。
  5. 「エージェント・フロー・オーサリング・モード」で、「ビジュアル・ビルダー」を選択します。

    「エージェント・プロジェクトの作成」ダイアログが表示されます。Visual Builder Radialオプションが強調表示されています。

  6. オプション: 「AIコンピュート」ドロップダウン・メニューから、エージェントに使用するコンピュートを選択します。
  7. 「作成」をクリックします。パレットからキャンバスにノードをドラッグして、エージェントの作成を開始します。

    ノート:

    最初のエージェント・ビルドをシンプルに開始します。1つのチャット・トリガー、1つのエグゼキュータ・エージェントです。ガードレール、追加のツール、さらにはマルチエージェントシステム設計など、最初のビルドを正常に実行した後、複雑さを増してください。

Visual Builderキャンバスへのチャット・トリガーおよびエージェントの追加

Visual Builderでエージェントを作成した後の最初のステップは、チャット・トリガーとスーパーバイザ・エージェントを追加することです。

トリガーはユーザー・メッセージを受信します。監督者は、リクエストを解釈し、作業を計画し、役員エージェントまたはツールに委任します。ノードをキャンバスにドラッグして構成し、後で接続できます。
  1. ワークスペースでエージェントにナビゲートします。
  2. チャット・トリガーをクリックして、パレットからキャンバスにドラッグします。ノードがキャンバスにメッセージとして表示されます。
  3. 「スーパーバイザ・エージェント」をクリックしてキャンバスにドラッグします。

    ビジュアル・ビルダー・キャンバスが表示され、チャット・トリガーとスーパーバイザ・エージェント・ノードが追加されます。

  4. チャット・トリガー・ノードでコネクタ・ハンドルをクリックしてドラッグし、エージェント・ノードに接続します。
スーパーバイザエージェントバッジには、接続されているエージェントとツールの数が表示されます。新しいビルドでは、スーパーバイザエージェントにエージェント(0)ツール(0)が表示されます。
Visual Builderキャンバス上のチャット・トリガーおよびスーパーバイザ・エージェント。スーパーバイザエージェントの下にあるバッジには、「エージェント(0)ツール(0)」と表示されます。

スーパーバイザエージェントの構成

スーパーバイザ・ロールの概要を説明する手順を使用して、Visual Builderキャンバスに追加されたスーパーバイザ・エージェントを構成する必要があります。

スーパーバイザエージェントは、次のフィールドで構成されています。
ビジュアル・ビルダーのキャンバスが表示されます。スーパーバイザエージェントが選択され、「構成」タブが表示されます。

フィールド 構成
エージェント名 スーパーバイザ・エージェントのわかりやすい名前を指定します。トレースおよびログを介してシステムの動作をデバッグするときに、わかりやすい名前を使用すると便利です。
エージェント摘要 エージェントの目的、役割および一般的な動作の説明を入力します。ドキュメント作成に役立ちます。
領域 スーパーバイザ・エージェントで使用されるOCI生成AIモデルがホストされるリージョンを選択します。リージョン別の生成AIモデルを参照してください。
モデル スーパーバイザが使用するOCI生成AIサービス・モデルを選択します。ドロップダウンには、選択したリージョンで使用可能なモデルがリストされます。
エージェントの指示 スーパーバイザ・ロール、ルーティング・ルール、委任ポリシー、ツール使用予想および最終応答フォーマットの説明。
  1. ワークスペース内のエージェントにナビゲートします。
  2. キャンバスで「スーパーバイザ・エージェント」ノードをクリックします。
  3. スーパーバイザエージェントのわかりやすい名前と説明を指定します。
  4. スーパーバイザが使用するOCI生成AIサービス・モデルのリージョンおよびモデルを入力します。
  5. スーパーバイザエージェントのエージェント命令を指定します。

推奨監督者インストラクション

スーパーバイザ・エージェントの「指示」フィールドを使用して、すべてのタスク自体を実行するのではなく、監督者がオーケストレーションを担当するようにしてください。

ルーティングの決定が予測可能になるように、指示を具体的に維持します。スーパーバイザの指示の例については、次を参照してください。

You are the supervisor for a multi-agent system.

Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.

Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.

スーパーバイザエージェントのメモリーと状態の分離を構成する

スーパーバイザ・エージェントの「メモリー」タブは、スーパーバイザが使用できる会話およびツール出力履歴の量と、エグゼキュータ・エージェントと共有されるコンテキストの量を制御します。

次のフィールドを使用して、スーパーバイザエージェントのメモリーおよび分離状態を構成します。
ビジュアル・ビルダーのキャンバスが表示されます。スーパーバイザエージェントが選択され、「メモリー」タブが表示されます。

フィールド 構成
エージェント・メモリーの有効化 ユーザーがマルチターン継続性を必要とする場合に有効にします。分離された1つの使用タスクに対して無効にします。

スーパーバイザエージェントでは、このフィールドを無効にできません。
会話履歴の制限 指定された制限に達した後にLLMコンテキスト・ウィンドウを切り捨てることを有効にします。すべての履歴を表示するには無効にしてください。
切捨て構成 「会話履歴の制限」が有効になっている場合は、このフィールドを使用して、コンテキスト・ウィンドウを切り捨てる条件を設定します。
オプションは次のとおりです:
  • 最後のNメッセージを保持
  • トークン予算
  • 両方
最大メッセージ制限およびトークン予算 「切捨て構成」の選択に応じて、これらのオプションの1つまたは両方が表示されます。

デフォルト値は20メッセージおよび5000トークンです。適度な値から開始し、必要に応じて調整することをお薦めします。
エグゼキュータ・エージェントの状態分離 「ステートレス」、「プライベート」または「共有」を選択します。
  • ステートレス: 各エグゼキュータ・エージェントには、スーパーバイザによって割り当てられたタスクのみが表示されます。コール間で履歴が繰り越されることはありません。これを選択すると、最強の分離と最少のエージェント間コンテキストが必要になります。
  • プライベート: 各エグゼキュータ・エージェントには、独自の過去の相互作用のみが表示されます。元のユーザー会話の他のエグゼキュータ・エージェントを表示できません。エグゼキュータが独自のタスクにわたって継続性を必要とするが、コンテキストを他のエージェントと共有する必要がない場合は、これを選択します。
  • 共有: エグゼキュータ・エージェントは、エージェントおよびユーザー間の完全な会話履歴を表示できます。すべてのエージェントは、1つの共有コンテキストから機能します。幅広いコンテキスト共有が必要で、プライバシおよび迅速なインジェクション・リスクを確認している場合は、これを選択します。
  1. ワークスペース内のエージェントにナビゲートします。
  2. キャンバスで「スーパーバイザ・エージェント」ノードをクリックします。
  3. 「メモリー」タブをクリックします。
  4. 「会話履歴の制限」を有効にするかどうかを選択します。「切捨て構成」を選択し、有効な場合は制限を設定します。
  5. 「エグゼキュータ・エージェントの状態分離」のオプションを選択します。

「モデル・パラメータ」タブ

「モデル・パラメータ」タブでは、選択したモデルで使用可能なモデル固有のパラメータを構成できます。

モデル・パラメータは、スーパーバイザおよびエグゼキュータ・エージェントに対して個別に構成できます。使用できるパラメータには、温度、トップK、トップP、および周波数ペナルティが含まれます。

ノート:

構成可能なパラメータを公開するのは、モデルのサブセットのみです。さらに、パラメータはモデルファミリによって異なります。

ビジュアル・ビルダーのキャンバスが表示されます。スーパーバイザエージェントが選択され、「モデルパラメータ」タブが表示されます。

エージェントへのガードレールの追加

1つ以上のガードレール・ノードをキャンバスに追加することで、保護のレイヤーをエージェントに追加できます。

デフォルトでは、選択したモデル・プロバイダがモデルにすぐに提供する以上のガードレールはエージェント・システムに適用されません。ガードレールは、チャット・トリガーとスーパーバイザ・エージェントの間に配置できるため、リクエストがスーパーバイザ・エージェントに到達する前、およびスーパーバイザ・エージェントがコール元にレスポンスを返す前にポリシーが適用されます。
ガードレール オプション 使用する状況
個人特定できる情報(PII)
  • 「入力」と「出力」のタブ
  • 個人、住所、電話番号、Eメールのチェックボックス
 フローがモデル処理の前または後に機密個人データをブロックまたはマスクする必要がある場合に使用します。
コンテンツのモデレーション防止 「ブロック」、「通知」および「許可」オプションがある入力行と出力行。 フローがヘイト、性的、暴力的、有毒、軽蔑的、または嫌がらせの内容をどのように処理するかを定義するために使用します。
プロンプトインジェクション検出 「ブロック」および「許可」オプションがある入力行。 悪意のある命令によってシステムまたはエージェントの命令がオーバーライドされる可能性を減らすために使用します。
ガードレール設定の詳細は、Guardrailsを参照してください。
  1. ワークスペース内のエージェントにナビゲートします。
  2. 「ガードレール」ノードをパレットからキャンバスにドラッグします。チャット・トリガー・ノードとスーパーバイザ・エージェント・ノードの間に配置します。
  3. 接続の上にカーソルを置き、赤いXをクリックして、チャット・トリガーとスーパーバイザ・エージェント間の接続を削除します。

    ビジュアル・ビルダー・キャンバスは、チャット・トリガー・ノード、スーパーバイザ・エージェント・ノードおよびガードレール・ノードとともに表示されます。赤い円に白いXが付いた矢印線は、チャット・トリガーとスーパーバイザ・ノードを接続します。

  4. チャット・トリガーのコネクタ・ハンドルをクリックし、ガードレール・ノードにドラッグします。次に、コネクタ・ハンドルをクリックして、GuardrailノードからSupervisor Agentにドラッグします。
  5. 「Guardrail」ノードをクリックして、「Configuration」ページを開きます。
  6. 入出力チェックに必要なアクションを選択するようにガードレールを構成します。

エージェントへのエグゼキュータ・エージェントおよびツールの追加

エグゼキュータエージェントをツールに追加して、スーパーバイザエージェント専用の作業を実行できます。

次の例では、監督者エージェントはAGENT_1とAGENT_2に委任します。AGENT_1は、SQL_1およびHTTP_1ツールに接続されています。
ビジュアル・ビルダーのキャンバスが表示されます。chatトリガーノードは、スーパーバイザノードに接続されているガードレールノードに接続されています。スーパーバイザノードは、AGENT_1とAGENT_2の2つのエージェントノードに接続されています。AGENT_1は、SQL_1とHTTP_1の2つのツール・ノードに接続されています。

  1. ワークスペース内のエージェントにナビゲートします。
  2. エージェント・ノードをパレットからキャンバスにドラッグします。エージェント・ノードは、Supervior Agentの下に配置する必要があります。
  3. 「ツール」をパレットからキャンバスにドラッグします。
  4. スーパーバイザ・エージェントのコネクタ・ハンドルをクリックしてドラッグし、エージェント・ノードに接続します。
  5. エージェントのコネクタ・ハンドルをクリックしてドラッグし、ツール・ノードに接続します。

実行者エージェント構成

エージェント・ノードは、「構成」、「メモリー」および「モデル」タブの設定を変更して、各エージェントの目的の定義に役立てることができます。

特定の機能および目標を指定してエージェントを絞り込んで構成し、スーパーバイザ・エージェントが確実に作業をルーティングできるようにする必要があります。
ビジュアル・ビルド・キャンバス。チャット・トリガー・ノードは、2つのエージェント・ノード(AGENT_1およびAGENT_2)に接続されているスーパーバイザ・エージェントに接続されます。AGENT_1は、SQL_1とHTTP_1の2つのツール・ノードに接続されています。

表17-1「エージェント構成」タブ

フィールド 構成
エージェント名 ベスト・プラクティスは、各エグゼキュータ・エージェントにSQL_AGENT、DOCUMENT_AGENT、API_AGENT、SUMMARY_AGENTなどの専門性に従って名前を付けることです。

各エグゼキュータ・エージェントの名前はスーパーバイザ・エージェントに表示されるため、わかりやすい名前を使用してください。
エージェント摘要 各エグゼキュータ・エージェントの詳細な説明を入力します。各エグゼキュータ・エージェントの説明は、スーパーバイザ・エージェントに表示されます。
領域 エージェントで使用されるOCI生成AIモデルがホストされるリージョンを選択します。リージョン別の生成AIモデルを参照してください。
モデル エージェントが使用するOCI生成AIサービス・モデルを選択します。ドロップダウン・メニューには、選択したリージョンで使用可能なモデルがリストされます。

エグゼキュータ・タスクに適合するモデルを選択します。エグゼキュータ・エージェントは、スーパーバイザ・エージェントと同じモデルを使用する必要はありません。
エージェントの指示 エグゼキュータが何をすべきか、どのツールを使用すべきか、どの出力構造を返すべきかを正確に記述します。

「エグゼキュータ・エージェント・メモリー」タブ

スーパーバイザエージェントに接続されているエグゼキュータエージェントの場合、エグゼキュータのメモリーはスーパーバイザノードに構成され、すべてのエグゼキュータエージェントに適用されます。

フィールド 構成
エージェント・メモリーの有効化 ユーザーがマルチターン継続性を必要とする場合に有効にします。分離された1つの使用タスクに対して無効にします。
会話履歴の制限 指定された制限に達した後にLLMコンテキスト・ウィンドウを切り捨てることを有効にします。すべての履歴を表示するには無効にしてください。
切捨て構成 「会話履歴の制限」が有効になっている場合は、このフィールドを使用して、コンテキスト・ウィンドウを切り捨てる条件を設定します。
オプションは次のとおりです:
  • 最後のNメッセージを保持
  • トークン予算
  • 両方
最大メッセージ制限およびトークン予算 「切捨て構成」の選択に応じて、これらのオプションの1つまたは両方が表示されます。

デフォルト値は20メッセージおよび5000トークンです。適度な値から開始し、必要に応じて調整することをお薦めします。
エグゼキュータ・エージェントの状態分離 「ステートレス」、「プライベート」または「共有」を選択します。
  • ステートレス: 各エグゼキュータ・エージェントには、スーパーバイザによって割り当てられたタスクのみが表示されます。コール間で履歴が繰り越されることはありません。これを選択すると、最強の分離と最少のエージェント間コンテキストが必要になります。
  • プライベート: 各エグゼキュータ・エージェントには、独自の過去の相互作用のみが表示されます。元のユーザー会話の他のエグゼキュータ・エージェントを表示できません。エグゼキュータが独自のタスクにわたって継続性を必要とするが、コンテキストを他のエージェントと共有する必要がない場合は、これを選択します。
  • 共有: エグゼキュータ・エージェントは、エージェントおよびユーザー間の完全な会話履歴を表示できます。すべてのエージェントは、1つの共有コンテキストから機能します。幅広いコンテキスト共有が必要で、プライバシおよび迅速なインジェクション・リスクを確認している場合は、これを選択します。

「エグゼキュータ・エージェント・モデル・パラメータ」タブ

「モデル・パラメータ」タブでは、選択したモデルで使用可能なモデル固有のパラメータを構成できます。

ノート:

構成可能なパラメータを公開するのは、モデルのサブセットのみです。パラメータは、モデルファミリによっても異なります。

パラメータの例には、温度、上位K、上位Pおよび頻度ペナルティがあります。モデル・パラメータは、スーパーバイザおよびエグゼキュータ・エージェントに対して個別に構成できます。

推奨されるエグゼキュータの指示

You are the SQL executor agent.

Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.

Visual Builderによるエージェントのチェックリスト

このリストをガイドとして使用して、Visual Builderを使用して構築されたエージェントに必要なすべてのコンポーネントを含めて構成したことを確認します。

チェックリストの作成

  • エージェントには、チャット・トリガー/メッセージの1つのエントリ・ポイントが必要です。
  • ガードレールは意図した位置で接続され、必要に応じて有効になります。トリガー・メッセージとエージェントの間にガードレールを挿入することをお薦めします。
  • スーパーバイザ・エージェントには、選択したリージョン、選択したモデルおよびオーケストレーション指示があります。エグゼクティブ・エージェントも同様です。
  • スーパーバイザ・エージェントの「メモリー」タブで、マルチエージェント・システムのメモリーを構成します。プライバシと継続性の要件に一致するエグゼキュータ状態分離を選択します。
  • 各エグゼキュータ・エージェントには、明確な専門性と狭い指示があります。
  • 各ツールは、それを使用するエージェントにのみアタッチされます。
  • ノードが切断されていません。
  • AIコンピューティングは、個々のツールをテストし、プレイグラウンド・エクスペリエンスを実行するためにエージェント・システムにアタッチされます。

表17-2一般的な問題

問題 発生の可能性 推奨されるアクション
スーパーバイザはエグゼキュータを呼び出しません スーパーバイザ命令が不明であるか、エグゼキュータが接続されていません。 明示的なルーティング・ルールを追加し、エグゼキュータ・ノードがスーパーバイザに接続されていることを確認します。
エグゼキュータは幅広い回答またはオフトピック回答を返します エグゼキュータの指示が一般的すぎます。 エグゼキュータ・ロールを狭くし、必要な出力構造を定義します。
ツールは使用されていません ツールが切断されているか、間違ったエージェントに接続されています。 ツール接続とエージェント・ツール数のバッジを確認してください。
ガードレールは起動しません ガードレールセクションは構成されていますが、有効になっていません。 guadrailsノードを開き、セクションのトグルがオンになっていることを確認します。
エージェント間のコンテキスト・リーク 状態分離が「共有」に設定されているか、メモリーが意図したよりも広い。 より厳密な分離にはステートレスまたはプライベートの分離を使用します。
フォローアップ質問がコンテキストを失う メモリーが無効になっているか、切捨てが攻撃的です。 メモリーを有効にし、最大メッセージ制限を調整します。

コードを介したエージェント

Oracle AI Data Platform WorkbenchのAIエージェントに独自のLangGraphコード・ベースを持ち込むか、エージェントのコーディング・エクスペリエンスを通じてプラットフォーム上で直接新しいLangGraphエージェントを作成できます。

AI Data Platform WorkbenchユーティリティのPythonライブラリaidputilsを使用して、基本モデルを構成し、システム・ツールをエージェントにインポートできます。helpputils APIリファレンスは、Oracle AI Data Platform WorkbenchのAidp-utils APIを参照してください。


Agent SkillsTestが「開発」タブで開きます。

コードを介してエージェントを作成するには、既存のコード・ファイルをアップロードするか、インライン・エディタを使用してエージェントでコード・ファイルを直接作成します。

エージェントのインライン・コード・エディタでは、次のコード・ファイル・タイプがサポートされます。
  • Python (.py)
  • JSON
  • TXT
  • CSV
  • PSV
  • SH
  • フォルダ

ファイル・セレクタ・ドロップダウン・リストをクリックすると、使用可能なコード・ファイルを表示およびナビゲートできます。


ファイル・セレクタ・ドロップダウン・リストが開いて強調表示されたエージェント・ページ

エントリおよび依存ファイル

エントリ・ファイルは、コードとして定義されたエージェントに必要なsetupメソッドおよびinvokeメソッドを持つクラスを持つコード・ファイルです。Oracle AI Data Platform Workbenchでは、コードを介してエージェントのエントリ・ファイルを設定する必要があります。

依存関係ファイルは、コードとして定義されているエージェントが必要とするサードパーティ・ライブラリを含むファイルです。依存性ファイルは通常、必要なサード・パーティ・ライブラリのリストを含むrequirements.txtファイルです。

ノート:

サード・パーティ・ライブラリは、「再生」ボタンをクリックしてエディタでコードをテストするとき、または「テスト」タブを使用してエージェントをテストするときにインストールされます。最初にコードをテストして、サードパーティ・ライブラリをインストールすることをお薦めします。ライブラリのインストール中のエラーが出力セルに表示されます。

Agentクラス

AgentBasicは、ステートフルLangGraphワークフローを使用して単純な会話エージェントを設定および呼び出すためのテンプレート・クラスです。これは、次の2つの主な方法で、最小限のエージェント開発に必要な構造を示しています。

  • setup(): エージェント・ワークフローを初期化し、グラフを定義します。
  • invoke(user_query, **kwargs): ユーザー・メッセージに対してエージェントを実行し、レスポンスを返します。

大規模なシステムに統合する前に、main()関数を使用して直接実行およびテストできます。

定義

class AgentBasic:
    def __init__(self) -> None:
        self.graph = None
    def setup(self) -> None:
        self.graph = StateGraph(MessagesState)
        self.graph.add_node(mock_llm)
        self.graph.add_edge(START, "mock_llm")
        self.graph.add_edge("mock_llm", END)
        self.graph = self.graph.compile()
        system_prompt = "Be a helpful assistant."
    async def invoke(self, user_query: str, **kwargs):
        user_message = HumanMessage(content=user_query)
        messages = {"messages": [dict(user_message)]}
        try:
            return self.graph.invoke(messages)
        except Exception as e:
            import traceback
            logger.error(f"Exception while calling invoke {e}", exc_info=True)
            print("Stack trace:\n", traceback.format_exc())

起動のテスト

このテスト呼出しは、初期機能テストに最適です。

ノート:

スタンドアロン・テストのメイン・エントリ・ポイントを含めます。 
import asyncio

async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
   asyncio.run(main())
機能:
  • スクリプトによってエージェントが作成され、エージェントが設定されて、サンプル・ユーザー・メッセージが送信されます。
  • エージェントが応答します({"messages": [{"role": "ai"、 "content": "hello world"}]})。

使用ガイド

setupメソッドおよびinvokeメソッドを使用してエージェント・クラスを作成します。

設定() エージェント・ワークフローを初期化します エージェントのセットアップ()
invoke() ユーザー・メッセージを使用してエージェントを実行します。 await agent.invoke("あなたの質問")
  • 非同期: invoke()は非同期メソッドです。awaitとともに使用するか、非同期ループで実行します。
  • テスト:付属のmain()ガード(if __name__ == "__main__":)により、デプロイメント前にエージェントを簡単にテストできます。

アップロードによるコードによるエージェントの作成

LangGraphコード・ベースをアップロードすることで、既存のコードでエンドツーエンドのエージェント・アプリケーションを構築できます。

Oracle AI Data Platform Workbenchは、LangGraphバージョン1.0.1をサポートしています。

ノート:

個々のファイルおよびフォルダは最大500ファイルまでアップロードでき、各ファイルのサイズは最大500MBです。アップロードは合計サイズが5GBに制限されています。
  1. ワークスペースでエージェントにナビゲートします。エージェント名をクリックします。
  2. 「アップロード」をクリックします。

    「アップロード」アイコンが強調表示されたエージェント・ページ

  3. ファイルをペインにドラッグ・アンド・ドロップするか、クリックして参照し、ファイルを選択します。
  4. 「アップロード」をクリックします。

新規コードの作成によるコードによるエージェントの構築

コード・エディタでコードを直接エージェントに作成することで、既存のコードを使用してエンドツーエンドのエージェント・アプリケーションを構築できます。

コード・エディタでは、次のファイル・タイプがサポートされています。
  • Python (.py)
  • JSON
  • TXT
  • CSV
  • PSV
  • SH
  • フォルダ
  1. ワークスペースでエージェントにナビゲートします。エージェント名をクリックします。
  2. 「Add new file」をクリックします。

    「Add new file」アイコンが強調表示された「Agent」ページ

  3. コード・ファイルの名前を入力します。
  4. ドロップダウンリストからファイルタイプを選択します。
  5. 「作成」をクリックします。

コードを使用したエージェントのエントリ・ファイルの設定

コードを介したAIエージェントには、エージェントに必要なクラス、設定および呼出しメソッドを持つエントリ・ファイルが必要です。

  1. ワークスペースでエージェントにナビゲートします。エージェント名をクリックします。
  2. 「コード・エディタ」タブで、左側のナビゲーション・ペインでエントリ・ファイルを見つけます。ファイルが存在しない場合は、「アップロード」をクリックしてアップロードするか、「新規ファイルの追加」をクリックして作成できます。
  3. エントリ・ファイルを右クリックし、「エントリ・ファイルの設定」をクリックします。ファイルを選択して、コード・エディタの右上にある「エントリ・ファイルの設定」ボタンをクリックすることもできます。

    エージェント・コード・エディタが開き、ファイルが左ペインで選択されています。セット・エントリ・ファイルは、右クリック・メニューとコード・エディタの右上に表示されます。

コードを使用したエージェントの依存関係ファイルの設定

コードが依存しているサード・パーティ・ライブラリを含むコードを介してエージェント・フローの依存性ファイルを設定する必要があります。

  1. ワークスペースでエージェントにナビゲートします。エージェント名をクリックします。
  2. 「コード・エディタ」タブで、左側のナビゲーション・ペイン(通常はrequirements.txt)で依存性ファイルを見つけます。ファイルが存在しない場合は、「アップロード」をクリックしてアップロードするか、「新規ファイルの追加」をクリックして作成できます。
  3. 依存性ファイルを右クリックし、「依存性の設定」をクリックします。ファイルを選択し、コード・エディタの右上にある「依存性ファイルの設定」ボタンをクリックすることもできます。

    ファイルが選択された状態でエージェント・コード・エディタ・タブが開きます。Set依存性ファイルとSet依存性ファイルが強調表示されます。

テストエージェントコード

「テスト」タブからエージェントに使用されるコードをテストして、コードを検証およびデバッグできます。

テストするには、エージェントにAIコンピュートがアタッチされている必要があります。
  1. ワークスペースでエージェントにナビゲートします。エージェント名をクリックします。
  2. 「プレイグラウンド」タブをクリックします。

    エージェント・ページが開いてトリミングされ、ページの上部にタブのみが表示されます。「Playground」タブが強調表示されています。

  3. 「再生」をクリックして、選択したコード・ファイルをテストします。

    「エージェント・コード・エディタ」タブが開き、AIコンピュート、再生ボタンおよびテスト出力フレームが強調表示されています

コード・エディタ・ウィンドウの下半分にある出力セルには、コード内のprint文またはlogging文の出力が表示されます。エラーは出力セルにも表示されます。

コーディング・エクスペリエンスにおけるエージェント・スキル

エージェント・スキルを使用すると、エージェントは、そのドメイン・ナレッジをエージェントの指示にハードコードすることなく、タスク固有の指示、参照ファイル、テンプレート、アセットおよびオプションの実行可能スクリプトを検出して使用できます。

スキルは、エージェント・コード・ベースにフォルダとして格納されます。各スキルには、スキルの動作およびエージェントによるスキルの使用方法を説明する必要なSKILL.mdファイルがあります。スキルには、スキーマ、例、プロンプト、テンプレート、アセット、スクリプトなどのサポート・ファイルを含めることもできます。

詳細は、エージェント・スキルの概要を参照してください。

エージェント・スキルは、プログレッシブな開示モデルをサポートします。
  1. エージェントは、スキルが存在することを検出します。
  2. エージェントは、スキルが関連している場合にのみスキルをアクティブ化します。
  3. エージェントは、必要な場合にのみスキル・フォルダから追加のファイルをロードします。
  4. スキルで許可されている場合、エージェントは明示的に宣言されたスキル・エントリポイントを実行できます。

エージェント・スキルを使用するタイミング

スキルは、次のような再利用可能なエージェント機能をパッケージ化する場合に使用する必要があります。
  • ドメイン固有の手順
  • コーディングまたはデータ分析ワークフロー
  • SQL生成ガイダンス
  • ビジネス・プロセス・プレイブック
  • ファイル・テンプレート
  • スキーマ・リファレンス
  • 安全な計算、変換または参照のための再利用可能なスクリプト
スキルは、エージェントが専門的かつ再利用可能なナレッジにアクセスする必要があるが、そのすべてのナレッジをエージェント・プロンプトに直接配置したくない場合に役立ちます。

実行時のスキルの動作

実行時に、ホスト・アプリケーションは、プロジェクト・レベル・スキル・フォルダやユーザー・レベル・スキル・フォルダなど、使用可能なスキル・ディレクトリを決定します。このプラットフォームは、各スキルのメタデータをSKILL.mdからロードし、スキル名をキーとするカタログを構築します。

その後、エージェントはスキル関連のツールを使用できます。

ツール 目 的
activate_skill(name) スキル指示をSKILL.mdからロードします。
list_skill_files(name, path) スキル・フォルダ内で使用可能なファイルをリストします。
load_skill_file(name, path) スキル・フォルダからサポート・ファイルをロードします。
run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds) スキルで許可されている場合、明示的に宣言されたPythonエントリポイントを実行します。

環境によっては、使用可能なスキルのサマリーをシステム・プロンプトに直接埋め込む場合もあります。この設定では、エージェントはプロンプトから使用可能なスキルを検出し、完全な指示が必要な場合はactivate_skillを使用できます。

スキル・フォルダ構造

スキルでは、エージェント・スキル形式のフォルダ・レイアウトが使用されます:

<skills_dir>/
	some-skill/
		SKILL.md
		references/
		...
		scripts/
		...
		assets/
		...

SKILL.mdのみが必要です。その他のフォルダはオプションです。

フォルダまたはファイル 必須 目 的
SKILL.md ○ 主なスキル・メタデータおよびインストラクション。
references/ × サポート・ドキュメント、スキーマ、例またはテンプレート。
scripts/ × エントリポイントとして明示的に宣言された場合にのみ実行できるPythonスクリプト。
assets/ × スキルで使用される静的アセット。

SKILL.mdの書込み

各スキルには、SKILL.mdの上部にYAMLフロント・マターが含まれ、その後にマークダウン指示が続く必要があります。

基本的な例

---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
  owner: data-platform
  domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---

# SQL Helper

Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.

Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.

表17-3サポートされているフロントマッタのフィールド

フィールド 必須 説明
name ○ カタログおよびツールで使用される一意のスキル名。
description ○ 検出およびルーティングに使用される簡単な説明。
license × スキルのライセンスまたは使用ポリシー。
互換性 × サポートされているランタイムまたはプラットフォームの互換性に関するノート。
metadata × 文字列から文字列へのメタデータ・マップ。
許可されたツール × このスキルで許可されるツールのスペース区切りリスト。
エントリポイント × スキルによって宣言された実行可能エントリポイントのリスト。

サポート・ファイルの追加

サポート・ファイルを使用すると、スキルは詳細なコンテンツをメインの指示の外部に保持できます。これにより、SKILL.mdは集中力を維持しながら、エージェントはより豊かなコンテキストにアクセスできるようになります。たとえば:

skills/
	sql-helper/
		SKILL.md
		references/
			warehouse_schema.md
			query_style_guide.md
			examples.md

エージェントは次の方法でこれらのファイルを検査できます。

list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")
次のようなコンテンツにサポート・ファイルを使用します。
  • データベース・スキーマ
  • APIの例
  • プロンプト・テンプレート
  • スタイルガイド
  • ドメイン用語集
  • ステップバイステップ方式のプレイブック
  • テスト・ケースまたは例

実行可能スキルの作成

スキルは、オプションで、run_skill_entrypointを介して再利用可能な実行可能動作を公開できます。これは、計算、変換、検証、構造化データのフェッチなどの制御操作を対象としています。

実行可能スキルは、次の2つの要件を満たす必要があります。
  1. スキルでは、許可されたツールにrun_skill_entrypointを含める必要があります。
  2. スクリプトは、SKILL.mdのエントリポイント・セクションで明示的に宣言する必要があります。

実行可能スキルの例

skills/
	statistics-helper/
		SKILL.md
		scripts/
			summarize_numbers.py

スキルmd

---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: summarize_numbers
    script: scripts/summarize_numbers.py
    func: run
    description: Returns count, min, max, mean, and median for a list of numbers.
---

# Statistics Helper

Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median

def run(*, values: list[float]) -> dict:
    if not values:
        raise ValueError("values must not be empty")

    return {
        "count": len(values),
        "min": min(values),
        "max": max(values),
        "mean": mean(values),
        "median": median(values),
    }
Example invocation:
run_skill_entrypoint(
  name="statistics-helper",
  entrypoint="summarize_numbers",
  args_json="{\"values\": [10, 20, 30, 40]}",
  timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.

実行可能エントリポイントのルール

実行可能なエントリポイントは意図的に制約されます。プラットフォームは、次のPythonファイルのみを実行します。
  • スキルのscripts/ディレクトリの下にあります
  • スキルのエントリ・ポイント・フロントマターで宣言されます
  • スキルのallowed-tools設定で許可されます

このプラットフォームでは、汎用的な任意のスクリプト実行は提供されません。SKILL.mdで宣言されていないスクリプトは実行できません。

スクリプトランナーはタイムアウトを使用し、デフォルトは10秒で、分離モード動作で Pythonを実行し、パスの制限を適用します。ただし、サブプロセスベースの実行は完全なオペレーティング・システム・サンドボックスではありません。本番環境では、コンテナ、制限付きファイルシステム、ネットワーク制御などの高い分離を考慮する必要があります。

allowed-toolsを使用したツール権限

allowed-toolsは、スキル・レベルの権限ゲートとして機能します。ドキュメンテーションのみのスキルの場合、ファイル読取りツールのみを許可できます: 

allowed-tools: "load_skill_file list_skill_files"

宣言されたスクリプトを実行できるスキルの場合は、run_skill_entrypointを含めます: 

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"

スキルに実行可能な動作が本当に必要でないかぎり、run_skill_entrypointを追加しないでください。

エージェントがスキルを発見して使用できるようにする方法

スキルをエージェントに補足するには、スキル・カタログ、スキル・ミドルウェアをインスタンス化し、aidpUtilsライブラリの次のオブジェクトを使用してスキルをツールに変換する必要があります。

ツール 目 的
discover_skill_catalog デフォルトのスキル検索場所を決定する(プロジェクト+ユーザー)検出されたディレクトリからSkillCatalogを作成する
SkillMiddleware 使用可能なスキル・サマリーおよびルーティング・ルールをシステム・プロンプトに追加します。

ワークスペース主導のミドルウェア構築のためのファクトリ・ヘルパーを提供します。

make_skill_tools このメソッドは、スキル検出ツール(activate_skill、list_skill_files、load_skill_fileおよびrun_skill_entrypoint)を返します。これらのツールは、エージェントが様々なスキルをアクティブ化して実行するために使用できます。

次に、エントリ・ファイルに含まれる内容の例を示します。 

from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
	...
	def init(self) -> None: 
		...
		self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
		self.skill_middleware = SkillMiddleware(self.catalog)
		self.tools = make_skill_tools(self.catalog)

このロガー文をコードに追加することで、スキル・カタログをデバッグできます。これにより、スキル・カタログで検出されたすべてのスキルが出力されます。

for info in self.catalog.list():
	logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)

スキル優先順位

このプラットフォームは、プロジェクト・レベル・ディレクトリやユーザー・レベル・ディレクトリなど、複数の場所からスキルをロードできます。カタログでは、これらの場所が単一の名前キー付きスキルのリストに集約されます。

複数のストアに同じ名前のスキルが含まれている場合、優先度によって使用されるスキルが決まります。後のストアでは以前のストアがオーバーライドされるため、ホスト・アプリケーションはユーザー・レベルのスキル、プロジェクト・レベルのスキルまたはワークスペース・レベルのスキルを優先するかどうかを制御できます。

スキル作成のベスト・プラクティス

SKILL.mdを重視

アクティブ化直後にエージェントが必要とするコア命令にはSKILL.mdを使用します。長いスキーマ、例および参照資料を参照/に配置します。

明確な説明を書く

説明フィールドは、検出に使用されます。スキルをアクティブ化するタイミングをエージェントが把握できるよう特定します。

良: 
description: Helps generate BigQuery SQL using the finance warehouse schema.
役に立たない: 
description: Helps with data.

明示的なエントリポイント名の使用

エントリポイント名は、操作を明確に記述する必要があります。 
entrypoints: 
   - name: validate_query 
   - name: summarize_numbers 
   - name: transform_csv
次のような曖昧な名前は避けてください。 
entrypoints: 
   - name: run 
   - name: do_it

構造化結果を返す

実行可能スクリプトは、可能な場合は常にJSONシリアライズ可能な結果を返す必要があります。これにより、エージェントが出力を検査して使用しやすくなります。

不要な実行を回避

可能な場合は、指示および参照ファイルを優先します。実行可能エントリポイントは、コードが本当に必要である操作にのみ使用します。

新規スキルの追加

新しいエージェント・スキルを追加するには、スキル・ディレクトリ内に新しいフォルダを作成し、必要なファイルおよびフォルダを追加します。

  1. スキル・ディレクトリの下にフォルダ.agents/skills/<skill-name>/を作成します。
  2. 必要なフロントマッターを含むSKILL.mdファイルを追加します。
    ---
name: <skill-name>
description: <what this skill helps the agent do>
---
  3. フロントマターの下のMarkdownにスキルの指示を記述します。
  4. 次の下にオプションのサポート・ファイルを追加します。 
    references/
assets/
scripts/
  5. スキルが実行可能な場合は、run_skill_entrypointをallowed-toolsに追加し、SKILL.mdでentrypointsを宣言して、Python実装をscripts/に配置します。

既存のスキルへの新しい実行可能機能の追加

既存のスキルに新しい実行可能操作を追加して、SKILL.mdの機能を拡張できます。

  1. 1. スキルのscripts/ディレクトリの下にPythonファイルを追加します。
    .agents/skills/<skill-name>/scripts/my_operation.py
  2. 2. run(...)ファンクションを実装します。
    def run(*, input_text: str) -> dict:
    return {
        "length": len(input_text),
        "uppercase": input_text.upper(),
    }
  3. 3. 一致するエントリ・ポイントをSKILL.mdに追加します。
    allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: my_operation
    script: scripts/my_operation.py
    func: run
    description: Processes input text and returns structured output.
  4. 4. 引数としてJSONオブジェクトを使用してエントリポイントをテストします。
    {
  "input_text": "hello"
}

エージェント・スキルのトラブルシューティング

エージェント・スキルの実装で問題が発生した場合は、このリストをチェックして問題の解決に役立ててください。

エージェントに自分のスキルが表示されません

次の点を確認してください。
  • スキル・フォルダは、構成されたスキル・ディレクトリの下にあります。
  • フォルダにはSKILL.mdが含まれます。
  • SKILL.mdには有効なYAMLフロント・マターがあります。
  • フロントマッターには名前と説明の両方が含まれています。

エージェントは誤ったスキルをアクティブ化します

スキル・ディレクトリ間で重複するスキル名がないかチェックします。2つのスキルが同じ名前の場合、使用するスキルはカタログの優先順位によって決まります。

サポート・ファイルをロードできません

次の点を確認してください。
  • ファイルはスキル・フォルダ内にあります。
  • パスには../などのトラバースは含まれません。
  • ファイルは非表示になりません。
  • __pycache__や.pycなどのファイルは除外されません。

エントリポイントは実行されません

次のことを確認してください。
  • run_skill_entrypointは、allowed-toolsに含まれています。
  • エントリポイントはSKILL.mdで宣言されます。
  • スクリプト・パスはscripts/の下にあります。
  • スクリプトは.pyファイルです。
  • 関数名がスクリプトに存在します。
  • 引数は有効なJSONオブジェクトです。

エントリポイントがタイムアウトする

操作に時間がかかることが予想される場合にのみ、timeout_secondsを増やします。長時間実行またはリソース集中型の操作の場合は、操作を専用サービスまたはより分離された実行環境に移動することを検討してください。

例: エージェント・スキルの完了

この例では、実装後の完全なエージェント・スキルがどのように表示されるかを示します。

フォルダ構造

skills/
	customer-support-reply/
		SKILL.md
		references/
			tone_guide.md
			refund_policy.md
			escalation_rules.md

スキルmd

---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
  owner: support-operations
  domain: customer-support
---

# Customer Support Reply

Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.

Workflow:

1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.

エージェントのテスト

エージェントをテストして、その出力をプレビューおよびデバッグできます。また、テスト・セッションを作成および管理して、エージェントの様々なテスト・シナリオを調べることもできます。

エージェントをテストする最初のステップは、エージェントをAIコンピュートにアタッチすることです。エージェントをアタッチするアクションは、エージェントのコピーをAIコンピュートにプッシュします。エージェントがAIコンピュートにアタッチされているかぎり、「テスト」ボタンをクリックするたびに、エージェントに加えた変更がアタッチされたコンピュートに伝播されます。

「テスト」ボタンをクリックすると、テスト・プレイグラウンドに移動します。


エージェント・ページがテスト・プレイグラウンドに開きます。「チャット」、「トレース」、「スパン」および「エクスプローラ」ペインが強調表示されます。

テスト・プレイグラウンドには次のコンポーネントがあります。
  • セッションを開始してエージェントとのチャットを開始したり、既存のセッションを再開できるチャット・ウィンドウ
  • エージェントのグラフベースの表現
  • セッション中に生成されたトレースおよびスパンのツリーを示すパネル
  • トレースおよびスパン属性、入出力を表示するトレースおよびスパン・エクスプローラ・パネル。「詳細」タブにはID、開始時間および終了時間、実行時間が含まれ、「イベント」タブには実行中のエラーがハイライト表示されます。

Playgroundでは、必要に応じて各エージェントを個別に操作およびテストできます。デフォルトでは、スーパーバイザ・エージェントが選択されていますが、各エグゼキュータ・エージェントとのチャットおよびテストを個別に選択できます。これにより、エグゼキュータ・エージェントにリクエストを発行するスーパーバイザ・エージェントの動作をシミュレートできます。これを行うには、チャット・ウィンドウのドロップダウン・メニューでテストするエージェントを選択します。

最初のメッセージを作成するとすぐに、トレースとスパンが中央パネルに表示されます。各タスクは、異なるユーザー・メッセージに対応しています。左側のキャレットをクリックすると、トレースを展開してスパンを検査できます。

プレイグラウンドでのエージェントのテスト

テスト・プレイグラウンドからビジュアル・ビルダーおよびLangGraphベースのエージェントをテストして、エージェントを検証およびデバッグできます。

テストするには、エージェントにAIコンピュートがアタッチされている必要があります。「エージェントのAIクラスタの作成」に従って新しいAIコンピュート・クラスタを追加するか、「エージェントへの既存のAIクラスタのアタッチ」に従って既存のAIコンピュート・クラスタをアタッチできます。
  1. ワークスペースでエージェントにナビゲートします。エージェント名をクリックします。
  2. キャンバスの上部で、「プレイグラウンド」をクリックします。アタッチされたコンピュートにエージェントをプッシュするのに数秒かかる場合があります。

    「プレイグラウンド」ボタンが強調表示されたエージェント・キャンバスの上部

エージェントがテスト・プレイグラウンドに表示されます。

エージェントのテスト・セッションの作成

テスト・セッションを作成して、エージェントとの新しい会話を開始できます。

エージェントがアタッチされたコンピュートでホストされる、テスト・プレイグラウンド・ターゲットで作成されたすべてのセッション。セッションが作成されると、後で再開できます。
  1. ワークスペースでエージェントにナビゲートします。エージェント名をクリックします。
  2. キャンバスの上部にある「プレイグラウンド」をクリックします。
  3. セッション・セレクタで、「Create session」アイコン 「セッションの作成」をクリックします。

    エージェントが開き、「プレイグラウンド」タブが選択されています。「テスト・セッションの作成」ボタンと「セッション」ドロップダウン・メニューの両方が強調表示されています。

  4. チャットボックスにクエリーを入力して、エージェントとのダイアログを開始します。

    チャット・ボックスが強調表示されたエージェント・テスト・プレイグラウンド・チャット・セッション・ページ

エージェント・テスト・セッションの再開

以前に作成したエージェント・テスト・セッションを再開できます。

ノート:

作成したセッションのみ再開できます。
  1. ワークスペースでエージェントにナビゲートします。エージェント名をクリックします。
  2. キャンバスの上部にある「プレイグラウンド」をクリックします。
  3. 「セッション」ドロップダウンから、前のセッションを選択します。

    チャット・ペインが強調表示されたエージェント・テスト・プレイグラウンド。複数のセッションが表示されます。

  4. チャット・ボックスに問合せを入力して、エージェントとのダイアログを再開します。

エージェント・テスト・セッションの削除

アタッチされたAIコンピュートでホストされているエージェントのテスト・セッションと、デプロイされたエージェントに作成されたセッションを削除できます。

  1. ワークスペースでエージェントにナビゲートします。
  2. 「セッション」タブをクリックします。

    「エージェント・セッション」タブが開き、「セッション」タブが強調表示されています

  3. 削除するセッションの横にあるアクションの3つのドット・アイコン 「アクション」をクリックし、「削除」をクリックします。

    セッションIDの「アクション」メニューが開き、「削除」アクションが強調表示された「エージェント・セッション」タブ

  4. 「削除」をクリックします