Select AI for Javaでのエージェントのサポート

Select AI for Javaは、DBMS_CLOUD_AI_AGENTを介してデータベース定義のAIエージェント、タスク、ツールおよびチームを操作するためのJava APIを提供します。エージェント・サポートは、Select AI for Javaの一部であり、個別のコンポーネントまたは製品ではありません。このフレームワークを使用して、エージェント・リソースの管理、ツールとチームの実行、リクエスト間でのチーム実行コンテキストの保持、および環境間でのチーム定義の移動を行います。

データベースは、リソースを検証および認可し、リクエストされた操作を実行します。Java SDKは、JDBCを介してデータベースと通信します。個別のJavaエージェント・ランタイムを提供したり、AIプロバイダ・エンドポイントに直接コールしたりすることはありません。

Select AIプロファイル、資格証明、会話、ベクトル索引およびその他のSelect AI操作については、Select AI for Javaを参照してください。

サポートされている環境

Select AI for JavaのSelect AI Agent Framework APIは、次の環境でサポートされています。

• Oracle Autonomous AI Database 26ai
• Oracle Autonomous AI Database 19c

機能要件およびデータベース・バージョン要件については、Oracle AI Database Select AI機能マトリックスを参照してください。

エージェント操作には、リクエストされたDBMS_CLOUD_AI_AGENT操作および関連するメタデータ・ビューをサポートするデータベース・リリースが必要です。Java SDKは、すべての操作のサポートを判断するためにデータベースをプローブしません。

実行可能な操作

Select AI for Java SDKには、Select AI Agent Frameworkリソースを操作するためのJava APIが用意されています。

次の表に、Select AI Agent Framework機能をサポートする主要なSelect AI for Javaの概要を示します。

データベースは、各リクエストを検証および認可し、Java APIを介して結果を返します。エンドツーエンドの例については、example AgentWorkflowSampleを参照してください。

Agent Frameworkオブジェクト・モデル

Select AI for Javaは、Javaインタフェースおよび関連するモデル・クラスを介して、各データベース定義のエージェント・リソースを表します。リソースのロード、リスト表示、構成および作成のエントリ・ポイントとしてSelectAIAgentを使用します。

オブジェクト・モデルには、次の関係があります。

• ツールは、エージェントまたはタスクで使用できる操作を定義します。
• タスクは、作業、指示、入力、およびその作業を完了するために使用できるツールを定義します。
• エージェントは、そのロール、Select AIプロファイル、ツール、タスク、メモリーおよびオプションの監督者の動作を定義します。
• チームは、エージェントをタスクにマップし、チームの実行中にエージェントがどのように連携するかを定義します。
• 会話IDは、アプリケーション・リクエストおよびJDBC接続全体にわたる関連チームの実行および実行状態操作を関連付けます。

Javaハンドルを作成しても、対応するデータベース・リソースは作成されません。新しいリソースの場合は、構成済ハンドルを取得し、そのcreate()メソッドをコールします。既存のリソースの場合は、そのライフサイクル、属性または操作メソッドをコールする前に、名前でロードします。

パブリック・エージェントAPIは、com.oracle.database.selectai.agentで提供されています。パブリック・エージェント・リクエストおよびモデル・クラスは、com.oracle.database.selectai.model.agentで提供されています。

クラスおよびメソッドの完全なドキュメントについては、Select AI for Java API Reference (Javadoc)を参照してください。

クイックスタート: エージェント・チームの作成および実行

エージェント・チームを作成して実行するには:

1. エージェントが使用する Select AIプロファイルを作成または識別します。
2. ワークフローにデータベース定義のツールが必要な場合は、Toolハンドルを構成し、Tool.create()をコールします。
3. Taskハンドルを構成し、Task.create()をコールします。
4. Agentハンドルを構成し、Agent.create()をコールします。
5. 必要なエージェントからタスクへのマッピングを使用してTeamハンドルを構成し、Team.create()をコールします。
6. ワークフローが複数の実行にわたってコンテキストを保持する必要がある場合は、データベース会話IDを作成または取得します。
7. ユーザー・プロンプト、会話IDおよび必要なRunTeamParamsを使用して、RunTeamRequestを作成します。
8. Team.run(RunTeamRequest request)をコールし、戻されたTeamRunResultを処理します。
9. アプリケーションが最新の状態を取得したり、ヒューマン入力を提供したり、チーム実行を再開する必要がある場合は、会話IDを保持します。

