Support for Agents in Select AI for Java

Select AI for Java provides Java APIs for working with database-defined AI agents, tasks, tools, and teams through DBMS_CLOUD_AI_AGENT. Agent support is part of Select AI for Java; it is not a separate component or product. Use the framework to manage agent resources, run tools and teams, preserve team run context across requests, and move team definitions between environments.

The database validates and authorizes resources and performs the requested operations. The Java SDK communicates with the database through JDBC. It does not provide a separate Java agent runtime or make direct calls to AI provider endpoints.

For Select AI profiles, credentials, conversations, vector indexes, and other Select AI operations, see Select AI for Java.

Supported Environments

Select AI Agent Framework APIs in Select AI for Java is supported in the following environments:

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

See Oracle AI Database Select AI capability matrix for feature and database-version requirements.

Agent operations require a database release that supports the requested DBMS_CLOUD_AI_AGENT operation and the associated metadata views. The Java SDK does not probe the database to determine support for every operation.

What You Can Do

The Select AI for Java SDK provides a Java API for working with Select AI Agent Framework resources.

The following table summarizes the primary Select AI for Java supporting Select AI Agent Framework capabilities:

Capability	Description
Agents	Create, load, list, enable, disable, and drop database-defined agents. Retrieve agent attributes and status.
Tasks	Create and manage task definitions, including the instructions and tools used to perform a task.
Tools	Create and manage tools, describe their configuration, and run a tool with JSON input.
Teams	Create and manage teams that coordinate agents and tasks.
Team runs	Start a team workflow with a prompt and runtime parameters.
Runtime-state management	Retrieve, update, or clear supported team state.
Conversation-aware workflows	Continue a team workflow across application requests using a database-created conversation ID.
Shared teams	Run a team owned by another database user when that user grants access. Use the owner-qualified team name.
Team definitions	Retrieve canonical definitions and import or export team specifications.

The database validates and authorizes each request and returns results through the Java API. For an end-to-end example, see example AgentWorkflowSample.

Agent Framework Object Model

Select AI for Java represents each database-defined agent resource through a Java interface and related model classes. Use SelectAIAgent as the entry point for loading, listing, configuring, and creating resources.

The object model has the following relationships:

• A tool defines an operation that an agent or task can use.
• A task defines work, instructions, input, and the tools available to complete that work.
• An agent defines its role, Select AI profile, tools, tasks, memory, and optional supervisor behavior.
• A team maps agents to tasks and defines how they cooperate during a team run.
• A conversation ID associates related team runs and run-state operations across application requests and JDBC connections.

Creating a Java handle does not create the corresponding database resource. For a new resource, obtain a configured handle and call its create() method. For an existing resource, load it by name before calling its lifecycle, attribute, or operational methods.

The public agent API is provided in com.oracle.database.selectai.agent. Public agent request and model classes are provided in com.oracle.database.selectai.model.agent.

Class or class group	Purpose
SelectAIAgent	Creates an agent client and provides collection-level and agent-framework operations.
Agent	Represents and manages a database-defined AI agent.
Task	Represents and manages a task definition.
Tool	Represents, describes, and runs a database-defined tool.
Team	Represents and manages a team, including team run and definition operations.
Resource attribute and status models	Define resource configuration and status through AgentAttributes, AgentStatus, TaskAttributes, TaskStatus, ToolAttributes, ToolStatus, TeamAttributes, and TeamStatus.
Tool parameter models	Define typed configuration for built-in tools through ToolParams, RagToolParams, SlackNotificationToolParams, EmailNotificationToolParams, SqlToolParams, and WebSearchToolParams. Use GenericToolParams for tools or parameter schemas that the SDK does not model with a dedicated class.
Tool input and result models	Represent tool input metadata and tool run results through ToolInput and ToolRunResult.
Team run models	Define team prompts and runtime parameters and represent team run results through RunTeamRequest, RunTeamParams, and TeamRunResult.
Team description and state models	Represent database-generated team descriptions and team run states through TeamDescription, TeamExecutionState, ExecutionStateRequest, and ExecutionStateParams.
Team import and export models	Configure team import and export operations through ImportTeamRequest, ExportTeamRequest, and ExportTeamParams.
Team discovery models	Provide read-only information about teams available to the connected database user through AvailableTeam.

