Unterstützung für Agents in Select AI für Java
Select AI for Java stellt über DBMS_CLOUD_AI_AGENT Java-APIs für die Arbeit mit datenbankdefinierten KI-Agents, Aufgaben, Tools und Teams bereit. Die Agent-Unterstützung ist Teil von Select AI for Java. Sie ist keine separate Komponente oder kein separates Produkt. Mit dem Framework können Sie Agent-Ressourcen verwalten, Tools und Teams ausführen, den Teamausführungskontext über Anforderungen hinweg beibehalten und Teamdefinitionen zwischen Umgebungen verschieben.
Die Datenbank validiert und autorisiert Ressourcen und führt die angeforderten Vorgänge aus. Das Java-SDK kommuniziert über JDBC mit der Datenbank. Es stellt keine separate Java-Agent-Laufzeit bereit und führt keine direkten Aufrufe an AI-Providerendpunkte durch.
Informationen zu ausgewählten KI-Profilen, Zugangsdaten, Unterhaltungen, Vektorindizes und anderen Select AI-Vorgängen finden Sie unter AI für Java auswählen.
Unterstützte Umgebungen
Die Auswahl von AI Agent Framework-APIs in Select AI for Java wird in den folgenden Umgebungen unterstützt:
- Oracle Autonomous AI Database 26ai
- Oracle Autonomous AI Database 19c
Informationen zu Funktions- und Datenbankversionsanforderungen finden Sie in der Oracle AI Database Select AI-Funktionsmatrix.
Agent-Vorgänge erfordern ein Datenbankrelease, das den angeforderten DBMS_CLOUD_AI_AGENT-Vorgang und die zugehörigen Metadaten-Views unterstützt. Das Java-SDK prüft die Datenbank nicht, um die Unterstützung für jeden Vorgang zu bestimmen.
Aufgaben, die sie ausführen können
Das Select AI for Java SDK stellt eine Java-API für die Arbeit mit Select AI Agent Framework-Ressourcen bereit.
In der folgenden Tabelle werden die primären Select AI for Java-Funktionen zusammengefasst, die Select AI Agent Framework unterstützen:
| Fähigkeit | Beschreibung |
|---|---|
| Agents | Erstellen, laden, auflisten, aktivieren, deaktivieren und löschen Sie datenbankdefinierte Agents. Agent-Attribute und -Status abrufen. |
| Aufgaben | Erstellen und verwalten Sie Aufgabendefinitionen, einschließlich der Anweisungen und Tools für die Ausführung einer Aufgabe. |
| Werkzeuge | Erstellen und verwalten Sie Tools, beschreiben Sie ihre Konfiguration, und führen Sie ein Tool mit JSON-Eingabe aus. |
| Teams | Erstellen und verwalten Sie Teams, die Agents und Aufgaben koordinieren. |
| Teamläufe | Starten Sie einen Teamworkflow mit einem Prompt und Laufzeitparametern. |
| Laufzeit-Statusverwaltung | Unterstützten Teamstatus abrufen, aktualisieren oder löschen. |
| Konversationsbezogene Workflows | Setzen Sie einen Teamworkflow über Anwendungsanforderungen hinweg mit einer von der Datenbank erstellten Unterhaltungs-ID fort. |
| Gemeinsame Teams | Führen Sie ein Team aus, das einem anderen Datenbankbenutzer gehört, wenn dieser Benutzer Zugriff erteilt. Verwenden Sie den vom Verantwortlichen qualifizierten Teamnamen. |
| Teamdefinitionen | Rufen Sie kanonische Definitionen ab und importieren oder exportieren Sie Teamspezifikationen. |
Die Datenbank validiert und autorisiert jede Anforderung und gibt Ergebnisse über die Java-API zurück. Ein End-to-End-Beispiel finden Sie unter Beispiel AgentWorkflowSample.
Agent-Framework-Objektmodell
Select AI for Java stellt jede datenbankdefinierte Agent-Ressource über eine Java-Schnittstelle und zugehörige Modellklassen dar. Verwenden Sie SelectAIAgent als Einstiegspunkt zum Laden, Auflisten, Konfigurieren und Erstellen von Ressourcen.
Das Objektmodell hat die folgenden Beziehungen:
- Ein Tool definiert einen Vorgang, den ein Agent oder eine Aufgabe verwenden kann.
- Eine Aufgabe definiert Arbeit, Anweisungen, Eingabe und die verfügbaren Tools, um diese Arbeit abzuschließen.
- Ein Agent definiert seine Rolle, Select AI-Profil, Tools, Aufgaben, Arbeitsspeicher und optionales Supervisor-Verhalten.
- Ein Team ordnet Agents Aufgaben zu und definiert, wie sie während eines Teamlaufs zusammenarbeiten.
- Mit einer Unterhaltungs-ID werden zugehörige Teamausführungen und Run-State-Vorgänge über Anwendungsanforderungen und JDBC-Verbindungen hinweg verknüpft.
Beim Erstellen eines Java-Handles wird die entsprechende Datenbankressource nicht erstellt. Rufen Sie für eine neue Ressource ein konfiguriertes Handle ab, und rufen Sie die zugehörige create()-Methode auf. Laden Sie eine vorhandene Ressource nach Namen, bevor Sie den Lebenszyklus, das Attribut oder die Betriebsmethoden aufrufen.
Die öffentliche Agent-API wird in com.oracle.database.selectai.agent bereitgestellt. Öffentliche Agent-Anforderungs- und Modellklassen werden in com.oracle.database.selectai.model.agent angegeben.
| Klasse oder Klassengruppe | Zweck |
|---|---|
SelectAIAgent |
Erstellt einen Agent-Client und stellt Auflistungs- und Agent-Framework-Vorgänge bereit. |
Agent |
Stellt einen datenbankdefinierten AI-Agent dar und verwaltet ihn. |
Task |
Stellt eine Aufgabendefinition dar und verwaltet sie. |
Tool |
Stellt ein datenbankdefiniertes Tool dar, beschreibt es und führt es aus. |
Team |
Stellt ein Team dar und verwaltet es, einschließlich Teamausführungs- und Definitionsvorgängen. |
| Ressourcenattribut- und Statusmodelle | Definieren Sie Ressourcenkonfiguration und -status über AgentAttributes, AgentStatus, TaskAttributes, TaskStatus, ToolAttributes, ToolStatus, TeamAttributes und TeamStatus. |
| Werkzeugparametermodelle | Definieren Sie die Typkonfiguration für integrierte Tools über ToolParams, RagToolParams, SlackNotificationToolParams, EmailNotificationToolParams, SqlToolParams und WebSearchToolParams. Verwenden Sie GenericToolParams für Tools oder Parameterschemas, die das SDK nicht mit einer dedizierten Klasse modelliert. |
| Werkzeugeingabe- und Ergebnismodelle | Stellen Sie Tool-Eingabemetadaten und Ergebnisse der Toolausführung über ToolInput und ToolRunResult dar. |
| Teamlaufmodelle | Definieren Sie Team-Prompts und Laufzeitparameter, und stellen Sie Teamausführungsergebnisse über RunTeamRequest, RunTeamParams und TeamRunResult dar. |
| Teambeschreibung und Zustandsmodelle | Stellen Sie datenbankgenerierte Teambeschreibungen und Teamausführungsstatus über TeamDescription, TeamExecutionState, ExecutionStateRequest und ExecutionStateParams dar. |
| Teamimport- und -exportmodelle | Konfigurieren Sie Teamimport- und -exportvorgänge über ImportTeamRequest, ExportTeamRequest und ExportTeamParams. |
| Team-Discovery-Modelle | Stellen Sie schreibgeschützte Informationen zu Teams bereit, die dem angemeldeten Datenbankbenutzer über AvailableTeam zur Verfügung stehen. |
Eine vollständige Dokumentation zu Klasse und Methode finden Sie unter Select AI for Java API Reference (Javadoc).
Schnellstart: Agent-Team erstellen und ausführen
So erstellen Sie ein Agent-Team und führen es aus:
- Erstellen oder identifizieren Sie das Select AI-Profil, das der Agent verwenden wird.
- Konfigurieren Sie ein
Tool-Handle, und rufen SieTool.create()auf, wenn der Workflow ein datenbankdefiniertes Tool erfordert. - Konfigurieren Sie ein
Task-Handle, und rufen SieTask.create()auf. - Konfigurieren Sie ein
Agent-Handle, und rufen SieAgent.create()auf. - Konfigurieren Sie ein
Team-Handle mit den erforderlichen Agent-zu-Task-Zuordnungen, und rufen SieTeam.create()auf. - Erstellen oder rufen Sie eine Datenbankkonversations-ID ab, wenn der Workflow den Kontext über alle Ausführungen hinweg beibehalten muss.
- Erstellen Sie eine
RunTeamRequestmit der Benutzereingabeaufforderung, der Unterhaltungs-ID und einer beliebigen erforderlichenRunTeamParams. - Rufen Sie
Team.run(RunTeamRequest request)auf, und verarbeiten Sie die zurückgegebeneTeamRunResult. - Behalten Sie die Konversations-ID bei, wenn die Anwendung den letzten Status abrufen, menschliche Eingaben vornehmen oder die Teamausführung fortsetzen muss.
Ein vollständiges Beispiel, in dem die erforderlichen Ressourcen erstellt, ein Team ausgeführt und dieselbe Datenbankunterhaltung fortgesetzt wird, finden Sie unter Beispiel AgentWorkflowSample.
Voraussetzungen
Bevor Sie die Unterstützung für Select AI Agent Framework in Select AI for Java verwenden, installieren und konfigurieren Sie das SDK, stellen Sie eine Verbindung zu einer unterstützten autonomen KI-Datenbank her, und erteilen Sie dem Datenbankbenutzer die Berechtigungen, die für Agent-Ressourcen und deren Abhängigkeiten erforderlich sind. Konfigurieren Sie die erforderlichen Select AI-Profile, Zugangsdaten, Providerzugriff, Netzwerkzugriff und Shared-Team-Berechtigungen, bevor Sie einen Workflow ausführen.
Select AI für Java installieren
Agent-APIs sind in Select AI for Java enthalten. Informationen zur Installation, den Java-Anforderungen und der Abhängigkeitskonfiguration finden Sie unter Select AI for Java zu Ihrer Anwendung hinzufügen.
API-Details finden Sie unter AI for Java API Reference (Javadoc) auswählen.
Bevor Sie beginnen
Vor der Verwendung des Select AI Agent Framework:
- Stellen Sie sicher, dass Ihr Datenbankrelease die Agent-Vorgänge unterstützt, die Ihre Anwendung benötigt.
- Fügen Sie Ihrer Anwendung Select AI für Java und einen kompatiblen Oracle JDBC Thin Driver hinzu. Siehe Select AI for Java zu Ihrer Anwendung hinzufügen.
- Konfigurieren Sie die JDBC-Konnektivität und die Datenbankauthentifizierung, die von der Anwendung benötigt wird. Siehe Verbindung zu autonomer KI-Datenbank herstellen.
- Erteilen Sie dem Datenbankbenutzer die erforderlichen
DBMS_CLOUD_AI_AGENT-Berechtigungen und Zugriff auf die Agent-Metadaten-Views. - Konfigurieren Sie alle erforderlichen Select AI-Profile, Zugangsdaten, Providerzugriff und Netzwerkzugriff.
- Prüfen Sie, ob referenzierte Datenbankfunktionen, Prozeduren, Tabellen, Views und externe Ressourcen für den Datenbankbenutzer verfügbar sind.
- Für ein gemeinsam verwendetes Team erhalten Sie die datenbankverwaltete Berechtigung vom Teamverantwortlichen.
- Für einen Workflow, der über Anforderungen oder Verbindungen im Pool hinweg fortgesetzt wird, rufen Sie die von der Datenbank erstellte Unterhaltungs-ID ab und bewahren sie auf.
Allgemeine Setupanforderungen für Select AI und Select AI Agent Framework finden Sie unter Voraussetzungen für Select AI ausführen und Voraussetzungen für die Verwendung des Select AI Agent Framework.
Siehe:
Datenbankberechtigungen und Netzwerkzugriff verwalten
Bevor Sie einen Agent, eine Aufgabe, ein Tool oder ein Team verwenden, stellen Sie sicher, dass der Datenbankbenutzer über die für DBMS_CLOUD_AI_AGENT erforderlichen Berechtigungen und den Zugriff auf die entsprechenden Agent-Metadatenansichten verfügt.
Der Datenbankbenutzer benötigt auch die Berechtigungen, die von den Ressourcen benötigt werden, die vom Workflow referenziert werden. Beispiel: Ein Tool, das eine Datenbankfunktion, -prozedur, einen SQL-Vorgang oder eine externe Ressource verwendet, benötigt die entsprechenden Datenbankberechtigungen und -konfigurationen.
Agent- und Teamworkflows können Select AI-Profile, Providerzugangsdaten und Netzwerkzugriff verwenden. Konfigurieren Sie diese Ressourcen entsprechend dem Workflow und Deployment. Das SDK erstellt nicht automatisch Datenbankbenutzer, Packageberechtigungen, Zugangsdaten, Netzwerk-ACLs oder Berechtigungen für freigegebene Teams.
Informationen zu Select AI-Setupanforderungen finden Sie unter Datenbankberechtigungen und Netzwerkzugriff verwalten. Details zu Agent-Packages finden Sie in der DBMS_CLOUD_AI_AGENT-Packagereferenz.
Mit Tools arbeiten
Tools bieten Vorgänge, die ein Agent oder eine Aufgabe verwenden kann. Ein Tool kann eine Datenbankfunktion, eine Prozedur, einen SQL-Vorgang oder einen anderen unterstützten datenbankdefinierten Vorgang darstellen.
Rufen Sie für ein neues Tool ein konfiguriertes Java-Handle ab, indem Sie:
SelectAIAgent.tool(String toolName, ToolAttributes attributes, String description, ToolStatus status)
Diese Methode erstellt nur ein Java-Handle. Rufen Sie Tool.create() auf, um das Datenbanktool zu erstellen, bevor Sie andere datenbankgestützte Methoden aufrufen. Die Datenbank validiert die Konfiguration ToolAttributes während der Erstellung.
Verwenden Sie für ein vorhandenes Tool SelectAIAgent.tool(String toolName), um das Tool nach Namen zu laden, bevor Sie Lebenszyklus-, Attribut-, Beschreibung- oder Ausführungsmethoden aufrufen. Mit dieser Methode werden die Toolmetadaten und -attribute aus der Datenbank geladen.
Verwenden Sie SelectAIAgent.listTools(), um die Tools aufzulisten, die dem angemeldeten Datenbankbenutzer gehören, oder SelectAIAgent.listTools(String toolNamePattern), um diese Liste nach Namensmuster zu filtern.
Toolparameter konfigurieren
ToolAttributes kann Implementierungen der ToolParams-Schnittstelle verwenden, um unterstützte integrierte Tools zu konfigurieren. Wählen Sie die Parameterklasse aus, die dem Tooltyp entspricht.
| Class | Zweck |
|---|---|
ToolParams |
Definiert die gemeinsame Schnittstelle für Konfigurationsparameter, die von integrierten Tools verwendet werden. |
RagToolParams |
Definiert Parameter für ein integriertes Retrieval-Augmented Generation-Tool. |
SlackNotificationToolParams |
Definiert Parameter für ein integriertes Slack-Benachrichtigungstool. |
EmailNotificationToolParams |
Definiert Parameter für ein integriertes E-Mail-Benachrichtigungstool. |
SqlToolParams |
Definiert Parameter für ein integriertes SQL-Tool. |
WebSearchToolParams |
Definiert Parameter für ein integriertes Web-Suchtool. |
GenericToolParams |
Definiert Parameter für Tools oder Parameterschemas, die das SDK nicht mit einer dedizierten Parameterklasse modelliert. |
Verwenden Sie den Builder, der von der entsprechenden Parameterklasse bereitgestellt wird. Die Datenbank validiert die Parameterwerte, wenn die Anwendung das Tool erstellt oder aktualisiert.
ToolInput stellt eine Eingabe dar, die im tool_inputs-Array eines Tools deklariert ist. Verwenden Sie Tool-Eingabemetadaten, um die Namen, Beschreibungen, Datentypen und andere unterstützte Informationen für die JSON-Payload zu bestimmen, die dem Tool bereitgestellt wird. Die Datenbank führt eine semantische Validierung der konfigurierten Eingabemetadaten durch.
Tool.run(String inputJson) gibt einen ToolRunResult zurück. Verwenden Sie das Ergebnisobjekt, um die Datenbankantwort aus der Toolausführung abzurufen. Informationen zu den Feldern und Accessor-Methoden finden Sie unter AI for Java API Reference (Javadoc) auswählen.
Mit den folgenden Tool-Methoden können Sie ein vorhandenes Datenbanktool verwalten:
| Methode | Zweck |
|---|---|
create() |
Erstellt ein Tool, das über die Erstellungsüberlastung konfiguriert wurde. |
enable() |
Aktiviert das Tool. |
disable() |
Deaktiviert das Tool. |
drop(boolean force) |
Entfernt das Tool. |
setAttribute(...) |
Aktualisiert ein unterstütztes Toolattribut. |
setAttributes(ToolAttributes toolAttributes) |
Aktualisiert mehrere unterstützte Toolattribute. |
describe() |
Gibt die datenbankgenerierte Tooldefinition und die Eingabemetadaten zurück. |
run(String inputJson) |
Führt das Tool mit einer JSON-Eingabe-Payload aus und gibt eine ToolRunResult zurück. |
getStatus() |
Ruft den aktuellen Toolstatus ab. |
getToolAttributes() |
Ruft die aktuellen Toolattribute ab. |
Rufen Sie Tool.describe() vor Tool.run(String inputJson) auf, wenn die Anwendung die datenbankdefinierten Eingabemetadaten benötigt. Geben Sie JSON an, die mit dem unterstützten Eingabeschema des Tools übereinstimmt. Die Datenbank validiert die Eingabe und führt den Toolvorgang aus.
Bevor Sie ein Tool ausführen, prüfen Sie, ob der Datenbankbenutzer auf die referenzierten Datenbankobjekte und externen Ressourcen zugreifen kann. Schützen Sie Werkzeugeingaben und -ergebnisse entsprechend den darin enthaltenen Daten.
Wenn die Anwendung eine datenbankgestützte Methode für ein Tool aufruft, das nicht erstellt oder geladen wurde, meldet das SDK IllegalStateException. Das SDK meldet Datenbank-, JDBC-, Autorisierungs- und Toolausführungsfehler über SelectAIException.
Informationen zu Toolattributen, Anforderungsformaten, Rückgabewerten und Ausnahmen finden Sie unter AI for Java API Reference (Javadoc) auswählen.
Mit Aufgaben arbeiten
Eine Aufgabe definiert Arbeit für einen Agent und kann die Tools identifizieren, die zum Abschließen dieser Arbeit verfügbar sind.
Rufen Sie für eine neue Aufgabe ein konfiguriertes Java-Handle ab, indem Sie:
SelectAIAgent.task(String taskName, TaskAttributes attributes, String description, TaskStatus status)
Diese Methode erstellt nur ein Java-Handle. Rufen Sie Task.create() auf, um die Datenbankaufgabe zu erstellen, bevor Sie andere datenbankgestützte Methoden aufrufen. TaskAttributes definiert die Aufgabenanweisungen, Tools, Eingaben und Human-Tool-Support.
Hinweis
Hinweis: Ein Human Tool ist ein datenbankdefiniertes Tool, mit dem ein Teamworkflow angehalten wird, sodass eine Person Informationen prüfen oder die zum Fortfahren erforderliche Eingabe angeben kann. Weitere Informationen zu Human Tools und angehaltenen Workflows finden Sie in der Dokumentation zur Auswahl von AI Agent.
Verwenden Sie für eine vorhandene Aufgabe SelectAIAgent.task(String taskName), um die Aufgabe nach Namen zu laden, bevor Sie Lebenszyklus- oder Attributmethoden aufrufen. Mit dieser Methode werden die Task-Metadaten und -Attribute aus der Datenbank geladen. Verwenden Sie SelectAIAgent.listTasks(), um Aufgaben aufzulisten, die dem verbundenen Benutzer gehören, oder SelectAIAgent.listTasks(String taskNamePattern), um Aufgaben nach Namensmuster zu filtern.
Verwenden Sie die folgenden Task-Methoden, um eine vorhandene Datenbankaufgabe zu verwalten:
| Methode | Zweck |
|---|---|
create() |
Erstellt eine Aufgabe, die über die Erstellungsüberlastung konfiguriert wurde. |
enable() |
Aktiviert die Aufgabe. |
disable() |
Deaktiviert die Aufgabe. |
drop(boolean force) |
Entfernt die Aufgabe. |
setAttribute(...) |
Aktualisiert ein unterstütztes Aufgabenattribut. |
setAttributes(TaskAttributes taskAttributes) |
Aktualisiert mehrere unterstützte Aufgabenattribute. |
getStatus() |
Ruft den aktuellen Aufgabenstatus ab. |
getTaskAttributes() |
Ruft die aktuellen Aufgabenattribute ab. |
Beim Erstellen einer Aufgabe wird sie nicht automatisch einem Agent oder Team zugeordnet. Definieren Sie diese Zuordnungen in den entsprechenden Agent- oder Teamattributen.
Wenn die Anwendung eine datenbankgestützte Methode für eine Aufgabe aufruft, die sie nicht erstellt oder geladen hat, meldet das SDK IllegalStateException. Das SDK meldet Fehler bei Datenbank, JDBC, Autorisierung und Aufgabenvorgängen über SelectAIException.
Aufgabenattribute, Lebenszyklusvorgänge und unterstützte Anforderungsmodelle finden Sie in der KI für Java-API-Referenz auswählen.
Mit Agents arbeiten
Ein Agent stellt einen datenbankdefinierten AI-Agent dar. Erstellen oder laden Sie einen Agent, konfigurieren Sie seine Attribute und das zugehörige Profil, und verknüpfen Sie ihn mit den Aufgaben, die für den Workflow erforderlich sind.
So konfigurieren Sie einen neuen Agent:
SelectAIAgent.agent(String agentName, AgentAttributes attributes, String description, AgentStatus status)
Diese Methode erstellt nur ein Java-Handle. Rufen Sie Agent.create() auf, um den Datenbank-Agent zu erstellen. AgentAttributes definiert die Agent-Konfiguration, einschließlich Profil, Rolle, Tools, Arbeitsspeicher, Human-Tool-Support und Supervisor-Konfiguration.
Die Supervisor-Konfiguration definiert, wie ein Agent oder Team eine Supervisor-Rolle verwendet. Bei einem Agent konfiguriert er das Supervisor-Verhalten des Agent. Für ein Team identifiziert und konfiguriert es die Vorgesetztenrolle, die Arbeit zwischen den Agents und Aufgaben des Teams koordiniert.
Verwenden Sie für einen vorhandenen Agent SelectAIAgent.agent(String agentName), um den Agent nach Namen zu laden, bevor Sie Lebenszyklus- oder Attributmethoden aufrufen. Mit dieser Methode werden die Agent-Metadaten und -Attribute aus der Datenbank geladen. Verwenden Sie SelectAIAgent.listAgents(), um Agents aufzulisten, deren Eigentümer der angemeldete Datenbankbenutzer ist, oder verwenden Sie SelectAIAgent.listAgents(String agentNamePattern), um Agents nach Namensmuster zu filtern.
Verwenden Sie die folgenden Agent-Methoden, um einen vorhandenen Datenbank-Agent zu verwalten:
| Methode | Zweck |
|---|---|
create() |
Erstellt einen Agent, der über die Erstellungsüberlastung konfiguriert wurde. |
enable() |
Aktiviert den Agent. |
disable() |
Deaktiviert den Agent. |
drop(boolean force) |
Entfernt den Agent. |
setAttribute(...) |
Aktualisiert ein unterstütztes Agent-Attribut. |
setAttributes(AgentAttributes attributes) |
Aktualisiert mehrere unterstützte Agent-Attribute. |
getStatus() |
Ruft den aktuellen Agent-Status ab. |
getAgentAttributes() |
Ruft die aktuellen Agent-Attribute ab. |
Eine Agent-Ressource stellt eine datenbankdefinierte Agent-Konfiguration dar. Führen Sie einen Agent als Teil eines Teamworkflows mithilfe der Team-APIs aus. Die Agent-API bietet keine separate direkte Agent-Ausführungsmethode.
Wenn die Anwendung eine datenbankgestützte Methode für einen Agent aufruft, den sie nicht erstellt oder geladen hat, meldet das SDK IllegalStateException. Das SDK meldet Fehler bei Datenbank-, JDBC-, Autorisierungs- und Agent-Vorgängen über SelectAIException.
Informationen zu Agent-Konfiguration, Statuswerten, Lebenszyklusvorgängen und Anforderungsmodellen sowie Beispielen finden Sie unter AI for Java API Reference (Javadoc) auswählen und einem Beispiel für Supervisor-Agent
Mitarbeiterteams verwalten
Ein Team koordiniert Agents und Aufgaben, um einen Workflow auszuführen. Erstellen oder laden Sie ein Team, konfigurieren Sie seine Attribute und Aufgabenzuweisungen, und führen Sie es mit einer Anforderung aus, die den Prompt und alle unterstützten Laufzeitwerte bereitstellt.
Verwenden Sie SelectAIAgent.team(String teamName), um ein Team zu laden, das dem angemeldeten Datenbankbenutzer gehört. Verwenden Sie SelectAIAgent.listTeams(), um eigene Teams aufzulisten, oder SelectAIAgent.listTeams(String teamNamePattern), um Teams nach Namensmuster zu filtern.
So konfigurieren Sie ein neues Team:
SelectAIAgent.team(String teamName, TeamAttributes attributes, String description, TeamStatus status)
Diese Methode erstellt nur ein Java-Handle. Rufen Sie Team.create() auf, um das Datenbankteam zu erstellen. TeamAttributes definiert Agent-zu-Task-Zuordnungen, Prozess-, Speicher- und Supervisor-Konfiguration. Die Datenbank führt den Workflow aus und gibt das Ergebnis über die Java-API zurück. Die Teamausführung kann Zeit in Anspruch nehmen, während die Datenbank Tools ausführt und mit konfigurierten KI-Providern kommuniziert.
Mit den folgenden Team-Methoden können Sie ein Team verwalten und ausführen, dessen Eigentümer der verbundene Benutzer ist:
| Methode | Zweck |
|---|---|
create() |
Erstellt ein Team, das durch die Erstellungsüberlastung konfiguriert wurde. |
enable() |
Aktiviert das Team. |
disable() |
Deaktiviert das Team. |
drop(boolean force) |
Entfernt das Team. |
setAttribute(...) |
Aktualisiert ein unterstütztes Teamattribut. |
setAttributes(TeamAttributes teamAttributes) |
Aktualisiert mehrere unterstützte Teamattribute. |
run(RunTeamRequest request) |
Startet oder setzt eine Teamausführung fort und gibt eine TeamRunResult zurück. |
describe() |
Gibt eine TeamDescription zurück, die eine datenbankgenerierte Teamdefinition und aggregierte Funktionen enthält. |
getStateByConversationId(String conversationId) |
Ruft den aktuellen Ausführungsstatus für den Teamworkflow ab, der mit der angegebenen Unterhaltungs-ID verknüpft ist. |
setExecutionState(ExecutionStateRequest request) |
Aktualisiert den Status eines Teams, das auf menschliche Eingaben wartet. |
exportDefinition(String paramsJson) |
Gibt die exportierte Teamdefinition als JSON zurück. |
exportDefinition(ExportTeamRequest request) |
Exportiert die Teamdefinition in Object Storage oder ein Datenbankverzeichnis. |
getStatus() |
Ruft den aktuellen Teamstatus ab. |
getTeamAttributes() |
Ruft die aktuellen Teamattribute ab. |
Teamlauf konfigurieren
RunTeamRequest gibt die Eingabe für Team.run(RunTeamRequest request) und SelectAIAgent.runTeam(String teamName, RunTeamRequest request) an. Verwenden Sie die Anforderung, um die Benutzereingabeaufforderung und optionale Laufzeitparameter anzugeben.
RunTeamParams stellt die eingegebenen Laufzeitparameter dar, die der vom Datenbankteam ausgeführte Vorgang akzeptiert. Verwenden Sie den Builder, um unterstützte Laufzeitwerte zu konfigurieren, anstatt das entsprechende JSON-Parameterobjekt direkt zu erstellen.
Ein Teamlauf gibt eine TeamRunResult zurück. Das Ergebnis behält die Antwort, die von der Datenbank zurückgegeben wird, und die Informationen, die zur Identifizierung der zugehörigen Unterhaltung erforderlich sind. Behalten Sie die Konversations-ID bei, wenn eine spätere Anforderung denselben Workflow fortsetzen oder den letzten Ausführungsstatus abrufen muss.
Unterhaltungen und Workflowstatus
Mit Team.getStateByConversationId(String conversationId) können Sie den letzten Ausführungsstatus für eine Unterhaltung abrufen, die einem geladenen Team zugeordnet ist. Alternativ können Sie SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId) verwenden, um den Status nach Teamname abzurufen, ohne zuerst ein Team-Handle zu laden.
Beide Methoden geben eine TeamExecutionState zurück. Diese Enumeration stellt die Teamausführungsstatus dar, die von der Datenbank unterstützt werden, und behält den Datenbankstatuswert bei.
Wenn ein Team für menschliche Eingaben pausiert, geben Sie mit Team.setExecutionState(ExecutionStateRequest request) oder SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request) den nächsten Status an, der von der Datenbank zugelassen wird.
ExecutionStateRequest gibt den neuen Status und die zu aktualisierende Teamunterhaltung an. ExecutionStateParams stellt eingegebene Parameter für den Statusaktualisierungsvorgang bereit. Verwenden Sie ExecutionStateRequest.Builder.params(ExecutionStateParams), um das eingegebene Parameterobjekt anzugeben. Verwenden Sie für den allgemeinen Fall ExecutionStateRequest.Builder.conversationId(String conversationId), um die Unterhaltungs-ID direkt festzulegen.
| Class | Zweck |
|---|---|
TeamExecutionState |
Stellt einen Teamausführungsstatus dar, der von der Datenbank zurückgegeben wird. |
ExecutionStateRequest |
Definiert eine Anforderung zum Aktualisieren des Status einer wartenden Teamausführung. |
ExecutionStateParams |
Definiert eingegebene Parameter für den Statusaktualisierungsvorgang, einschließlich der Unterhaltungs-ID. |
Behalten Sie die von der Datenbank erstellte Konversations-ID bei, und verwenden Sie dieselbe ID für die anfängliche Teamausführung, den späteren Statusabruf und alle Anforderungen, die den Workflow fortsetzen.
Unterstützte Statusnamen, Anforderungswerte, Rückgabewerte und Vorgangsverhalten sowie ein Beispiel finden Sie unter Select AI for Java API Reference (Javadoc) und Example getTeamStateByConversationId
Workflows mit Unterhaltungs-IDs fortsetzen
Verwenden Sie eine RunTeamRequest, um einen Teamworkflow zu starten oder fortzusetzen. Legen Sie die von der Datenbank erstellte Unterhaltungs-ID mit RunTeamRequest.builder().conversationId(conversationId) fest.
Erstellen Sie eine Unterhaltung über die SelectAI-Core-API. Die Methode Conversation.create() gibt die datenbankgenerierte Unterhaltungs-ID zurück:
Conversation conversation = selectAI.conversation(
ConversationAttributes.builder()
.title("Customer support workflow")
.build());
String conversationId = conversation.create();Dieselbe ID ist später über conversation.getConversationId() verfügbar. Öffnen Sie eine vorhandene Unterhaltung mit SelectAI.conversation(conversationId), und rufen Sie die ID mit getConversationId() ab.
Übergeben Sie die ID an den Teamlauf:
RunTeamRequest request = RunTeamRequest.builder()
.userPrompt("Review the customer request")
.conversationId(conversationId)
.build();
TeamRunResult result = selectAIAgent.runTeam(teamName, request);Behalten Sie für eine zustandslose Anwendung oder eine Anwendung, die JDBC-Pools verwendet, diese Unterhaltungs-ID bei, und geben Sie dieselbe ID in jedem späteren RunTeamRequest an. Die ID behält den Kontext der Teamausführung über separate Anwendungsanforderungen und JDBC-Verbindungen hinweg bei. Informationen zum Wiederverwenden einer conversation_id zum Fortsetzen eines unterbrochenen Teamworkflows finden Sie unter DBMS_CLOUD_AI_AGENT Package.
Verwenden Sie dieselbe ID für spätere Statusvorgänge, wie getStateByConversationId(conversationId), und wenn Sie einen Workflow fortsetzen, der auf eine menschliche Eingabe wartet. Ersetzen Sie die datenbankgenerierte ID nicht durch einen neuen vom Client generierten Wert.
Mit einer der folgenden Methoden können Sie einen Workflow starten oder fortsetzen:
| Methode | Verwendung |
|---|---|
Team.run(RunTeamRequest request) |
Startet oder setzt einen Workflow für ein geladenes Team fort, das dem angemeldeten Datenbankbenutzer gehört. |
SelectAIAgent.runTeam(String teamName, RunTeamRequest request) |
Startet oder setzt ein Team fort, das nach Namen ausgeführt wird, und gibt eine TeamRunResult zurück. Mit dieser Methode können Sie ein freigegebenes Team nach dem vom Verantwortlichen qualifizierten Namen ausführen. |
Koordinieren Sie Anforderungen, die dieselbe Unterhaltung verwenden. Verschieben Sie eine Unterhaltung nicht gleichzeitig aus mehreren Anwendungsthreads, es sei denn, die Anwendung synchronisiert diese Anforderungen. Hintergrundprozesse können zu widersprüchlichen Statusänderungen führen oder dazu führen, dass die Datenbank die spätere Anforderung ablehnt.
Mit Team.getStateByConversationId(String conversationId) können Sie den letzten Ausführungsstatus für eine Unterhaltung abrufen, die einem geladenen Team zugeordnet ist.
Mit Team.getStateByConversationId(String conversationId) können Sie den letzten Ausführungsstatus für eine Unterhaltung abrufen, die einem geladenen Team zugeordnet ist. Alternativ können Sie SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId) verwenden, um den letzten Status nach Teamname abzurufen. Beide Methoden geben eine TeamExecutionState zurück.
Beide Methoden geben eine TeamExecutionState zurück. Übergeben Sie dieselbe von der Datenbank erstellte Unterhaltungs-ID, mit der die Anwendung die Teamausführung gestartet oder fortgesetzt hat. Diese Methoden akzeptieren die Unterhaltungs-ID direkt. Die Anwendung muss keine Payload für JSON-Laufzeitparameter erstellen.
Wenn ein Teamworkflow auf menschliche Eingaben wartet, geben Sie mit Team.setExecutionState(ExecutionStateRequest request) oder SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request) den nächsten Ausführungsstatus an. Die Datenbank validiert den angeforderten Statusübergang und den Konversationskontext.
Wenn eine spätere Anforderung die erforderliche Unterhaltungs-ID auslässt, kann die Datenbank fehlenden Unterhaltungskontext über SelectAIException melden, wie ORA-20053. Rufen Sie nach einem Timeout oder einem Verbindungsfehler den Teamstatus ab, bevor Sie eine weitere Anforderung senden. Ein JDBC-Timeout garantiert nicht, dass die datenbankseitige oder providerseitige Verarbeitung gestoppt wurde.
Geteilte Teams
Ein Datenbankbenutzer kann ein Team ausführen, das einem anderen Datenbankbenutzer gehört, wenn der Eigentümer Zugriff über die Datenbank erteilt. Verwenden Sie den vom Verantwortlichen qualifizierten Teamnamen, wenn Sie das gemeinsame Team ausführen.
Die Datenbank erzwingt die Teamberechtigung und Berechtigungen für die Ressourcen, die das Team verwendet. Bei der Unterstützung von gemeinsam genutzten Teams kann die Java-Anwendung die Ressourcen des Eigentümers nicht verwalten oder die Datenbankautorisierung umgehen.
Ein freigegebenes Team gehört zu einem anderen Datenbankbenutzer. Sie können ein freigegebenes Team nicht über SelectAIAgent.team(String teamName) laden oder über listTeams() finden.
Geteiltes Team führen mit:
SelectAIAgent.runTeam(String teamName, RunTeamRequest request)
Geben Sie den vom Verantwortlichen qualifizierten Teamnamen an, der für die Datenbankberechtigung erforderlich ist. Verwenden Sie SelectAIAgent.getTeamStateByConversationId(String teamName, String conversationId), um den letzten Ausführungsstatus abzurufen, und SelectAIAgent.setTeamExecutionState(String teamName, ExecutionStateRequest request), um einen Status für die Warteausführung zu aktualisieren.
Die Datenbank erzwingt den Zugriff auf freigegebene Teams. Die Berechtigung lässt nur die Ausführung zu. Der verbundene Benutzer kann das Team des Verantwortlichen nicht aktualisieren, exportieren, deaktivieren oder löschen.
Team importieren und exportieren
Exportieren Sie eine Teamdefinition, um eine Teamkonfiguration beizubehalten oder zu verschieben. Importieren Sie eine Teamdefinition, um die entsprechenden Datenbankressourcen in einer anderen Umgebung zu erstellen.
Das Select AI Agent Framework unterstützt auch das Abrufen kanonischer Definitionen für Agent Framework-Ressourcen. Prüfen Sie die Definition und referenzierte Ressourcen, bevor Sie sie importieren. Der importierende Datenbankbenutzer muss über die erforderlichen Berechtigungen verfügen, um die Ressourcen zu erstellen und auf ihre Abhängigkeiten zuzugreifen.
Verwenden Sie die folgenden Methoden für datenbankgenerierte Definitionen und Teamimport:
| Methode | Zweck |
|---|---|
Team.exportDefinition() |
Gibt die geladene Teamdefinition mit den Datenbankstandardwerten als JSON zurück. |
Team.exportDefinition(ExportTeamParams params) |
Gibt die geladene Teamdefinition mit eingegebenen Exportparametern als JSON zurück. |
Team.exportDefinition(ExportTeamRequest request) |
Exportiert die geladene Teamdefinition in Object Storage oder ein Datenbankverzeichnis. |
SelectAIAgent.getDefinition(AgentObjectType objectType, String objectName, boolean includeDependentObjects) |
Ruft die kanonische Datenbankdefinition eines Agent, einer Aufgabe, eines Tools oder eines Teams ab. |
SelectAIAgent.importTeam(ImportTeamRequest request) |
Importiert eine Teamdefinition und die zugehörigen Ressourcen in die Datenbank. |
ExportTeamParams stellt eingegebene Parameter bereit, wenn die Anwendung eine exportierte Teamdefinition als JSON zurückgibt. Die Klasse unterstützt derzeit das optionale Feld overwrite. Übergeben Sie null an Team.exportDefinition(ExportTeamParams params), um die Datenbankstandardwerte zu verwenden.
ExportTeamRequest gibt eine Object Storage-URI oder ein Datenbankverzeichnisziel für einen Export an. Sie kann ExportTeamParams für die typisierten Exportoptionen enthalten, die von der Datenbank unterstützt werden.
Prüfen Sie die exportierten oder abgerufenen Definitionen, bevor Sie sie in eine andere Umgebung importieren. Stellen Sie sicher, dass die erforderlichen Ressourcen, Berechtigungen, Profile, Zugangsdaten und Datenbankfunktionen in der Zielumgebung vorhanden sind.
Informationen zu Anforderungsformaten, Definitionsinhalten, Exportzielen und Importverhalten finden Sie unter AI für Java-API-Referenz (Javadoc) auswählen.
Vorhandene Objekte abrufen, aktualisieren und löschen
Agents, Aufgaben, Tools und Teams laden oder auflisten, die dem angemeldeten Datenbankbenutzer gehören. Ruft Status und Attribute ab, wenn die Anwendung aktuelle Ressourceninformationen benötigt.
Aktualisieren Sie nur Attribute, die von der Ressourcen-API unterstützt werden. Bevor Sie eine Ressource löschen, prüfen Sie, ob eine Aufgabe, ein Agent oder ein Team davon abhängt. Die Datenbank erzwingt die Berechtigungen, die zum Abrufen, Aktualisieren und Entfernen erforderlich sind.
Mit SelectAIAgent können Sie Agent-Framework-Ressourcen laden oder auflisten, deren Eigentümer der angemeldete Datenbankbenutzer ist.
| Ressource | Eine Ressource laden | Ressourcen auflisten |
|---|---|---|
| Agent | SelectAIAgent.agent(String agentName) |
SelectAIAgent.listAgents() oder SelectAIAgent.listAgents(String agentNamePattern) |
| Aufgabe | SelectAIAgent.task(String taskName) |
SelectAIAgent.listTasks() oder SelectAIAgent.listTasks(String taskNamePattern) |
| Tool | SelectAIAgent.tool(String toolName) |
SelectAIAgent.listTools() oder SelectAIAgent.listTools(String toolNamePattern) |
| Team | SelectAIAgent.team(String teamName) |
SelectAIAgent.listTeams() oder SelectAIAgent.listTeams(String teamNamePattern) |
Die Nur-Name-Lademethoden rufen die Ressourcenmetadaten und Attribute aus der Datenbank ab. Die Listenmethoden geben Ressourcen zurück, die dem angemeldeten Datenbankbenutzer gehören. Ein freigegebenes Team, das einem anderen Benutzer gehört, wird nicht von listTeams() zurückgegeben und kann nicht mit team(String teamName) geladen werden. Verwenden Sie SelectAIAgent.runTeam(String teamName, RunTeamRequest request) mit dem erforderlichen vom Verantwortlichen qualifizierten Teamnamen, um ein gemeinsames Team auszuführen.
Ressourceninformationen abrufen
Verwenden Sie die Resource Getter-Methoden, wenn die Anwendung aktuelle Datenbankinformationen benötigt.
| Ressource | Ressourcenname | Beschreibung | Status | Attribute |
|---|---|---|---|---|
| Agent | getAgentName() |
getDescription() |
getStatus() |
getAgentAttributes() |
| Aufgabe | getTaskName() |
getDescription() |
getStatus() |
getTaskAttributes() |
| Tool | getToolName() |
getDescription() |
getStatus() |
getToolAttributes() |
| Team | getTeamName() |
getDescription() |
getStatus() |
getTeamAttributes() |
Bei datenbankgestützten Ressourcen rufen getStatus() und der Attribut-Getter aktuelle Informationen aus der Datenbank ab. Die Name- und Beschreibungs-Getter geben die Ressourcenmetadaten zurück, die für das Java-Objekt verfügbar sind.
Ressourcenattribute aktualisieren
Verwenden Sie die Methoden setAttribute(...), um ein unterstütztes Attribut zu aktualisieren, oder verwenden Sie setAttributes(...), um mehrere unterstützte Attribute zu aktualisieren.
| Ressource | Ein Attribut aktualisieren | Mehrere Attribute aktualisieren |
|---|---|---|
| Agent | Agent.setAttribute(...) |
Agent.setAttributes(AgentAttributes attributes) |
| Aufgabe | Task.setAttribute(...) |
Task.setAttributes(TaskAttributes attributes) |
| Tool | Tool.setAttribute(...) |
Tool.setAttributes(ToolAttributes attributes) |
| Team | Team.setAttribute(...) |
Team.setAttributes(TeamAttributes attributes) |
Die setAttribute(...)-Methoden unterstützen die dokumentierten Zeichenfolgen-, booleschen, ganzzahligen und Gleitkommaattributwerte. Die Datenbank bestimmt, ob sich ein Attribut nach der Ressourcenerstellung ändern kann. Rufen Sie die aktuellen Attribute ab, bevor Sie eine Aktualisierung vornehmen, wenn die Anwendung die vorhandene Konfiguration beibehalten muss.
Mit enable() und disable() können Sie den Ressourcenstatus ändern:
| Ressource | Aktivieren | Deaktivieren |
|---|---|---|
| Agent | Agent.enable() |
Agent.disable() |
| Aufgabe | Task.enable() |
Task.disable() |
| Tool | Tool.enable() |
Tool.disable() |
| Team | Team.enable() |
Team.disable() |
Eine Ressource muss erstellt oder geladen werden, bevor die Anwendung ihre Attribute oder ihren Status aktualisiert. Andernfalls meldet das SDK IllegalStateException. Ungültige Argumente führen zu IllegalArgumentException. Datenbankvalidierungs-, Autorisierungs- und JDBC-Fehler führen zu SelectAIException.
Ressourcen entfernen
Mit drop(boolean force) können Sie eine Datenbankressource entfernen.
| Ressource | Methode löschen |
|---|---|
| Agent | Agent.drop(boolean force) |
| Aufgabe | Task.drop(boolean force) |
| Tool | Tool.drop(boolean force) |
| Team | Team.drop(boolean force) |
Bevor Sie eine Ressource löschen, stellen Sie sicher, dass keine Aufgaben-, Agent-, Tool- oder Teamdefinition davon abhängt. Das Entfernen einer Ressource kann dazu führen, dass ein späterer Teamworkflow nicht erfolgreich verläuft. Verwenden Sie force nur, wenn die Anwendung eine bereits abwesende Ressource sicher als den beabsichtigten endgültigen Status behandeln kann. force steuert, wie das SDK eine fehlende Ressource behandelt. Wenn force false ist, verläuft der Vorgang drop nicht erfolgreich, wenn die Ressource nicht vorhanden ist. Wenn force true ist, ignoriert das SDK den Fehler "feast-resource" und schließt den Vorgang erfolgreich ab. Das Kennzeichen umgeht die Autorisierung nicht, blendet nicht zugehörige Datenbankfehler aus oder löscht abhängige Ressourcen nicht.
Die Datenbank erzwingt die Berechtigungen, die zum Abrufen, Aktualisieren, Aktivieren, Deaktivieren und Entfernen von Ressourcen erforderlich sind. Informationen zu ressourcenspezifischen Lebenszyklusmethoden, unterstützten Attributen, Rückgabewerten und Ausnahmen finden Sie in der AI für Java-API-Referenz auswählen.
Objektspezifische Lebenszyklusmethoden und Rückgabewerte finden Sie unter AI für Java-API-Referenz auswählen.
Verbindungen, Nebenläufigkeit, Transaktionen und Timeouts
Select AI for Java unterstützt SDK-verwaltete und anwendungsverwaltete JDBC-Verbindungen für Agent-Vorgänge. Wählen Sie einen Verbindungsmodus basierend auf Ressourcenverantwortung und Nebenläufigkeitsanforderungen, koordinieren Sie Anforderungen, die dieselbe Teamunterhaltung verwenden, und berücksichtigen Sie das Transaktionsverhalten, die Nutzung von Verbindungspools und Timeouts bei Tools mit langer Ausführungszeit und Teamvorgängen.
Verbindung zu Autonomous AI Database
Verbindungsmodi, DbConnectionConfig, DataSource und allgemeine JDBC-Verbindungsverwaltung finden Sie unter Verbindung zu autonomer KI-Datenbank herstellen.
Das folgende Agent-spezifische Verhalten gilt für diese Verbindungsmodi.
DbConnectionConfig
Mit DbConnectionConfig erstellt und besitzt das SDK eine JDBC-Verbindung für den SelectAIAgent-Client. Der Client verwendet diese Verbindung für Agent-Vorgänge wieder und schließt sie, wenn die Anwendung den Client schließt.
Behandeln Sie einen auf diese Weise erstellten Client als Single-Threaded, es sei denn, die Anwendung synchronisiert den Zugriff. SelectAIAgent stellt die beibehaltene Verbindung nicht für benutzerdefinierte JDBC-Arbeiten bereit. Verwenden Sie eine anwendungsverwaltete DataSource, wenn die Anwendung Agent-Vorgänge benötigt und benutzerdefinierte JDBC über dieselbe Infrastruktur für das Verbindungsmanagement funktioniert.
DataSource
Im Modus DataSource ruft das SDK eine Verbindung für jeden öffentlichen Vorgang ab und gibt sie zurück, wenn dieser Vorgang abgeschlossen ist. Die Anwendung ist weiterhin Eigentümer der DataSource.
Ein Teamlauf mit langer Ausführungszeit kann eine ausgeliehene Verbindung speichern, bis der Vorgang zurückkehrt. Berücksichtigen Sie die erwartete Dauer von Teamworkflows bei der Konfiguration von Poolkapazität und Anweisungs-Timeouts.
Verbindungslebenszyklus und Threading
Schließen Sie den SelectAIAgent-Client, wenn die Anwendung ihn nicht mehr benötigt. Wenn Sie den Client im DbConnectionConfig-Modus schließen, wird die SDK-eigene Verbindung freigegeben. Im Modus DataSource schließt das Schließen des Clients nicht das anwendungseigene DataSource.
Verwenden Sie für nebenläufige unabhängige Vorgänge den Modus DataSource. Ändern oder führen Sie nicht gleichzeitig zustandsverändernde Vorgänge für dasselbe Objekt Agent, Task, Tool oder Team aus, es sei denn, die Anwendung synchronisiert den Zugriff. Wenn mehrere Anforderungen mit derselben Teamunterhaltung arbeiten, koordinieren Sie diese Anforderungen, damit sie die Unterhaltung nicht gleichzeitig vorantreiben.
Datenbankautorisierung und Ressourcenberechtigungen gelten weiterhin für gemeinsame Teams, unabhängig von der Java-Verbindung oder dem Threading-Modell.
Transaktions- und Timeoutverhalten
Das SDK schreibt Agent-, Aufgaben-, Tool- oder Teamvorgänge nicht explizit fest oder setzt sie zurück, und die Einstellung autoCommit der JDBC-Verbindung wird nicht geändert. Das Transaktionsverhalten hängt von der Verbindungskonfiguration und den vom Vorgang verwendeten Datenbank-APIs ab. Die Datenbank kann Transaktionsaktionen ausführen, die vom SDK nicht kontrolliert werden.
Wiederholen Sie einen Statusänderungsvorgang nicht automatisch nach einem Timeout. Datenbank- oder anbieterseitige Arbeiten werden möglicherweise noch ausgeführt.
Fehler und Sicherheit verarbeiten
Das SDK meldet Validierungs- und Datenbankfehler über das Java-Ausnahmemodell, einschließlich SelectAIException für Datenbank- und Vorgangsfehler. Fehler behandeln, je nachdem, ob der Vorgang den Datenbankstatus ändert.
Eine Teamausführung kann eine JDBC-Verbindung belegen, bis sie zurückkehrt. Konfigurieren Sie Connection Pools und Anweisungs-Timeouts für die erwartete Workload. Ein Timeout garantiert nicht, dass die datenbank- oder anbieterseitige Verarbeitung gestoppt wurde.
Oracle empfiehlt, dass Sie nach einem Timeout keine zustandsverändernden Agent-, Aufgaben-, Tool- oder Teamvorgänge automatisch wiederholen. Prüfen Sie die Datenbankressource oder den Workflowstatus, bevor Sie entscheiden, ob ein erneuter Versuch möglich ist. Loggen Sie keine Zugangsdaten, Private Keys, Prompts, Tool-Eingaben, generierten Ergebnisse oder vollständigen Agent-Attribut-Payloads.
SDK-Ausnahmen verarbeiten
Das SDK verwendet die folgenden Ausnahmen für allgemeine Fehlerbedingungen:
| Ausnahme | Wenn es passiert |
|---|---|
IllegalArgumentException |
Die Anwendung stellt ein ungültiges Argument oder eine ungültige Anforderung bereit. Beispiele: Null- oder leerer Agent, Aufgabe, Tool oder Teamname, Null-Anforderung oder ungültiger Anforderungswert. Das SDK erkennt diese Fehler, wenn möglich, vor der JDBC-Verarbeitung. |
IllegalStateException |
Die Anwendung ruft einen Vorgang auf, wenn die SDK-Ressource nicht den erforderlichen Lebenszyklusstatus aufweist. Beispiel: Die Anwendung versucht einen ressourcenspezifischen Vorgang, bevor sie die Ressource erstellt oder lädt. |
SelectAIException |
JDBC oder die Datenbank meldet einen Fehler während eines Agent-, Task-, Tool-, Team-, Ausführungsstatus-, Import- oder Exportvorgangs. Dazu gehören Datenbankvalidierungs-, Berechtigungs-, Ressourcen-Lookup-, Workflow- und andere DBMS_CLOUD_AI_AGENT-Fehler. |
Weitere Informationen finden Sie unter Fehler behandeln.
Ausnahmedetails und das betriebsspezifische Verhalten finden Sie unter AI for Java API Reference (Javadoc) auswählen.
Nicht erfolgreiche Vorgänge wiederholen
Das SDK wiederholt nicht erfolgreiche Agent-Vorgänge nicht automatisch. Wiederholen Sie nicht automatisch die Erstellung, Aktualisierung, Löschung, Administration, Toolausführungen, Teamausführungen, Laufzeitänderungen oder Definitionsimporte. Möglicherweise hat die Datenbank die Verarbeitung gestartet, bevor die Anwendung einen Fehler erhalten hat.
Rufen Sie nach einem Timeout oder Verbindungsfehler den Ressourcen- oder Teamausführungsstatus ab, bevor Sie entscheiden, ob der Vorgang wiederholt werden soll. Ein JDBC-Timeout garantiert nicht, dass die datenbank- oder anbieterseitige Arbeit gestoppt wurde. Wiederholen Sie den Vorgang erst, nachdem Sie festgestellt haben, dass die Wiederholung sicher ist.
Agent-Fehler beheben
Wenn ein Agent-Vorgang nicht erfolgreich verläuft:
- Prüfen Sie für
IllegalArgumentExceptiondie erforderlichen Namen, Anforderungsobjekte und Attributwerte. - Bestätigen Sie für
IllegalStateException, dass die Anwendung die Ressource erstellt oder geladen hat, bevor Sie den Vorgang aufrufen. - Unter
SelectAIExceptionprüfen Sie die Meldung, den Oracle-Fehlercode, den SQL-Status und die zugrunde liegende Ursache, wenn verfügbar. - Vergewissern Sie sich, dass der angemeldete Datenbankbenutzer über die erforderlichen Packageberechtigungen und den erforderlichen Zugriff auf die angeforderte Ressource verfügt.
- Bestätigen Sie bei Vorgängen mit gemeinsamem Team, dass die Datenbank dem angemeldeten Benutzer Zugriff erteilt hat und dass die Anforderung den erforderlichen vom Eigentümer qualifizierten Teamnamen verwendet.
- Bestätigen Sie für die Teamausführung, dass in der Anforderung die Unterhaltungs-ID angegeben ist, die zum Starten oder Fortsetzen des Workflows erforderlich ist.
- Bei Import- oder Exportfehlern prüfen Sie die Definition, die Unterstützung der Zieldatenbank und die Berechtigungen des angemeldeten Benutzers.
Methodenspezifische Ausnahmedeklarationen und Details finden Sie unter AI für Java-API-Referenz auswählen.
Sensible Daten schützen
Nehmen Sie keine Datenbank- oder Mitarbeiterzugangsdaten, Private Keys, Zugriffstoken, vollständigen Zugangsdatenkonfigurationen, sensiblen Prompts, Unterhaltungshistorie oder generierten Ergebnisse in Protokollen oder Diagnoseberichten auf. Notieren Sie nur die Details zum sicheren Fehler, die zur Fehlerbehebung erforderlich sind.
Das Java-SDK kommuniziert über JDBC mit der Datenbank. Wenn ein Datenbankvorgang einen AI-Provider oder Objektspeicher erfordert, stellt die Datenbank die ausgehende Verbindung entsprechend ihrer Konfiguration her. Prüfen Sie die datenbankseitige Providerkonfiguration, den Netzwerkzugriff und die KI-Datenzugriffskontrollen "Select AI", bevor Sie den Workflow aktivieren.