必要なリソースを作成し、チームを実行し、同じデータベース会話を続行する完全な例は、例AgentWorkflowSampleを参照してください。

前提条件

Select AI for JavaでSelect AI Agent Frameworkサポートを使用する前に、SDKをインストールして構成し、サポートされているAutonomous AI Databaseに接続し、エージェント・リソースとその依存関係に必要な権限をデータベース・ユーザーに付与します。ワークフローを実行する前に、必要な Select AIプロファイル、資格情報、プロバイダアクセス、ネットワークアクセス、および共有チーム付与を構成します。

Select AI for Javaのインストール

エージェントAPIは、Select AI for Javaに含まれています。インストール、Java要件および依存性構成については、アプリケーションへのSelect AI for Javaの追加を参照してください。

APIの詳細は、Select AI for Java APIリファレンス(Javadoc)を参照してください。

始める前に

Select AI Agent Frameworkを使用する前に:

1. データベース・リリースが、アプリケーションに必要なエージェント操作をサポートしていることを確認します。
2. Select AI for Javaおよび互換性のあるOracle JDBC Thinドライバをアプリケーションに追加します。アプリケーションへのSelect AI for Javaの追加を参照してください。
3. JDBC接続およびアプリケーションに必要なデータベース認証を構成します。Autonomous AI Databaseへの接続を参照してください。
4. データベース・ユーザーに、必要なDBMS_CLOUD_AI_AGENT権限およびエージェント・メタデータ・ビューへのアクセス権を付与します。
5. 必要なSelect AIプロファイル、資格証明、プロバイダ・アクセスおよびネットワーク・アクセスを構成します。
6. 参照されたデータベース・ファンクション、プロシージャ、表、ビューおよび外部リソースがデータベース・ユーザーに使用可能であることを確認します。
7. 共有チームの場合は、チーム所有者からデータベース管理の権限を取得します。
8. リクエストまたはプールされた接続間で再開するワークフローの場合は、データベース作成の会話IDを取得して保持します。

Select AIおよびSelect AI Agent Frameworkの一般的な設定要件については、Select AIの前提条件の実行およびSelect AI Agent Frameworkを使用するための前提条件を参照してください。

データベース権限およびネットワーク・アクセスの管理

エージェント、タスク、ツールまたはチームを使用する前に、データベース・ユーザーにDBMS_CLOUD_AI_AGENTに必要な権限と、該当するエージェント・メタデータ・ビューへのアクセス権があることを確認します。

データベース・ユーザーには、ワークフローで参照されるリソースに必要な権限も必要です。たとえば、データベース・ファンクション、プロシージャ、SQL操作または外部リソースを使用するツールには、対応するデータベース権限および構成が必要です。

エージェントおよびチームのワークフローでは、Select AIプロファイル、プロバイダ資格証明およびネットワーク・アクセスを使用できます。これらのリソースをワークフローおよびデプロイメントに従って構成します。SDKでは、データベース・ユーザー、パッケージ権限、資格証明、ネットワークACLまたは共有チーム権限は自動的に作成されません。

Select AIの設定要件については、Manage Database Privileges and Network Accessを参照してください。エージェント・パッケージの詳細は、DBMS_CLOUD_AI_AGENTパッケージ・リファレンスを参照してください。

ツールの操作

ツールは、エージェントまたはタスクで使用できる操作を提供します。ツールは、データベース・ファンクション、プロシージャ、SQL操作またはサポートされている別のデータベース定義操作を表すことができます。

新しいツールの場合は、次を使用して構成済のJavaハンドルを取得します。

SelectAIAgent.tool(String toolName, ToolAttributes attributes, String description, ToolStatus status)

このメソッドは、Javaハンドルのみを作成します。他のデータベース・バックアップ・メソッドをコールする前に、Tool.create()をコールしてデータベース・ツールを作成します。データベースは、作成中にToolAttributes構成を検証します。

既存のツールの場合、ライフサイクル、属性、説明またはメソッドの実行をコールする前に、SelectAIAgent.tool(String toolName)を使用してツールを名前でロードします。このメソッドは、データベースからツール・メタデータおよび属性をロードします。