For complete class and method documentation, see Select AI for Java API Reference (Javadoc).

Quickstart: Create and Run an Agent Team

To create and run an agent team:

1. Create or identify the Select AI profile that the agent will use.
2. Configure a Tool handle and call Tool.create() if the workflow requires a database-defined tool.
3. Configure a Task handle and call Task.create().
4. Configure an Agent handle and call Agent.create().
5. Configure a Team handle with the required agent-to-task mappings and call Team.create().
6. Create or obtain a database conversation ID when the workflow must preserve context across runs.
7. Build a RunTeamRequest with the user prompt, conversation ID, and any required RunTeamParams.
8. Call Team.run(RunTeamRequest request) and process the returned TeamRunResult.
9. Preserve the conversation ID if the application must retrieve the latest state, provide human input, or resume the team run.

For a complete example that creates the required resources, runs a team, and continues the same database conversation, see Example AgentWorkflowSample.

Prerequisites

Before using Select AI Agent Framework support in Select AI for Java, install and configure the SDK, connect to a supported Autonomous AI Database, and grant the database user the privileges required for agent resources and their dependencies. Configure the required Select AI profiles, credentials, provider access, network access, and shared-team grants before running a workflow.

Install Select AI for Java

Agent APIs are included with Select AI for Java. For installation, Java requirements, and dependency configuration, see Add Select AI for Java to Your Application.

For API details, see the Select AI for Java API Reference (Javadoc).

Before You Begin

Before using the Select AI Agent Framework:

1. Confirm that your database release supports the agent operations your application needs.
2. Add Select AI for Java and a compatible Oracle JDBC Thin Driver to your application. See Add Select AI for Java to Your Application.
3. Configure JDBC connectivity and the database authentication required by the application. See Connect to Autonomous AI Database.
4. Grant the database user the required DBMS_CLOUD_AI_AGENT privileges and access to the agent metadata views.
5. Configure any required Select AI profiles, credentials, provider access, and network access.
6. Confirm that referenced database functions, procedures, tables, views, and external resources are available to the database user.
7. For a shared team, obtain the database-managed grant from the team owner.
8. For a workflow that resumes across requests or pooled connections, obtain and preserve the database-created conversation ID.

For general Select AI and Select AI Agent Framework setup requirements, see Perform Prerequisites for Select AI and Prerequisites for Using the Select AI Agent Framework.

See Also:

• Use Select AI for Natural Language Interaction with your Database
• DBMS_CLOUD_AI Package
• DBMS_CLOUD_AI_AGENT Package
• Select AI for Java GitHub Repository

Manage Database Privileges and Network Access

Before using an agent, task, tool, or team, confirm that the database user has the privileges required by DBMS_CLOUD_AI_AGENT and access to the applicable agent metadata views.

The database user also needs the privileges required by the resources referenced by the workflow. For example, a tool that uses a database function, procedure, SQL operation, or external resource requires the corresponding database privileges and configuration.

Agent and team workflows can use Select AI profiles, provider credentials, and network access. Configure those resources according to the workflow and deployment. The SDK does not automatically create database users, package grants, credentials, network ACLs, or shared-team grants.

For Select AI setup requirements, see Manage Database Privileges and Network Access. For agent package details, see the DBMS_CLOUD_AI_AGENT package reference.

Work with Tools

Tools provide operations that an agent or task can use. A tool can represent a database function, procedure, SQL operation, or another supported database-defined operation.

For a new tool, obtain a configured Java handle by using:

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

This method creates a Java handle only. Call Tool.create() to create the database tool before calling other database-backed methods. The database validates the ToolAttributes configuration during creation.

For an existing tool, use SelectAIAgent.tool(String toolName) to load the tool by name before calling lifecycle, attribute, description, or run methods. This method loads the tool metadata and attributes from the database.

