001/*
002 * Copyright (c) 2026, Oracle and/or its affiliates.
003 *
004 * Licensed under the Universal Permissive License Version 1.0 as shown at
005 * https://oss.oracle.com/licenses/upl/
006 */
007package com.oracle.database.selectai.agent;
008
009import com.oracle.database.selectai.model.agent.AgentAttributes;
010import com.oracle.database.selectai.model.agent.AgentStatus;
011import com.oracle.database.selectai.model.SelectAIException;
012
013/**
014 * Contract for Select AI agent lifecycle management and metadata access.
015 * <p>
016 * A Select AI agent is a database-side resource managed by the
017 * {@code DBMS_CLOUD_AI_AGENT} PL/SQL package. Agents can use a configured
018 * Select AI profile and may participate in task, tool, and team orchestration.
019 * <p>
020 * An {@code Agent} instance can represent an existing database agent or be
021 * configured for creation. The name-only {@link SelectAIAgent#agent(String)}
022 * factory verifies that the agent exists and loads its metadata and attributes
023 * before returning. {@link SelectAIAgent#listAgents()} also returns handles with
024 * loaded metadata and attributes. A handle configured for creation is obtained with
025 * {@link SelectAIAgent#agent(String, AgentAttributes, String, AgentStatus)}.
026 * <p>
027 * A creation-configured handle retains its supplied attributes, description,
028 * and status without querying the database. Only such a handle can call
029 * {@link #create()}; after creation succeeds, it becomes database-backed.
030 * {@link #enable()}, {@link #disable()}, and {@link #drop(boolean)} require an
031 * existing agent and operate on the database-side resource.
032 * <p>
033 * Before creation, {@link #getStatus()} and {@link #getAgentAttributes()} return
034 * the configured values. For a database-backed handle, each call to either
035 * method queries the database. {@code getStatus()} does not change the
036 * description returned by {@link #getDescription()}. The description is
037 * supplied or loaded when the handle is initialized; {@code getDescription()}
038 * does not query the database.
039 * <p>
040 * Agent names and a non-null attributes object are checked locally. Required
041 * values within {@link AgentAttributes}, including the profile name and role,
042 * are validated by the database during {@link #create()}. Loading metadata
043 * and executing lifecycle operations require database access and privileges.
044 * <p>
045 * For a complete runnable example, see
046 * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/CreateAgentSample.html">
047 * CreateAgentSample source</a>.
048 *
049 * @see SelectAIAgent
050 * @see <a href="https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/adbsb/dbms-cloud-ai-agent-package.html">
051 *      DBMS_CLOUD_AI_AGENT package documentation</a>
052 * @since 1.1.0
053 */
054public interface Agent {
055    /**
056     * Creates this creation-configured agent in the database.
057     * For a runnable example, see
058     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/CreateAgentSample.html">
059     * CreateAgentSample source</a>.
060     *
061     * @return {@code true} when the database creates the agent
062     * @throws IllegalStateException when this handle was loaded from an existing agent
063     * @throws SelectAIException when the database rejects or cannot complete the operation
064     */
065    boolean create() throws SelectAIException;
066    /**
067     * Enables this database-backed agent.
068     * For a runnable example, see
069     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/EnableAgentSample.html">
070     * EnableAgentSample source</a>.
071     *
072     * @return {@code true} when the database enables the agent
073     * @throws IllegalStateException when this agent has not been created
074     * @throws SelectAIException when the database operation fails
075     */
076    boolean enable() throws SelectAIException;
077    /**
078     * Disables this database-backed agent.
079     * For a runnable example, see
080     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/DisableAgentSample.html">
081     * DisableAgentSample source</a>.
082     *
083     * @return {@code true} when the database disables the agent
084     * @throws IllegalStateException when this agent has not been created
085     * @throws SelectAIException when the database operation fails
086     */
087    boolean disable() throws SelectAIException;
088    /**
089     * Drops this database-backed agent. When {@code force} is {@code true},
090     * the operation may be retried after the handle has already been dropped;
091     * the database force-drop semantics determine the result.
092     * For a runnable example, see
093     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/DropAgentSample.html">
094     * DropAgentSample source</a>.
095     *
096     * @param force database force-drop option
097     * @return {@code true} when the drop completes
098     * @throws IllegalStateException when {@code force} is {@code false} and
099     *         this agent has not been created
100     * @throws SelectAIException when the database operation fails
101     */
102    boolean drop(boolean force) throws SelectAIException;
103
104    /**
105     * Updates one agent attribute in the database.
106     * <p>
107     * The database validates the attribute name and value for the selected
108     * database release. A {@code null} string value is passed to the database
109     * as SQL {@code NULL}; whether that clears an attribute is database-defined.
110     *
111     * @param attributeName database agent attribute name
112     * @param attributeValue string value, or {@code null} where supported
113     * @return {@code true} when the update succeeds
114     * @throws IllegalArgumentException when {@code attributeName} is null or blank
115     * @throws IllegalStateException when this agent has not been created
116     * @throws SelectAIException when the database update fails
117     * @see <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetAgentAttributeSample.html">
118     *      SetAgentAttributeSample source</a>
119     */
120    boolean setAttribute(String attributeName, String attributeValue) throws SelectAIException;
121
122    /**
123     * Updates one boolean agent attribute in the database.
124     * For a runnable example, see
125     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetAgentAttributeSample.html">
126     * SetAgentAttributeSample source</a>.
127     *
128     * @param attributeName database agent attribute name
129     * @param attributeValue boolean value
130     * @return {@code true} when the update succeeds
131     * @throws IllegalArgumentException when {@code attributeName} is null or blank
132     * @throws IllegalStateException when this agent has not been created
133     * @throws SelectAIException when the database update fails
134     */
135    boolean setAttribute(String attributeName, boolean attributeValue) throws SelectAIException;
136
137    /**
138     * Updates one integer agent attribute in the database.
139     * For a runnable example, see
140     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetAgentAttributeSample.html">
141     * SetAgentAttributeSample source</a>.
142     *
143     * @param attributeName database agent attribute name
144     * @param attributeValue integer value
145     * @return {@code true} when the update succeeds
146     * @throws IllegalArgumentException when {@code attributeName} is null or blank,
147     *         or {@code attributeValue} is null
148     * @throws IllegalStateException when this agent has not been created
149     * @throws SelectAIException when the database update fails
150     */
151    boolean setAttribute(String attributeName, Integer attributeValue) throws SelectAIException;
152
153    /**
154     * Updates one floating-point agent attribute in the database.
155     * For a runnable example, see
156     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetAgentAttributeSample.html">
157     * SetAgentAttributeSample source</a>.
158     *
159     * @param attributeName database agent attribute name
160     * @param attributeValue floating-point value
161     * @return {@code true} when the update succeeds
162     * @throws IllegalArgumentException when {@code attributeName} is null or blank,
163     *         or {@code attributeValue} is null
164     * @throws IllegalStateException when this agent has not been created
165     * @throws SelectAIException when the database update fails
166     */
167    boolean setAttribute(String attributeName, Float attributeValue) throws SelectAIException;
168
169    /**
170     * Updates multiple agent attributes in one database operation.
171     * For a runnable example, see
172     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/SetAgentAttributesSample.html">
173     * SetAgentAttributesSample source</a>.
174     * <p>
175     * The payload is serialized as the JSON document accepted by
176     * {@code DBMS_CLOUD_AI_AGENT.SET_ATTRIBUTES}. Values omitted from the
177     * payload are handled according to the database package semantics.
178     *
179     * @param agentAttributes agent attributes to update
180     * @return {@code true} when the update succeeds
181     * @throws IllegalArgumentException when {@code agentAttributes} is null
182     * @throws IllegalStateException when this agent has not been created
183     * @throws SelectAIException when the database update fails
184     */
185    boolean setAttributes(AgentAttributes agentAttributes) throws SelectAIException;
186
187    /**
188     * Returns the database-reported name for a loaded agent, or the configured
189     * name before creation. This method does not access the database.
190     * For a runnable example, see
191     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/LoadAgentSample.html">
192     * LoadAgentSample source</a>.
193     *
194     * @return configured or database-reported agent name
195     */
196    String getAgentName();
197    /**
198     * Returns the description supplied or loaded when this handle was initialized.
199     * This method does not access the database and the value is not changed by
200     * {@link #getStatus()}.
201     * For a runnable example, see
202     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/LoadAgentSample.html">
203     * LoadAgentSample source</a>.
204     *
205     * @return supplied or loaded agent description, or {@code null} when absent
206     */
207    String getDescription();
208    /**
209     * Returns the configured status before creation or the current database
210     * status for an existing agent. A pending agent with no configured status
211     * returns {@code null}. This method does not change the description.
212     * For a runnable example, see
213     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/LoadAgentSample.html">
214     * LoadAgentSample source</a>.
215     *
216     * @return configured or current agent status
217     * @throws SelectAIException when current agent metadata cannot be fetched
218     */
219    AgentStatus getStatus() throws SelectAIException;
220    /**
221     * Returns agent attributes for this handle.
222     * <p>
223     * For a database-backed agent, this method reloads the attributes from the
224     * database on each call and therefore can fail if the resource was deleted.
225     * For a creation-configured agent, it returns the configured attributes
226     * without querying the database.
227     * For a runnable example, see
228     * <a href="{@docRoot}/src-html/com/oracle/database/selectai/samples/agent/LoadAgentSample.html">
229     * LoadAgentSample source</a>.
230     *
231     * @return current agent attributes for an existing agent, or configured
232     *         attributes for an agent pending creation
233     * @throws SelectAIException when the agent no longer exists or current attributes cannot be fetched
234     */
235    AgentAttributes getAgentAttributes() throws SelectAIException;
236}