SelectAIAgent.listTools()を使用して、接続されたデータベース・ユーザーが所有するツールをリストするか、SelectAIAgent.listTools(String toolNamePattern)を使用してそのリストを名前パターンでフィルタします。

ツール・パラメータの構成

ToolAttributesでは、ToolParamsインタフェースの実装を使用して、サポートされている組込みツールを構成できます。ツール・タイプに対応するパラメータ・クラスを選択します。

適用可能なパラメータ・クラスによって提供されるビルダーを使用します。アプリケーションがツールを作成または更新するときに、データベースによってパラメータ値が検証されます。

ToolInputは、ツールのtool_inputs配列で宣言された1つの入力を表します。ツール入力メタデータを使用して、ツールに提供されるJSONペイロードの名前、説明、データ型およびその他のサポートされている情報を決定します。データベースは、構成された入力メタデータのセマンティック検証を実行します。

Tool.run(String inputJson)は、ToolRunResultを返します。結果オブジェクトを使用して、ツール実行からデータベース・レスポンスを取得します。フィールドおよびアクセッサ・メソッドについては、Select AI for Java APIリファレンス(Javadoc)を参照してください。

既存のデータベース・ツールを管理するには、次のToolメソッドを使用します。

アプリケーションでデータベース定義の入力メタデータが必要な場合は、Tool.run(String inputJson)の前にTool.describe()をコールします。ツールでサポートされている入力スキーマに一致するJSONを指定します。データベースは入力を検証し、ツール操作を実行します。

ツールを実行する前に、データベース・ユーザーが参照先データベース・オブジェクトおよび外部リソースにアクセスできることを確認します。ツール入力と、それらに含まれるデータに従って結果を保護します。

アプリケーションが作成またはロードされていないツールでデータベース・バック・メソッドをコールした場合、SDKはIllegalStateExceptionを報告します。SDKは、SelectAIExceptionを介してデータベース、JDBC、認可およびツール実行の失敗を報告します。

ツール属性、リクエスト・フォーマット、戻り値および例外については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

タスクの操作

タスクはエージェントの作業を定義し、その作業を完了するために使用できるツールを識別できます。

新しいタスクの場合は、次を使用して構成済のJavaハンドルを取得します。

SelectAIAgent.task(String taskName, TaskAttributes attributes, String description, TaskStatus status)

このメソッドは、Javaハンドルのみを作成します。他のデータベース・バックアップ・メソッドをコールする前に、Task.create()をコールしてデータベース・タスクを作成します。TaskAttributesは、タスクの指示、ツール、入力およびヒューマン・ツールのサポートを定義します。

ノート

ノート:ヒューマン・ツールは、チームが情報をレビューしたり、続行するために必要な入力を提供できるように、チーム・ワークフローを一時停止するデータベース定義のツールです。ヒューマン・ツールおよび一時停止されたワークフローの詳細は、Select AI Agentのドキュメントを参照してください。

既存のタスクの場合は、ライフサイクル・メソッドまたは属性メソッドをコールする前に、SelectAIAgent.task(String taskName)を使用してタスクを名前でロードします。このメソッドは、データベースからタスク・メタデータおよび属性をロードします。SelectAIAgent.listTasks()を使用して、接続ユーザーが所有するタスクをリストするか、SelectAIAgent.listTasks(String taskNamePattern)を使用して名前パターンでタスクをフィルタします。

既存のデータベース・タスクを管理するには、次のTaskメソッドを使用します。

タスクを作成すると、そのタスクがエージェントまたはチームに自動的に関連付けられることはありません。これらの関連付けは、該当するエージェントまたはチーム属性で定義します。

アプリケーションが、作成またはロードされていないタスクに対してデータベース・バック・メソッドをコールした場合、SDKはIllegalStateExceptionを報告します。SDKは、SelectAIExceptionを介してデータベース、JDBC、認可およびタスク操作の失敗を報告します。

タスク属性、ライフサイクル操作およびサポートされているリクエスト・モデルについては、Select AI for Java APIリファレンスを参照してください。

エージェントの操作

エージェントは、データベース定義のAIエージェントを表します。エージェントを作成またはロードし、その属性および関連プロファイルを構成して、ワークフローに必要なタスクに関連付けます。

