22 AIエージェント
この章では、ワークスペースでエージェントを作成、テスト、デプロイおよび監視する方法について説明します。
エージェントは、エンドツーエンドのエージェント・アプリケーションです。エージェントは、様々なタイプのノード(トリガー、エージェント、ガードレールまたはツール)で表されるステップのグラフによって定義されます。エージェントは、コードなしのビジュアル・フロー・ビルダーおよびLangGraphなどのサード・パーティ・ライブラリを介したコードを介して定義できます。
- カスタム・ツール: カスタム・コード・ツールを使用すると、エージェント開発者は独自のPythonコードを使用してAIデータ・プラットフォームを拡張できます。ツール実装をZIPファイルとしてパッケージ化し、ワークスペースにアップロードして構成します。エージェントは、実行時にLLMによって提供されるパラメータを使用して、コードをツールとしてコールします。
- HTTP: HTTPリクエスト・ツールを使用すると、エージェントは任意のHTTPS REST APIをコールできます。メソッド、URL、ヘッダー、問合せパラメータ、リクエスト本文、認証、およびオプションでレスポンス最適化ステップを含むリクエストを構成します。その後、エージェントは実行時にエンドポイントを呼び出します。HTTPリクエスト・ツールは、ビジュアル・ビルダーとコード・ビルダーの両方で使用できます。コード・ビルダーでは、このツールはaidpUtils Pythonライブラリを介して構成されます。
- プロンプト: プロンプト・ツールを使用すると、AI開発者は、選択したLLMに発行できるパラメータ化されたプロンプトを定義できます。プロンプト・ツールの一般的なユース・ケースには、電子メール作成タスク、翻訳タスク、スタイル変換、gitコミット・メッセージ、コードの説明などがあります。
- リモートMCPサーバー: エージェント開発者は、リモートMCPサーバー・ツールを使用して、エージェントをリモート・モデル・コンテキスト・プロトコル(MCP)サーバーに接続できます。
- RAG: RAGツールを使用すると、エージェントは、レスポンスを生成する前に関連する外部ナレッジを取得できます。AIデータ・プラットフォーム・ワークベンチでは、RAGツールがナレッジ・ベース(23ai Vector Search)を問い合せて、意味に関連するドキュメント・チャンクを取得します。これらのチャンクは、レスポンス生成のためにエージェントに渡されます。
- SQL: SQLツールを使用すると、エージェントは、Oracle Autonomous AI Lakehouse、Oracle Autonomous AI Transaction Processing、Oracle AI Databaseなどの外部カタログを介して登録された構造化データ・ソースに対してSQLクエリを実行できます。このツールは、SQL問合せが事前定義され、パラメータ化できるシナリオを対象としています。目的は、エージェントがパラメータに値を割り当てるようにすることです。このツールは、自然言語プロンプトに基づいてSQL問合せを生成するNL2SQLツールではありません。
ノート:
SQLツールは、外部カタログのデータに対してのみ問合せを実行します。標準カタログに格納されたデータはサポートされません。
ノート:
システム・ツールをテストする前に、エージェントにAIコンピュートをアタッチする必要があります。コンピュートがアタッチされていない場合、「テスト」タブは無効になります。AI Data Platform Workbenchでエージェントを作成すると、選択したワークスペース・フォルダにエージェント・アーティファクト・ファイル(.aflow)が生成されます。このファイルは変更できません。
マルチエージェント・システムとスーパーバイザ・パターン
マルチエージェント・システムは、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%のズーム・レベルが示されています。 |
エージェントの作成
管理権限を持つワークスペースにエージェントを作成できます。
「エージェントの作成」をクリックするか、右上にある「作成」をクリックします。
- 「エージェント・フロー・オーサリング・モード」で、「ビジュアル・ビルダー」を選択します。
Visual Builderキャンバスへのチャット・トリガーおよびエージェントの追加
Visual Builderでエージェントを作成した後の最初のステップは、チャット・トリガーとスーパーバイザ・エージェントを追加することです。
- 「スーパーバイザ・エージェント」をクリックしてキャンバスにドラッグします。
スーパーバイザエージェントの構成
スーパーバイザ・ロールの概要を説明する手順を使用して、Visual Builderキャンバスに追加されたスーパーバイザ・エージェントを構成する必要があります。
| フィールド | 構成 |
|---|---|
| エージェント名 | スーパーバイザ・エージェントのわかりやすい名前を指定します。トレースおよびログを介してシステムの動作をデバッグするときに、わかりやすい名前を使用すると便利です。 |
| エージェント摘要 | エージェントの目的、役割および一般的な動作の説明を入力します。ドキュメント作成に役立ちます。 |
| 領域 | スーパーバイザ・エージェントで使用されるOCI生成AIモデルがホストされるリージョンを選択します。リージョン別の生成AIモデルを参照してください。 |
| モデル | スーパーバイザが使用するOCI生成AIサービス・モデルを選択します。ドロップダウンには、選択したリージョンで使用可能なモデルがリストされます。 |
| エージェントの指示 | スーパーバイザ・ロール、ルーティング・ルール、委任ポリシー、ツール使用予想および最終応答フォーマットの説明。 |
- ワークスペース内のエージェントにナビゲートします。
- キャンバスで「スーパーバイザ・エージェント」ノードをクリックします。
- スーパーバイザエージェントのわかりやすい名前と説明を指定します。
- スーパーバイザが使用するOCI生成AIサービス・モデルのリージョンおよびモデルを入力します。
- スーパーバイザエージェントのエージェント命令を指定します。
推奨監督者インストラクション
スーパーバイザ・エージェントの「指示」フィールドを使用して、すべてのタスク自体を実行するのではなく、監督者がオーケストレーションを担当するようにしてください。
ルーティングの決定が予測可能になるように、指示を具体的に維持します。スーパーバイザの指示の例については、次を参照してください。
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コンテキスト・ウィンドウを切り捨てることを有効にします。すべての履歴を表示するには無効にしてください。 |
| 切捨て構成 | 「会話履歴の制限」が有効になっている場合は、このフィールドを使用して、コンテキスト・ウィンドウを切り捨てる条件を設定します。
オプションは次のとおりです:
|
| 最大メッセージ制限およびトークン予算 | 「切捨て構成」の選択に応じて、これらのオプションの1つまたは両方が表示されます。
デフォルト値は20メッセージおよび5000トークンです。適度な値から開始し、必要に応じて調整することをお薦めします。 |
| エグゼキュータ・エージェントの状態分離 | 「ステートレス」、「プライベート」または「共有」を選択します。
|
- ワークスペース内のエージェントにナビゲートします。
- キャンバスで「スーパーバイザ・エージェント」ノードをクリックします。
- 「メモリー」タブをクリックします。
- 「会話履歴の制限」を有効にするかどうかを選択します。「切捨て構成」を選択し、有効な場合は制限を設定します。
- 「エグゼキュータ・エージェントの状態分離」のオプションを選択します。
「モデル・パラメータ」タブ
「モデル・パラメータ」タブでは、選択したモデルで使用可能なモデル固有のパラメータを構成できます。
モデル・パラメータは、スーパーバイザおよびエグゼキュータ・エージェントに対して個別に構成できます。使用できるパラメータには、温度、トップK、トップP、および周波数ペナルティが含まれます。
ノート:
構成可能なパラメータを公開するのは、モデルのサブセットのみです。さらに、パラメータはモデルファミリによって異なります。
エージェントへのガードレールの追加
1つ以上のガードレール・ノードをキャンバスに追加することで、保護のレイヤーをエージェントに追加できます。
| ガードレール | オプション | 使用する状況 |
|---|---|---|
| 個人特定できる情報(PII) |
|
フローがモデル処理の前または後に機密個人データをブロックまたはマスクする必要がある場合に使用します。 |
| コンテンツのモデレーション防止 | 「ブロック」、「通知」および「許可」オプションがある入力行と出力行。 | フローがヘイト、性的、暴力的、有毒、軽蔑的、または嫌がらせの内容をどのように処理するかを定義するために使用します。 |
| プロンプトインジェクション検出 | 「ブロック」および「許可」オプションがある入力行。 | 悪意のある命令によってシステムまたはエージェントの命令がオーバーライドされる可能性を減らすために使用します。 |
- 接続の上にカーソルを置き、赤いXをクリックして、チャット・トリガーとスーパーバイザ・エージェント間の接続を削除します。
エージェントへのエグゼキュータ・エージェントおよびツールの追加
エグゼキュータエージェントをツールに追加して、スーパーバイザエージェント専用の作業を実行できます。
- ワークスペース内のエージェントにナビゲートします。
- エージェント・ノードをパレットからキャンバスにドラッグします。エージェント・ノードは、Supervior Agentの下に配置する必要があります。
- 「ツール」をパレットからキャンバスにドラッグします。
- スーパーバイザ・エージェントのコネクタ・ハンドルをクリックしてドラッグし、エージェント・ノードに接続します。
- エージェントのコネクタ・ハンドルをクリックしてドラッグし、ツール・ノードに接続します。
実行者エージェント構成
エージェント・ノードは、「構成」、「メモリー」および「モデル」タブの設定を変更して、各エージェントの目的の定義に役立てることができます。
特定の機能および目標を指定してエージェントを絞り込んで構成し、スーパーバイザ・エージェントが確実に作業をルーティングできるようにする必要があります。
表22-1「エージェント構成」タブ
| フィールド | 構成 |
|---|---|
| エージェント名 | ベスト・プラクティスは、各エグゼキュータ・エージェントにSQL_AGENT、DOCUMENT_AGENT、API_AGENT、SUMMARY_AGENTなどの専門性に従って名前を付けることです。
各エグゼキュータ・エージェントの名前はスーパーバイザ・エージェントに表示されるため、わかりやすい名前を使用してください。 |
| エージェント摘要 | 各エグゼキュータ・エージェントの詳細な説明を入力します。各エグゼキュータ・エージェントの説明は、スーパーバイザ・エージェントに表示されます。 |
| 領域 | エージェントで使用されるOCI生成AIモデルがホストされるリージョンを選択します。リージョン別の生成AIモデルを参照してください。 |
| モデル | エージェントが使用するOCI生成AIサービス・モデルを選択します。ドロップダウン・メニューには、選択したリージョンで使用可能なモデルがリストされます。
エグゼキュータ・タスクに適合するモデルを選択します。エグゼキュータ・エージェントは、スーパーバイザ・エージェントと同じモデルを使用する必要はありません。 |
| エージェントの指示 | エグゼキュータが何をすべきか、どのツールを使用すべきか、どの出力構造を返すべきかを正確に記述します。 |
「エグゼキュータ・エージェント・メモリー」タブ
スーパーバイザエージェントに接続されているエグゼキュータエージェントの場合、エグゼキュータのメモリーはスーパーバイザノードに構成され、すべてのエグゼキュータエージェントに適用されます。
| フィールド | 構成 |
|---|---|
| エージェント・メモリーの有効化 | ユーザーがマルチターン継続性を必要とする場合に有効にします。分離された1つの使用タスクに対して無効にします。 |
| 会話履歴の制限 | 指定された制限に達した後にLLMコンテキスト・ウィンドウを切り捨てることを有効にします。すべての履歴を表示するには無効にしてください。 |
| 切捨て構成 | 「会話履歴の制限」が有効になっている場合は、このフィールドを使用して、コンテキスト・ウィンドウを切り捨てる条件を設定します。
オプションは次のとおりです:
|
| 最大メッセージ制限およびトークン予算 | 「切捨て構成」の選択に応じて、これらのオプションの1つまたは両方が表示されます。
デフォルト値は20メッセージおよび5000トークンです。適度な値から開始し、必要に応じて調整することをお薦めします。 |
| エグゼキュータ・エージェントの状態分離 | 「ステートレス」、「プライベート」または「共有」を選択します。
|
「エグゼキュータ・エージェント・モデル・パラメータ」タブ
「モデル・パラメータ」タブでは、選択したモデルで使用可能なモデル固有のパラメータを構成できます。
ノート:
構成可能なパラメータを公開するのは、モデルのサブセットのみです。パラメータは、モデルファミリによっても異なります。パラメータの例には、温度、上位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コンピューティングは、個々のツールをテストし、プレイグラウンド・エクスペリエンスを実行するためにエージェント・システムにアタッチされます。
表22-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を参照してください。
コードを介してエージェントを作成するには、既存のコード・ファイルをアップロードするか、インライン・エディタを使用してエージェントでコード・ファイルを直接作成します。
- 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コード・ベースをアップロードすることで、既存のコードでエンドツーエンドのエージェント・アプリケーションを構築できます。
ノート:
個々のファイルおよびフォルダは最大500ファイルまでアップロードでき、各ファイルのサイズは最大500MBです。アップロードは合計サイズが5GBに制限されています。- 「アップロード」をクリックします。
新規コードの作成によるコードによるエージェントの構築
コード・エディタでコードを直接エージェントに作成することで、既存のコードを使用してエンドツーエンドのエージェント・アプリケーションを構築できます。
- Python (.py)
- JSON
- TXT
- CSV
- PSV
- SH
- フォルダ
- 「Add new file」をクリックします。
コードを使用したエージェントのエントリ・ファイルの設定
コードを介したAIエージェントには、エージェントに必要なクラス、設定および呼出しメソッドを持つエントリ・ファイルが必要です。
- エントリ・ファイルを右クリックし、「エントリ・ファイルの設定」をクリックします。ファイルを選択して、コード・エディタの右上にある「エントリ・ファイルの設定」ボタンをクリックすることもできます。
コードを使用したエージェントの依存関係ファイルの設定
コードが依存しているサード・パーティ・ライブラリを含むコードを介してエージェント・フローの依存性ファイルを設定する必要があります。
- 依存性ファイルを右クリックし、「依存性の設定」をクリックします。ファイルを選択し、コード・エディタの右上にある「依存性ファイルの設定」ボタンをクリックすることもできます。
テストエージェントコード
「テスト」タブからエージェントに使用されるコードをテストして、コードを検証およびデバッグできます。
- 「プレイグラウンド」タブをクリックします。
- 「再生」をクリックして、選択したコード・ファイルをテストします。
コーディング・エクスペリエンスにおけるエージェント・スキル
エージェント・スキルを使用すると、エージェントは、そのドメイン・ナレッジをエージェントの指示にハードコードすることなく、タスク固有の指示、参照ファイル、テンプレート、アセットおよびオプションの実行可能スクリプトを検出して使用できます。
スキルは、エージェント・コード・ベースにフォルダとして格納されます。各スキルには、スキルの動作およびエージェントによるスキルの使用方法を説明する必要なSKILL.mdファイルがあります。スキルには、スキーマ、例、プロンプト、テンプレート、アセット、スクリプトなどのサポート・ファイルを含めることもできます。
詳細は、エージェント・スキルの概要を参照してください。
- エージェントは、スキルが存在することを検出します。
- エージェントは、スキルが関連している場合にのみスキルをアクティブ化します。
- エージェントは、必要な場合にのみスキル・フォルダから追加のファイルをロードします。
- スキルで許可されている場合、エージェントは明示的に宣言されたスキル・エントリポイントを実行できます。
エージェント・スキルを使用するタイミング
- ドメイン固有の手順
- コーディングまたはデータ分析ワークフロー
- 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.
表22-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を介して再利用可能な実行可能動作を公開できます。これは、計算、変換、検証、構造化データのフェッチなどの制御操作を対象としています。
- スキルでは、許可されたツールに
run_skill_entrypointを含める必要があります。 - スクリプトは、
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.
実行可能エントリポイントのルール
- スキルの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_csventrypoints:
- name: run
- name: do_it 構造化結果を返す
実行可能スクリプトは、可能な場合は常にJSONシリアライズ可能な結果を返す必要があります。これにより、エージェントが出力を検査して使用しやすくなります。
不要な実行を回避
可能な場合は、指示および参照ファイルを優先します。実行可能エントリポイントは、コードが本当に必要である操作にのみ使用します。
エージェント・スキルのトラブルシューティング
エージェント・スキルの実装で問題が発生した場合は、このリストをチェックして問題の解決に役立ててください。
エージェントに自分のスキルが表示されません
- スキル・フォルダは、構成されたスキル・ディレクトリの下にあります。
- フォルダには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ベースのエージェントをテストして、エージェントを検証およびデバッグできます。
- キャンバスの上部で、「プレイグラウンド」をクリックします。アタッチされたコンピュートにエージェントをプッシュするのに数秒かかる場合があります。
エージェントのテスト・セッションの作成
テスト・セッションを作成して、エージェントとの新しい会話を開始できます。
- セッション・セレクタで、 「セッションの作成」をクリックします。
- チャットボックスにクエリーを入力して、エージェントとのダイアログを開始します。
エージェント・ツールについて
Oracle AI Data Platform Workbenchは、データにアクセスし、ユース・ケースに適合するように構成できるツール・テンプレートをサポートしています。
エージェントは、1つ以上のツールとインタフェースできる単一のエージェントで構成される構成をサポートします。Oracle AI Data Platform Workbenchには、ビジュアル・フローまたはコードを介して使用するように構成できる3つのツール・テンプレートが用意されています。
- カスタム・コード:カスタム・コード・ツールを使用すると、AI開発者はPythonを使用してツールを実装できます。開発者は、ツールをZIPにパッケージ化し、ワークスペースにアップロードして、エージェントのノードとして構成します。カスタム・コード・ツールは、組込みツールが必要とする統合を提供しないケースを対象としています。
- HTTPリクエスト: HTTPリクエスト・ツールを使用すると、開発者は、AI Data Platform Workbench APIおよびそれらが提供する機能を利用して、サポートされているREST APIコールをエージェントで使用できます。エージェントは、REST APIを使用して、ワークスペース・オブジェクトの作成、詳細の確認、リストのプル、または既存のオブジェクトの変更を行うことができます。使用可能なAPIの完全なリストは、Oracle AI Data Platform Workbench REST APIを参照してください。
- プロンプト: プロンプト・ツールを使用すると、AI開発者は、選択したLLMに発行できるパラメータ化されたプロンプトを定義できます。プロンプト・ツールの一般的なユース・ケースには、電子メール作成タスク、翻訳タスク、スタイル変換、gitコミット・メッセージ、コードの説明などがあります。
- RAG: RAGツールを使用すると、エージェントは、レスポンスを生成する前に関連する外部ナレッジを取得できます。AIデータ・プラットフォーム・ワークベンチでは、RAGツールがナレッジ・ベース(26ai Vector Search)を問い合せて、意味に関連するドキュメント・チャンクを取得します。これらのチャンクは、レスポンス生成のためにエージェントに渡されます。
- SQL: SQLツールを使用すると、エージェントは、Oracle Autonomous AI Lakehouse、Oracle Autonomous AI Transaction Processing、Oracle AI Databaseなどの外部カタログを介して登録された構造化データ・ソースに対してSQLクエリを実行できます。このツールは、SQL問合せが事前定義され、パラメータ化できるシナリオを対象としています。目的は、エージェントがパラメータに値を割り当てるようにすることです。このツールは、自然言語プロンプトに基づいてSQL問合せを生成するNL2SQLツールではありません。
ノート:
SQLツールは、外部カタログのデータに対してのみ問合せを実行します。標準カタログに格納されたデータはサポートされません。
ビジュアル・フローを使用したエージェント・フロー・ツール
ビジュアル・フローを使用してツールをエージェントに追加すると、エージェントの「ツール・テンプレート」でツールを検索できます。ツールをエージェントに追加するには、ビジュアル・フロー・キャンバスにドラッグ・アンド・ドロップします。キャンバス上でツール・ノードをドラッグすると、ノードは自動的にエージェントに接続します。
各ツールは、「パラメータ」タブで構成でき、「テスト」タブをクリックしてエージェントとは独立してテストできます。
ノート:
システム・ツールをテストする前に、エージェントにAIコンピュートをアタッチする必要があります。コンピュートがアタッチされていない場合、「テスト」タブは無効になります。LangGraphコードを介したエージェント・フロー・ツール
AIDPToolConf()クラスのインスタンスを使用して、RAG、SQLおよびプロンプト・ツールをLangGraphコード化されたエージェントに追加します。
from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool = AIDPToolConf(name, description, tool_class , conf, params)
- 名前:ユーザーおよびLLMがツールの目的を理解するのに役立つわかりやすい名前。
- 説明:ユーザーおよびLLMがツールの動作を理解するのに十分な情報を提供する完全なサマリー。
- tool_class:サポートされているツール・タイプ(
PromptTool、SQLToolまたはRAGTool)。 - conf:ツール構成。この情報はLLMには表示されません。
- params: LLMに公開されるパラメータ。
カスタム・ツール
カスタム・コード・ツールを使用すると、エージェント開発者は独自のPythonコードを使用してAIデータ・プラットフォームを拡張できます。
ツール実装をZIPファイルとしてパッケージ化し、ワークスペースにアップロードして、エージェントのカスタム・コード・ツール・ノードとして構成します。エージェントは、実行時にLLMによって提供されるパラメータを使用して、コードをツールとしてコールします。
カスタム・コード・ツールは、組込みツール(HTTP、SQL、RAG、MCP)が、ローカル計算の実行、ドメイン固有のフォーマットの解析、エージェントに単一のツール・コールとして表示される複数のステップの作成など、必要な統合に対応していないケースを対象としています。
AI Data Platform Workbenchには、カスタム・コード・ツールのPythonコードを使用してZIPファイルをアップロードする際に、次の制限があります:
| 制約 | 制限 |
|---|---|
| 最大ZIPサイズ | 10MB |
| ZIP内の最大ファイル・サイズ | ファイル当たり10MB |
| 最大合計非圧縮サイズ | 500MB |
| パス・トラバース | ブロック済(../拒否) |
ノート:
カスタム・コード・ツールは、エージェントにアタッチされたAIコンピュート上で実行されます。このコードは、ワークスペース・ネットワーキング構成の対象となるコンピュート環境およびアウトバウンド・ネットワーク・アクセスにアクセスできます。信頼できるソースからのコードのみをアップロードします。カスタム・コード・ツールのパラメータ
「パラメータ」タブで、パッケージ内の各ツール・クラスの静的設定を構成します。「ツールクラス」ドロップダウンを使用すると、パッケージ内で検出されたツールを切り替えることができます。
- ツール・クラス:構成するツール・クラスを選択します。ドロップダウンは、
tool_implementation.pyに登録されているクラスから移入されます。 - 説明:ツールの動作の明確で簡潔な説明。この説明はエージェントに提供され、LLMがツールを呼び出すタイミングを決定するのに役立ちます。デフォルトの説明はtool_config.jsonから読み取られ、ここでオーバーライドできます。
- 構成:ツールが実行時に必要とする静的設定。これらは、
tool_config.jsonのconfオブジェクトで定義されているキーです。たとえば、timeout、base_dir、max_output_linesおよび資格証明参照があります。構成値は、{{variable}}ランタイム・パラメータ参照をサポートします。セッション変数は、現在カスタム・ツール構成に置換されていません。セッション値が必要な場合は、エージェントからランタイム・パラメータとして渡してください。 - AIツール定義:エージェントに公開されるスキーマ(ツール名、説明、エージェントが渡すことができるランタイム・パラメータなど)。スキーマは、
tool_config.jsonのスキーマ配列から自動的にレンダリングされます。
カスタムコードツールオーサリング
カスタムコードツールパッケージは、次の構造を持つZIPファイルです。
my_tool.zip
├── tool_implementation.py # Required. Contains the tool class(es).
├── tool_config.json # Required. Tool metadata and schema.
├── requirements.txt # Optional. Python dependencies.
├── utils/ # Optional. Helper modules.
│ ├── __init__.py
│ └── helpers.py
├── config/ # Optional. Static configuration files.
│ └── settings.yaml
└── wheels/ # Optional. Bundled wheel files for offline install.
└── humanize-4.15.0-py3-none-any.whl ツール_実装.py
各ツール・クラスはCustomToolBaseを拡張し、@BaseTool.registerで装飾されています。クラスは、ツール構成、エージェントからのランタイム・パラメータおよびシステム・コンテキスト変数を受信する_execute_toolクラス・メソッドを実装し、dict、str、listなどの値を戻す必要があります。
次に、tool_implementation.pyの空白のサンプル・テンプレートを示します。
"""Custom Code tool implementation."""
from aidputils.agents.tools.custom_tools.base import CustomToolBase
@BaseTool.register
class MyTool(CustomToolBase):
"""Brief description of what the tool does."""
@classmethod
def _validate_config(cls, conf, runtime_params, **context_vars):
"""Optional. Validate configuration before execution.
Raise ValueError to abort the call.
"""
# Example: require an api_key in the tool configuration
if not conf.get("conf", {}).get("api_key"):
raise ValueError("api_key is required")
@classmethod
def _execute_tool(cls, conf, runtime_params, **context_vars):
"""Required. Implement the tool logic.
Args:
conf: the AIDPToolConf dict. User configuration values
live under conf["conf"] when the tool is invoked from
a deployed agent. During a Test run the tool may
receive a flat conf dict; the Developer Toolkit example
below uses a small _get_cfg helper that tolerates both
shapes.
runtime_params: the runtime parameters passed by the
agent at invocation time.
context_vars: system context (such as datalake_id).
Returns:
Any value (dict, str, list, ...). It will be wrapped into
the MCP response by the framework.
To signal a failure, raise an exception:
- ValueError -> INVALID_CONFIG
- any other exception -> TOOL_EXECUTION_ERROR
Do NOT return {"error": "..."}; the framework wraps a
successful return in {"response": ..., "success": True},
so a returned error dict is treated as a normal payload
and the agent will not see it as a failure.
"""
tool_conf = conf.get("conf", conf)
param_value = runtime_params.get("my_param", "")
# Tool logic here
return {"output": f"Processed: {param_value}"}
@classmethod
def _transform_response(cls, response):
"""Optional. Transform the response before MCP formatting."""
return responseツール_構成.json
tool_config.jsonファイルには、パッケージ内のツール(表示名、説明、バージョン、ランタイム・パラメータ・スキーマおよびデフォルトの構成値)が記述されます。tool_implementation.pyに登録された各ツールには、対応するエントリがtoolsアレイ内に存在する必要があります。
tool_config.jsonの空白のサンプル・テンプレートを示します。{
"displayName": "My Tool Package",
"description": "Brief description of the tool package.",
"tools": [
{
"toolClassName": "MyTool",
"displayName": "My Tool",
"description": "Clear description of when the agent should call this tool.",
"version": "1.0.0",
"schema": [
{
"name": "my_param",
"type": "string",
"description": "What this parameter is for."
}
],
"conf": {
"timeout": 30
}
}
]
}
スキーマ・フィールド・タイプ
ビジュアル・ビルダーの「パラメータ」タブには、文字列、数値およびブール値を指定できます。tool_config.jsonを手動で作成する場合、ランタイムはより広いセットを受け入れます: int、integer、float、double、number、numeric、bytes、list、array、sequence、dict、map、mapping、set、tuple、none、null、およびlist[int]のような汎用形式。これらのより広いタイプはJSONから使用できますが、UIドロップダウンには表示されません。
要件.txt
requirements.txtファイルには、ツールに必要なPythonの依存関係がリストされます。バージョン指定子やコメントなど、標準のpip構文がサポートされています。ファイルはオプションです。ツールでPython標準ライブラリまたは事前インストール済パッケージのみを使用する場合は、requirements.txtは必要ありません。
次に、requirements.txtの空白の例を示します。
# List third-party dependencies one per line.
# Examples:
# humanize>=4.0
# python-dateutil>=2.8,<3.0
# beautifulsoup4==4.12.3 AI Data Platform Workbenchは、requirements.txtの依存関係をフィルタリングしてから、AIコンピュートにインストールし、プラットフォーム自体とのランタイム競合を防止します。フィルタリング・ルールは次のとおりです。
| カテゴリ | 例 | アクション |
|---|---|---|
| プラットフォームパッケージ | langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml | 破棄されました(エージェント・ランタイムは中断されます)。 |
| インストール済みパッケージ | oci、リクエスト、requests-toolbelt、websockets、cryptography、certifi、pyopenssl、urlib3、pydantic、pydantic-core、pydantic-settings、numpy、oracledb、sqlalchemy、aiohttp、httpx、httpx-sse、anyio、jsonschema、orjson | スキップされました(すでに使用可能であり、宣言する必要はありません)。 |
| URLまたはVCSインストール | git+https://...、-e ./local_pkg | ブロック(セキュリティ)。 |
| その他すべて | ヒューマライズ、 beautifulsoup4、 jmespath | インストール済みです。 |
ノート:
requirements.txtで宣言された依存性は、エージェントの完全デプロイメント中にインストールされます。構成パネルからの単一のテスト実行中は、依存関係はインストールされません。ツールがサード・パーティ・パッケージに依存している場合は、まずエージェントをデプロイしてから、プレイグラウンドからツールを実行します。
事前インストールされておらず、確定的、オフラインでのインストールが重要な依存関係を必要とするツールの場合、.whlファイルをZIPのルートにあるwheels/ディレクトリ内にバンドルできます。プラットフォームは、最初にローカルwheelsディレクトリからインストールされ、必要に応じてパッケージ索引にフォールバックします。これは、本番ツールに推奨される方法です。
オフラインインストール用のバンドルホイール
pip download \
--dest wheels/ \
--platform manylinux_2_28_x86_64 \
--python-version 3.11 \
--only-binary=:all: \
-r requirements.txt
ツール・ライフサイクル・フック
カスタム・コード・ツールでは、3つのライフサイクル方法がサポートされています。_execute_toolのみが必要です。
| Method | 呼び出されたとき | 目 的 |
|---|---|---|
| 構成の検証(_V) | _execute_toolの前 | 構成を検証します。ValueErrorを呼び出して、実行前にコールを中止します。 |
| ツールの実行(_E) | すべてのツールの起動時 | 必須フィールドです。ツールの動作を実装します。任意の値(dict、str、list)を返し、失敗を示す例外を発生させます(ValueError→INVALID_CONFIG、その他の例外 →TOOL_EXECUTION_ERROR)。返される{"error": "..."} dictは通常のペイロードとして扱われるため、使用しないでください。 |
| 応答を変換(_T) | _execute_toolの後 | MCP形式でラップされてエージェントに戻される前に、レスポンスを変換します。 |
| prompt_template | 文字列 | 動的挿入のために、{{variable}}形式の変数とともにLLMで使用されるプロンプト・テンプレート |
構成値とランタイム・パラメータ
カスタム・コード・ツールには、混乱しやすい2つの異なる入力ソースがあります。構成値は、「パラメータ」タブの「構成」セクションから取得され、エージェントのデプロイ時にツールにベイク処理されます。ランタイム・パラメータは起動時にエージェントから取得され、コールごとに異なります。
- 構成値には、conf.get("conf"、 conf)を介してアクセスします。ベースURL、資格証明参照、タイムアウト、出力制限など、コール間で変更されないものに使用します。
- ランタイム・パラメータはruntime_params.get("name")を介してアクセスします。これらは、エージェントがコール時に実際に決定する値(問合せ、ファイル・パス、リクエスト本文)に使用します。
ノート:
構成値はテンプレート置換を通過でき、数値として定義した場合でも文字列として到着する可能性があります。数値構成値は常にint(tool_conf.get("timeout", 30))のように防御的に強制します。
パッケージごとの複数のツール
1つのZIPに複数のツールクラスを含めることができます。@CustomToolBase.registerに登録された各クラスは、エージェント内の個別のツールになります。「パッケージ」タブの「ツール」パネルには、検出されたすべてのツールがリストされ、各ツールを個別に有効にできます。各ツールは、「ツール・クラス」ドロップダウンを介して「パラメータ」タブで個別に構成されます。
LangGraphコードを使用したコード・ツール
コード・ビルダーから、カスタム・コード・ツールは、アップロードされたパッケージを参照し、そのツール・クラスの1つを選択することで、aidpUtils Pythonライブラリを介して登録されます。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf
hello_tool_conf = AIDPToolConf(
name="hello_tool",
description="Returns a hello world greeting.",
tool_class="HelloTool", # the class registered with @BaseTool.register
conf={}, # values from tool_config.json "conf"; supports {{variable}} substitution
params=[
{"name": "name", "type": "string",
"description": "Name to greet."}
],
)
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())
tool_classは、tool_implementation.pyの@BaseTool.registerを介して登録された正確なクラス名である必要があります。フレームワークは、BaseTool.tool_class_registry[tool_class]でクラスをルックアップします。confは、tool_config.jsonの一致するエントリのconfオブジェクトをミラー化します。
ノート:
package_pathまたはtool_class_nameは消費されないため、conf内に配置しないでください。
テストエージェントカスタムコードツール
「テスト」タブでは、エージェント全体を実行せずにツールを実行できます。構成で参照されるランタイム・パラメータおよびセッション変数の値を指定し、「実行」をクリックしてツールを起動し、レスポンスを表示します。
ノート:
ツールがrequirements.txtで宣言されたサード・パーティ・パッケージに依存している場合、依存関係は、単一のテスト実行中ではなく、エージェントのフル・デプロイメント中にインストールされます。追加パッケージに依存するコードをテストするには、まずエージェントをデプロイしてから、プレイグラウンドからツールを起動します。
エージェントへのカスタム・ツールの追加
カスタム・ツールをエージェントに追加して、独自のPythonコードを使用してAIデータ・プラットフォームを拡張できます。
ノート:
カスタム・コード・ツールを追加する前に、エージェントにAIコンピュートをアタッチする必要があります。依存関係をインストールしてツールを実行するには、AIコンピュートが必要です。- 「パッケージ」タブで、クリックしてカスタム・コードを含むZIPファイルを選択するか、画面にドラッグ・アンド・ドロップします。アップロードが完了するのを待ちます。
- 「パッケージ」タブの「ツール」セクションで、検出されたツールのリストを確認します。
tool_implementation.pyにある各ツール・クラスは、そのクラス名、説明およびバージョンとともにリストされます。
- オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。
リモートMCPサーバーツール
エージェント・フロー開発者は、リモートMCPサーバー・ツールを使用して、エージェント・フローをリモート・モデル・コンテキスト・プロトコル(MCP)サーバーに接続できます。
MCPツールは、ビジュアル・ビルダーとコード・ビルダーの両方のエクスペリエンスで使用できます。コード・ビルダーの経験では、MCP接続はaidpUtils Pythonライブラリを介して構成できます。この項では、ビジュアル・ビルダーとコード・ビルダーの両方のエクスペリエンスについて説明します。
ノート:
この機能では、HTTPストリーム可能トランスポート(リモートサーバー)を備えたMCPサーバーがサポートされます。ローカルなstdio-transport MCPサーバーはサポートされていません。Oracle AI Data Platform Workbench資格証明ストアのMCP資格証明
MCPサーバーを構成するときは、リモートMCPサーバーに No Authenticationまたは Bearer tokenのどちらが必要かを選択する必要があります。MCPサーバーで認証トークンが必要な場合は、そのトークンをMCPサーバーによって参照する前に、資格証明ストアに追加する必要があります。
MCPサーバー資格証明を作成する場合は、「資格証明タイプ」に「シークレット・トークン」オプションを選択し、APIキーやトークン値などの識別子キーを指定します。詳細は、資格証明の作成(プレビュー)を参照してください。
ノート:
1つの資格証明に複数のキーを保持できます。パブリックで使用可能なMCPサーバーは、追加の認証を必要としません。たとえば、https://mcp.deepwiki.com/mcpへの接続は次のようになります。
MCPツールをエージェントに公開する方法
リモートMCPサーバーへの接続が成功したら、エージェントに公開するサーバー上でホストされているツールの構成を開始できます。DeepWiki MCPサーバーの場合、MCPサーバー構成パネルを以下に示します。
左側の「ツール」タブには、MCPサーバーで使用可能なツールのリストが表示されます。エージェントに公開するツールを追加する必要があります。これを行うには、「すべて追加」オプションをクリックしてすべてのツールを一度に公開するか、各ツールの「追加」オプションを個別にクリックしてツールのサブセットを選択します。
次の例では、2つのツール(read_wiki_structure、read_wiki_structure)を追加しました。ツールを削除するには、「削除」をクリックします。
「ツール」タブの右側のパネルには、ツール名、ツールの説明、ツールのパラメータなど、各ツールに関するドキュメントが表示されます。次のスクリーンショットでは、GitHub MCPサーバー・ツールadd_comment_to_pending_reviewの例を示します。
Oracle AI Data Platform Workbenchには、各ツールに対する追加のコントロールがいくつか用意されています。エージェントからパラメータを非表示にし、それらのパラメータに値を割り当てることができます。たとえば、GitHubでは、エージェントがoracle-aidp-samplesなど、事前に決定された1つのリポジトリのみにコメントするように選択できます。これを実現するには、repoパラメータを無効にし、テキストボックスにデフォルト値を割り当てます。
「ツール・インストラクション」フィールドで、ツールの説明を上書きしたり、追加のインストラクションを含む別の説明を提供することもできます。ほとんどのユースケースでは、MCPサーバーから提供される説明を採用することをお勧めします。
LangGraphコードによるリモートMCPサーバツール
aidpUtils Pythonライブラリは、開発者がリモートMCPサーバーを選択し、そのツールのサブセットをLangGraphで構築されたエージェントに公開する機能を提供します。helpputils APIリファレンスは、Oracle AI Data Platform WorkbenchのAidp-utils APIを参照してください。
build_structured_tools_from_allowed_mcp_toolsのインスタンスを作成することで、許可されるツールのコレクションを構築できます。
from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools
TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>,
server_name=<MCP_SERVER_NAME>,
endpoint=<MCP_ENDPOINT>,
transport="streamable_http",
auth=<MCP_AUTH>,
headers={}
)- <MCP_SERVER_NAME>は、MCPサーバーに付与する表示名です。これはドキュメント目的で使用され、エージェントには公開されません。
- <MCP_ENDPOINT>は、MCPサーバーのエンドポイントです(例: https://api.githubcopilot.com/mcp/)
- <MCP_AUTH>は、キーauthTypeを持つディクショナリです。このキーには、
NO_AUTHまたはBEARER_TOKENの2つの値を指定できます。BEARER_TOKENの場合、Bearerトークンの値を持つ"token"という別のキーが必要です。 - <ALLOWED_MCP_TOOLS>は、エージェントに公開するMCPサーバーからのツールのリストです。各ツールには、MCPプロトコルに従った完全なJSONツール定義が必要です。
次に例を示します:
MCP_SERVER_NAME = "test_mcp"
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp"
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }
{
"ALLOWED_TOOLS": [
{
"tool": {
"name": "get_current_weather",
"description": "Get current weather for a given city with advanced options.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"unit": {
"type": "string",
"default": "metric"
},
"include_historical": {
"type": "boolean",
"default": false
},
"detailed": {
"type": "boolean",
"default": true
},
"timeout": {
"type": "integer",
"default": 30
}
},
"required": [
"city"
]
}
},
"instruction": "",
"argOverrides": {}
},
{
"tool": {
"name": "get_forecast",
"description": "Get forecast for a given city with customizable options.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"days": {
"type": "integer",
"default": 5
},
"unit": {
"type": "string",
"default": "metric"
},
"include_alerts": {
"type": "boolean",
"default": false
},
"detailed": {
"type": "boolean",
"default": true
},
"hourly": {
"type": "boolean",
"default": false
}
},
"required": [
"city"
]
}
},
"instruction": "",
"argOverrides": {}
}
]
}
MCP_HEADERS = {}
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
server_name=MCP_SERVER_NAME,
endpoint=MCP_ENDPOINT,
transport="streamable_http",
auth=MCP_AUTH,
headers=MCP_HEADERS,
)
TOOLSオブジェクトは、クラス・エージェント定義のsetup()メソッドでlangchain.agent create_agentを使用してエージェントのインスタンスを作成するときに使用できます。
def setup(self):
logger.info("Initializing TestMcpAgent")
oci_llm = init_oci_llm(llm_conf)
system_prompt = textwrap.dedent(
"""
You're a weather agent. Append 12345 to every response.
"""
).strip()
self.agent = create_agent(
name="test_mcp_high_code",
model=oci_llm,
tools=TOOLS,
system_prompt=system_prompt,
debug=True,
)
logger.info("Agent ready.")または、セッション変数を使用してベアラー・トークンの値を格納している場合は、以前に作成したセッション変数への参照を認証構成ディクショナリのトークン・キーに割り当てることができます。たとえば:
test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=test_mcp_mcp_allowed_tools,
server_name="test_mcp",
endpoint="http://144.25.36.217:9301/mcp",
transport="streamable_http",
auth=test_mcp_mcp_auth_config,
headers={}
)リモートMCPサーバーツールのコード例
AI Data Platform WorkbenchサンプルGitHubリポジトリには、複数のMCPシナリオのエンドツーエンドのコード・サンプルが用意されています。
リモートMCPサーバーツールのテスト
ツールを選択したら、通常、次のステップは、個々のツールが期待どおりに動作することを確認するためのテストです。これは、MCPツール・ノードの「テスト」タブで実行できます。
「ツール」タブで追加したツールの1つを選択し、パラメータ値を指定して「テスト」ボタンをクリックします。
ツールの出力が右側のパネルに表示されます。
「詳細」タブには、認証方法、MCPサーバーURLおよび説明に関する情報が表示されます。
認証方法の横にある「編集」ボタンを使用して、リモートMCPツール・ノードの構成を変更します。接続の確立時に使用される表示名、説明およびベアラー・トークンを変更できます。
Visual BuilderからリモートMCPサーバーへのエージェントの接続
カスタムMCPサーバー・ツール・ノードをキャンバスにドラッグすることで、リモートMCPサーバーへのアクセスをエージェントに追加できます。
ノート:
エージェントをホストするAIコンピュートは、そのワークスペースのネットワーク設定を継承します。AIコンピュートをホストしているワークスペースに対してプライベート・ネットワーク・アクセスを有効にした場合、エージェントは選択したプライベートVCNおよびサブネットでホストされているMCPサーバーにのみ到達できます。エージェントが、パブリック・インターネットで使用可能なリモートHTTPサーバーにアクセスできない可能性があります。- エージェントにナビゲートします。
- 「フロー」タブの「ツール・テンプレート」で、「カスタムMCPサーバー」をクリックしてキャンバスにドラッグします。
- MCPサーバーのサーバーURLを指定します。
- MCPサーバーの表示名を指定します。これは、ビジュアル・ビルダーのキャンバスに表示されるノードの名前です。
- オプション: MCPサーバーの説明を入力します。説明フィールドがエージェントに指定されていません。
- 「認証」ドロップダウン・メニューから、認証方法を選択します。
- 認証なし: リモートMCPサーバーがパブリックに使用可能であり、認証を必要としない場合は、このオプションを使用します。
- Bearer token: リモートMCPサーバーに認証トークンが必要な場合、このオプションを使用します。APIキーをOracle AI Data Platform Workbench資格証明ストアに格納し、資格証明ストア・エントリへの参照を指定する必要があります。
- 「接続」をクリックします。AI Data Platform Workbenchによって接続がテストされ、結果がレポートされます。
HTTPリクエスト・ツール
HTTPリクエスト・ツールを使用すると、エージェントは任意のHTTPS REST APIをコールできます。
メソッド、URL、ヘッダー、問合せパラメータ、リクエスト本文、認証、およびオプションでレスポンス最適化ステップを含むリクエストを構成します。その後、エージェントは実行時にエンドポイントを呼び出します。HTTPリクエスト・ツールは、ビジュアル・ビルダーとコード・ビルダーの両方で使用できます。コード・ビルダーでは、このツールはaidpUtils Pythonライブラリを介して構成されます。
ノート:
HTTPリクエスト・ツールでは、https://およびHTTP://リクエストのみがサポートされます。WebSocket接続(ws/wss)、バイナリ・ファイルのアップロードおよび自己署名証明書はサポートされていません。ノート:
エージェントをホストするAIコンピュートは、そのワークスペースのネットワーク設定を継承します。AIコンピュートをホストしているワークスペースに対してプライベート・ネットワーク・アクセスを有効にすると、エージェントは選択したプライベートVCNおよびサブネット内のHTTPエンドポイントにのみ到達します。エージェントは、パブリック・インターネットで使用可能なエンドポイントにアクセスできません。HTTPリクエスト・ツールを構成する場合は、次の設定を指定する必要があります。
| 構成 | 説明 |
|---|---|
| HTTPメソッド | 使用するHTTP動詞。サポートされているメソッドは、GET、POST、PUT、PATCHおよびDELETEです。 |
| URL | ターゲット・エンドポイントの完全なURL。URLでは、{{sessionVariables.variable_name}}セッション変数参照および{{variable}}ランタイム・パラメータ参照がサポートされます。例: https://api.example.com/users/{{user_id}}/orders。
|
| タイムアウト | ツールがリモート・エンドポイントからのレスポンスを待機する最大時間。デフォルトは30秒で、最大は300秒です。 |
| 認証タイプ | エンドポイントのコール時に使用する認証メソッド。サポートされている認証方式のリストについては、後述の「認証」セクションを参照してください。 |
ノート:
カスタム・コード・ツールは、エージェントにアタッチされたAIコンピュート上で実行されます。このコードは、ワークスペース・ネットワーキング構成の対象となるコンピュート環境およびアウトバウンド・ネットワーク・アクセスにアクセスできます。信頼できるソースからのコードのみをアップロードします。ヘッダー
ヘッダーは、HTTPリクエストとともに送信されるキーと値のペアです。「新規追加」ボタンをクリックすると、必要な数のヘッダーを追加できます。ヘッダー値は、{{variable_name}}構文を使用してセッション変数およびランタイム・パラメータを参照できます。
ノート:
機密ヘッダーの場合は、「認証タイプ」フィールドを使用して、資格証明が資格証明ストアから安全に注入されるようにする必要があります。認可、CookieおよびX-API-Keyは機密ヘッダーであり、「ヘッダー」セクションからは設定できません。問合せパラメータ
問合せパラメータは、問合せ文字列としてURLに追加されます。「新規追加」ボタンをクリックすると、必要な数の問合せパラメータを追加できます。ヘッダーと同様に、問合せパラメータ値はセッション変数およびランタイム・パラメータを参照できます。
説明
descriptionフィールドは、ツールの動作、使用するタイミング、およびツールが生成する出力や効果の種類を示します。この説明はエージェントに提供され、LLMがツールを呼び出すタイミングを決定するのに役立ちます。
- • 目的:ツールが1つの明確な文で何をするように設計されているかを説明します。例: 「このツールは、ナレッジ・ベースからカスタマ・サポート・チケットを取得し、優先度レベルで要約します。」
- 使用するタイミング:エージェントがこのツールをコールする条件と別のツールをコールする条件を説明します。
- 入力および出力:ツールが必要とするパラメータと、ツールが返す形状を簡単に説明します。
HTTPリクエスト認証
HTTPリクエスト・ツールでは、いくつかの認証方法がサポートされています。「認証タイプ」ドロップダウンから適切なメソッドを選択します。
| 認証タイプ | 説明 |
|---|---|
| 認証なし | リクエストに認証は追加されません。パブリックにアクセスできるエンドポイントに使用します。 |
| OCIリソース・主体 | リクエストは、AI ComputeのOCI Resource Principalを使用して署名されます。これは、オブジェクト・ストレージやOCI生成AIサービスなどのOCIサービスをコールする場合に使用します。アクセスは、OCI IAMポリシーによって管理されます。 |
| Basic認証 | ユーザー名とパスワードは、認可ヘッダーでエンコードされて送信されます。資格証明は、資格証明ストアに格納する必要があります。 |
| Bearerトークン | BearerトークンがAuthorizationヘッダーで送信されます。トークンは資格証明ストアに格納される必要があります。 |
| ヘッダー認証 | APIキーはカスタムヘッダー(X-API-Keyなど)で送信されます。ヘッダー名は構成可能で、キー値は資格証明ストアに格納される必要があります。 |
シークレットを必要とする認証方法を選択すると、構成パネルに資格証明ピッカーが表示されます。資格証明ピッカーをクリックして、以前に格納した資格証明を選択するか、資格証明ストアから新しい資格証明を作成します。手順については、MCPサーバーのドキュメントの「資格証明ストア」セクションにある資格証明の格納を参照してください。
セッション変数およびランタイム・パラメータ
セッション変数は、{{sessionVariables.variable_name}}構文を使用して、URL、ヘッダー値、問合せパラメータ値およびリクエスト本文で参照できます。呼出し時にエージェントによって渡されるランタイム・パラメータは、{{variable_name}}構文を使用して参照できます。
https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/oツールが実行されると、{{sessionVariables.region}}は現在のセッションのリージョン・セッション変数の値に置き換えられ、{{bucket}}は、起動時にエージェントが渡した値に置き換えられます。
ノート:
テンプレート値は、URLまたは問合せパラメータに置換されるときに自動的にURLエンコードされます。自分でURLエンコードする必要はありません。AIツール定義
構成パネルの右側にAIツールの定義が表示されます。これは、エージェントに公開されるスキーマであり、ツール名、説明およびツールのコール時にエージェントが渡すことができるランタイム・パラメータのリストが含まれます。AIツール定義は、「説明」フィールドおよびURL、ヘッダー、問合せパラメータおよび本文で検出された{{variable}}プレースホルダから自動的に生成されます。
AIツール定義ペインは、このドキュメントで前述したHTTPツール構成パネルの右側にあるパネルです。説明を指定し、1つ以上のランタイム・パラメータを定義するまで、AIツール定義ペインにプレースホルダ・メッセージが表示されます。説明を入力し、URL、ヘッダー、問合せパラメータまたは本文で少なくとも1つの{{variable}}を参照すると、スキーマがペインにレンダリングされます。
エージェントに対する応答の最適化
多くのAPIは、エージェントが必要としないフィールドを含む大規模なレスポンスを返します。レスポンス全体をエージェントに送信すると、トークンが消費され、エージェントの推論の品質が低下する可能性があります。HTTPリクエスト・ツールには、レスポンス・ペイロードをエージェントに返す前に減らすことができるレスポンス最適化セクションが用意されています。
- JSONフィールドの選択: JSONレスポンスからフィールドのサブセットを選択します。ドット表記法(data.resultsなど)および包含または除外するフィールドのリストを使用して、ネストされたオブジェクトへのパスを指定できます。
- HTML CSSセレクタ: CSSセレクタ(article.contentなど)を使用して、HTMLレスポンスのサブセットを抽出します。オプションで、HTMLタグを削除してテキストのみを返します。
- テキストの切捨て:テキスト・レスポンスが大きくなりすぎないように、最大文字数でレスポンスを大文字にします。
エラー処理およびエラー・コード
HTTPリクエストが失敗すると、ツールは構造化されたエラー・レスポンスをエージェントに返します。エラーには、エラー・コード、判読可能なメッセージ、および失敗の詳細が含まれます。エージェントはこの情報を使用して、再試行するか、別のツールにフォールバックするか、失敗をユーザーに報告するかを決定できます。
| エラー・コード | カテゴリ | 意味 | 再試行可能 |
|---|---|---|---|
| CONNECTION_TIMEOUT | ネットワーク | リモート・エンドポイントは、構成されたタイムアウト内に応答しませんでした。 | ○ |
| DNS失敗 | ネットワーク | URLのホスト名を解決できませんでした。 | ○ |
| CONNECTION_REFUSED | ネットワーク | リモート・エンドポイントが接続を拒否しました。 | ○ |
| SSL_CERTIFICATEエラー | TLS | リモート・エンドポイントのTLS証明書を検証できませんでした。 | × |
| 未承認 | HTTP 401 | リモート・エンドポイントが資格証明を拒否しました。資格証明参照が有効であり、失効していないことを確認します。OCIリソース・プリンシパルの場合、AIコンピュートにこの環境にアクティブなリソース・プリンシパルがあることを確認します。 | × |
| 禁止 | HTTP 403 | 資格証明は正常に認証されましたが、リクエストされたリソースに対する権限がありません。リソースにアタッチされているAPIスコープ、権限またはIAMポリシーを確認します。 | × |
| 見つからない(_F) | HTTP 404 | リモート・エンドポイントで、リクエストされたリソースが見つかりませんでした。 | × |
| レート限度 | HTTP 429 | リモート・エンドポイントがコール元をレート制限しています。Retry-Afterヘッダーで示された遅延後に再試行します。 | ○ |
| サーバーエラー | HTTP 5xx | リモート・エンドポイントがサーバー・エラーを返しました。多くの場合、一時的な問題です。 | ○ |
| サービスが利用できません | HTTP 503 | リモート・エンドポイントは一時的に使用できません。 | ○ |
| INVALID_TEMPLATE | 検証 | {{variable}}参照を解決できませんでした。参照されるすべてのセッション変数およびランタイム・パラメータが定義され、起動時に値が設定されていることを確認します。
|
× |
| 無効URL | 検証 | URLの形式が正しくないか、サポートされていないプロトコルを使用しているか、ブロックされたアドレス(プライベートIPアドレスやクラウド・メタデータ・エンドポイントなど)に解決されます。 | × |
| レスポンスが大きすぎます | 検証 | レスポンスが最大レスポンス・サイズ10MBを超えました。 | × |
| レート_制限_超過 | プラットフォーム | エージェントは、プラットフォームのエージェントごとのリクエスト率制限(60リクエスト/分)または同時実行性の制限(10同時リクエスト)を超えました。 | ○ |
各エラー・レスポンスには、提示された次のステップを含むガイダンス・フィールドと、経過時間およびエラー固有のコンテキスト(HTTPステータス・コードなど)を含む詳細フィールドが含まれます。
LangGraphコードによるHTTPリクエスト・ツール
コード・ビルダーから、HTTPリクエスト・ツールはaidpUtils Pythonライブラリを介して構成されます。tool_classをHttpEndpointToolに設定してAIDPToolConfを定義し、confフィールドに構成ディクショナリを渡します。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf
weather_http_tool_def = {
"method": "GET",
"url": "https://api.openweathermap.org/data/2.5/weather",
"params": {
"q": "{city}",
"units": "metric",
"appid": "{api_key}"
},
"auth_type": "NO_AUTH",
"auth_config": {}
}
weather_http_tool_params = [
{"name": "city", "type": "string",
"description": "Name of the city."},
{"name": "api_key", "type": "string",
"description": "OpenWeather API key."}
]
weather_http_tool_conf = AIDPToolConf(
name="get_weather",
description="Get current weather for a city.",
tool_class="HttpEndpointTool",
conf=weather_http_tool_def,
params=weather_http_tool_params
)
weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())
confディクショナリは、method、url、headers、params、body、auth_type、auth_configおよびresponse_optimizationというビジュアル・ビルダーと同じフィールドをサポートします。パラメータ・リストは、エージェントが渡すことができるランタイム・パラメータを定義します。
| 認証のタイプ | auth_configフィールド |
|---|---|
| 認証がありません | {} (空)
|
| RESOURCE_PRINCIPAL | {} (空)
|
| BASIC_AUTH | ユーザー名、パスワード(またはOCI Vaultの資格証明の場合はusername_vault_id、password_vault_id) |
| ベアラー認証 | Bearer_token (またはBearer_token_vault_id) |
| API_キー_認証 | api_key (またはapi_key_vault_id)、header_name (デフォルトのX-API-Key) |
| OAUTH2_CLIENT_CREDENTIALS | token_endpoint、scope、client_id、client_secret (またはclient_id_vault_id、client_secret_vault_id) |
テストエージェントカスタムコードツール
「テスト」タブでは、エージェント全体を実行せずにツールを実行できます。構成で参照されるランタイム・パラメータおよびセッション変数の値を指定し、「実行」をクリックしてツールを起動し、レスポンスを表示します。
レスポンス・パネルには、HTTPステータス・コード、レスポンス・ヘッダー、レスポンス本文および経過時間(ミリ秒)が表示されます。レスポンス最適化が有効な場合、最適化されたレスポンスもRAWレスポンスとともに表示されます。
エージェント・フローへのHTTPリクエスト・ツールの追加
HTTPリクエスト・ツールをエージェントに追加して、HTTPS REST APIをコールできます。
ノート:
カスタム・コード・ツールを追加する前に、エージェントにAIコンピュートをアタッチする必要があります。依存関係をインストールしてツールを実行するには、AIコンピュートが必要です。- ツール・テンプレートから、HTTPリクエスト・ツールをキャンバスにドラッグ・アンド・ドロップします。
- HTTPリクエストのヘッダーを指定します。ヘッダーを追加するには、「新規追加」をクリックします。
- HTTPリクエストの問合せパラメータを指定します。「新規追加」をクリックして、パラメータを追加します。
- オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。
プロンプト・ツール
プロンプト・ツールを使用すると、テンプレート化されたプロンプトを使用してAIエージェントでLLMをコールし、LLMレスポンスをエージェントに戻すことができます。
LLMに提供するプロンプトには、二重中カッコで識別されるパラメータ({{PARAMETER_NAME}}など)を含めることができます。パラメータ値は、ツールが呼び出されたときにエージェントによって割り当てられます。
プロンプト ツールを使用するタイミング
- プロンプトの長さが長く、複数の100sトークンにまたがる詳細な書式指示が必要です。
- エージェントの指示にプロンプトを組み込むと、コンテキストの使用量が増加し、特にエージェントにSOTA LLMを採用している場合、コストが大幅に増加します。
- コストを削減するために、エージェントに与えられた指示のサイズを最小限に抑えたいと考えています。
- プロンプト・ツールによって定義されたタスクは、エージェントが使用した推論モデルよりも小さく高速なLLMで処理できます。通常、小規模なモデルはコスト効率が高く、場合によっては特定のモダリティまたはフォーマットでデータを生成するように特殊化できます。
- プロンプト・ツールを使用すると、構造化された入力パラメータで出力生成を制御できます。ユース・ケースをパラメータ化し、セッションごとに生成が異なる可能性がある場合、プロンプト・ツールで生成をカプセル化することは理にかなっています。
さらに、プロンプト・ツールでの生成手順のカプセル化は、ツールの再利用性、メンテナンス性、モダリティ、出力の一貫性、スケーラビリティ、ガバナンスなど、最新のエージェント・アーキテクチャのベストプラクティスに従います。ユースケースの例を次に示します。
- テンプレートとして使用できる事前定義済の承認済構造に従ったEメール、レポート、要約、記事などの生成
- 複雑なJSON出力の生成
- ドキュメントの要約、キー・センテンス抽出、説明タスク
- 問合せの生成
- 特定のモデル用に最適化された特定のモダリティ生成(イメージ、ビデオ、オーディオ、ポイント・クラウド・データなど)
ビジュアル・フローでのプロンプト・ツール
次に、ビジュアル・フローを介して構築されたプロンプト・ツールの例を示します。このツールでは、エージェントによって割り当てられたトピックに基づいてLLMにブログ投稿タイトルを生成するように求められます。
あなたはマスター・ブログの戦略家です。あなたの仕事は、特定のトピックに基づいて魅力的なブログ投稿のアイデアをブレーンストーミングすることです。指定された{{topic}について、5つの一意のブログ投稿タイトルを生成します。タイトルごとに、ポストが取る角度について一文の説明を含めます。出力を番号付きリストとして表示します。
- ツール名:エージェントのガイドに役立つツールのわかりやすい名前を使用します。この例では、
blog_ideasを提案します。tool123のような役に立たない名前を使用しないでください。
- ツールの説明:ツールの動作に関する包括的な説明を提供します。ツールに制限がある場合や、ツールを使用しないシナリオがある場合は、「説明」フィールドにリストします。
- OCIリージョンおよび生成AIサービスLLM: OCIリージョンを選択して、そのリージョンで使用可能なLLMのリストを移入し、LLMを選択します。
- LLMパラメータ:最大出力トークン、温度、上位pなどのパラメータは、「モデル・パラメータ」タブで構成されます。値を割り当てない場合、OCI生成AIサービスのデフォルト値が使用されます。
- 問合せ:ツールの目的の定義に使用されるプロンプトは、「問合せ」フィールドに定義されます。
プロンプトで定義するパラメータは、「AIツール」定義パネルに自動移入されます。エージェントに、各パラメータの説明、および適用可能な場合はパラメータ・タイプとデフォルト値を指定します。
LangGraphコードによるプロンプト・ツール
コードを使用してエージェントを構築する場合は、ビジュアル・フローの例で次のように同じプロンプト・ツールを構成できます。
prompt_config = {
"llm": {
"model_id" : "xai.grok-4",
"model_provider" : "generic",
"compartment_id" : "<your-compartment-ocid>",
"endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
}, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
"name" : "topic",
"type" : "string",
"description" : "Blog topic",
"defaultValue" : "golf"
} ]
次に、次のようにAIDPToolConfをインスタンス化します。
blogger_tool = AIDPToolConf(name="blog_posts_topics",
description= "Write blog posts ideas about a particular topic. ",
tool_class = "PromptTool", conf=prompt_config params=prompt_params)
最後に、支援ユーティリティからcreate_langgraph_tool()ユーティリティ関数を使用してLangGraph互換ツールを作成します。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())
新しく作成したツールをReActエージェントに追加します。LangGraphでは、コードは次のようになります。
tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>,
tools=tools_agent1,
prompt=<system_prompt>,
debug=True, checkpointer= checkpointer)
表22-4プロンプト・ツールの構成プロパティ
| プロパティ | 入力してください | 説明 |
|---|---|---|
| llm | オブジェクト | LLM接続の詳細およびパラメータ |
| model_id | 文字列 | 使用するモデルの識別子(例: "xai.grok-4") |
| モデルプロバイダ | 文字列 | LLMモデルのプロバイダ名(汎用など) |
| compartment_id | 文字列 | Oracle Cloud Infrastructure (OCI)コンパートメントOCID |
| endpoint | 文字列 | モデルのエンドポイントURL |
| prompt_template | 文字列 | 動的挿入のために、{{variable}}形式の変数とともにLLMで使用されるプロンプト・テンプレート |
テスト・エージェント・プロンプト・ツール
エージェントとは無関係にツールをテストするには、「テスト」タブをクリックして、各パラメータの値を入力します。プロンプトが、選択したLLMに送信されます。
プロンプト・ツールが適切に定義され、文書化されていることを確認して、エージェントの結果を改善します。
エージェントへのプロンプト・ツールの追加
プロンプト・ツールをエージェントに追加して、選択したLLMに発行するパラメータ化されたプロンプトを定義できます。
- エージェントにナビゲートします。
- ツール・テンプレートから、プロンプト・ツールをキャンバスにドラッグ・アンド・ドロップします。
- 「構成」タブで、使用するLLMを選択し、LLMのプロンプトを指定します。「コード」
をクリックして、構成をJSONコードとして指定します。 - レスポンスの温度を0.0から1.0の間の値として指定します。0.0は厳密に事実に基づくレスポンスを提供し、1.0は最も創造的なレスポンスを提供します。
- 「適用」をクリックします
- 構成で設定したパラメータの定義を指定します。「コード」 をクリックして、構成をJSONコードとして指定します。
「Apply」をクリックします。- オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。
RAGツール
RAGツールは、自然言語問合せをベクトル・ストアに発行し、問合せと格納されたドキュメントのセマンティック類似性に基づいてドキュメントを取得します。
ノート:
ナレッジ・ベースは、RAGツールを作成するための前提条件です。詳細は、「ナレッジ・ベース」を参照してください。ビジュアルフローによるRAGツール
RAGツールでは、エージェント開発者が次のパラメータの値を指定する必要があります。
- エージェント対応:
- ツール名:自分および他のユーザーがその機能を識別するのに役立つツールのわかりやすい名前。
- ツールの説明:ツールの概要を示す簡単なサマリー。
- ツール構成:
- ナレッジ・ベース: Oracle AI Data Platform Workbenchカタログの1つに格納されているナレッジ・ベース。
- ナレッジ・ベース: Oracle AI Data Platform Workbenchカタログの1つに格納されているナレッジ・ベース。
エージェントは、エンド・ユーザーとの会話に基づいて問合せフィールドの値を設定します。この問合せフィールドは、自然言語問合せを使用します。
制限は、ツールがベクトル・ストアから取得するドキュメント・チャンクの数です。この値は、エージェント自体ではなく、エージェント開発者によって設定されます。
RAGのテスト・タブをクリックして、エージェントによって発行された問合せをシミュレートすることもできます。
LangGraphコードによるRAGツール
コードを使用してエージェントにRAGツールを構築するには、ビジュアル・フローと同じ設定およびパラメータを構成する必要があります。たとえば、RAGパラメータを次のように設定します。
rag_params = [ { "name" : "query",
"type" : "string",
"description" : "<insert a description>",
"defaultValue" : "<empty>”} ]次に、RAG構成を設定します。
rag_config = { "catalog": "<catalog>",
"schema": "<schema>",
"knowledgeBase": "<knowledge-base-name>",
"top_k": <number-of-documents-retrieved>,
"llm": {
"model_id" : "<model-name>",
"model_provider" : "<model-provider>",
"compartment_id" : "<your-compartment-OCID>",
"endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" }
}最後に、支援ユーティリティからcreate_langgraph_tool()ユーティリティ関数を使用してLangGraph互換ツールを作成します。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>",
description= "<your-tool-description>",
tool_class = "RAGTool",
conf=rag_config,
params=rag_params)
rag_tool = create_langgraph_tool(rag_conf.model_dump())表22-5 RAGツールの構成プロパティ
| プロパティ | 入力してください | 説明 |
|---|---|---|
| llm | オブジェクト | LLM接続の詳細 |
| catalog | 文字列 | データ・カタログ識別子 |
| スキーマ | 文字列 | カタログ内のスキーマ |
| ナレッジベース | 文字列 | 検索するナレッジ・ベースの名前またはキー |
| 上位_K | 整数 | 取得する上位一致ドキュメントの数 |
テスト・エージェントRAGツール
エージェントをAIコンピュート・クラスタにアタッチした後、「テスト」タブからRAGツールをテストできます。詳細は、Attach an Existing AI Cluster to an Agentを参照してください。
RAGツールをエージェントに追加する
エージェントに検索拡張生成(RAG)ツールを追加して、エージェントがレスポンスの生成時に関連する外部ナレッジを取得できるようにします。
- エージェントにナビゲートします。
- ツール・テンプレートから、RAGツールをキャンバスにドラッグ・アンド・ドロップします。
- 「構成」タブで、RAGツールが情報をプルするナレッジ・ベースを選択し、プルする情報を定義するためのプロンプトを指定します。「コード」 をクリックして、構成をJSONコードとして指定します。
- 「適用」をクリックします
- 構成で設定したパラメータの定義を指定します。「コード」 をクリックして、構成をJSONコードとして指定します。
- 「Apply」をクリックします。
- オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。
SQLツール
SQLツールを使用すると、エージェント・フロー開発者は、Oracle AI Data Platformカタログに登録された表に対して事前定義済のSQL問合せを実行できます。
設計時に問合せを記述し、必要なランタイム変数を定義します。エージェントはツールを呼び出すときにこれらの変数の値を提供し、その結果はエージェントが要約またはダウンストリーム・ノードに渡すことができる構造化行として返されます。
SQLツールでは、2つの問合せ言語がサポートされています。Spark SQLは、AIデータ・プラットフォームに格納された標準カタログ表に対して実行され、Sparkクラスタが必要です。Oracle SQLは、Oracle Autonomous AI Databaseなどの外部データベースに対して実行されます。ツールごとに方言を選択し、設定の復元は両方で同じです。
ノート:
SQLツールは、読取り問合せを対象としています。一般的なツールはSELECT文を実行し、行を返します。構成するカタログ、スキーマおよび問合せは、ツールに対してプライベートであり、エージェントには公開されません。エージェントには、ツール名、説明、およびAIツール定義(実行時変数)のみが表示されます。ノート:
SQL問合せツールは、停止したクラスタを自動的に起動しません。そのため、Spark SQL問合せツールに使用されるSparkクラスタには、永久の期間が必要です。クラスタがアイドル・タイムアウトでスピン・ダウンできる場合、クラスタが停止すると、Spark SQL問合せは本番での動作を停止します。静的問合せと動的問合せ
静的問合せは、エージェントによる実行時決定なしで、指定した内容を正確に返します。動的問合せには、実行時に値が設定されていることをエージェントに通知する1つ以上の{{variable}}プレースホルダが含まれます。プレースホルダごとに、名前、タイプ、オプションのデフォルト値、およびエージェントが値の選択に使用する説明を指定します。
SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = 2025
ORDER BY customer_name {{year}}プレースホルダに置き換えると、エージェントがパラメータ化できる動的問合せになります。 SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = {{year}}
ORDER BY customer_name プレースホルダを追加すると、「AI Tool」定義ペインに各変数が移入されるため、そのタイプ、デフォルト値および説明を設定できます。
SELECT incident_id, project_id, incident_date, incident_type,
severity, description, workers_involved, days_lost,
root_cause, corrective_action, reported_by, status
FROM safety_incidents
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')各変数に明確な説明と適切なデフォルトを指定します。この説明は、有効な値をエージェントに知らせ、エージェントが値を指定しない場合のデフォルトが使用されます。
ノート:
プレースホルダ名では、大文字と小文字は区別されます。{{SEVERITY}}として記述され、{{severity}}として記述されたプレースホルダは、常に小文字を使用しないかぎり、2つの異なる変数として扱われます。
JSONとしての構成の編集
{
"catalogKey": "construction_data",
"schemaKey": "admin",
"query": "SELECT project_id, project_name, client_name, ...",
"isRowLimitEnabled": null,
"maxRows": null
}
行の制限
ツールが返す行数を制限するには、「戻す最大行数」を選択し、制限値を入力します。行制限により、パフォーマンスが保護され、エージェントに送信されるデータの量が制御されます。
この値は、エージェントが使用しているモデルに対して相対的に設定します。値を大きくすると、問合せが大きい行または大きいテキスト値を持つ列を返した場合に、エージェントが失敗する可能性があります。予期しないエージェント・エラーが表示される場合は、maxRowsを減らすことから始めます。
行制限は、問合せが実行される前に、SQL問合せ自体に適用されます。ほとんどのモデルは制限を検出し、エンド・ユーザーに表示します。静的問合せの場合、制限は使用可能な最初のn行を返します。
ノート:
エンド・ユーザーに対して行制限を表示しない場合は、指示に従ってエージェントに指示します。問合せの例
問合せの例およびSQLツール問合せの記述ガイドは、「問合せの例およびガイドの表示」ボタンから参照できます。
このガイドでは、様々な問合せパターンを示し、問合せパラメータに関する様々な推奨事項を示します。
LangGraphコードを使用したSQLツール
ビジュアル・フローと同様に、問合せを作成して、LangGraphコードを使用してエージェントのSQLツールの作成を開始します。
sql_config = { "catalogKey": "adw23ai_phx",
"schemaKey": "gold",
"query": """Select ... from ... limit {{max_number}}""" }
SQL問合せの各パラメータは、名前、型、説明およびオプションでdefaultValueを使用してparams引数に記述します。
sql_params = [ { "name" : "max_number",
"type" : "string",
"description" : "<your-description>",
"defaultValue" : "<your-default-value>" } ]最後に、支援ユーティリティからcreate_langgraph_tool()ユーティリティ関数を使用してLangGraph互換ツールを作成します。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>",
description= "<your-tool-description>",
tool_class = "SQLTool",
conf=sql_config,
params=sql_params)
sql_tool = create_langgraph_tool(sql_conf.model_dump())表22-6 SQLツールの構成プロパティ
| プロパティ | 入力してください | 説明 |
|---|---|---|
| カタログ・キー | 文字列 | カタログまたはデータベース接続の識別子 |
| スキーマ・キー | 文字列 | カタログ/データベース内のスキーマ名 |
| 問合せ | 文字列 | SQL問合せ文字列には、{{}}にプレースホルダを含めることができます |
テスト・エージェントSQLツール
「テスト」タブは、エージェント・フロー全体を実行せずに、ツールを単独で実行します。テストは両方の方言で同じように機能します。「テスト」タブを開き、各ランタイム・パラメータの値を指定(またはデフォルトを使用)し、「送信」をクリックして問合せを実行し、レスポンスを表示します。
ノート:
ツールをテストするには、エージェントがAIコンピュートにアタッチされている必要があります。AIコンピュート・ラベルが緑色で、選択したAIコンピュートがACTIVE状態の場合は、AIコンピュートがアタッチされます。SQLコマンド・リファレンス
SQLツール問合せは、標準のSQL句から作成された読取り問合せです。Oracle SQL方言は、外部データベースに対してOracle SQLに従います。Spark SQL方言は、Delta Lake表である標準のカタログ表をターゲットとします。この標準カタログでは、現在、Delta Lake 3.2.0でSpark 3.5が実行されます。ほとんどの句は、標準のSQLに従うため、両方の方言で同じように記述されます。主な違いは、各方言が行数を制限する方法です。次の表に、SQLツール問合せで最も頻繁に使用される句およびキーワードを、各方言のフォームとともにリストします。
| キーワードまたは句 | 目 的 | Oracle SQL | Spark SQL |
|---|---|---|---|
| SELECT | 戻す列を選択します | SELECT col1, col2 |
|
| DISTINCT | 一意の行のみを返す | SELECT DISTINCT col |
SELECT DISTINCT col |
| FROM | ソース表に名前を付けます。 | FROM table_name |
FROM table_name |
| WHERE | 条件による行のフィルタ | WHERE col = value |
WHERE col = value |
| その他 | 条件の組合せまたは否定 | a AND b OR NOT c |
a AND b OR NOT c |
| 次に含まれる | リスト内の任意の値に一致 | col IN (a, b, c) |
col IN (a, b, c) |
| BETWEEN | 包含範囲に一致 | col BETWEEN x AND y |
col BETWEEN x AND y |
| LIKE | テキスト・パターンに一致 | col LIKE 'A%' |
col LIKE 'A%' |
| IS NULL | 欠損値のテスト | col IS NULL |
col IS NULL |
| ORDER BY | 結果をソートします。 | ORDER BY col DESC |
ORDER BY col DESC |
| GROUP BY | 集計の行をグループ化 | GROUP BY col |
GROUP BY col |
| HAVING | グループ化された行のフィルタ | HAVING COUNT(*) > 1 |
HAVING COUNT(*) > 1 |
| 参加 | 2つの表の行を結合 | a JOIN b ON a.id = b.id |
a JOIN b ON a.id = b.id |
| AS | 列の別名または表 | col AS name |
col AS name |
| UNION ALL | 2つの結果セットの結合 | q1 UNION ALL q2 |
q1 UNION ALL q2 |
| CASE | 条件付きで値を返します。 | CASE WHEN c THEN x END |
CASE WHEN c THEN x END |
| 集計 | 行の集計 | COUNT SUM AVG MIN MAX |
COUNT SUM AVG MIN MAX |
| 行制限 | 行数を制限する | FETCH FIRST n ROWS ONLY |
LIMIT n |
ノート:
通常、行制限は自分で記述しません。返す最大行数の設定が適用されます。FETCH FIRSTおよびLIMITフォームは、問合せ内に明示的な制限が必要な場合にのみ役立ちます。完全なSQL文法および各方言の背後にある問合せエンジンについては、次の参照を参照してください。
Spark SQLおよびDelta Lake (標準カタログ)
- Apache Spark SQL構文: DML文 Spark SQL問合せおよびDML文の構文。
- デルタ・レイク: デルタ表に対する表の削除、更新およびマージDELETE、UPDATEおよびMERGE操作。
- デルタ・レイク: 表ユーティリティ・コマンド OPTIMIZEやVACUUMなどのユーティリティ操作。
- デルタ・レイク: デルタ表に対する液体クラスタリングの使用デルタ表レイアウトに対する液体クラスタリング。
エージェントへのSQLツールの追加
エージェントにSQLツールを追加して、登録済外部カタログ内の構造化データ・ソースに対してSQL問合せを実行できるようにすることができます。
- エージェントのコネクタ・ハンドルをクリックしてドラッグし、ツール・ノードに接続します。
- 「問合せ方言」を選択します。
- Spark SQLは、標準のAI Data Platformカタログに対して問合せを記述します。
- Oracle SQLは、外部AI Data Platformカタログに対して問合せを書き込みます。
ノート:
Spark SQLには、AIデータ・プラットフォーム・ワークベンチ・ワークスペースで実行中のSparkクラスタが必要です。
- 「クラスタ」ドロップダウンから、実行中のSparkクラスタを選択します。「クラスタの作成」をクリックして、新しいSparkクラスタをプロビジョニングします。新規クラスタの作成のガイダンスは、カスタム・クラスタの作成を参照してください。
ノート:
SQL問合せツールは、停止したクラスタを自動的に起動しません。そのため、Spark SQL問合せツールに使用されるSparkクラスタには、永久の期間が必要です。クラスタがアイドル・タイムアウトでスピン・ダウンできる場合、クラスタが停止すると、Spark SQL問合せは本番での動作を停止します。
- 「カタログの参照」で、検索フィールドを使用してカタログを名前で検索するか、カタログ・マネージャをクリックしてカタログを検索します。
- 「問合せ」フィールドに、問合せを入力します。「問合せの例およびガイドの表示」をクリックして、コピーまたは適応できる既製のパターンを含むパネルを開きます。
- 「AIツール定義」ペインで、問合せで設定した変数のタイプ、デフォルト値および説明を設定します。
- オプション: 「テスト」タブをクリックします。テスト・パラメータを指定し、「発行」をクリックします。「テスト結果」ペインのテスト結果を参照してください。
エージェント・メモリー
エージェント・メモリーは、エージェントがターン、タスクまたはセッション間で情報を保持および再利用できるようにするAIエージェント・システムの一部です。
一時的で現在のプロンプトに限定されるモデルのコンテキスト・ウィンドウとは異なり、メモリーは、ファクト、プリファレンス、事前の決定、ツール出力、中間計画または環境に関する観察を保持できます。
AIデータ・プラットフォームのエージェント・メモリー
AIデータ・プラットフォームは、セッションの期間に制限された短期メモリーを提供します。エージェントの「メモリー」タブで、メモリーに保持できる内容を構成できます。
単一エージェントのメモリー構成
単一のエージェント・システムのメモリー構成は、エージェント・ノードの「メモリー」タブにあります。
| メモリー構成 | 説明 |
|---|---|
| エージェント・メモリーの有効化 | この設定により、エージェント・メモリーが有効になります。無効にすると、エージェントは基本的にステートレス・システムになります。各ターンが独立して扱われ、フォローアップの質問はできません。メモリーを有効にすることをお薦めします。 |
| 会話履歴の制限 | この選択を無効にすると、モデルがコンテキストを使い果たしてエラーが返されるまで、前のターンでメモリーがいっぱいになります。短いセッションが予想される場合は、この設定を無効にしてもかまいません。ただし、ほとんどのユース・ケースでは、会話履歴を制限することをお薦めします。 |
| 切捨て構成 | 会話履歴を制限する場合は、次の方法で履歴を切り捨てることができます。
|
| 最大メッセージ制限 | 最後のNメッセージを保持することを選択した場合は、値Nを設定できます。 |
| トークン予算 | または、トークン予算全体を設定できます。最初のトークンは、最新のトークンをメモリー内に保持するために削除されます。 |
マルチエージェント・システム・メモリー構成(スーパーバイザ・パターン)
マルチエージェント・システムのメモリーは、スーパーバイザ・エージェントの「メモリー」タブで構成されます。
マルチエージェントシステムのメモリーは強制され、無効にすることはできません。また、スーパーバイザエージェントノードに表示されるメモリーの切り捨てオプションは、スーパーバイザエージェントのメモリーにのみ適用されます。各エグゼキュータ・エージェントのメモリー切捨てポリシーは、システム全体に対して選択された状態分離ポリシーに基づいて、エグゼキュータ・ノードの「メモリー」タブで構成できます。
マルチエージェント・システム・メモリー構成では、エグゼキュータ・エージェントのメモリー共有ポリシーを選択することもできます。ステートレス、プライベートおよび共有の3つのオプションを使用できます。ポリシーはすべてのエグゼキュータ・エージェントに適用されます。
| エグゼキュータ・エージェントの状態分離 | 説明 |
|---|---|
| ステートレス | 各エグゼキュータ・エージェントには、スーパーバイザによって割り当てられたタスクのみが表示されます。コール間で履歴が繰り越されることはありません。エグゼキュータエージェントがスーパーバイザエージェントに対してフォローアップ要求を行うことはできません。
ステートレスを選択すると、各エグゼキュータ・エージェントのメモリーが無効になります。 |
| プライベート | 各エグゼキュータ・エージェントは、独自の過去の相互作用のみを参照します。
他のエグゼキュータ・エージェントまたはスーパーバイザ・エージェントとの元のユーザー会話を表示できません。 |
| 共有 | エグゼキュータ・エージェントは、エージェントおよびユーザー全体の会話履歴全体を表示できます。すべてのエージェントは、1つの共有コンテキストから機能します。
共有が選択されている場合は、各エージェント・ノードの「メモリー」タブで、エグゼキュータ・エージェントごとにメモリー切捨てポリシーを個別に構成できます。 |
セッション変数
カスタムのエージェント定義セッション変数を使用して、ユーザー・セッション中にエージェントに追加のコンテキスト・データ・ポイントを提供できます。
セッション変数とは
カスタムのエージェント定義セッション変数は、ユーザー・セッション中にエージェントに追加のコンテキスト・データポイントを提供します。変数は、ツールでのパラメータ値の設定、エージェントへの全体的な指示の提供、コール元やエージェントが埋め込まれているアプリケーションに関するコンテキスト情報の提供など、様々な目的で使用できます。
カスタマー・サポート・エージェントを構築する簡略化されたシナリオを次に示します。カスタマー・サポート・エージェントは、小売Webサイトに統合されています。ユーザーが小売Webサイトにログインすると、そのユーザーに関する情報がクライアント・アプリケーション(ユーザーID、ユーザー名、ジオロケーション、使用デバイス、ショッピング・カートIDなど)によって取得され、その情報はダウンストリーム・サポート・エージェントが使用できます。AIDPのエージェント指示フィールド内でこれらのセッション・パラメータを使用する方法の例を見てみましょう。
You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.
A few guidelines before your start:
You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}? - userName
- 優先挨拶
- 現在のユーザー位置
エージェントは、ユーザーが小売Webサイトとやり取りしていること、ユーザーのロケーションが何であるか、またはユーザーのショッピング・カートの内容に関するコンテキストがないことを事前に把握していません。原則として、クライアント・アプリケーションはこれらの値のすべてまたはサブセットを認識し、リクエスト内の値をエージェントに渡すことができます。次に、セッション・パラメータなど、エージェントへのリクエストの外観の例を示します。
ノート:
次の例では、このリクエストの外観を説明します。これは、実装決定の代理ではありません。"input": [
{ "role": "user",
"content": [
{ "type": "input_text”,
"text": "What material is the belt Mr Outcast made of?",
“variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]
}
]
}
] 「こんにちは、ポールさん、今日のカンクン、Mxの天気はどうですか?」と返答します。
これらのセッション・パラメータのもう1つの用途は、ツールでパラメータ値を設定することです。たとえば、SQL問合せでは、セッション・パラメータ{{sessionParam.CartID}}}を使用してショッピング・カートの内容を取得できます。
Select productID, productName, productDescription,
productPrice from cartTable where cartID ==
{{sessionVariable.cartID}} セッション変数は、エージェントの作成時にエージェント開発者によって定義され、セッションの作成時または再開時にクライアント・アプリケーションによってこれらの属性の値が設定されます。
新しいセッション変数を作成するときに、次の設定を構成できます。
| 設定 | 説明 |
|---|---|
| 必須変数 | エージェントの呼出しごとに、このセッション変数を必須にできるようにします。無効化すると、起動コールごとにセッション変数がオプションになります。 |
| ログ変数 | ログおよびトレースでセッション変数の値を取得できるようにします。無効にすると、変数がログに表示されなくなります。この設定は、機密データを含む変数に対して無効にすることをお薦めします。 |
| 名前 | セッション変数の名前です。わかりやすい名前を使用して、自分および他のユーザーが変数の目的を簡単に判断できるようにします。 |
| デフォルト値 | 定義されている場合、呼出しコールで別の値が定義されていない場合は、デフォルト値がセッション変数に割り当てられます。空白のままにした場合は、呼出しコールの一部として値を割り当てる必要があります。 |
| 説明 | セッション変数の説明。自分および他のユーザーがセッション変数の機能を理解できるように、役立つ説明を入力します。 |
例: ツール構成でのセッション変数の使用
SQL問合せ自体の一部として、SQLツール構成でセッション変数を使用できます。
この例では、セッション変数geoを使用してSQL問合せの結果をフィルタ処理します。
同じ問合せ内でセッション変数およびツール・パラメータを使用できます。次の例では、titleIDパラメータがエージェントによって設定され、セッション変数geoがコール側アプリケーションによって指定されています。
システム生成のセッション変数
セッション変数は、リモートMCPサーバーがエージェントに接続され、MCPサーバーがBearerトークンなどの認証を必要とするときに自動的に生成されます。
session変数は、Bearerトークンの値を保持します。このシステム生成セッション変数の名前は変更できず、必須変数です。システム変数は、MCPノードがキャンバスから削除されると削除されます。
プレイグラウンドでは、システム生成のセッション変数の値を指定します。この場合、MCPサーバーを使用するにはBearerトークンを提供する必要があります。MCPノードの構成時に使用したものと同じ(または異なる)トークンを選択できます。
エージェントをデプロイする場合も同様です。認可トークンを指定する必要があります。詳細は、「プレイグラウンドからのセッション変数への値の割当て」を参照してください。
例: デプロイ済エンドポイントのコール時のセッション変数への値の割当て
この例では、クライアント・アプリケーションがbodyのmetadataフィールドを介してセッション変数値を渡すuserLocationとUserNameの2つのセッション変数があります。PythonおよびOCI CLIを使用して値を割り当てる方法をデモンストレーションします。
Pythonリクエスト・ライブラリを使用する場合、ペイロードは次のようになります。
body = {
"isStreamEnabled" : False,
"trace" : False,
"input" :[{
"role":"User",
"content":[{
"type" : "INPUT_TEXT",
"text" : “Hello how can you help me?”
}]
}],
"metadata": {
"sessionvariables.userLocation": "Canada",
"sessionvariables.UserName": "George"
}
}
response = requests.post(
url = <insert-chat-url>,
params = None,
auth = <insert-oci-signer>,
json = body,
headers={“x-session-id": <insert-a-session-key>,}
) または、OCI CLIを使用する場合、ペイロードは次のようになります。
oci raw-request \
--http-method POST \
--auth security_token \
--request-body '{
"isStreamEnabled": false,
"input": [
{
"role": "user",
"content": [
{
"type": "INPUT_TEXT",
"text": "Hello how can you help me?"
}
]
}
],
"metadata": {
"sessionvariables.userName": "George",
"sessionvariables.userLocation": "Canada"}"
}
}' \
--request-headers '{
"x-session-id": "george-session-may11"
}' \
--target-uri "<insert-your-agent-flow-uri>" 「エージェント変数」タブでのセッション変数の作成
新しいセッション変数を作成し、「変数」タブからエージェントに追加できます。
- 「変数」タブをクリックします。
- 「セッション変数の追加」をクリックします。
エージェント・フローの手順のセッション変数を参照してください
SQLおよびプロンプト・ツール問合せなど、エージェントの指示およびツール構成でセッション変数を参照できます。
- プレイグラウンドで「SQL」または「プロンプト」ツール・ノードをクリックします。
ガードレール
ガードレールは、AIエージェントの動作をガイドおよび制御するための安全メカニズムです。
ノート:
Oracle AI Data Platform Workbenchで提供されるガードレールは、英語でのみ使用可能です。AIデータ・プラットフォーム・ワークベンチで提供されるガードレールは、OCI生成AIサービス・チームによって実装されます。Guardrails for OCI Generative AIを参照してください。ガードレール構成に基づいて、AIデータ・プラットフォーム・ワークベンチ・サービスによって、OCIテナンシ内のガードレールAPIの適用が起動されます。
ビジュアル・フロー・キャンバスのガードレール
デフォルトでは、モデル・プロバイダのネイティブ・セーフティ・コントロールを超えるガードレールはシステムに適用されません。ガードレールを追加するには、エージェント・ビジュアル・フロー・ビルダーにガードレール・ノードをドラッグし、エージェントに接続する必要があります。
ガードレール・ノードは、チャット・トリガーとエージェント・ノード間、スーパーバイザとエグゼキュータ・エージェント間、またはエージェントとツール・ノード間のトラフィックをフィルタできます。ほとんどのシナリオでは、chatトリガーとエージェント・ノードの間に単一のガードレール・ノードを推奨します。これにより、受信ユーザーからのメッセージおよびエージェントによって生成されたメッセージがガードレールでフィルタされます。
- チャット・トリガー・ノードおよびエージェント(スーパーバイザまたはエグゼキュータ)
どのようなガードレールが利用できますか?
次の図は、エンド・ユーザーとエージェント間の単純な相互作用を示しています。このシナリオでは、すべてのガイドレールが適用されます(コンテンツ・モデレーション- CM、迅速な注入防止- PI、PII検出- PII)。PIはユーザークエリーにのみ適用されます。
エンド・ユーザーによって発行された2番目のメッセージの後、PI試行が検出され、エージェント開発者がPI検出(ブロック)に対して選択したアクションの後にユーザー・メッセージがブロックされました。
コンテンツ・モデレーション
コンテンツのモデレーションは、ほとんどの生成AIにおけるガードレールの一般的な実装です。チェックを外すと、LLMは有害なコンテンツを生成し、暴力的、人種差別的、性的に露骨なコンテンツを宣伝することができます。エージェント開発者は、エージェントとのユーザー・インタラクションを監視し、有害なコンテンツがないかスキャンする方法を完全に可視化し、制御することが不可欠です。コンテンツのモデレーションは、憎悪、性的、暴力的、有毒、軽蔑的、またはハラスメントベースのコンテンツがエージェントのフローによって考慮または生成されることを防ぎます。ガードレール・モデルは、これらの6つのカテゴリに沿ってコンテンツを分類し、それらのカテゴリのいずれかに属するコンテンツにフラグを付けます。
- ブロック:エージェントがユーザー入力を処理してレスポンスを生成できないようにします。ユーザーは、エージェント・フローからエラー・レスポンスを受け取ります。
- 通知:エージェント・フローでユーザー入力を処理し、レスポンスを生成できます。エージェントは、入力またはレスポンスにガードレール基準を満たすコンテンツが含まれていることをユーザーに通知します。
- 許可:エージェント・フローによる有害なコンテンツの処理または生成(あるいはその両方)を許可します。
エージェント・フローの作成時に、コンテンツ・モデレーションに対して「ブロック」アクションが選択されます。Oracleでは、コンテンツ・モデレーションのガードレール選択として「ブロック」を保持することをお薦めします。
プロンプトインジェクション
AIエージェントのプロンプト・インジェクション・ガードレールは、ユーザー入力に埋め込まれた悪意のある命令または意図しない命令を検出、防止および軽減する保護メカニズムです。プロンプト・インジェクション攻撃では、以前のルールの無視、シークレットの抽出、認可されていないアクションの実行をモデルに指示する隠しテキストを挿入して、エージェントの元の指示、ポリシーまたは目標をオーバーライドまたは無効化しようとします。
- ブロック:エージェントがユーザー入力を処理できないようにします。ユーザーは、エージェント・フローからエラー・レスポンスを受け取ります。
- 通知:エージェント・フローによるユーザー入力の処理を許可します。エージェントは、入力にガードレール条件を満たすコンテンツが含まれていることをユーザーに通知します。
- 許可:エージェント・フローによる潜在的に有害なコンテンツの処理を許可します。
「ブロック」アクションは、エージェント・フローの作成時にプロンプト・インジェクションが選択されます。Oracleでは、プロンプト・インジェクション用のガードレール選択として「ブロック」を保持することをお薦めします。
個人の身元を特定する情報(PII)
PIIガードレールは、ユーザー入力問合せまたはエージェント・レスポンスからPIIを自動的に検出、ブロックまたはマスクします。このガードレールは、エージェントがプライバシー規制や組織ポリシーに違反する方法で機密ユーザー情報を公開することを防ぎます。
- 電話番号
- 物理アドレス
- 個人情報
- ブロック:エージェントがユーザー入力を処理してレスポンスを生成できないようにします。ユーザーは、エージェント・フローからエラー・レスポンスを受け取ります。
- 通知:エージェント・フローでユーザー入力を処理し、レスポンスを生成できます。エージェントは、入力またはレスポンスにPIIが含まれていることをユーザーに通知します。
- マスク:エージェント・フローが入力を処理し、マスクされたレスポンスを生成することを許可します。使用されるPIIは、露出を防ぐためにリダクションされます。
- 許可:エージェント・フローによるPIIデータの処理または生成(あるいはその両方)を許可します。
新規エージェント・フローでは、PIIはデフォルトでユーザー入力とレスポンスの両方で許可されます。Oracleでは、セキュリティ・ニーズに基づいてPIIのガードレールを慎重に選択することをお薦めします。
エージェントのAIクラスタの作成
新しいAIクラスタをエージェント・インタフェースから直接作成し、すぐにアタッチできます。
- ホーム・ページで、エージェントにナビゲートします。
- 「コンピュート」をクリックし、「新しいAIコンピュートの作成」をクリックします。
- AIコンピュート・クラスタの名前および説明を指定します。
- AIコンピュート・クラスタのOCPU数およびメモリー・サイズを選択します。
- 「作成」をクリックします。
AIコンピュートからのエージェントのデタッチ
AIコンピュートからエージェントをデタッチできます。AIコンピュートをデタッチすると、アタッチされたコンピュートで実行されているエージェント・コードが削除され、テストが回避されます。
ノート:
AIコンピュートからエージェントをデタッチしても、エージェントは削除されません。同じまたは異なるAIコンピュートにエージェントをアタッチすることで、エージェントの構築およびテストを再開できます。- 「コンピュート」をクリックし、「AIコンピュートからのデタッチ」をクリックします。
A2Aエージェント・デプロイメント
Agent2Agent(A2A)プロトコルは、異なるフレームワークで構築されたエージェント、異なるベンダーによってホストされたエージェント、または不透明なリモート・システムとして実行されるエージェントなど、独立したAIエージェント間の通信のためのオープン・スタンダードです。
その目的は、これらのエージェントに共有インタラクション・モデルを提供して、互いの能力を発見し、サポートされている入出力形式を交渉し、タスクを委任または協力し、内部メモリー、ツールまたは実装の詳細を公開せずに情報を安全に交換できるようにすることです。詳細は、Agent2Agent (A2A)プロトコルを参照してください。
A2Aは、エージェントの相互運用性を解決することを目的としています。すべてのエージェント統合がカスタムであるのではなく、クライアントまたは別のエージェントは、共通の概念と操作セットを使用して、任意のA2A準拠のリモート・エージェントと対話できます。この仕様は、メッセージ、タスク、パーツ、アーティファクト、ストリーミング更新およびプッシュ通知を中心にしており、同期応答、長時間実行される非同期作業、ストリーミング、およびエンタープライズスタイルの認証/セキュリティ・パターンをサポートしています。
Oracle AI Data Platformでは、デプロイされたすべてのエージェントに、A2Aクライアント・アプリケーションからコールできる/A2A呼出しパスが提供されます。
エージェントカードとは?
エージェント・カードは、A2Aサーバーによって公開されるJSONメタデータ・ドキュメントです。AIDPでは、A2Aサーバーはエージェント・デプロイメントをホストするAIコンピュートです。
このカードは、エージェントのID、サービス・エンドポイント、サポートされているプロトコル/トランスポート、機能、スキル、サポートされている入出力モードおよび認証要件を記述します。クライアントはこれを使用して、エージェントが適切かどうか、およびエージェントの呼出し方法を検出します。適切に文書化されたエージェント・カードは、A2Aプロトコルの要件です。
AI Data Platform Workbenchのエージェント・カードは、「ドラフト」状態(エージェントがデプロイされていないことを意味する)または「公開済」のいずれかであり、カードがエージェントとともにデプロイされたことを意味します。
エージェント・カード処理
エージェントの開発中に、エージェントの「アクション」メニューでカードを使用できます。
- ドラフト・カードには、開発中のエージェントの現在の状態が反映されます。
- 公開済カードは、エージェントのデプロイ時に取得されたカードのスナップショットに対応しています。公開済カードには、デプロイ済エージェントの状態が反映されます。
エージェント・カード・フィールド
AI Data Platform Workbenchでは、現在のA2Aプロトコル・エージェント・カード・フィールドのサブセットがサポートされています(A2Aプロトコル- エージェント・カード)。
| フィールド | 必須 | 説明 |
|---|---|---|
name |
○ | 人間が判読可能なエージェント名。例: "レシピ・エージェント" |
description |
○ | エージェントの人間が読める説明で、ユーザーや他のエージェントがその目的を理解するのに役立ちます。例: 「レシピと料理をユーザーに提供するエージェント」。 |
Agent Version |
○ | エージェントのバージョン。例: "1.0.0" |
Documentation URL |
× | エージェントに関する追加のドキュメントを提供するURL。 |
Provider - Organization |
× | エージェントのサービス・プロバイダ。 |
Provider - URL |
× | サービス・プロバイダのURL。 |
Capabilities |
○ | エージェントがサポートするA2A機能セット。
|
Skills
|
○ | スキルは、エージェントの能力を表します。これは主に説明的な概念ですが、エージェントが成功する可能性が高い、より焦点を絞った一連の動作を表します。スキルはAgentSkillの配列を表します。 |
各AgentSkillは、エージェントの機能をドキュメント化する複数のフィールドで構成されています。エージェント・カードでのエージェント・スキルの定義は最も時間がかかる操作であり、反復プロセスです。スキルは、デプロイ前にエージェント・カードのドラフトで(エージェント・カードの残りとともに)編集できます。
ノート:
inputModes、outputModesおよび securityRequirementsは、AI Data Platform Workbenchによって提供されており、変更できません。
| フィールド | 必須 | 説明 |
|---|---|---|
Skill ID |
○ | エージェントのスキルの一意の識別子。 |
Skill Name |
○ | スキルの判読可能な名前。 |
Description |
○ | スキルの詳細な説明。 |
Tags |
○ | スキルの機能を記述する一連のキーワード。 |
Examples |
× | このスキルが処理できるプロンプトまたはシナリオの例。 |
エージェント・デプロイメント・エンドポイントA2Aパス
/a2aパスは、デプロイされたエージェントのURLに/chatに加えて公開されます。
たとえば、エージェントはこれらのパスを外部クライアントに公開します。
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chathttps://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a
両方のパス(/chat、/a2a)を別々のクライアントで使用できます。
A2Aのセッション変数
セッション変数の値は、メッセージmetadataフィールドでA2Aエージェントに渡すことができます。次のJSONスニペットは、userName、geoLocationおよびosの3つのセッション変数を使用してa2aエージェントに発行されたユーザー・メッセージのペイロードを示しています。
{
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"contextId": "session_12345",
"taskId": "task_67890",
"message": {
"role": "user",
"parts": [
{
"text": "What is the current status of my order?",
}
],
"metadata": {
"sessionvariables.userName": "George",
"sessionvariables.geoLocation": “Dallas, TX”,
"sessionvariables.os": "mobile_ios"
}
}
},
"id": "rpc-99821"
}
例: OCI CLIを使用したA2Aエージェントの起動(非ストリーミング)
oci raw-request \
--http-method POST \
--auth security_token \
--request-body '{
"id": "<your-request-id>",
"jsonrpc": "2.0",
"method": "message/send",
"params": {
"configuration": {
"acceptedOutputModes": [
"text/plain",
"text"
]
},
"message": {
"contextId": "<your-context-id>",
"kind": "message",
"messageId": "<your-message-id>",
"parts": [
{
"kind": "text",
"text": "What is the capital of India?"
}
],
"role": "user"
}
}
}' \
--request-headers '{
"x-session-id": "<your-session-id>",
"dh-user-principal": "<your-user-principal>"
}' \
--target-uri " <your-a2a-agent-endpoint-url>"
例: OCI CLIを使用したA2Aエージェントの起動(ストリーミング)
oci raw-request \
--http-method POST \
--auth security_token \
--request-body '{
"id": "<your-request-id>",
"jsonrpc": "2.0",
"method": "message/stream",
"params": {
"configuration": {
"acceptedOutputModes": [
"text/plain",
"text"
]
},
"message": {
"contextId": "<your-context-id>",
"kind": "message",
"messageId": " <your-message-id>",
"parts": [
{
"kind": "text",
"text": "What is the capital of India?"
}
],
"role": "user"
}
}
}' \
--request-headers '{
"x-session-id": "<your-session-id>",
"dh-user-principal": "<user-principal>"
}' \
--target-uri "<your-a2a-agent-endpoint-url>"
例: A2AクライアントSDK
import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
AgentCard,
Message,
Part,
Role,
TextPart,
SendMessageRequest,
MessageSendParams,
MessageSendConfiguration,
Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)
class OCIAuth(httpx.Auth):
"""httpx auth implementation using OCI signer via requests auth adapter."""
def __init__(self, signer: oci.signer.AbstractBaseSigner):
self._requests_auth = _OCIRequestsAuth(signer)
def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
req = RequestsRequest(
method=request.method,
url=str(request.url),
headers=dict(request.headers),
data=request.content,
)
prepared: RequestsPreparedRequest = req.prepare()
prepared = self._requests_auth(prepared)
request.headers.update(dict(prepared.headers))
yield request
def getOCIAuth():
conf = oci.config.from_file(profile_name="DEFAULT")
token_file = conf['security_token_file']
token = None
with open(token_file, 'r') as f:
token = f.read()
private_key = oci.signer.load_private_key_from_file(conf['key_file'])
signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
auth = OCIAuth(signer=signer)
return auth
async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
"""Call an agent using the A2A protocol."""
try:
# Initialize OCI signer
#headers = {"dh-user-principal": "dh-user"}
headers = {"Accept": "*/*",
"dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
agent_card = await _get_agent_card(agent_url,auth)
print(f"Agent card is {agent_card}")
client = A2AClient(httpx_client=hc, agent_card=agent_card)
# Create message
message = Message(
message_id=str(uuid.uuid4()),
context_id=context_id,
role=Role.user,
parts=[Part(root=TextPart(text=query))],
metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
)
request = SendMessageRequest(
id=str(uuid.uuid4()), # Add the required id field
params=MessageSendParams(
message=message,
configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
),
)
#json_string = json.dumps(message, indent=4)
print(f"Send request : {request}")
response = await client.send_message(request)
logging.info("Received response from A2A server: %s", response.root.result)
# Extract response
result = response.root.result
# Handle different response types
if isinstance(result, Task):
# Task response
if result.artifacts:
# Extract text from artifacts
texts = []
for artifact in result.artifacts:
for part in artifact.parts:
if hasattr(part, "root") and hasattr(part.root, "text"):
texts.append(part.root.text)
return "\n".join(texts) if texts else "Task completed with no text response"
elif result.status and result.status.message:
logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
if result.status.state== "failed":
print("Failure observed in Task invocation")
for m_part in result.status.message.parts:
print(f"Error message { m_part.root.text}")
return get_message_text(result.status.message)
else:
return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"
elif isinstance(result, Message):
return get_message_text(result)
else:
logging.warning(f"Unexpected response type: {type(result)}")
return "Received response but unable to extract text"
except Exception as ex:
logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
return f"Error communicating with agent: {str(ex)}"
async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
"""Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
try:
async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
agent_card = await _get_agent_card(agent_url)
if not agent_card:
return "No Agent Card Found"
print(f"Agent card is {agent_card}")
client = A2AClient(httpx_client=hc, agent_card=agent_card)
message = Message(
message_id=str(uuid.uuid4()),
context_id=context_id,
role=Role.user,
parts=[Part(root=TextPart(text=query))],
)
request = SendStreamingMessageRequest(
id=str(uuid.uuid4()),
params=MessageSendParams(
message=message,
configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
),
)
print("Invoking Remote Agent request (beautified JSON):")
print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
# Expected event types:
# - TaskStatusUpdateEvent (working/in-progress)
# - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
final_artifact_text_parts: list[str] = []
async for event in client.send_message_streaming(request):
# Print each SSE event as-is (SDK object)
print(f"[A2A stream event] {event}")
try:
result = getattr(event.root, "result", None)
if not result:
continue
# TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
# extract by attribute presence.
artifact = getattr(result, "artifact", None)
if artifact and getattr(artifact, "parts", None):
for part in artifact.parts:
root = getattr(part, "root", None)
txt = getattr(root, "text", None)
if txt:
final_artifact_text_parts.append(txt)
except Exception:
# Keep streaming even if an event can't be parsed
continue
return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
except Exception as ex:
logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
return f"Error communicating with agent: {str(ex)}"ドラフト・エージェント・カードの編集
まだデプロイされていないエージェントのエージェント・カードを編集できます。
- 「アクション」をクリックし、「エージェント・カードの表示」および「エージェント・カードのドラフト」をクリックします。
- 「Edit」をクリックします。
- 右上の「フォーム」または「JSON」をクリックすると、ビューを切り替えることができます。JSONビューはより完全ですが、読取り専用です。フィールドは、フォーム・ビューでのみ編集できます。
- 「スキルの追加」をクリックして、A2Aクライアントに公開するスキルを追加します。
公開済エージェント・カードの編集
エージェントをアンデプロイまたは再デプロイしなくても、公開されたエージェント・カードを変更できます。
ノート:
公開されたカードに加えた変更は、A2Aクライアントからアクセス可能なagent-card.jsonファイルにすぐに反映されます。- 「アクション」をクリックし、「エージェント・カードの表示」および「公開済エージェント・カード」をクリックします。
- 「Edit」をクリックします。
- 「スキルの追加」をクリックして、A2Aクライアントに公開するスキルを追加します。
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.jsonエージェントのデプロイメント
エージェントをデプロイすると、エージェントがホスト・アプリケーションになります。
エージェントは、プレイグラウンドまたは別のAIコンピュートにアタッチされているのと同じAIコンピュートにデプロイできます。アタッチされたAIコンピュートにエージェントに最新の変更をデプロイすると、デプロイされたエージェントはデプロイメント時のエージェントのスナップショットを表します。デプロイされたエージェントを最新バージョンに更新するには、エージェントを再デプロイする必要があります。
各エージェントには、一意のエージェント・キーに依存する安定したデプロイメントURLがあります。エージェントを複数回再デプロイすると、デプロイメントURLの背後にあるエージェントが上書きされます。
- エージェントは、いつでも1つのAIコンピュート・クラスタにのみデプロイできます。
- 同じAIコンピュート・クラスタに同じエージェントを複数回デプロイすると、以前にデプロイされたエージェントの反復が上書きされます。
エージェントをデプロイしたら、チャットURIを取得して、プログラムで問合せを発行し、エージェントの「詳細」タブからエージェントからレスポンスを取得できます。
エンドポイントURLは安定しており、各エージェントに関連付けられています。URLには、各エージェントに割り当てられた一意のagentIDが含まれます。つまり、エージェントをアンデプロイして再度デプロイしても、URLは同じままです。利点は、エンドポイントをコールするクライアント・コードを変更する必要がないことです。デメリットは、本番環境でエージェントを上書きできることです。
https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}oci-regionは、AI Data Platformインスタンス・リージョンに対応します。agentIdは、エージェントに関連付けられた一意のIDです。protocolは通信プロトコルです。chatはOpenAIレスポンスAPI形式に従い、a2aはエージェント間通信プロトコルに従います。両方のプロトコルは、エージェント・エンドポイントごとに使用できます。詳細は、「A2Aエージェントのデプロイ」を参照してください。
ノート:
「Details」タブに2つのAI計算が一覧表示されます。「AIコンピュートにアタッチ」は、プレイグラウンドでエージェントをテストするために使用されます。「AIコンピュートにデプロイ済」は、デプロイされたエージェントをホストします。「エンドポイントURL」フィールドは、エージェントのデプロイ後に移入されます。このエンドポイントURLは、本番アプリケーションからコールできます。
エージェントのデプロイ
作成して構成したエージェントをデプロイし、他のユーザーがAI Data Platformインスタンスで表示して使用できるようにします。
- エージェントの横にある
「アクション」をクリックし、「デプロイ」をクリックします。エージェント名をクリックして、右上の「デプロイ」をクリックすることもできます。
OAuth2でのエージェントのデプロイ
作成して構成したエージェントをデプロイして、OAuth2認証を使用して外部アイデンティティ・プロバイダに接続できます。
- エージェントの横にある 「アクション」をクリックし、「デプロイ」をクリックします。エージェント名をクリックして、右上の「デプロイ」をクリックすることもできます。
デプロイ済エージェントの起動
本番アプリケーションからエージェントのエンドポイントURLを起動できます。
エージェント・エンドポイントの起動に使用されるプログラム・インタフェースに関係なく、OCIで認証され、関連する権限を持っている必要があります。エージェント・フロー・エンドポイントの場合、コール元には、エージェント・エンドポイントに対する少なくともUSE権限が必要です。
エンドポイントURIは、エージェントUIの詳細タブに記載されています。そのエンドポイントURIをコードにコピーして、エージェントを起動できます。
エンドポイントURIを呼び出すメソッド
エージェント・エンドポイントURIは、様々なツール、SDKおよびCLIを介して起動できます。
次のメソッドを使用すると、Oracle AI Data Platform WorkbenchエージェントでエンドポイントURIを起動できます。
OCI CLIで起動
oci raw-request
--http-method POST
--target-uri <your-agent-flow-endpoint-uri>
--request-body '{"query":"Tell me about the Ryder Cup in 1985"}'
--auth <security_token>Pythonリクエスト・ライブラリで起動
import oci import requests import json import uuid from contextlib import closing from requests import Request, Response
class AuthHelper: """ AuthHelper allows creating an OCI signer with either API key or security_token (which are short term sessions) """ def init(self, oci_profile: str, use_security_token:bool = True): config = oci.config.from_file(file_location="/Volumes/jr/default/misc/config",profile_name=oci_profile) if use_security_token: with open(config["security_token_file"], 'r') as f: token = f.read() private_key = oci.signer.load_private_key_from_file(config["key_file"])
self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key) else: self.signer = oci.signer.Signer( tenancy=config["tenancy"], user=config["user"], fingerprint=config["fingerprint"], private_key_file_location=config["key_file"], #pass_phrase=config.get("pass_phrase"), #private_key_content=config.get("key_content") )
@property
def Signer(self):
return self.signer
class MyRawJsonRpcClient: """ Simple class using requests lib to post JSON to chat endpoint using OCI signing """ def init(self, chat_url:str, oci_profile: str, sessionKey:str, use_security_token:bool = True): self.authhelper = AuthHelper(oci_profile=oci_profile, use_security_token=use_security_token) self.authsigner = self.authhelper.Signer self.chat_url = chat_url self.sessionKey = sessionKey
def send(self, input:str) -> Response:
body = {
"isStreamEnabled" : False,
"sessionKey" : self.sessionKey,
"trace" : False,
"input" :[{
"role":"User",
"content":[{
"type" : "INPUT_TEXT",
"text" : input
}]
}]
}
response:Request = requests.post(
url =self.chat_url,
params = None,
auth = self.authsigner,
json=body,
headers={}
)
return response
sessionKeyを指定できます。sessionKeyは、エージェントとのユーザー・セッションの一意の識別子です。同じsessionKeyを再利用し続けると、ユーザー・メッセージとエージェント・レスポンスが同じ保護に追加されます。 client = MyRawJsonRpcClient(chat_url="<your-agent-flow-endpoint-uri>",
oci_profile = "DEFAULT",
sessionKey= “<your-session-key>”,
use_security_token = False )user_input = f"Hello, tell me a good dad joke."
r = client.send(input = user_input)
response_json = r.json()APEX経由
AI Data Platform WorkbenchサンプルGithubリポジトリで使用可能なコード・サンプルを使用できます。サンプルでは、APEXアプリケーションからエージェント・デプロイメント・エンドポイントをコールするプロセスについて説明します。
Streamlitを使用
AI Data Platform WorkbenchサンプルGithubリポジトリで使用可能なコード・サンプルを使用できます。サンプルでは、Streamlitアプリケーションからエージェント・デプロイメント・エンドポイントをコールするプロセスについて説明します。
ベスト・プラクティス- 非同期応答と非同期応答
非同期レスポンスを想定したクライアント・コードを作成することをお薦めします。たとえば:
import httpx
async def fetch_data():
async with httpx.AsyncClient() as client:
response = await client.get(URL)
return response.json()
エージェントのモニター
エージェントのセッションおよびメトリックに関連する詳細をモニターして、エージェントがどのように使用されているか、使用するリソースなどに関する情報を確認できます。
使用状況の詳細を追跡するためのタブがエージェント内に複数あり、「セッション」タブ、「メトリック」タブおよび「アクティビティ」タブがあります。これらは、エージェント・キャンバスの上部にあります。
トレースおよびスパン
トレースは、エージェント・リクエストのフローを取得および表示することで、エージェントの可観測性を提供します。スパンは、トレースを構成するオブジェクトです。各スパンは、ユーザーからのチャット・プロンプト、エージェントの起動、ワークフロー・タスクなど、フロー内の異なるステップです。
現在のセッション、テスト実行または前のセッションのトレースを確認できます。現在のセッション・トレースを表示するには、「フロー」タブに移動して「プレイグラウンド」をクリックします。ページ下部の「詳細」ペインには、左側のペインに現在のセッションのトレースが表示されます。トレース内のオブジェクトをクリックして展開したり、より詳細な情報を表示できます。右側のペインで、「情報」、「詳細」または「イベント」タブをクリックして、選択したスパン・オブジェクトについてさらに学習できます。
セッションの名前をクリックすると、以前のセッションのトレースを「セッション」タブで確認できます。
セッション
「セッション」タブには、このエージェントのセッションの履歴が表示されます。各セッションが成功したか失敗したか、URIの起点、セッションが開始されたとき、セッションの継続時間、およびセッションで使用されたトークンを確認できます。セッションIDをクリックすると、そのセッションの詳細、およびその特定のセッションのトレースを表示できます。
検索バーを使用してセッションIDまたはURIの起点でフィルタし、日付フィルタを使用して特定の日付範囲のみを表示し、「セッション・ステータス」ドロップダウン・メニューを使用してセッションが成功したか失敗したかによってフィルタすることで、表示されるセッションをフィルタできます。
メトリック
「メトリック」タブには、すべてのエージェント・セッションの使用状況データのサマリーが表示されます。「日付範囲」ドロップダウンは、表示されているカードに要約された期間をフィルタします。URI選択によって、詳細を表示するURI選択ソースがフィルタされます。表示するカードを変更したり、グラフを使用状況の視覚的な表現として含めるかどうかを変更できます。
アクティビティ
「アクティビティ」タブには、エージェント・デプロイメント・ステータスのサマリーが表示されます。「操作」列ではデプロイメント操作のタイプ(デプロイまたはアンデプロイ)を指定し、「ステータス」列では操作の結果(成功、エラー、警告、失敗)を指定します。誰が操作を開始したか、いつ操作の結果に関連付けられたステータス・メッセージを確認できます。
エージェントの移動
所有しているエージェントを移動したり、MANAGE権限を持つエージェントを移動できます。
- ホーム・ページで、移動するエージェントが含まれているフォルダに移動します。
- 変更するエージェントの横にある 「アクション」をクリックし、「移動」をクリックします。
- エージェントの新しいワークスペースの場所を選択します。「移動」をクリックします。
エージェントのコピー
所有しているエージェントをコピーするか、使用可能なワークスペースの別の場所にMANAGE権限を持つことができます。
- ホーム・ページで、移動するエージェントが含まれているフォルダに移動します。
- 変更するエージェントの横にある 「アクション」をクリックし、「ワークスペースにコピー」をクリックします。
- 必要に応じて、コピーしたエージェントの新しい名前と説明を指定します。
- 「参照」をクリックし、エージェントのコピー先となるワークスペース内の新しい場所を選択します。「選択」をクリックします。
- 「コピー」をクリックします。
エージェント・ファイルのダウンロード
エージェント・ファイルと、そのエージェントの定義を含むそれらのガードレール・ファイルをダウンロードできます。
_guardrails.JSONというラベルが付けられ、エージェントのガードレール定義が含まれています。
- ダウンロードするエージェントの名前をクリックします。
- エージェントのAFLOWファイルの横にある 「アクション」をクリックし、「ダウンロード」をクリックします。ファイルがローカル・マシンにダウンロードされる。
_guardrails.JSONファイルの横にある 「アクション」をクリックし、「ダウンロード」をクリックします。ファイルがローカル・マシンにダウンロードされる。