Use SelectAIAgent.listTools() to list the tools owned by the connected database user, or SelectAIAgent.listTools(String toolNamePattern) to filter that list by name pattern.

Configure Tool Parameters

ToolAttributes can use implementations of the ToolParams interface to configure supported built-in tools. Select the parameter class that corresponds to the tool type.

Class	Purpose
ToolParams	Defines the common interface for configuration parameters used by built-in tools.
RagToolParams	Defines parameters for a built-in retrieval-augmented generation tool.
SlackNotificationToolParams	Defines parameters for a built-in Slack notification tool.
EmailNotificationToolParams	Defines parameters for a built-in email notification tool.
SqlToolParams	Defines parameters for a built-in SQL tool.
WebSearchToolParams	Defines parameters for a built-in web-search tool.
GenericToolParams	Defines parameters for tools or parameter schemas that the SDK does not model with a dedicated parameter class.

Use the builder supplied by the applicable parameter class. The database validates the parameter values when the application creates or updates the tool.

ToolInput represents one input declared in a tool’s tool_inputs array. Use tool input metadata to determine the names, descriptions, data types, and other supported information for the JSON payload supplied to the tool. The database performs semantic validation of the configured input metadata.

Tool.run(String inputJson) returns a ToolRunResult. Use the result object to retrieve the database response from the tool run. For its fields and accessor methods, see Select AI for Java API Reference (Javadoc).

Use these Tool methods to manage an existing database tool:

Method	Purpose
create()	Creates a tool configured through the creation overload.
enable()	Enables the tool.
disable()	Disables the tool.
drop(boolean force)	Removes the tool.
setAttribute(...)	Updates one supported tool attribute.
setAttributes(ToolAttributes toolAttributes)	Updates multiple supported tool attributes.
describe()	Returns the database-generated tool definition and input metadata.
run(String inputJson)	Runs the tool with a JSON input payload and returns a ToolRunResult.
getStatus()	Retrieves the current tool status.
getToolAttributes()	Retrieves the current tool attributes.

Call Tool.describe() before Tool.run(String inputJson) when the application needs the database-defined input metadata. Supply JSON that matches the tool’s supported input schema. The database validates the input and performs the tool operation.

Before running a tool, confirm that the database user can access the referenced database objects and external resources. Protect tool inputs and results according to the data they contain.

If the application calls a database-backed method on a tool that it has not created or loaded, the SDK reports IllegalStateException. The SDK reports database, JDBC, authorization, and tool-run failures through SelectAIException.

For tool attributes, request formats, return values, and exceptions, see Select AI for Java API Reference (Javadoc).

Work with Tasks

A task defines work for an agent and can identify the tools available to complete that work.

For a new task, obtain a configured Java handle by using:

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

This method creates a Java handle only. Call Task.create() to create the database task before calling other database-backed methods. TaskAttributes defines the task instructions, tools, input, and human-tool support.

Note: A human tool is a database-defined tool that pauses a team workflow so a person can review information or provide the input required to continue. For more information about human tools and paused workflows, see Select AI Agent documentation.

For an existing task, use SelectAIAgent.task(String taskName) to load the task by name before calling lifecycle or attribute methods. This method loads the task metadata and attributes from the database. Use SelectAIAgent.listTasks() to list tasks owned by the connected user, or use SelectAIAgent.listTasks(String taskNamePattern) to filter tasks by name pattern.

Use these Task methods to manage an existing database task:

Method	Purpose
create()	Creates a task configured through the creation overload.
enable()	Enables the task.
disable()	Disables the task.
drop(boolean force)	Removes the task.
setAttribute(...)	Updates one supported task attribute.
setAttributes(TaskAttributes taskAttributes)	Updates multiple supported task attributes.
getStatus()	Retrieves the current task status.
getTaskAttributes()	Retrieves the current task attributes.

Creating a task does not automatically associate it with an agent or team. Define those associations in the applicable agent or team attributes.