新しいエージェントを構成するには、次を使用します。

SelectAIAgent.agent(String agentName, AgentAttributes attributes, String description, AgentStatus status)

このメソッドは、Javaハンドルのみを作成します。Agent.create()をコールして、データベース・エージェントを作成します。AgentAttributesは、プロファイル、ロール、ツール、メモリー、ヒューマン・ツール・サポート、スーパーバイザ構成などのエージェント構成を定義します。

スーパーバイザ構成では、エージェントまたはチームがスーパーバイザ・ロールをどのように使用するかを定義します。エージェントの場合は、エージェントのスーパーバイザの動作を構成します。チームの場合、チームのエージェントおよびタスク間で作業を調整する監督者ロールを識別および構成します。

既存のエージェントの場合、ライフサイクル・メソッドまたは属性メソッドをコールする前に、SelectAIAgent.agent(String agentName)を使用してエージェントを名前でロードします。このメソッドは、エージェントのメタデータおよび属性をデータベースからロードします。SelectAIAgent.listAgents()を使用して、接続されたデータベース・ユーザーが所有するエージェントをリストするか、SelectAIAgent.listAgents(String agentNamePattern)を使用して名前パターンでエージェントをフィルタします。

既存のデータベース・エージェントを管理するには、次のAgentメソッドを使用します。

エージェント・リソースは、データベース定義のエージェント構成を表します。チームAPIを使用して、チーム・ワークフローの一部としてエージェントを実行します。エージェントAPIは、個別の直接エージェント実行メソッドを提供しません。

アプリケーションが作成またはロードされていないエージェントでデータベース・バック・メソッドをコールした場合、SDKはIllegalStateExceptionを報告します。SDKは、SelectAIExceptionを介してデータベース、JDBC、認可およびエージェント操作の失敗を報告します。

エージェント構成、ステータス値、ライフサイクル操作、リクエスト・モデルおよび例については、Select AI for Java API Reference (Javadoc)およびスーパーバイザ・エージェントの例を参照してください

エージェント・チームの処理

チームは、ワークフローを実行するためにエージェントとタスクを調整します。チームを作成またはロードし、その属性およびタスク割当てを構成し、プロンプトおよびサポートされているランタイム値を提供するリクエストを使用して実行します。

SelectAIAgent.team(String teamName)を使用して、接続データベース・ユーザーが所有するチームをロードします。SelectAIAgent.listTeams()を使用して所有チームをリストするか、SelectAIAgent.listTeams(String teamNamePattern)を使用してチームを名前パターンでフィルタします。

新しいチームを設定するには、次を使用します。

SelectAIAgent.team(String teamName, TeamAttributes attributes, String description, TeamStatus status)

このメソッドは、Javaハンドルのみを作成します。Team.create()をコールして、データベース・チームを作成します。TeamAttributesは、エージェントとタスクのマッピング、プロセスの実行、メモリーおよびスーパーバイザの構成を定義します。データベースはワークフローを実行し、Java APIを介して結果を返します。データベースがツールを実行し、構成されたAIプロバイダと通信している間に、チームの実行に時間がかかる場合があります。

接続ユーザーが所有するチームを管理および実行するには、次のTeamメソッドを使用します。

チーム実行の構成

RunTeamRequestは、Team.run(RunTeamRequest request)およびSelectAIAgent.runTeam(String teamName, RunTeamRequest request)の入力を提供します。リクエストを使用して、ユーザー・プロンプトおよびオプションで入力されたランタイム・パラメータを指定します。

RunTeamParamsは、データベース・チーム実行操作で受け入れられる型付きランタイム・パラメータを表します。対応するJSONパラメータ・オブジェクトを直接構築するかわりに、そのビルダーを使用して、サポートされているランタイム値を構成します。

チーム実行はTeamRunResultを返します。結果には、データベースが返すレスポンスと、関連する会話の識別に必要な情報が保持されます。後のリクエストで同じワークフローを再開するか、最新の実行状態を取得する必要がある場合は、会話IDを保持します。

会話およびワークフローの状態

Team.getStateByConversationId(String conversationId)を使用して、ロードされたチームに関連付けられた会話の最新の実行状態を取得します。または、SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId)を使用して、最初にTeamハンドルをロードせずにチーム名で状態を取得します。

