Soporte para agentes en Select AI for Java

Select AI for Java proporciona API de Java para trabajar con agentes, tareas, herramientas y equipos de IA definidos por base de datos a través de DBMS_CLOUD_AI_AGENT. El soporte de agente forma parte de Select AI for Java; no es un componente o producto independiente. Utilice el marco para gestionar recursos de agente, ejecutar herramientas y equipos, conservar el contexto de ejecución de equipo entre solicitudes y mover definiciones de equipo entre entornos.

La base de datos valida y autoriza los recursos y realiza las operaciones solicitadas. El SDK de Java se comunica con la base de datos a través de JDBC. No proporciona un tiempo de ejecución de agente Java independiente ni realiza llamadas directas a los puntos finales del proveedor de AI.

Para seleccionar perfiles, credenciales, conversaciones, índices vectoriales y otras operaciones de selección de IA, consulte Seleccionar IA para Java.

Entornos soportados

Seleccionar API de marco de agente de AI en Seleccionar AI para Java está soportado en los siguientes entornos:

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

Consulte la matriz de capacidades Select AI de Oracle AI Database para conocer los requisitos de función y versión de base de datos.

Las operaciones de agente necesitan una versión de base de datos que soporte la operación DBMS_CLOUD_AI_AGENT solicitada y las vistas de metadatos asociadas. El SDK de Java no sondea la base de datos para determinar el soporte para cada operación.

Acciones que Puede Realizar

El SDK de Select AI for Java proporciona una API de Java para trabajar con recursos de Select AI Agent Framework.

En la siguiente tabla se resumen las capacidades principales de Select AI for Java compatibles con Select AI Agent Framework:

La base de datos valida y autoriza cada solicitud y devuelve resultados a través de la API de Java. Para ver un ejemplo completo, consulte el ejemplo AgentWorkflowSample.

Modelo de objeto de marco de agente

Select AI for Java representa cada recurso de agente definido por la base de datos a través de una interfaz Java y clases de modelo relacionadas. Utilice SelectAIAgent como punto de entrada para cargar, enumerar, configurar y crear recursos.

El modelo de objeto tiene las siguientes relaciones:

• Una herramienta define una operación que puede utilizar un agente o una tarea.
• Una tarea define el trabajo, las instrucciones, la entrada y las herramientas disponibles para completar ese trabajo.
• Un agente define su rol, el perfil Seleccionar IA, las herramientas, las tareas, la memoria y el comportamiento opcional del supervisor.
• Un equipo asigna agentes a tareas y define cómo cooperan durante la ejecución de un equipo.
• Un ID de conversación asocia ejecuciones de equipos relacionados y operaciones de estado de ejecución entre solicitudes de aplicación y conexiones JDBC.

La creación de un manejador Java no crea el recurso de base de datos correspondiente. Para un nuevo recurso, obtenga un identificador configurado y llame a su método create(). Para un recurso existente, cárguelo por nombre antes de llamar a su ciclo de vida, atributo o métodos operativos.

La API de agente público se proporciona en com.oracle.database.selectai.agent. La solicitud de agente público y las clases de modelo se proporcionan en com.oracle.database.selectai.model.agent.

Para obtener documentación completa sobre clases y métodos, consulte Select AI for Java API Reference (Javadoc).

Inicio rápido: creación y ejecución de un equipo de agentes

Para crear y ejecutar un equipo de agentes:

1. Cree o identifique el perfil Select AI que utilizará el agente.
2. Configure un manejador Tool y llame a Tool.create() si el flujo de trabajo necesita una herramienta definida por la base de datos.
3. Configure un manejador Task y llame a Task.create().
4. Configure un manejador Agent y llame a Agent.create().
5. Configure un manejador Team con las asignaciones de agente a tarea necesarias y llame a Team.create().
6. Cree u obtenga un ID de conversación de base de datos cuando el flujo de trabajo debe conservar el contexto en todas las ejecuciones.
7. Cree un RunTeamRequest con el símbolo del sistema del usuario, el ID de conversación y cualquier RunTeamParams necesario.
8. Llame a Team.run(RunTeamRequest request) y procese el TeamRunResult devuelto.
9. Conservar el ID de conversación si la aplicación debe recuperar el estado más reciente, proporcionar información de usuario o reanudar la ejecución del equipo.