If the application calls a database-backed method on a task that it has not created or loaded, the SDK reports IllegalStateException. The SDK reports database, JDBC, authorization, and task-operation failures through SelectAIException.

For task attributes, lifecycle operations, and supported request models, see the Select AI for Java API Reference.

Work with Agents

An agent represents a database-defined AI agent. Create or load an agent, configure its attributes and associated profile, and associate it with the tasks required by the workflow.

To configure a new agent, use:

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

This method creates a Java handle only. Call Agent.create() to create the database agent. AgentAttributes defines agent configuration, including profile, role, tools, memory, human-tool support, and supervisor configuration.

Supervisor configuration defines how an agent or team uses a supervisor role. For an agent, it configures the agent’s supervisor behavior. For a team, it identifies and configures the supervisor role that coordinates work among the team’s agents and tasks.

For an existing agent, use SelectAIAgent.agent(String agentName) to load the agent by name before calling lifecycle or attribute methods. This method loads the agent metadata and attributes from the database. Use SelectAIAgent.listAgents() to list agents owned by the connected database user, or use SelectAIAgent.listAgents(String agentNamePattern) to filter agents by name pattern.

Use these Agent methods to manage an existing database agent:

Method	Purpose
create()	Creates an agent configured through the creation overload.
enable()	Enables the agent.
disable()	Disables the agent.
drop(boolean force)	Removes the agent.
setAttribute(...)	Updates one supported agent attribute.
setAttributes(AgentAttributes attributes)	Updates multiple supported agent attributes.
getStatus()	Retrieves the current agent status.
getAgentAttributes()	Retrieves the current agent attributes.

An agent resource represents a database-defined agent configuration. Run an agent as part of a team workflow by using the team APIs. The Agent API does not provide a separate direct agent-run method.

If the application calls a database-backed method on an agent that it has not created or loaded, the SDK reports IllegalStateException. The SDK reports database, JDBC, authorization, and agent-operation failures through SelectAIException.

For agent configuration, status values, lifecycle operations, and request models, and examples, see Select AI for Java API Reference (Javadoc) and an example for supervisor agent

Work with Agent Teams

A team coordinates agents and tasks to perform a workflow. Create or load a team, configure its attributes and task assignments, and run it with a request that supplies the prompt and any supported runtime values.

Use SelectAIAgent.team(String teamName) to load a team owned by the connected database user. Use SelectAIAgent.listTeams() to list owned teams, or SelectAIAgent.listTeams(String teamNamePattern) to filter teams by name pattern.

To configure a new team, use:

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

This method creates a Java handle only. Call Team.create() to create the database team. TeamAttributes defines agent-to-task mappings, run process, memory, and supervisor configuration. The database executes the workflow and returns its result through the Java API. Team run can take time while the database runs tools and communicates with configured AI providers.

Use these Team methods to manage and run a team that the connected user owns:

Method	Purpose
create()	Creates a team configured through the creation overload.
enable()	Enables the team.
disable()	Disables the team.
drop(boolean force)	Removes the team.
setAttribute(...)	Updates one supported team attribute.
setAttributes(TeamAttributes teamAttributes)	Updates multiple supported team attributes.
run(RunTeamRequest request)	Starts or resumes a team run and returns a TeamRunResult.
describe()	Returns a TeamDescription containing the database-generated team definition and aggregated capabilities.
getStateByConversationId(String conversationId)	Retrieves the current run state for the team workflow associated with the specified conversation ID.
setExecutionState(ExecutionStateRequest request)	Updates the state of a team waiting for human input.
exportDefinition(String paramsJson)	Returns the exported team definition as JSON.
exportDefinition(ExportTeamRequest request)	Exports the team definition to Object Storage or a database directory.
getStatus()	Retrieves the current team status.
getTeamAttributes()	Retrieves the current team attributes.

Configure a Team Run

RunTeamRequest supplies the input for Team.run(RunTeamRequest request) and SelectAIAgent.runTeam(String teamName, RunTeamRequest request). Use the request to provide the user prompt and optional typed runtime parameters.