どちらのメソッドもTeamExecutionStateを返します。この列挙は、データベースでサポートされているチーム実行状態を表し、データベースの状態値を保持します。

チームが人間の入力を一時停止する場合は、Team.setExecutionState(ExecutionStateRequest request)またはSelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request)を使用して、データベースで許可される次の状態を指定します。

ExecutionStateRequestは、新しい状態および更新するチーム会話を識別します。ExecutionStateParamsは、状態更新操作用の型付きパラメータを提供します。ExecutionStateRequest.Builder.params(ExecutionStateParams)を使用して、型付きパラメータ・オブジェクトを指定します。一般的なケースでは、ExecutionStateRequest.Builder.conversationId(String conversationId)を使用して会話IDを直接設定します。

データベース作成の会話IDを保持し、最初のチーム実行、後の状態取得およびワークフローを再開するリクエストに同じIDを使用します。

サポートされている状態名、リクエスト値、戻り値および操作動作および例は、Select AI for Java APIリファレンス(Javadoc)および例: getTeamStateByConversationIdを参照してください。

会話IDを持つワークフローの再開

チーム・ワークフローを開始または再開するには、RunTeamRequestを使用します。データベース作成の会話IDをRunTeamRequest.builder().conversationId(conversationId)で設定します。

コアSelectAI APIを使用して会話を作成します。Conversation.create()メソッドは、データベース生成の会話IDを返します。

Conversation conversation = selectAI.conversation(
        ConversationAttributes.builder()
                .title("Customer support workflow")
                .build());

String conversationId = conversation.create();

同じIDは、後でconversation.getConversationId()を介して使用できます。既存の会話の場合は、SelectAI.conversation(conversationId)で開き、getConversationId()を使用してIDを取得します。

チーム実行にIDを渡します。

RunTeamRequest request = RunTeamRequest.builder()
        .userPrompt("Review the customer request")
        .conversationId(conversationId)
        .build();

TeamRunResult result = selectAIAgent.runTeam(teamName, request);

プールされたJDBC接続を使用するステートレス・アプリケーションまたはアプリケーションの場合、この会話IDを保持し、後の各RunTeamRequestで同じIDを指定します。IDは、個別のアプリケーション・リクエストおよびJDBC接続にわたってチームの実行コンテキストを保持します。conversation_idを再利用して一時停止されたチーム・ワークフローを再開する方法の詳細は、DBMS_CLOUD_AI_AGENTパッケージを参照してください。

後の状態操作(getStateByConversationId(conversationId)など)およびヒューマン入力を待機しているワークフローを再開する場合は、同じIDを使用します。データベース生成IDを新しいクライアント生成値に置き換えないでください。

ワークフローを開始または再開するには、次のいずれかの方法を使用します。

同じ会話を使用するリクエストを調整します。アプリケーションがそれらのリクエストを同期しないかぎり、1つの会話を複数のアプリケーション・スレッドから同時に進めないでください。同時リクエストでは、競合する状態の変更が発生したり、データベースによって後のリクエストが拒否されることがあります。

Team.getStateByConversationId(String conversationId)を使用して、ロードされたチームに関連付けられた会話の最新の実行状態を取得します。

Team.getStateByConversationId(String conversationId)を使用して、ロードされたチームに関連付けられた会話の最新の実行状態を取得します。または、SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId)を使用して、チーム名ごとに最新の状態を取得します。どちらのメソッドもTeamExecutionStateを返します。

どちらのメソッドもTeamExecutionStateを返します。アプリケーションがチームの実行を開始または再開するために使用したものと同じデータベース作成の会話IDを渡します。これらのメソッドは、対話IDを直接受け入れます。アプリケーションは、JSONランタイム・パラメータ・ペイロードを構成する必要はありません。

チーム・ワークフローがヒューマン入力を待機する場合は、Team.setExecutionState(ExecutionStateRequest request)またはSelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request)を使用して次の実行状態を指定します。データベースは、要求された状態遷移および会話コンテキストを検証します。

後のリクエストで必要な会話IDが省略された場合、データベースはORA-20053などのSelectAIExceptionを介して欠落している会話コンテキストをレポートできます。タイムアウトまたは接続の失敗後、別のリクエストを送信する前にチーム状態を取得します。JDBCタイムアウトは、データベース側またはプロバイダ側の処理が停止することを保証するものではありません。