Para ver un ejemplo completo que cree los recursos necesarios, ejecute un equipo y continúe con la misma conversación de base de datos, consulte el ejemplo AgentWorkflowSample.

Requisitos

Antes de utilizar el soporte de Select AI Agent Framework en Select AI for Java, instale y configure el SDK, conéctese a una instancia de Autonomous AI Database soportada y otorgue al usuario de la base de datos los privilegios necesarios para los recursos del agente y sus dependencias. Configure los perfiles, las credenciales, el acceso de proveedor, el acceso de red y los permisos de equipo compartido de Select AI antes de ejecutar un flujo de trabajo.

Instalación de Select AI para Java

Las API de agente se incluyen con Select AI for Java. Para conocer la instalación, los requisitos de Java y la configuración de dependencias, consulte Add Select AI for Java to Your Application.

Para obtener más información sobre la API, consulte Select AI for Java API Reference (Javadoc).

Antes de empezar

Antes de utilizar el marco Select AI Agent:

1. Confirme que la versión de la base de datos soporta las operaciones de agente que necesita la aplicación.
2. Agregue Select AI for Java y un controlador Oracle JDBC Thin compatible a la aplicación. Consulte Adición de Select AI para Java a la aplicación.
3. Configurar la conectividad JDBC y la autenticación de base de datos necesaria para la aplicación. Consulte Conexión a Autonomous AI Database.
4. Otorgue al usuario de la base de datos los privilegios DBMS_CLOUD_AI_AGENT necesarios y el acceso a las vistas de metadatos del agente.
5. Configure los perfiles, credenciales, acceso de proveedor y acceso de red de Select AI necesarios.
6. Confirme que las funciones, procedimientos, tablas, vistas y recursos externos de la base de datos a los que se hace referencia están disponibles para el usuario de la base de datos.
7. Para un equipo compartido, obtenga el permiso gestionado por la base de datos del propietario del equipo.
8. Para un flujo de trabajo que se reanuda entre solicitudes o conexiones agrupadas, obtenga y conserve el ID de conversación creado por la base de datos.

Para conocer los requisitos generales de configuración de Select AI y Select AI Agent Framework, consulte Realización de requisitos previos para Select AI y Requisitos previos para utilizar Select AI Agent Framework.

Gestión de Privilegios de Base de Datos y Acceso de Red

Antes de utilizar un agente, una tarea, una herramienta o un equipo, confirme que el usuario de la base de datos tiene los privilegios necesarios para DBMS_CLOUD_AI_AGENT y el acceso a las vistas de metadatos de agente aplicables.

El usuario de la base de datos también necesita los privilegios necesarios para los recursos a los que hace referencia el flujo de trabajo. Por ejemplo, una herramienta que utiliza una función de base de datos, un procedimiento, una operación SQL o un recurso externo necesita los privilegios y la configuración de la base de datos correspondientes.

Los flujos de trabajo de agentes y equipos pueden utilizar perfiles Select AI, credenciales de proveedor y acceso a la red. Configure esos recursos según el flujo de trabajo y el despliegue. El SDK no crea automáticamente usuarios de base de datos, permisos de paquetes, credenciales, ACL de red ni permisos de equipo compartido.

Para conocer los requisitos de configuración de Select AI, consulte Manage Database Privileges and Network Access. Para obtener detalles sobre el paquete de agente, consulte la referencia de paquete DBMS_CLOUD_AI_AGENT.

Trabajar con herramientas

Las herramientas proporcionan operaciones que un agente o una tarea puede utilizar. Una herramienta puede representar una función de base de datos, un procedimiento, una operación SQL u otra operación definida por la base de datos soportada.

Para una nueva herramienta, obtenga un identificador Java configurado mediante:

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

Este método sólo crea un manejador Java. Llame a Tool.create() para crear la herramienta de base de datos antes de llamar a otros métodos respaldados por base de datos. La base de datos valida la configuración ToolAttributes durante la creación.

Para una herramienta existente, utilice SelectAIAgent.tool(String toolName) para cargar la herramienta por nombre antes de llamar al ciclo de vida, atributo, descripción o métodos de ejecución. Este método carga los metadatos y atributos de la herramienta de la base de datos.

Utilice SelectAIAgent.listTools() para mostrar las herramientas que posee el usuario de la base de datos conectada o SelectAIAgent.listTools(String toolNamePattern) para filtrar esa lista por patrón de nombre.