RunTeamParams represents the typed runtime parameters that the the database team-run operation accepts. Use its builder to configure supported runtime values instead of constructing the corresponding JSON parameter object directly.

A team run returns a TeamRunResult. The result retains the response that the database returns and the information required to identify the associated conversation. Preserve the conversation ID when a later request must resume the same workflow or retrieve its latest run state.

Conversations and Workflow State

Use Team.getStateByConversationId(String conversationId) to retrieve the latest run state for a conversation associated with a loaded team. Alternatively, use SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId) to retrieve the state by team name without first loading a Team handle.

Both methods return a TeamExecutionState. This enum represents the team run states supported by the database and retains the database state value.

When a team pauses for human input, use Team.setExecutionState(ExecutionStateRequest request) or SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request) to provide the next state allowed by the database.

ExecutionStateRequest identifies the new state and the team conversation to update. ExecutionStateParams supplies typed parameters for the state-update operation. Use ExecutionStateRequest.Builder.params(ExecutionStateParams) to supply the typed parameter object. For the common case, use ExecutionStateRequest.Builder.conversationId(String conversationId) to set the conversation ID directly.

Class	Purpose
TeamExecutionState	Represents a team run state returned by the database.
ExecutionStateRequest	Defines a request to update the state of a waiting team run.
ExecutionStateParams	Defines typed parameters for the state-update operation, including the conversation identifier.

Preserve the database-created conversation ID and use the same ID for the initial team run, later state retrieval, and any request that resumes the workflow.

For supported state names, request values, return values, and operation behavior, and an example, see Select AI for Java API Reference (Javadoc) and example getTeamStateByConversationId

Resume Workflows with Conversation IDs

Use a RunTeamRequest to start or resume a team workflow. Set the database-created conversation ID with RunTeamRequest.builder().conversationId(conversationId).

Create a conversation through the core SelectAI API. The Conversation.create() method returns the database-generated conversation ID:

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

String conversationId = conversation.create();

The same ID is available later through conversation.getConversationId(). For an existing conversation, open it with SelectAI.conversation(conversationId) and retrieve the ID using getConversationId().

Pass the ID to the team run:

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

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

For a stateless application or an application that uses pooled JDBC connections, preserve this conversation ID and supply the same ID in each later RunTeamRequest. The ID preserves team run context across separate application requests and JDBC connections. For information about reusing a conversation_id to resume a paused team workflow, see DBMS_CLOUD_AI_AGENT Package.

Use the same ID for later state operations, such as getStateByConversationId(conversationId), and when resuming a workflow waiting for human input. Do not replace the database-generated ID with a new client-generated value.

Use one of these methods to start or resume a workflow:

Method	Use
Team.run(RunTeamRequest request)	Starts or resumes a workflow for a loaded team owned by the connected database user.
SelectAIAgent.runTeam(String teamName, RunTeamRequest request)	Starts or resumes a team run by name and returns a TeamRunResult. Use this method to run a shared team by its owner-qualified name.

Coordinate requests that use the same conversation. Do not advance one conversation concurrently from multiple application threads unless the application synchronizes those requests. Concurrent requests can produce conflicting state changes or cause the database to reject the later request.

Use Team.getStateByConversationId(String conversationId) to retrieve the latest run state for a conversation associated with a loaded team.

Use Team.getStateByConversationId(String conversationId) to retrieve the latest run state for a conversation associated with a loaded team. Alternatively, use SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId) to retrieve the latest state by team name. Both methods return a TeamExecutionState.

Both methods return a TeamExecutionState. Pass the same database-created conversation ID that the application used to start or resume the team run. These methods accept the conversation ID directly; the application does not need to construct a JSON runtime-parameters payload.

When a team workflow waits for human input, use Team.setExecutionState(ExecutionStateRequest request) or SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request) to provide the next run state. The database validates the requested state transition and the conversation context.