共有チーム

データベース・ユーザーは、所有者がデータベースを介してアクセス権を付与したときに、別のデータベース・ユーザーが所有するチームを実行できます。共有チームの実行時に、所有者修飾チーム名を使用します。

データベースは、チームが使用するリソースに対して、チームの付与および権限を強制します。共有チーム・サポートでは、Javaアプリケーションで所有者のリソースを管理したり、データベース認可をバイパスすることはできません。

共有チームは別のデータベース・ユーザーに属しています。SelectAIAgent.team(String teamName)を介して共有チームをロードしたり、listTeams()を介して共有チームを検索することはできません。

次を使用して共有チームを実行します。

SelectAIAgent.runTeam(String teamName, RunTeamRequest request)

データベース権限に必要な所有者修飾チーム名を指定します。SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId)を使用して最新の実行状態を取得し、SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request)を使用して待機実行状態を更新します。

データベースでは、共有チーム・アクセスが強制されます。付与では実行のみが許可され、接続ユーザーは所有者のチームを更新、エクスポート、無効化または削除できません。

チームのインポートおよびエクスポート

チーム定義をエクスポートして、チーム構成を保持または移動します。チーム定義をインポートして、対応するデータベース・リソースを別の環境に作成します。

Select AI Agent Frameworkでは、エージェント・フレームワーク・リソースの正規定義の取得もサポートされています。インポートする前に、定義および参照リソースをレビューしてください。インポートするデータベース・ユーザーは、リソースを作成し、その依存関係にアクセスするために必要な権限を持っている必要があります。

データベース生成の定義およびチーム・インポートには、次の方法を使用します。

アプリケーションがエクスポートされたチーム定義をJSONとして返す場合、ExportTeamParamsは型付きパラメータを提供します。現在、このクラスはオプションのoverwriteフィールドをサポートしています。データベースのデフォルトを使用するには、nullをTeam.exportDefinition(ExportTeamParams params)に渡します。

ExportTeamRequestは、エクスポートのオブジェクト・ストレージURIまたはデータベース・ディレクトリの宛先を識別します。データベースがサポートする型付きエクスポート・オプションには、ExportTeamParamsを含めることができます。

別の環境にインポートする前に、エクスポートまたは取得した定義を確認します。必要なリソース、権限、プロファイル、資格証明およびデータベース機能がターゲット環境に存在することを確認します。

リクエスト・フォーマット、定義内容、エクスポート先およびインポート動作については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

既存のオブジェクトの取得、更新および削除

接続されたデータベース・ユーザーが所有するエージェント、タスク、ツールおよびチームをロードまたはリストします。アプリケーションで現在のリソース情報が必要な場合に、ステータスおよび属性を取得します。

リソースAPIがサポートする属性のみを更新します。リソースを削除する前に、タスク、エージェントまたはチームがリソースに依存しているかどうかを確認します。データベースでは、取得、更新および削除に必要な権限が強制されます。

SelectAIAgentを使用して、接続されたデータベース・ユーザーが所有するエージェント・フレームワーク・リソースをロードまたはリストします。

名前のみのロード・メソッドは、データベースからリソース・メタデータおよび属性を取得します。listメソッドは、接続されたデータベース・ユーザーが所有するリソースを返します。別のユーザーが所有する共有チームは、listTeams()によって返されず、team(String teamName)でロードできません。共有チームを実行するには、必要な所有者修飾チーム名とともにSelectAIAgent.runTeam(String teamName, RunTeamRequest request)を使用します。

リソース情報の取得

アプリケーションで現在のデータベース情報が必要な場合、リソース・ゲッター・メソッドを使用します。

データベース・バックアップ・リソースの場合、getStatus()および属性getterはデータベースから現在の情報を取得します。名前および説明のgetterは、Javaオブジェクトで使用可能なリソース・メタデータを返します。

リソース属性の更新

setAttribute(...)メソッドを使用してサポートされている1つの属性を更新するか、setAttributes(...)を使用してサポートされている複数の属性を更新します。

setAttribute(...)メソッドは、文書化された文字列、ブール、整数および浮動小数点の属性値をサポートします。データベースは、リソースの作成後に属性を変更できるかどうかを決定します。アプリケーションで既存の構成を保持する必要がある場合に、更新を行う前に現在の属性を取得します。