Configuración de parámetros de herramienta

ToolAttributes puede utilizar implantaciones de la interfaz ToolParams para configurar las herramientas incorporadas soportadas. Seleccione la clase de parámetro que corresponde al tipo de herramienta.

Utilice el creador proporcionado por la clase de parámetro aplicable. La base de datos valida los valores de parámetros cuando la aplicación crea o actualiza la herramienta.

ToolInput representa una entrada declarada en la matriz tool_inputs de una herramienta. Utilice metadatos de entrada de herramienta para determinar los nombres, las descripciones, los tipos de dato y otra información soportada para la carga útil de JSON proporcionada a la herramienta. La base de datos realiza la validación semántica de los metadatos de entrada configurados.

Tool.run(String inputJson) devuelve un valor ToolRunResult. Utilice el objeto de resultado para recuperar la respuesta de la base de datos de la ejecución de la herramienta. Para conocer sus campos y métodos de acceso, consulte Seleccionar AI para Java API Reference (Javadoc).

Utilice estos métodos Tool para gestionar una herramienta de base de datos existente:

Llame a Tool.describe() antes de Tool.run(String inputJson) cuando la aplicación necesite los metadatos de entrada definidos por la base de datos. Proporcione un JSON que coincida con el esquema de entrada soportado de la herramienta. La base de datos valida la entrada y realiza la operación de la herramienta.

Antes de ejecutar una herramienta, confirme que el usuario de la base de datos puede acceder a los objetos de base de datos a los que se hace referencia y a los recursos externos. Proteja las entradas y los resultados de las herramientas según los datos que contengan.

Si la aplicación llama a un método respaldado por base de datos en una herramienta que no ha creado ni cargado, el SDK informa de IllegalStateException. El SDK informa fallos de la base de datos, JDBC, autorización y ejecución de herramientas mediante SelectAIException.

Para conocer los atributos de herramientas, los formatos de solicitud, los valores de devolución y las excepciones, consulte Seleccionar AI para Java API Reference (Javadoc).

Trabajo con tareas

Una tarea define el trabajo de un agente y puede identificar las herramientas disponibles para completar ese trabajo.

Para una nueva tarea, obtenga un manejador Java configurado mediante:

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

Este método sólo crea un manejador Java. Llame a Task.create() para crear la tarea de base de datos antes de llamar a otros métodos respaldados por base de datos. TaskAttributes define las instrucciones de la tarea, las herramientas, la entrada y el soporte de herramientas humanas.

Nota

Nota: una herramienta humana es una herramienta definida por la base de datos que pausa un flujo de trabajo de equipo para que una persona pueda revisar la información o proporcionar la entrada necesaria para continuar. Para obtener más información sobre las herramientas humanas y los flujos de trabajo en pausa, consulte la documentación de selección de agente de IA.

Para una tarea existente, utilice SelectAIAgent.task(String taskName) para cargar la tarea por nombre antes de llamar a métodos de atributo o ciclo de vida. Este método carga los metadatos y atributos de la tarea desde la base de datos. Utilice SelectAIAgent.listTasks() para mostrar las tareas que pertenecen al usuario conectado o utilice SelectAIAgent.listTasks(String taskNamePattern) para filtrar las tareas por patrón de nombre.

Utilice estos métodos Task para gestionar una tarea de base de datos existente:

La creación de una tarea no la asocia automáticamente a un agente o equipo. Defina esas asociaciones en los atributos de agente o equipo aplicables.

Si la aplicación llama a un método respaldado por base de datos en una tarea que no ha creado ni cargado, el SDK informa de IllegalStateException. El SDK informa fallos de la base de datos, JDBC, autorización y operación de tareas mediante SelectAIException.

Para conocer los atributos de tarea, las operaciones de ciclo de vida y los modelos de solicitud soportados, consulte la referencia de selección de IA para API de Java.

Trabajo con agentes

Un agente representa un agente de AI definido por la base de datos. Cree o cargue un agente, configure sus atributos y el perfil asociado y asócielo a las tareas que necesita el flujo de trabajo.

Para configurar un nuevo agente, utilice:

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