If a later request omits the required conversation ID, the database can report missing conversation context through SelectAIException, such as ORA-20053. After a timeout or connection failure, retrieve the team state before sending another request. A JDBC timeout does not guarantee that database-side or provider-side processing stopped.

Shared Teams

A database user can run a team owned by another database user when the owner grants access through the database. Use the owner-qualified team name when running the shared team.

The database enforces the team grant and privileges on the resources the team uses. Shared-team support does not let the Java application manage the owner’s resources or bypass database authorization.

A shared team belongs to another database user. You cannot load a shared team through SelectAIAgent.team(String teamName) or find it through listTeams().

Run a shared team with:

SelectAIAgent.runTeam(String teamName, RunTeamRequest request)

Supply the owner-qualified team name required by the database grant. Use SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId) to retrieve the latest run state and SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request) to update a waiting run state.

The database enforces shared-team access. The grant allows run only; it does not allow the connected user to update, export, disable, or drop the owner’s team.

Import and Export a Team

Export a team definition to preserve or move a team configuration. Import a team definition to create the corresponding database resources in another environment.

The Select AI Agent Framework also supports retrieving canonical definitions for agent framework resources. Review the definition and referenced resources before importing it. The importing database user must have the privileges required to create the resources and access their dependencies.

Use these methods for database-generated definitions and team import:

Method	Purpose
Team.exportDefinition()	Returns the loaded team definition as JSON using the database defaults.
Team.exportDefinition(ExportTeamParams params)	Returns the loaded team definition as JSON using typed export parameters.
Team.exportDefinition(ExportTeamRequest request)	Exports the loaded team definition to Object Storage or a database directory.
SelectAIAgent.getDefinition(AgentObjectType objectType, String objectName, boolean includeDependentObjects)	Retrieves the canonical database definition of an agent, task, tool, or team.
SelectAIAgent.importTeam(ImportTeamRequest request)	Imports a team definition and its related resources into the database.

ExportTeamParams supplies typed parameters when the application returns an exported team definition as JSON. The class currently supports the optional overwrite field. Pass null to Team.exportDefinition(ExportTeamParams params) to use the database defaults.

ExportTeamRequest identifies an Object Storage URI or database directory destination for an export. It can include ExportTeamParams for the typed export options that the database supports.

Review exported or retrieved definitions before importing them into another environment. Confirm that required resources, privileges, profiles, credentials, and database capabilities exist in the target environment.

For request formats, definition contents, export destinations, and import behavior, see Select AI for Java API Reference (Javadoc).

Retrieve, Update, and Delete Existing Objects

Load or list agents, tasks, tools, and teams owned by the connected database user. Retrieve status and attributes when the application needs current resource information.

Update only attributes that the resource API supports. Before dropping a resource, check whether a task, agent, or team depends on it. The database enforces the privileges required for retrieval, updates, and removal.

Use SelectAIAgent to load or list agent framework resources owned by the connected database user.

Resource	Load one resource	List resources
Agent	SelectAIAgent.agent(String agentName)	SelectAIAgent.listAgents() or SelectAIAgent.listAgents(String agentNamePattern)
Task	SelectAIAgent.task(String taskName)	SelectAIAgent.listTasks() or SelectAIAgent.listTasks(String taskNamePattern)
Tool	SelectAIAgent.tool(String toolName)	SelectAIAgent.listTools() or SelectAIAgent.listTools(String toolNamePattern)
Team	SelectAIAgent.team(String teamName)	SelectAIAgent.listTeams() or SelectAIAgent.listTeams(String teamNamePattern)

The name-only load methods retrieve the resource metadata and attributes from the database. The list methods return resources owned by the connected database user. A shared team owned by another user is not returned by listTeams() and cannot be loaded with team(String teamName). Use SelectAIAgent.runTeam(String teamName, RunTeamRequest request) with the required owner-qualified team name to run a shared team.

Retrieve Resource Information

Use the resource getter methods when the application needs current database information.

