Package com.oracle.database.selectai.agent

Interface SelectAIAgent

All Superinterfaces:
AutoCloseable
public interface SelectAIAgent extends AutoCloseable
Client interface for Oracle Select AI Agent operations.

This interface provides access to the agent framework resources managed by DBMS_CLOUD_AI_AGENT: agents, tasks, tools, and teams. It also provides collection-level operations for listing agents, tasks, tools, and teams, executing teams, inspecting and updating team state, accessing runtime variables, retrieving object definitions, and importing team definitions.

Use SelectAIAgent separately from SelectAI so agent orchestration and application-facing Select AI profile operations remain explicit. Agent resources may use Select AI profiles, but creating or managing an agent resource does not create or modify a profile.

SelectAIAgent extends AutoCloseable. Creating a client with create(DbConnectionConfig) opens one SDK-owned JDBC connection immediately. Call close() when the client is no longer needed to release that connection and its database session.

Creating a client with create(DataSource) does not obtain a connection immediately. The application owns the DataSource; the SDK borrows a connection for each database operation and closes that connection after use, returning pooled connections to their pool. Calling close() does not close the caller-owned DataSource. Each operation may therefore use a different pooled connection; applications should not depend on uncommitted transaction or other session state being available to a later operation.

The name-only agent(String), task(String), tool(String), and team(String) factories verify that the current user owns the resources and load their metadata and attributes before returning. Granted cross-schema teams can be run through runTeam(String, RunTeamRequest) without loading owner-only metadata. The owner-scoped list methods also load metadata and attributes for each returned handle. listAvailableTeams() provides a separate read-only discovery view backed by DBMS_CLOUD_AI_AGENT.LIST_TEAMS; its results may include shared teams that cannot be opened with team(String). The overloads that accept attributes retain their configuration without a database query; a resource is not persisted until its create() method succeeds. For agents, required attribute values such as profile name and role are validated by the database during Agent.create(), not by the AgentAttributes builder.

For a complete runnable example, see CreateAgentSample source. For an end-to-end example that creates a tool, task, agent, and team, runs the team, and continues the same conversation, see AgentWorkflowSample source.