Este método sólo crea un manejador Java. Llame a Agent.create() para crear el agente de base de datos. AgentAttributes define la configuración del agente, incluidos el perfil, el rol, las herramientas, la memoria, el soporte de herramientas humanas y la configuración del supervisor.

La configuración del supervisor define cómo un agente o equipo utiliza un rol de supervisor. Para un agente, configura el comportamiento del supervisor del agente. Para un equipo, identifica y configura el rol de supervisor que coordina el trabajo entre los agentes y las tareas del equipo.

Para un agente existente, utilice SelectAIAgent.agent(String agentName) para cargar el agente por nombre antes de llamar a métodos de atributo o ciclo de vida. Este método carga los metadatos y atributos del agente de la base de datos. Utilice SelectAIAgent.listAgents() para mostrar los agentes que son propiedad del usuario de base de datos conectado o utilice SelectAIAgent.listAgents(String agentNamePattern) para filtrar los agentes por patrón de nombre.

Utilice estos métodos Agent para gestionar un agente de base de datos existente:

Un recurso de agente representa una configuración de agente definida por la base de datos. Ejecute un agente como parte de un flujo de trabajo de equipo mediante las API de equipo. La API de agente no proporciona un método de ejecución de agente directo independiente.

Si la aplicación llama a un método respaldado por base de datos en un agente que no ha creado ni cargado, el SDK informa de IllegalStateException. El SDK informa fallos de base de datos, JDBC, autorización y operación de agente mediante SelectAIException.

Para conocer la configuración del agente, los valores de estado, las operaciones de ciclo de vida y los modelos de solicitud, y ejemplos, consulte Select AI for Java API Reference (Javadoc) y un ejemplo para el agente supervisor.

Trabajo con equipos de agente

Un equipo coordina agentes y tareas para realizar un flujo de trabajo. Cree o cargue un equipo, configure sus atributos y asignaciones de tareas, y ejecútelo con una solicitud que proporcione la petición de datos y cualquier valor de tiempo de ejecución soportado.

Utilice SelectAIAgent.team(String teamName) para cargar un equipo propiedad del usuario de la base de datos conectada. Utilice SelectAIAgent.listTeams() para mostrar los equipos en propiedad o SelectAIAgent.listTeams(String teamNamePattern) para filtrar los equipos por patrón de nombre.

Para configurar un nuevo equipo, utilice:

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

Este método sólo crea un manejador Java. Llame a Team.create() para crear el equipo de la base de datos. TeamAttributes define las asignaciones de agente a tarea, el proceso de ejecución, la memoria y la configuración del supervisor. La base de datos ejecuta el flujo de trabajo y devuelve su resultado a través de la API de Java. La ejecución del equipo puede llevar tiempo mientras la base de datos ejecuta herramientas y se comunica con los proveedores de IA configurados.

Utilice estos métodos Team para gestionar y ejecutar un equipo del que es propietario el usuario conectado:

Configuración de una ejecución de equipo

RunTeamRequest proporciona la entrada para Team.run(RunTeamRequest request) y SelectAIAgent.runTeam(String teamName, RunTeamRequest request). Utilice la solicitud para proporcionar la petición de datos de usuario y los parámetros de tiempo de ejecución introducidos opcionales.

RunTeamParams representa los parámetros de tiempo de ejecución introducidos que acepta la operación de ejecución en equipo de la base de datos. Utilice su creador para configurar valores de tiempo de ejecución soportados en lugar de crear directamente el objeto de parámetro JSON correspondiente.

Una ejecución de equipo devuelve un TeamRunResult. El resultado conserva la respuesta que devuelve la base de datos y la información necesaria para identificar la conversación asociada. Conservar el ID de conversación cuando una solicitud posterior deba reanudar el mismo flujo de trabajo o recuperar su último estado de ejecución.

Conversaciones y estado de flujo de trabajo

Utilice Team.getStateByConversationId(String conversationId) para recuperar el último estado de ejecución de una conversación asociada a un equipo cargado. También puede utilizar SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId) para recuperar el estado por nombre de equipo sin cargar primero un manejador Team.

Ambos métodos devuelven un valor TeamExecutionState. Esta enumeración representa los estados de ejecución del equipo soportados por la base de datos y conserva el valor de estado de la base de datos.

Cuando un equipo se detiene para la entrada humana, utilice Team.setExecutionState(ExecutionStateRequest request) o SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request) para proporcionar el siguiente estado permitido por la base de datos.