Resource	Resource name	Description	Status	Attributes
Agent	getAgentName()	getDescription()	getStatus()	getAgentAttributes()
Task	getTaskName()	getDescription()	getStatus()	getTaskAttributes()
Tool	getToolName()	getDescription()	getStatus()	getToolAttributes()
Team	getTeamName()	getDescription()	getStatus()	getTeamAttributes()

For database-backed resources, getStatus() and the attribute getter retrieve current information from the database. The name and description getters return the resource metadata available to the Java object.

Update Resource Attributes

Use the setAttribute(...) methods to update one supported attribute, or use setAttributes(...) to update multiple supported attributes.

Resource	Update one attribute	Update multiple attributes
Agent	Agent.setAttribute(...)	Agent.setAttributes(AgentAttributes attributes)
Task	Task.setAttribute(...)	Task.setAttributes(TaskAttributes attributes)
Tool	Tool.setAttribute(...)	Tool.setAttributes(ToolAttributes attributes)
Team	Team.setAttribute(...)	Team.setAttributes(TeamAttributes attributes)

The setAttribute(...) methods support the documented string, Boolean, integer, and floating-point attribute values. The database determines whether an attribute can change after resource creation. Retrieve the current attributes before making an update when the application needs to preserve existing configuration.

Use enable() and disable() to change the resource status:

Resource	Enable	Disable
Agent	Agent.enable()	Agent.disable()
Task	Task.enable()	Task.disable()
Tool	Tool.enable()	Tool.disable()
Team	Team.enable()	Team.disable()

A resource must be created or loaded before the application updates its attributes or status. Otherwise, the SDK reports IllegalStateException. Invalid arguments result in IllegalArgumentException. Database validation, authorization, and JDBC failures result in SelectAIException.

Delete Resources

Use drop(boolean force) to remove a database resource.

Resource	Delete method
Agent	Agent.drop(boolean force)
Task	Task.drop(boolean force)
Tool	Tool.drop(boolean force)
Team	Team.drop(boolean force)

Before dropping a resource, confirm that no task, agent, tool, or team definition depends on it. Removing a resource can cause a later team workflow to fail. Use force only when the application can safely treat an already absent resource as the intended final state. force controls how the SDK handles a missing resource. When force is false, the drop operation fails if the resource does not exist. When force is true, the SDK ignores the missing-resource error and completes the operation successfully. The flag does not bypass authorization, hide unrelated database errors, or delete dependent resources.

The database enforces the privileges required to retrieve, update, enable, disable, and remove resources. For resource-specific lifecycle methods, supported attributes, return values, and exceptions, see the Select AI for Java API Reference.

For object-specific lifecycle methods and return values, see the Select AI for Java API Reference.

Connections, Concurrency, Transactions, and Timeouts

Select AI for Java supports SDK-managed and application-managed JDBC connections for agent operations. Select a connection mode based on resource ownership and concurrency requirements, coordinate requests that use the same team conversation, and account for transaction behavior, connection-pool usage, and timeouts during long-running tool and team operations.

Connect to Autonomous AI Database

For connection modes, DbConnectionConfig, DataSource, and general JDBC connection management, see Connect to Autonomous AI Database.

The following agent-specific behavior applies to those connection modes.

DbConnectionConfig

With DbConnectionConfig, the SDK creates and owns one JDBC connection for the SelectAIAgent client. The client reuses that connection for agent operations and closes it when the application closes the client.

Treat a client created this way as single-threaded unless the application synchronizes access. SelectAIAgent does not expose its retained connection for custom JDBC work. Use an application-managed DataSource when the application needs agent operations and custom JDBC work through the same connection-management infrastructure.

DataSource

In DataSource mode, the SDK borrows a connection for each public operation and returns it when that operation completes. The application continues to own the DataSource.

A long-running team run can hold a borrowed connection until the operation returns. Consider the expected duration of team workflows when configuring pool capacity and statement timeouts.

Connection Lifecycle and Threading

Close the SelectAIAgent client when the application no longer needs it. In DbConnectionConfig mode, closing the client releases the SDK-owned connection. In DataSource mode, closing the client does not close the application-owned DataSource.