Since:
1.1.0
See Also:

  • Method Details

    • create

      static SelectAIAgent create(DbConnectionConfig dbConnectionConfig) throws SelectAIException
      Creates a SelectAIAgent client from database connection configuration.

      For a runnable example, see RunTeamSample source.

      Parameters:
      dbConnectionConfig - database connection configuration
      Returns:
      SelectAIAgent client
      Throws:
      IllegalArgumentException - when dbConnectionConfig is null
      SelectAIException - when the database connection cannot be initialized

    • create

      static SelectAIAgent create(DbConnectionConfig dbConnectionConfig, SelectAIOptions options) throws SelectAIException
      Creates a SelectAIAgent client from database connection configuration and SDK execution options.

      For a runnable example, see CreateSelectAIAgentWithOptionsSample source.

      Parameters:
      dbConnectionConfig - database connection configuration
      options - SDK execution options; null uses defaults
      Returns:
      SelectAIAgent client
      Throws:
      IllegalArgumentException - when dbConnectionConfig is null
      SelectAIException - when the database connection cannot be initialized

    • create

      static SelectAIAgent create(DataSource dataSource)
      Creates a DataSource-backed SelectAIAgent client.

      For a runnable example, see CreateSelectAIAgentDataSourceSample source.

      Parameters:
      dataSource - DataSource used to obtain JDBC connections
      Returns:
      SelectAIAgent client
      Throws:
      IllegalArgumentException - when dataSource is null

    • create

      static SelectAIAgent create(DataSource dataSource, SelectAIOptions options)
      Creates a DataSource-backed SelectAIAgent client with SDK execution options.

      For a runnable example, see CreateSelectAIAgentDataSourceWithOptionsSample source.

      Parameters:
      dataSource - DataSource used to obtain JDBC connections
      options - SDK execution options; null uses defaults
      Returns:
      SelectAIAgent client
      Throws:
      IllegalArgumentException - when dataSource is null

    • agent

      Agent agent(String agentName) throws SelectAIException
      Loads an existing agent, including its metadata and attributes.

      For a runnable example, see LoadAgentSample source.

      Parameters:
      agentName - agent name
      Returns:
      database-backed agent object
      Throws:
      IllegalArgumentException - when agentName is null or blank
      SelectAIException - when the agent does not exist or its metadata or attributes cannot be loaded

    • agent

      Agent agent(String agentName, AgentAttributes attributes, String description, AgentStatus status)
      Initializes an agent object for explicit creation.

      For a runnable example, see CreateAgentSample source.

      Parameters:
      agentName - agent name
      attributes - agent creation attributes
      description - optional agent description
      status - optional initial status; null uses the database default
      Returns:
      agent object configured for creation
      Throws:
      IllegalArgumentException - when agentName is null or blank, or attributes is null

    • task

      Task task(String taskName) throws SelectAIException
      Loads an existing task, including its metadata and attributes.

      For a runnable example, see LoadTaskSample source.

      Parameters:
      taskName - task name
      Returns:
      database-backed task object
      Throws:
      IllegalArgumentException - when taskName is null or blank
      SelectAIException - when the task does not exist or its metadata or attributes cannot be loaded

    • task

      Task task(String taskName, TaskAttributes attributes, String description, TaskStatus status)
      Initializes a task object for explicit creation.

      For a runnable example, see CreateTaskSample source.

      Parameters:
      taskName - task name
      attributes - task creation attributes
      description - optional task description
      status - optional initial status; null uses the database default
      Returns:
      task object configured for creation
      Throws:
      IllegalArgumentException - when taskName is null or blank, or attributes is null

    • tool

      Tool tool(String toolName) throws SelectAIException
      Loads an existing tool, including its metadata and attributes.

      For a runnable example, see LoadToolSample source.

      Parameters:
      toolName - tool name
      Returns:
      database-backed tool object
      Throws:
      IllegalArgumentException - when toolName is null or blank
      SelectAIException - when the tool does not exist or its metadata or attributes cannot be loaded

    • tool

      Tool tool(String toolName, ToolAttributes attributes, String description, ToolStatus status)
      Initializes a tool object for explicit creation.

      For runnable examples, see CreateToolSample source, CreateSqlToolSample source, and ToolParamsSample source.

      Parameters:
      toolName - tool name
      attributes - tool creation attributes
      description - optional tool description
      status - optional initial status; null uses the database default
      Returns:
      tool object configured for creation
      Throws:
      IllegalArgumentException - when toolName is null or blank, or attributes is null

    • team

      Team team(String teamName) throws SelectAIException
      Loads a team owned by the current database user, including its metadata and attributes. To run a granted team owned by another user, use runTeam(String, RunTeamRequest) with an owner-qualified name.

      For a runnable example, see LoadTeamSample source.

      Parameters:
      teamName - team name
      Returns:
      database-backed team object
      Throws:
      IllegalArgumentException - when teamName is null or blank
      SelectAIException - when the team does not exist or its metadata or attributes cannot be loaded

    • team

      Team team(String teamName, TeamAttributes attributes, String description, TeamStatus status)
      Initializes a team object for explicit creation.

      For a runnable example, see CreateTeamSample source.

      Parameters:
      teamName - team name
      attributes - team creation attributes
      description - optional team description
      status - optional initial status; null uses the database default
      Returns:
      team object configured for creation
      Throws:
      IllegalArgumentException - when teamName is null or blank, or attributes is null

    • runTeam

      TeamRunResult runTeam(String teamName, RunTeamRequest request) throws SelectAIException
      Runs an existing team by name without loading owner-only team metadata. A consumer can run a team granted by another database user with a name such as TEAM_OWNER.SHARED_SUPPORT_TEAM. The database checks team existence and the caller's access; this method does not grant access to manage the team's definition. Without established session context, the request must contain a database-created conversation identifier. The operation is synchronous. In DataSource mode, the borrowed JDBC connection can remain occupied for the duration of the workflow. The SDK does not provide a cancellation API, and a JDBC timeout or interrupted call may not stop server-side or provider work. Retry only when the workflow is known to be safe to repeat.

      For a runnable example, see RunSharedTeamSample source.

      For a human-input workflow resumed in a new process through a pooled DataSource, see PooledTeamResumeSample source.

      Parameters:
      teamName - team name, optionally owner-qualified
      request - prompt and optional runtime parameters
      Returns:
      typed team-run result retaining the database response
      Throws:
      IllegalArgumentException - when teamName is null or blank, or request is null
      SelectAIException - when the database rejects or cannot complete the run

    • getTeamStateByConversationId

      TeamExecutionState getTeamStateByConversationId(String teamName, String conversationId) throws SelectAIException
      Returns the latest state for a team run identified by a database conversation identifier.

      This operation does not load a Team handle and supports an owner-qualified team name for a shared team.

      For a runnable example, see GetTeamStateSample source. For a runnable example that verifies WAITING_FOR_HUMAN before resuming through a pooled DataSource, see PooledTeamResumeSample source.

      Parameters:
      teamName - team name, optionally owner-qualified
      conversationId - existing database conversation identifier
      Returns:
      typed team execution state retaining the original database value
      Throws:
      IllegalArgumentException - when either argument is null or blank
      SelectAIException - when the database operation fails
      Since:
      1.1.0

    • setTeamExecutionState

      boolean setTeamExecutionState(String teamName, ExecutionStateRequest request) throws SelectAIException
      Updates the execution state of a team run.

      This operation does not load a Team handle and therefore also supports an owner-qualified team name for a team granted to the current database user. Set the request's conversation identifier to address a run across pooled database connections.

      For a runnable example, see SetTeamExecutionStateSample source.

      Parameters:
      teamName - team name, optionally owner-qualified
      request - execution state and a typed conversation identifier
      Returns:
      true when the database operation succeeds
      Throws:
      IllegalArgumentException - when teamName is null or blank, or request is null or does not identify a conversation
      SelectAIException - when the database operation fails

    • grantTeamAccess

      boolean grantTeamAccess(String teamName, String userOrRoleName) throws SelectAIException
      Grants a database user or role permission to run an owner-managed team. The connected database user must own the team, and teamName must be the owner's unqualified team name. This method does not load a Team handle and is useful when the owner wants a client-level sharing operation.

      For a runnable example, see GrantTeamAccessSample source.

      Parameters:
      teamName - owner's unqualified team name
      userOrRoleName - database user or role receiving execution access
      Returns:
      true when the database accepts the grant
      Throws:
      IllegalArgumentException - when either name is null, blank, invalid, or the grantee is PUBLIC
      SelectAIException - when the database rejects or cannot complete the grant
      Since:
      1.1.0

    • revokeTeamAccess

      boolean revokeTeamAccess(String teamName, String userOrRoleName) throws SelectAIException
      Revokes a database user or role permission to run an owner-managed team. The connected database user must own the team, and teamName must be the owner's unqualified team name.

      For a runnable example, see RevokeTeamAccessSample source.

      Parameters:
      teamName - owner's unqualified team name
      userOrRoleName - database user or role losing execution access
      Returns:
      true when the database accepts the revoke
      Throws:
      IllegalArgumentException - when either name is null, blank, invalid, or the grantee is PUBLIC
      SelectAIException - when the database rejects or cannot complete the revoke
      Since:
      1.1.0

    • getVariable

      default String getVariable(String namespace, String name) throws SelectAIException
      Reads an ephemeral runtime variable from the current database session.

      Runtime variables are session-scoped. In DataSource mode, separate calls may use different pooled connections, so applications that require the value to remain available across calls should use a connection mode that retains one database session or manage the session explicitly.

      For a runnable example, see GetVariableSample source.

      Parameters:
      namespace - runtime-variable namespace, such as state_variables
      name - runtime-variable key
      Returns:
      the variable value, or null when the key is not set
      Throws:
      IllegalArgumentException - when namespace or name is null or blank
      SelectAIException - when the database operation fails
      Since:
      1.1.0

    • getVariable

      String getVariable(String namespace, String name, String scope) throws SelectAIException
      Reads a runtime variable from the current database session and scope.

      For a runnable example, see GetVariableSample source.

      Parameters:
      namespace - runtime-variable namespace, such as state_variables
      name - runtime-variable key
      scope - runtime-variable scope; the database currently supports ephemeral
      Returns:
      the variable value, or null when the key is not set
      Throws:
      IllegalArgumentException - when an argument is null or blank
      SelectAIException - when the database operation fails
      Since:
      1.1.0

    • setVariable

      default boolean setVariable(String namespace, String name, String value) throws SelectAIException
      Sets or clears an ephemeral runtime variable in the current database session. A null value clears the variable.

      For a runnable example, see SetVariableSample source.

      Parameters:
      namespace - runtime-variable namespace, such as state_variables
      name - runtime-variable key
      value - value to store, or null to clear the key
      Returns:
      true when the database accepts the operation
      Throws:
      IllegalArgumentException - when namespace or name is null or blank
      SelectAIException - when the database operation fails
      Since:
      1.1.0

    • setVariable

      boolean setVariable(String namespace, String name, String value, String scope) throws SelectAIException
      Sets or clears a runtime variable in the current database session and scope. A null value clears the variable.

      For a runnable example, see SetVariableSample source.

      Parameters:
      namespace - runtime-variable namespace, such as state_variables
      name - runtime-variable key
      value - value to store, or null to clear the key
      scope - runtime-variable scope; the database currently supports ephemeral
      Returns:
      true when the database accepts the operation
      Throws:
      IllegalArgumentException - when an argument is null or blank, except value
      SelectAIException - when the database operation fails
      Since:
      1.1.0

    • listAgents

      List<Agent> listAgents() throws SelectAIException
      Lists agents owned by the current database user.

      For a runnable example, see ListAgentsSample source.

      Returns:
      agent handles initialized from USER_AI_AGENTS metadata and their current database attributes
      Throws:
      SelectAIException - when agent metadata or attributes cannot be loaded

    • listAgents

      List<Agent> listAgents(String agentNamePattern) throws SelectAIException
      Lists owned agents whose names match a database regular-expression pattern. Matching is case-insensitive. Each returned handle includes metadata and attributes loaded from the database.

      For a runnable example, see ListAgentsSample source.

      Parameters:
      agentNamePattern - regular-expression pattern matched against agent names
      Returns:
      matching agent handles
      Throws:
      IllegalArgumentException - when agentNamePattern is null or blank
      SelectAIException - when listing agents fails

    • listTasks

      List<Task> listTasks() throws SelectAIException
      Lists tasks owned by the current database user.

      For a runnable example, see ListTasksSample source.

      Returns:
      task handles initialized from USER_AI_AGENT_TASKS metadata and their current database attributes
      Throws:
      SelectAIException - when task metadata or attributes cannot be loaded

    • listTasks

      List<Task> listTasks(String taskNamePattern) throws SelectAIException
      Lists owned tasks whose names match a database regular-expression pattern. Matching is case-insensitive. Each returned handle includes metadata and attributes loaded from the database.

      For a runnable example, see ListTasksSample source.

      Parameters:
      taskNamePattern - regular-expression pattern matched against task names
      Returns:
      matching task handles
      Throws:
      IllegalArgumentException - when taskNamePattern is null or blank
      SelectAIException - when listing tasks fails

    • listTools

      List<Tool> listTools() throws SelectAIException
      Lists tools owned by the current database user.

      For a runnable example, see ListToolsSample source.

      Returns:
      tool handles initialized from USER_AI_AGENT_TOOLS metadata and their current database attributes
      Throws:
      SelectAIException - when tool metadata or attributes cannot be loaded

    • listTools

      List<Tool> listTools(String toolNamePattern) throws SelectAIException
      Lists owned tools whose names match a database regular-expression pattern. Matching is case-insensitive. Each returned handle includes metadata and attributes loaded from the database.

      For a runnable example, see ListToolsSample source.

      Parameters:
      toolNamePattern - regular-expression pattern matched against tool names
      Returns:
      matching tool handles
      Throws:
      IllegalArgumentException - when toolNamePattern is null or blank
      SelectAIException - when listing tools fails

    • listTeams

      List<Team> listTeams() throws SelectAIException
      Lists agent teams owned by the current database user.

      For a runnable example, see ListAgentTeamsSample source.

      Returns:
      team handles initialized from USER_AI_AGENT_TEAMS metadata and their current database attributes
      Throws:
      SelectAIException - when team metadata or attributes cannot be loaded

    • listTeams

      List<Team> listTeams(String teamNamePattern) throws SelectAIException
      Lists owned teams whose names match a database regular-expression pattern. Matching is case-insensitive. Each returned handle includes metadata and attributes loaded from the database. Granted cross-schema teams are not returned; use runTeam(String, RunTeamRequest) to run those teams.

      For a runnable example, see ListAgentTeamsSample source.

      Parameters:
      teamNamePattern - regular-expression pattern matched against team names
      Returns:
      matching team handles
      Throws:
      IllegalArgumentException - when teamNamePattern is null or blank
      SelectAIException - when listing teams fails

    • listAvailableTeams

      List<AvailableTeam> listAvailableTeams() throws SelectAIException
      Lists teams available to the calling database user for discovery.

      The returned objects are read-only discovery snapshots, not mutable Team lifecycle handles.

      For a runnable example, see ListAvailableTeamsSample source.

      Returns:
      available team discovery snapshots
      Throws:
      SelectAIException - when the database discovery operation or its JSON response cannot be processed

    • getDefinition

      String getDefinition(AgentObjectType objectType, String objectName, boolean includeDependentObjects) throws SelectAIException
      Returns the definition produced by DBMS_CLOUD_AI_AGENT.GET_DEFINITION for an agent framework object.

      For a runnable example, see GetDefinitionSample source.

      Parameters:
      objectType - object type to describe
      objectName - agent, task, tool, or team name
      includeDependentObjects - whether dependent objects should be included
      Returns:
      definition returned by the database package
      Throws:
      IllegalArgumentException - when objectType is null or objectName is null or blank
      SelectAIException - when the database operation fails

    • importTeam

      boolean importTeam(ImportTeamRequest request) throws SelectAIException
      Imports an agent team definition into the database.

      For a runnable example, see ImportTeamSample source.

      Parameters:
      request - import request
      Returns:
      true when import succeeds
      Throws:
      IllegalArgumentException - when request is null
      SelectAIException - when import fails

    • close

      void close() throws SelectAIException
      Releases resources owned by this client.

      For a runnable example, see CreateSelectAIAgentWithOptionsSample source.

      Specified by:
      close in interface AutoCloseable
      Throws:
      SelectAIException - when an owned JDBC connection cannot be closed