リソース・ステータスを変更するには、enable()およびdisable()を使用します。

リソースは、アプリケーションがその属性またはステータスを更新する前に作成またはロードする必要があります。それ以外の場合、SDKはIllegalStateExceptionを報告します。無効な引数がIllegalArgumentExceptionになります。データベースの検証、認可およびJDBCが失敗すると、SelectAIExceptionが発生します。

リソースの削除

drop(boolean force)を使用して、データベース・リソースを削除します。

リソースを削除する前に、タスク、エージェント、ツールまたはチームの定義がリソースに依存していないことを確認します。リソースを削除すると、後のチーム・ワークフローが失敗する可能性があります。forceは、アプリケーションがすでに存在しないリソースを意図した最終状態として安全に処理できる場合にのみ使用します。forceは、SDKが欠落しているリソースを処理する方法を制御します。forceがfalseの場合、リソースが存在しない場合、drop操作は失敗します。forceがtrueの場合、SDKはリソース不足エラーを無視し、操作を正常に完了します。このフラグは、認可をバイパスしたり、関連のないデータベース・エラーを非表示にしたり、依存リソースを削除したりしません。

データベースでは、リソースの取得、更新、有効化、無効化および削除に必要な権限が強制されます。リソース固有のライフサイクル・メソッド、サポートされている属性、戻り値および例外については、Select AI for Java APIリファレンスを参照してください。

オブジェクト固有のライフサイクル・メソッドおよび戻り値については、Select AI for Java APIリファレンスを参照してください。

接続、同時実行性、トランザクションおよびタイムアウト

Select AI for Javaは、エージェント操作のためのSDK管理およびアプリケーション管理JDBC接続をサポートしています。リソースの所有権および同時実行性の要件に基づいて接続モードを選択し、同じチームの会話を使用するリクエストを調整し、長時間実行されるツールおよびチーム操作中のトランザクション動作、接続プールの使用状況およびタイムアウトを考慮します。

Autonomous AI Databaseへの接続

接続モード、DbConnectionConfig、DataSourceおよび一般的なJDBC接続管理については、Autonomous AI Databaseへの接続を参照してください。

これらの接続モードには、次のエージェント固有の動作が適用されます。

DbConnectionConfig

DbConnectionConfigを使用すると、SDKはSelectAIAgentクライアントに対して1つのJDBC接続を作成して所有します。クライアントは、その接続をエージェント操作のために再利用し、アプリケーションがクライアントを閉じると閉じます。

この方法で作成されたクライアントは、アプリケーションがアクセスを同期しないかぎり、シングルスレッドとして扱います。SelectAIAgentは、カスタムJDBC作業用に保持されている接続を公開しません。アプリケーションでエージェント操作が必要で、カスタムJDBCが同じ接続管理インフラストラクチャを介して動作する必要がある場合は、アプリケーション管理のDataSourceを使用します。

DataSource

DataSourceモードでは、SDKはパブリック操作ごとに接続を流用し、その操作の完了時にそれを返します。アプリケーションは引き続きDataSourceを所有します。

長時間実行されるチーム実行では、操作が戻るまで借用した接続を保持できます。プールの容量とステートメントのタイムアウトを構成する場合、チームワークフローの予想される期間を考慮してください。

接続のライフサイクルとスレッド化

アプリケーションで必要なくなったら、SelectAIAgentクライアントを閉じます。DbConnectionConfigモードでは、クライアントを閉じると、SDK所有の接続が解放されます。DataSourceモードでは、クライアントをクローズしても、アプリケーション所有のDataSourceはクローズされません。

同時独立操作の場合は、DataSourceモードを使用します。アプリケーションがアクセスを同期しないかぎり、同じAgent、Task、ToolまたはTeamオブジェクトで状態変更操作を同時に変更または実行しないでください。複数のリクエストが同じチームの会話を処理する場合は、それらのリクエストを調整して、会話を同時に進めないようにします。

データベースの認可およびリソース権限は、Java接続またはスレッド・モデルに関係なく、引き続き共有チームに適用されます。

トランザクションおよびタイムアウトの動作