For concurrent independent operations, use DataSource mode. Do not concurrently change or run state-changing operations on the same Agent, Task, Tool, or Team object unless the application synchronizes access. When multiple requests work with the same team conversation, coordinate those requests so they do not advance the conversation concurrently.

Database authorization and resource privileges continue to apply to shared teams, regardless of the Java connection or threading model.

Transaction and Timeout Behavior

The SDK does not explicitly commit or roll back agent, task, tool, or team operations and does not change the JDBC connection’s autoCommit setting. Transaction behavior depends on the connection configuration and the database APIs used by the operation. The database can perform transaction actions that the SDK does not control.

Do not automatically retry a state-changing operation after a timeout. Database-side or provider-side work might still be running.

Handle Errors and Security

The SDK reports validation and database failures through its Java exception model, including SelectAIException for database and operation failures. Handle errors according to whether the operation changes database state.

A team run can occupy a JDBC connection until it returns. Configure connection pools and statement timeouts for the expected workload. A timeout does not guarantee that database-side or provider-side processing has stopped.

Oracle recommends that you not automatically retry state-changing agent, task, tool, or team operations after a timeout. Check the database resource or workflow state before deciding whether it is safe to retry. Do not log credentials, private keys, prompts, tool inputs, generated results, or complete agent attribute payloads.

Handle SDK Exceptions

The SDK uses the following exceptions for common error conditions:

Exception	When it occurs
IllegalArgumentException	The application supplies an invalid argument or request. Examples include a null or blank agent, task, tool, or team name, a null request, or an invalid request value. The SDK detects these errors before JDBC processing when possible.
IllegalStateException	The application calls an operation when the SDK resource is not in the required lifecycle state. For example, the application attempts a resource-specific operation before it creates or loads the resource.
SelectAIException	JDBC or the database reports a failure during an agent, task, tool, team, run-state, import, or export operation. This includes database validation, privilege, resource lookup, workflow, and other DBMS_CLOUD_AI_AGENT failures.

See Handle Errors for more details.

For exception details and operation-specific behavior, see the Select AI for Java API Reference (Javadoc).

Retry Failed Operations

The SDK does not automatically retry failed Agent operations. Do not automatically retry resource creation, updates, deletion, administration, tool runs, team runs, run-state changes, or definition imports. The database might have started processing before the application received an error.

After a timeout or connection failure, retrieve the resource or team run state before deciding whether to retry. A JDBC timeout does not guarantee that database-side or provider-side work has stopped. Retry only after you determine that repeating the operation is safe.

Troubleshoot Agent Errors

When an Agent operation fails:

1. For IllegalArgumentException, check required names, request objects, and attribute values.
2. For IllegalStateException, confirm that the application created or loaded the resource before calling the operation.
3. For SelectAIException, inspect the message, Oracle error code, SQL state, and underlying cause when available.
4. Confirm that the connected database user has the required package privileges and access to the requested resource.
5. For shared-team operations, confirm that the database granted the connected user access and that the request uses the required owner-qualified team name.
6. For team run, confirm that the request supplies the conversation ID required to start or resume the workflow.
7. For import or export failures, check the definition, target database support, and the connected user’s privileges.

See the Select AI for Java API Reference for method-specific exception declarations and details.

Protect Sensitive Data

Do not include database or provider credentials, private keys, access tokens, full credential configurations, sensitive prompts, conversation history, or generated results in logs or diagnostic reports. Record only the safe error details needed to troubleshoot the failure.

The Java SDK communicates with the database over JDBC. When a database operation requires an AI provider or object store, the database makes the outbound connection according to its configuration. Review database-side provider configuration, network access, and Select AI data-access controls before enabling the workflow.

Related Resources

• Select AI for Java
• Select AI for Python supporting Select AI Agent Framework
• Select AI for Java API Reference (Javadoc)
• DBMS_CLOUD_AI_AGENT package reference
• Select AI for Java GitHub Repository
• Select AI for Java Examples