ExecutionStateRequest identifica el nuevo estado y la conversación del equipo que se va a actualizar. ExecutionStateParams proporciona los parámetros introducidos para la operación de actualización de estado. Utilice ExecutionStateRequest.Builder.params(ExecutionStateParams) para proporcionar el objeto de parámetro escrito. Para el caso común, utilice ExecutionStateRequest.Builder.conversationId(String conversationId) para definir el ID de conversación directamente.

Conservar el ID de conversación creado por la base de datos y utilizar el mismo ID para la ejecución inicial del equipo, la recuperación posterior del estado y cualquier solicitud que reanude el flujo de trabajo.

Para ver los nombres de estado, los valores de solicitud, los valores de retorno y el comportamiento de la operación soportados, y un ejemplo, consulte Select AI for Java API Reference (Javadoc) y el ejemplo getTeamStateByConversationId

Reanudar flujos de trabajo con Id. de conversación

Utilice RunTeamRequest para iniciar o reanudar un flujo de trabajo de equipo. Defina el ID de conversación creado por la base de datos con RunTeamRequest.builder().conversationId(conversationId).

Cree una conversación a través de la API SelectAI principal. El método Conversation.create() devuelve el identificador de conversación generado por la base de datos:

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

String conversationId = conversation.create();

El mismo ID está disponible más adelante mediante conversation.getConversationId(). Para una conversación existente, ábrala con SelectAI.conversation(conversationId) y recupere el ID con getConversationId().

Transfiera el ID a la ejecución del equipo:

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

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

Para una aplicación sin estado o una aplicación que utiliza conexiones JDBC de pool, conserve este ID de conversación y proporcione el mismo ID en cada RunTeamRequest posterior. El ID conserva el contexto de ejecución del equipo en solicitudes de aplicación independientes y conexiones JDBC. Para obtener información sobre la reutilización de conversation_id para reanudar un flujo de trabajo de equipo en pausa, consulte el paquete DBMS_CLOUD_AI_AGENT.

Utilice el mismo ID para operaciones de estado posteriores, como getStateByConversationId(conversationId), y al reanudar un flujo de trabajo esperando la entrada humana. No sustituya el ID generado por la base de datos por un nuevo valor generado por el cliente.

Utilice uno de estos métodos para iniciar o reanudar un flujo de trabajo:

Coordinar las solicitudes que utilizan la misma conversación. No avance una conversación simultáneamente desde varios threads de aplicación a menos que la aplicación sincronice esas solicitudes. Las solicitudes simultáneas pueden producir cambios de estado en conflicto o hacer que la base de datos rechace la solicitud posterior.

Utilice Team.getStateByConversationId(String conversationId) para recuperar el último estado de ejecución de una conversación asociada a un equipo cargado.

Utilice Team.getStateByConversationId(String conversationId) para recuperar el último estado de ejecución de una conversación asociada a un equipo cargado. También puede utilizar SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId) para recuperar el último estado por nombre de equipo. Ambos métodos devuelven un valor TeamExecutionState.

Ambos métodos devuelven un valor TeamExecutionState. Transfiera la misma ID. de conversación creada por la base de datos que la aplicación utilizó para iniciar o reanudar la ejecución del equipo. Estos métodos aceptan el ID de conversación directamente; la aplicación no necesita crear una carga útil de parámetros de tiempo de ejecución JSON.

Cuando un flujo de trabajo de equipo espera la entrada humana, utilice Team.setExecutionState(ExecutionStateRequest request) o SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request) para proporcionar el siguiente estado de ejecución. La base de datos valida la transición de estado solicitada y el contexto de conversación.

Si una solicitud posterior omite el ID de conversación necesario, la base de datos puede informar del contexto de conversación que falta a través de SelectAIException, como ORA-20053. Después de un timeout o un fallo de conexión, recupere el estado del equipo antes de enviar otra solicitud. Un timeout de JDBC no garantiza que el procesamiento de la base de datos o del proveedor se haya parado.

Equipos compartidos

Un usuario de base de datos puede ejecutar un equipo propiedad de otro usuario de base de datos cuando el propietario otorga acceso a través de la base de datos. Utilice el nombre del equipo cualificado para el propietario al ejecutar el equipo compartido.