SDKでは、エージェント、タスク、ツールまたはチームの操作を明示的にコミットまたはロールバックすることはなく、JDBC接続のautoCommit設定は変更されません。トランザクションの動作は、接続構成および操作で使用されるデータベースAPIによって異なります。データベースは、SDKで制御されないトランザクション・アクションを実行できます。

タイムアウト後に状態変更操作を自動的に再試行しないでください。データベース側またはプロバイダ側の作業がまだ実行されている可能性があります。

エラーとセキュリティの処理

SDKは、データベースおよび操作の失敗に対するSelectAIExceptionなど、Java例外モデルを介して検証およびデータベースの失敗を報告します。操作によってデータベースの状態が変更されるかどうかに従ってエラーを処理します。

チーム実行は、JDBC接続が返されるまで占有できます。予想されるワークロードの接続プールおよび文のタイムアウトを構成します。タイムアウトは、データベース側またはプロバイダ側の処理が停止していることを保証するものではありません。

Oracleでは、タイムアウト後に状態変更エージェント、タスク、ツールまたはチーム操作を自動的に再試行しないことをお薦めします。再試行しても安全かどうかを判断する前に、データベース・リソースまたはワークフローの状態を確認してください。資格証明、秘密キー、プロンプト、ツール入力、生成された結果、または完全なエージェント属性ペイロードを記録しないでください。

SDK例外の処理

SDKでは、一般的なエラー条件に次の例外が使用されます。

詳細は、Handle Errorsを参照してください。

例外の詳細および操作固有の動作については、Select AI for Java APIリファレンス(Javadoc)を参照してください。

失敗した操作の再試行

SDKは、失敗したエージェント操作を自動的に再試行しません。リソースの作成、更新、削除、管理、ツール実行、チーム実行、実行状態の変更または定義のインポートを自動的に再試行しないでください。アプリケーションがエラーを受信する前に、データベースが処理を開始した可能性があります。

タイムアウトまたは接続の失敗後、再試行するかどうかを決定する前に、リソースまたはチームの実行状態を取得します。JDBCタイムアウトは、データベース側またはプロバイダ側の作業が停止したことを保証するものではありません。操作を繰り返しても問題ないと判断してから再試行してください。

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

エージェント操作が失敗した場合:

1. IllegalArgumentExceptionの場合は、必要な名前、リクエスト・オブジェクトおよび属性値を確認します。
2. IllegalStateExceptionの場合、操作がコールされる前に、アプリケーションがリソースを作成またはロードしたことを確認します。
3. SelectAIExceptionの場合は、メッセージ、Oracleエラー・コード、SQL状態および基礎となる原因(使用可能な場合)を調べます。
4. 接続されたデータベース・ユーザーに、必要なパッケージ権限およびリクエストされたリソースへのアクセス権があることを確認します。
5. 共有チーム操作の場合は、データベースで接続ユーザー・アクセス権が付与され、リクエストで必要な所有者修飾チーム名が使用されていることを確認します。
6. チーム実行の場合は、ワークフローの開始または再開に必要な会話IDがリクエストで指定されていることを確認します。
7. インポートまたはエクスポートの失敗については、定義、ターゲット・データベース・サポートおよび接続ユーザーの権限を確認してください。

メソッド固有の例外宣言および詳細は、Select AI for Java APIリファレンスを参照してください。

機密データの保護

データベースまたはプロバイダの資格証明、秘密キー、アクセス・トークン、完全な資格証明構成、機密プロンプト、会話履歴または生成された結果をログまたは診断レポートに含めないでください。障害のトラブルシューティングに必要な安全なエラーの詳細のみを記録します。

Java SDKはJDBCを介してデータベースと通信します。データベース操作にAIプロバイダまたはオブジェクト・ストアが必要な場合、データベースはその構成に従ってアウトバウンド接続を行います。ワークフローを有効にする前に、データベース側のプロバイダ構成、ネットワーク・アクセスおよびSelect AIデータ・アクセス制御を確認します。

関連資源

• Select AI for Java
• Select AI Agent FrameworkをサポートするPython用のSelect AI
• Select AI for Java APIリファレンス(Javadoc)
• DBMS_CLOUD_AI_AGENTパッケージ・リファレンス
• Java GitHubリポジトリのSelect AI
• Select AI for Javaの例