La base de datos aplica el permiso de equipo y los privilegios en los recursos que utiliza el equipo. El soporte de equipo compartido no permite que la aplicación Java gestione los recursos del propietario ni omita la autorización de la base de datos.

Un equipo compartido pertenece a otro usuario de base de datos. No puede cargar un equipo compartido a través de SelectAIAgent.team(String teamName) ni encontrarlo a través de listTeams().

Ejecute un equipo compartido con:

SelectAIAgent.runTeam(String teamName, RunTeamRequest request)

Proporcione el nombre de equipo cualificado para el propietario que necesita el permiso de base de datos. Utilice SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId) para recuperar el último estado de ejecución y SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request) para actualizar un estado de ejecución en espera.

La base de datos aplica el acceso de equipo compartido. El permiso solo permite la ejecución; no permite que el usuario conectado actualice, exporte, desactive o borre el equipo del propietario.

Importación y exportación de un equipo

Exportar una definición de equipo para conservar o mover la configuración de un equipo. Importe una definición de equipo para crear los recursos de base de datos correspondientes en otro entorno.

Select AI Agent Framework también admite la recuperación de definiciones canónicas para recursos del marco del agente. Revise la definición y los recursos a los que se hace referencia antes de importarla. El usuario de la base de datos de importación debe tener los privilegios necesarios para crear los recursos y acceder a sus dependencias.

Utilice estos métodos para las definiciones generadas por la base de datos y la importación de equipos:

ExportTeamParams proporciona parámetros introducidos cuando la aplicación devuelve una definición de equipo exportada como JSON. La clase soporta actualmente el campo opcional overwrite. Transfiera null a Team.exportDefinition(ExportTeamParams params) para utilizar los valores por defecto de la base de datos.

ExportTeamRequest identifica un URI de almacenamiento de objetos o un destino de directorio de base de datos para una exportación. Puede incluir ExportTeamParams para las opciones de exportación introducidas que soporta la base de datos.

Revise las definiciones exportadas o recuperadas antes de importarlas a otro entorno. Confirme que los recursos, privilegios, perfiles, credenciales y capacidades de base de datos necesarios existen en el entorno de destino.

Para conocer los formatos de solicitud, el contenido de la definición, los destinos de exportación y el comportamiento de importación, consulte Seleccionar AI para Java API Reference (Javadoc).

Recuperar, actualizar y suprimir objetos existentes

Cargue o muestre agentes, tareas, herramientas y equipos propiedad del usuario de la base de datos conectada. Recupere el estado y los atributos cuando la aplicación necesite información de recursos actual.

Actualice solo los atributos que soporta la API de recursos. Antes de borrar un recurso, compruebe si una tarea, un agente o un equipo dependen de él. La base de datos aplica los privilegios necesarios para la recuperación, las actualizaciones y la eliminación.

Utilice SelectAIAgent para cargar o mostrar los recursos del marco del agente propiedad del usuario de la base de datos conectada.

Los métodos de carga de solo nombre recuperan los metadatos y atributos del recurso de la base de datos. Los métodos de lista devuelven recursos que son propiedad del usuario de la base de datos conectada. listTeams() no devuelve un equipo compartido propiedad de otro usuario y no se puede cargar con team(String teamName). Utilice SelectAIAgent.runTeam(String teamName, RunTeamRequest request) con el nombre de equipo cualificado para el propietario necesario para ejecutar un equipo compartido.

Recuperar información de recurso

Utilice los métodos getter de recursos cuando la aplicación necesite información de la base de datos actual.

Para los recursos respaldados por la base de datos, getStatus() y el getter de atributo recuperan la información actual de la base de datos. Los getters de nombre y descripción devuelven los metadatos del recurso disponibles para el objeto Java.

Actualizar atributos de recurso

Utilice los métodos setAttribute(...) para actualizar un atributo soportado o utilice setAttributes(...) para actualizar varios atributos soportados.

Los métodos setAttribute(...) soportan los valores de atributo de cadena, booleano, entero y coma flotante documentados. La base de datos determina si un atributo puede cambiar después de la creación del recurso. Recupere los atributos actuales antes de realizar una actualización cuando la aplicación necesite conservar la configuración existente.

Utilice enable() y disable() para cambiar el estado del recurso:

Se debe crear o cargar un recurso antes de que la aplicación actualice sus atributos o estado. De lo contrario, el SDK informa de IllegalStateException. Los argumentos no válidos dan como resultado IllegalArgumentException. Los fallos de validación, autorización y JDBC de la base de datos dan como resultado SelectAIException.

Suprimir Recursos

Utilice drop(boolean force) para eliminar un recurso de base de datos.

Antes de borrar un recurso, confirme que no depende de él ninguna definición de tarea, agente, herramienta o equipo. La eliminación de un recurso puede hacer que falle un flujo de trabajo de equipo posterior. Utilice force solo cuando la aplicación pueda tratar de forma segura un recurso que ya está ausente como el estado final previsto. force controla cómo maneja el SDK un recurso que falta. Cuando force es false, la operación drop falla si el recurso no existe. Cuando force es true, el SDK ignora el error de recurso que falta y completa la operación correctamente. El indicador no omite la autorización, oculta errores de base de datos no relacionados ni suprime recursos dependientes.

La base de datos aplica los privilegios necesarios para recuperar, actualizar, activar, desactivar y eliminar recursos. Para ver los métodos de ciclo de vida específicos del recurso, los atributos soportados, los valores de devolución y las excepciones, consulte la Referencia de selección de IA para API de Java.

Para ver los métodos de ciclo de vida específicos del objeto y los valores de retorno, consulte la Referencia de selección de AI para API de Java.

Conexiones, Simultaneidad, Transacciones y Timeouts

Seleccione AI para Java soporta conexiones JDBC gestionadas por SDK y por aplicaciones para operaciones de agente. Seleccione un modo de conexión basado en los requisitos de simultaneidad y propiedad de recursos, coordine las solicitudes que utilizan la misma conversación de equipo y tenga en cuenta el comportamiento de la transacción, el uso del pool de conexiones y los timeouts durante las operaciones de equipo y la herramienta de larga ejecución.

Conexión a Autonomous AI Database

Para conocer los modos de conexión, DbConnectionConfig, DataSource y la gestión general de conexiones JDBC, consulte Conexión a Autonomous AI Database.

El siguiente comportamiento específico del agente se aplica a esos modos de conexión.

DbConnectionConfig

Con DbConnectionConfig, el SDK crea y posee una conexión JDBC para el cliente SelectAIAgent. El cliente reutiliza esa conexión para operaciones de agente y la cierra cuando la aplicación cierra el cliente.

Tratar a un cliente creado de esta forma como de thread único a menos que la aplicación sincronice el acceso. SelectAIAgent no expone su conexión retenida para el trabajo de JDBC personalizado. Utilice una DataSource gestionada por la aplicación cuando la aplicación necesite operaciones de agente y JDBC personalizadas que funcionen a través de la misma infraestructura de gestión de conexiones.

DataSource

En el modo DataSource, el SDK toma prestada una conexión para cada operación pública y la devuelve cuando finaliza esa operación. La aplicación sigue siendo propietaria de DataSource.

Una ejecución de equipo de larga duración puede retener una conexión prestada hasta que se devuelva la operación. Tenga en cuenta la duración esperada de los flujos de trabajo de equipo al configurar la capacidad del pool y los timeouts de sentencia.

Ciclo de vida de conexión y thread

Cierre el cliente SelectAIAgent cuando la aplicación ya no lo necesite. En el modo DbConnectionConfig, al cerrar el cliente, se libera la conexión propiedad del SDK. En el modo DataSource, al cerrar el cliente no se cierra el DataSource propiedad de la aplicación.

Para operaciones independientes simultáneas, utilice el modo DataSource. No cambie ni ejecute simultáneamente operaciones de cambio de estado en el mismo objeto Agent, Task, Tool o Team a menos que la aplicación sincronice el acceso. Cuando varias solicitudes funcionan con la misma conversación de equipo, coordine esas solicitudes para que no avancen la conversación simultáneamente.

La autorización de base de datos y los privilegios de recursos siguen aplicándose a los equipos compartidos, independientemente de la conexión Java o el modelo de thread.

Comportamiento de transacción y timeout

El SDK no confirma ni realiza un rollback explícito de las operaciones de agente, tarea, herramienta o equipo y no cambia el valor autoCommit de la conexión JDBC. El comportamiento de la transacción depende de la configuración de conexión y de las API de base de datos que utilice la operación. La base de datos puede realizar acciones de transacción que el SDK no controla.

No vuelva a intentar automáticamente una operación de cambio de estado después de un timeout. Es posible que el trabajo del lado de la base de datos o del lado del proveedor aún se esté ejecutando.

Manejo de errores y seguridad

El SDK informa de fallos de validación y base de datos a través de su modelo de excepción de Java, incluido SelectAIException para fallos de base de datos y operación. Manejar los errores según si la operación cambia el estado de la base de datos.

Una ejecución de equipo puede ocupar una conexión JDBC hasta que se devuelva. Configure los pools de conexiones y los timeouts de sentencias para la carga de trabajo esperada. Un timeout no garantiza que el procesamiento de la base de datos o del proveedor se haya detenido.

Oracle recomienda que no vuelva a intentar automáticamente las operaciones de agente, tarea, herramienta o equipo que cambian de estado después de un timeout. Compruebe el estado del flujo de trabajo o el recurso de la base de datos antes de decidir si es seguro volver a intentarlo. No registre credenciales, claves privadas, peticiones de datos, entradas de herramientas, resultados generados ni cargas útiles de atributos de agente completas.

Manejar excepciones de SDK

El SDK utiliza las siguientes excepciones para condiciones de error comunes:

Consulte Gestión de errores para obtener más información.

Para obtener detalles sobre las excepciones y el comportamiento específico de la operación, consulte Select AI for Java API Reference (Javadoc).

Reintentar operaciones fallidas

El SDK no reintenta automáticamente las operaciones fallidas del agente. No vuelva a intentar automáticamente la creación, las actualizaciones, la supresión, la administración, las ejecuciones de herramientas, las ejecuciones de equipos, los cambios de estado de ejecución ni las importaciones de definiciones de recursos. Es posible que la base de datos haya iniciado el procesamiento antes de que la aplicación recibiera un error.

Después de un timeout o un fallo de conexión, recupere el estado de ejecución del recurso o del equipo antes de decidir si desea volver a intentarlo. Un timeout de JDBC no garantiza que el trabajo de la base de datos o del proveedor se haya parado. Vuelva a intentarlo solo después de determinar que la repetición de la operación es segura.

Solución de errores del agente

Cuando falla una operación de agente:

1. Para IllegalArgumentException, compruebe los nombres necesarios, los objetos de solicitud y los valores de atributo.
2. Para IllegalStateException, confirme que la aplicación ha creado o cargado el recurso antes de llamar a la operación.
3. Para SelectAIException, inspeccione el mensaje, el código de error de Oracle, el estado SQL y la causa subyacente cuando estén disponibles.
4. Confirme que el usuario de la base de datos conectada tiene los privilegios de paquete necesarios y acceso al recurso solicitado.
5. Para operaciones de equipo compartido, confirme que la base de datos ha otorgado acceso de usuario conectado y que la solicitud utiliza el nombre de equipo cualificado para el propietario necesario.
6. Para la ejecución de equipo, confirme que la solicitud proporciona el ID de conversación necesario para iniciar o reanudar el flujo de trabajo.
7. Para los fallos de importación o exportación, compruebe la definición, el soporte de la base de datos de destino y los privilegios del usuario conectado.

Consulte la sección sobre selección de AI para la referencia de API de Java para obtener más información y declaraciones de excepciones específicas del método.

Proteger Datos Confidenciales

No incluya credenciales de base de datos o de proveedor, claves privadas, tokens de acceso, configuraciones de credenciales completas, peticiones de datos confidenciales, historial de conversaciones ni resultados generados en logs o informes de diagnóstico. Registre solo los detalles de error seguro necesarios para solucionar el fallo.

El SDK de Java se comunica con la base de datos a través de JDBC. Cuando una operación de base de datos necesita un proveedor de AI o un almacén de objetos, la base de datos realiza la conexión saliente según su configuración. Revise la configuración del proveedor del lado de la base de datos, el acceso de red y los controles de acceso a datos Select AI antes de activar el flujo de trabajo.

Recursos relacionados

• Select AI for Java
• Seleccionar AI para Python compatible con Select AI Agent Framework
• Seleccionar AI para referencia de API de Java (Javadoc)
• Referencia de paquete DBMS_CLOUD_AI_AGENT
• Seleccione AI para el repositorio GitHub de Java
• Seleccionar AI para ejemplos de Java