Package DBMS_CLOUD_AI_AGENT

Questo package definisce e gestisce gli agenti, i task, gli strumenti e l'orchestrazione Select AI.

Nota: il supporto per il package DBMS_CLOUD_AI_AGENT è disponibile in Oracle Database 19c a partire dalla versione 19.29 e in Oracle Database 26ai a partire dalla versione 23.26.

Riepilogo dei sottoprogrammi DBMS_CLOUD_AI_AGENT

In questa sezione vengono descritti i programmi secondari DBMS_CLOUD_AI_AGENT di Select AI Agent forniti con Autonomous AI Database.

Sottoprogramma	Descrizione
Procedura CREATE_AGENT	Questa procedura crea un agente.
Attributi CREATE_AGENT	Fornisce gli attributi per la creazione di un agente.
Procedura ENABLE_AGENT	Questa procedura abilita un agente.
Procedura DISABLE_AGENT	Questa procedura disabilita un agente.
Procedura DROP_AGENT	Questa procedura elimina un agente esistente.
Procedura CREATE_TASK	Questa procedura crea un task che un agente e un team agente possono includere.
Attributi CREATE_TASK	Fornisce gli attributi per la creazione di un task agente.
Procedura ENABLE_TASK	Questa procedura abilita un task agente.
Procedura DISABLE_TASK	Questa procedura disabilita un task agente.
Procedura DROP_TASK	Questa procedura elimina un task agente esistente.
Procedura CREATE_TOOL	Questa procedura crea strumenti personalizzati che possono essere inclusi da un agente.
Attributi CREATE_TOOL	Fornisce gli attributi per la creazione degli strumenti.
Procedura ENABLE_TOOL	Questa procedura abilita uno strumento registrato.
Procedura DISABLE_TOOL	Questa procedura disabilita uno strumento registrato.
Procedura DROP_TOOL	Questa procedura comporta l'eliminazione di uno strumento esistente.
Procedura CREATE_TEAM	Questa procedura crea un team agente e include agenti e task.
Attributi CREATE_TEAM	Fornisce gli attributi per la creazione di un team agente.
Funzione SET_TEAM	Questa procedura imposta il team agente nella sessione corrente.
Funzione GET_TEAM	Questa procedura restituisce il team agente impostato nella sessione corrente.
Funzione CLEAR_TEAM	Questa procedura cancella il team agente impostato nella sessione corrente.
Funzione RUN_TEAM	Questa procedura crea un nuovo agente o ne esegue uno in pausa.
Procedura ENABLE_TEAM	Questa procedura abilita un team agente.
Procedura DISABLE_TEAM	Questa procedura disabilita un team agente.
Procedura DROP_TEAM	Questa procedura elimina un team agente esistente.
Funzione DESCRIBE_TOOL	Restituisce i metadati e le informazioni sullo schema di input per uno strumento Seleziona agente AI.
Funzione RUN_TOOL	Chiama uno strumento Seleziona agente AI per nome utilizzando un payload di input JSON.
Funzione LIST_TEAMS	Elenca i team agente disponibili per l'utente chiamante.
Funzione DESCRIBE_TEAM	Restituisce i metadati e le funzionalità aggregate per un team agente selezionato.
Funzione GET_TEAM_STATE	Restituisce lo stato di esecuzione più recente per una conversazione del team agente.
Procedura SET_EXECUTION_STATE	Aggiorna lo stato di esecuzione di un team in attesa, ad esempio contrassegnando una sessione interattiva come riuscita.

Procedura CREATE_AGENT

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.CREATE_AGENT per registrare un nuovo agente AI nel framework Seleziona agente AI. Definire l'identità dell'agente utilizzando agent_name, configurarne il funzionamento con il parametro attributi e, facoltativamente, fornire una descrizione.

Sintassi

DBMS_CLOUD_AI_AGENT.CREATE_AGENT(
     agent_name          IN  VARCHAR2,
     attributes          IN  CLOB,
     status              IN  VARCHAR2  DEFAULT NULL,
     description         IN  CLOB      DEFAULT NULL
  );

Parametri

Parametro	Descrizione
`agent_name`	Nome dell'agente AI. Il nome dell'agente deve seguire le regole di denominazione dell'identificativo Oracle SQL. La lunghezza massima del nome è di 125 caratteri. Parametro obbligatorio.
`attributes`	Attributi personalizzati per l'agente AI. Per ulteriori informazioni, vedere Attributi REATE_AGENT.
`status`	Stato dell'agente. Il valore predefinito è `enabled`.
`description`	Descrizione specificata dall'utente per l'agente AI. Il valore predefinito è NULL.

Esempio

Nell'esempio seguente viene creato un agente per elaborare i resi dei prodotti del cliente. Per un esempio completo, vedere Esempio: creazione di un agente restituzione prodotto.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_AGENT(
    agent_name => 'CustomerAgent',
    attributes => '{
       "profile_name": "GOOGLE",
                       "role": "You are an experienced customer agent who deals with customers return request."
     }'
  );
END;
/

Attributi CREATE_AGENT

Questi attributi definiscono il ruolo di un agente e il nome del profilo AI.

Attributi

Nome attributo	Valore predefinito	Descrizione
`profile_name`	-	Il profilo AI utilizzato dall'agente per inviare una richiesta a LLM. Questo è un parametro obbligatorio.
`role`	-	Definire la funzione dell'agente e fornire il contesto all'agente. Viene inviato a LLM. Questo è un parametro obbligatorio.
`enable_human_tool`	`True`	Consenti all'agente di porre domande all'utente per informazioni o chiarimenti.
`short_term_memory_length`	30	Specifica il numero massimo di turni di conversazione inclusi in ogni chiamata LLM per l'esecuzione di un task.

L'esempio seguente mostra come personalizzare gli attributi dell'agente nella procedura.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_AGENT(
    agent_name => 'Customer_Return_Agent',
    attributes => '{
       "profile_name": "GOOGLE",
                       "role": "You are an experienced customer agent who deals with customers return request.",
			   "enable_human_tool": "False"
     }'
  );
END;
/

Procedura ENABLE_AGENT

Questa procedura abilita l'agente AI specificato dall'utente. La procedura modifica lo stato dell'agente AI in ENABLED.

Sintassi

DBMS_CLOUD_AI_AGENT.ENABLE_AGENT(
   agent_name           IN  VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`agent_name`	Nome dell'agente AI da abilitare. Questo parametro è obbligatorio.

agent_name

Nome dell'agente AI da abilitare.

Questo parametro è obbligatorio.

Esempio per abilitare il profilo AI

BEGIN
     DBMS_CLOUD_AI_AGENT.ENABLE_AGENT(
         agent_name    => 'Customer_Return_Agent'
     );
END;
/

Procedura DISABLE_AGENT

Questa procedura disabilita l'agente AI nel database corrente. Lo stato dell'agente AI viene modificato in DISABLED mediante questa procedura.

Sintassi

DBMS_CLOUD_AI_AGENT.DISABLE_AGENT(
   agent_name           IN  VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`agent_name`	Nome dell'agente AI. Questo parametro è obbligatorio.

agent_name

Nome dell'agente AI.

Questo parametro è obbligatorio.

Esempio

BEGIN
     DBMS_CLOUD_AI_AGENT.DISABLE_AGENT(
         agent_name    => 'Customer_Return_Agent'
     );
END;
/

Procedura DROP_AGENT

La procedura elimina un agente AI esistente. Se l'agente non esiste, la procedura genera un errore.

Sintassi

DBMS_CLOUD_AI_AGENT.DROP_AGENT(
    agent_name          IN  VARCHAR2,
    force               IN  BOOLEAN DEFAULT FALSE
 );

Parametri

Parametro Descrizione

Parametro	Descrizione
`agent_name`	Nome dell'agente AI. Questo è un parametro obbligatorio.
`force`	Se `TRUE`, la procedura ignora gli errori se l'agente AI non esiste. Il valore predefinito di questo parametro è `FALSE`.

agent_name

Nome dell'agente AI.

Questo è un parametro obbligatorio.

force

Se TRUE, la procedura ignora gli errori se l'agente AI non esiste.

Il valore predefinito di questo parametro è FALSE.

Esempio

BEGIN
     DBMS_CLOUD_AI_AGENT.DROP_AGENT(agent_name => 'Customer_Return_Agent);
END;
/

Nota per l'uso

Utilizzare force per eliminare un agente e ignorare gli errori se l'agente AI non esiste.

Procedura CREATE_TASK

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.CREATE_TASK per definire un task che un agente Select AI può includere nel relativo processo di ragionamento. Ogni task ha un nome univoco e un set di attributi che specificano il comportamento dell'agente durante la pianificazione e l'esecuzione del task.

È possibile definire le dipendenze tra i task utilizzando l'attributo input, consentendo a Select AI di passare l'output di un task a un altro. Questo supporta il ragionamento concatenato e i flussi di lavoro a più fasi.

Sintassi

DBMS_CLOUD_AI_AGENT.CREATE_TASK(
     task_name           IN  VARCHAR2,
     attributes          IN  CLOB,
     status              IN  VARCHAR2  DEFAULT NULL,
     description         IN  CLOB      DEFAULT NULL
  );

Parametri

Parametro	Descrizione
`task_name`	Un nome univoco per il task. Questo è un parametro obbligatorio.
`attributes`	Oggetto JSON contenente attributi specifici del task. Vedere Attributi CREATE_TASK.
`status`	Stato del task. Il valore predefinito è `ENABLED`.
`description`	Descrizione definita dall'utente che facilita l'identificazione del task. Questo valore viene memorizzato nel database ma non inviato al LLM. Il valore predefinito è NULL.

Esempio

Nell'esempio seguente viene creato un task per elaborare il reso di un prodotto da un cliente.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_TASK(
    task_name => 'Return_And_Price_Match',
    attributes => '{"instruction": "Process a product return request from a customer:{query}' ||
                    '1. Ask customer the reason for return (price match or defective)' ||
                    '2. If price match:' ||
                    '   a. Request customer to provide a price match link' ||
                    '   b. Use websearch tool to get the price for that price match link' ||
                    '   c. Ask customer if they want a refund.' ||
                    '   d. Send email notification only if customer accept the refund.' ||
                    '3. If defective:' ||
                     '   a. Process the defective return",
                    "tools": ["WebSearch", "Email"]}'
  );
END;
/

Attributi CREATE_TASK

Questi attributi definiscono le istruzioni e gli strumenti dell'agente disponibili per il task.

Attributi

Nome attributo	Valore predefinito	Descrizione
`instruction`	-	Affermazione chiara e concisa che descrive ciò che l'attività deve compiere. Questo testo è incluso nel prompt inviato al LLM. È possibile includere un segnaposto `{query}` per rappresentare l'input del linguaggio naturale. Ad esempio: `SELECT AI AGENT <user_prompt>` Questo è un parametro obbligatorio.
`tools`	-	Array JSON di nomi di strumenti che l'agente può utilizzare per completare il task. Ad esempio: `"tools": ["RAG", "SQL", "WEBSEARCH", "NOTIFICATION"]`. Questo è un parametro obbligatorio.
`input`	-	Identifica altri task i cui output devono essere utilizzati come input per questo task. Select AI fornisce automaticamente questi output all'LLM.
`enable_human_tool`	-	Consenti all'agente di porre domande all'utente quando richiede informazioni o chiarimenti durante un task. Il valore predefinito è true. Nota Il task `enable_human_tool` sovrascrive l'attributo `enable_human_tool` dell'agente. Se l'agente `enable_human_tool` è impostato su `false` e il task `enable_human_tool` è impostato su `true`, durante l'esecuzione del task, l'LLM deve porre domande.

Procedura ENABLE_TASK

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.ENABLE_TASK per abilitare un task definito in precedenza. In questo modo lo stato del task viene modificato in ENABLED, consentendo all'agente di utilizzarlo durante l'elaborazione.

Sintassi

DBMS_CLOUD_AI_AGENT.ENABLE_TASK(
   task_name           IN  VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`task_name`	Nome per il task da abilitare. Questo parametro è obbligatorio.

task_name

Nome per il task da abilitare.

Questo parametro è obbligatorio.

Note sull'uso

Il task deve esistere già nel sistema. Questa procedura aggiorna lo stato del task rendendolo disponibile per il processo agente durante i flussi di lavoro di ragionamento.

Esempio di abilitazione di un task

BEGIN
     DBMS_CLOUD_AI_AGENT.ENABLE_TASK(
         task_name    => 'Return_And_Price_Match'
     );
END;
/

Procedura DISABLE_TASK

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.DISABLE_TASK per disabilitare un task nel database corrente. In questo modo lo stato del task viene modificato in DISABLED, impedendo all'agente di utilizzarlo durante l'elaborazione.

Sintassi

DBMS_CLOUD_AI_AGENT.DISABLE_TASK(
   task_name           IN  VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`task_name`	Nome del task da disabilitare. Questo parametro è obbligatorio.

task_name

Nome del task da disabilitare.

Questo parametro è obbligatorio.

Note sull'uso

La disabilitazione di un task non comporta l'eliminazione; è possibile riabilitarlo in un secondo momento utilizzando DBMS_CLOUD_AI_AGENT.ENABLE_TASK. Una volta disabilitato, il task diventa inattivo e l'agente non lo considera più durante la selezione del task.

Esempio

Nell'esempio seguente viene disabilitato un task esistente.

BEGIN
     DBMS_CLOUD_AI_AGENT.DISABLE_TASK(
         task_name    => 'Return_And_Price_Match'
     );
END;
/

Procedura DROP_TASK

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.DROP_TASK per rimuovere un task definito in precedenza dal database. Se il task non esiste, è possibile eliminare l'errore impostando il parametro force su TRUE.

Sintassi

DBMS_CLOUD_AI_AGENT.DROP_TASK(
   task_name IN  VARCHAR2,
   force     IN  BOOLEAN DEFAULT FALSE
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`task_name`	Nome del task da eliminare. Questo è un parametro obbligatorio.
`force`	Se `TRUE`, la procedura ignora gli errori se il task non esiste. Il valore predefinito di questo parametro è `FALSE`.

task_name

Nome del task da eliminare.

Questo è un parametro obbligatorio.

force

Se TRUE, la procedura ignora gli errori se il task non esiste.

Il valore predefinito di questo parametro è FALSE.

Esempio

BEGIN
     DBMS_CLOUD_AI_AGENT.DROP_TASK(task_name => 'Return_And_Price_Match');
END;
/

Note sull'uso

Utilizzare force per eliminare un task e ignorare gli errori se il task non esiste.

Procedura CREATE_TOOL

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.CREATE_TOOL per registrare uno strumento personalizzato che un agente può utilizzare durante l'elaborazione dei task. Ogni strumento è identificato da un tool_name univoco e include attributi che ne definiscono lo scopo, la logica di implementazione e i metadati.

Gli strumenti possono essere procedure o funzioni PL/SQL personalizzate o tipi di strumenti integrati come RAG, SQL, WEBSEARCH o NOTIFICA.

Sintassi

DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
     tool_name          IN  VARCHAR2,
     attributes          IN  CLOB,
     status              IN  VARCHAR2  DEFAULT NULL,
     description         IN  CLOB      DEFAULT NULL
  );

Parametri

Parametro	Descrizione
`tool_name`	Nome univoco per identificare lo strumento. Questo è un parametro obbligatorio.
`attributes`	Attributi dello strumento in formato JSON. Vedere Attributi CREATE_TOOL. Questo è un parametro obbligatorio.
`status`	Stato dello strumento. Il valore predefinito è `ENABLED`.
`description`	Descrizione definita dall'utente che facilita l'identificazione dello strumento. Questo valore viene memorizzato nel database ma non inviato al LLM. Il valore predefinito è NULL.

Esempio

Nell'esempio seguente viene creato uno strumento per generare un messaggio e-mail per il destinatario.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
    tool_name  => 'NOTIFICATION',
    attributes => '{"tool_type": "EMAIL"}'
  );
END;
/

Attributi CREATE_TOOL

Questi attributi forniscono la configurazione dello strumento utilizzando un oggetto JSON nel parametro degli attributi. Ogni attributo configura il modo in cui l'agente utilizza lo strumento durante il ragionamento.

Attributi

Nome attributo	Valore predefinito	Descrizione
`instruction`	-	Affermazione chiara e concisa che descrive cosa dovrebbe realizzare lo strumento e come farlo. Questo testo è incluso nel prompt inviato al LLM. Questo è un parametro obbligatorio.
`function`	-	Specifica la procedura o la funzione PL/SQL da chiamare quando viene utilizzato lo strumento. Parametro obbligatorio per gli strumenti personalizzati.
`tool_type`	-	Specifica un tipo di strumento incorporato. Se impostato, `instruction` e `function` non sono obbligatori. I possibili valori sono riportati di seguito. `SQL` `RAG` `WEBSEARCH` `NOTIFICATION` È possibile creare strumenti integrati con nomi e parametri personalizzati. È inoltre possibile creare più strumenti built-in con lo stesso `tool_type` ma un `tool_params` diverso.
`tool_params`	-	Specifica i parametri per la registrazione degli strumenti incorporati.
`tool_inputs`	-	Descrive gli argomenti di input. Simile ai commenti sulle colonne in una tabella. Ad esempio: `"tool_inputs": [ { "name": "data_guard", "description": "Only supported values are "Enabled" and "Disabled"" } ]`

Prerequisiti per lo strumento integrato

Procedere come segue prima di utilizzare gli strumenti integrati:

Strumento RAG

Creare un profilo AI che faccia riferimento a un indice vettoriale. Vedere Migliora i prompt del linguaggio naturale utilizzando la Retrieval Augmented Generation (RAG).

Strumento di notifica

Sono supportati i seguenti metodi: SLACK e EMAIL.

Strumento SLACK:

Impostare un'applicazione Slack per ricevere messaggi da Autonomous Database.
Creare una credenziale utilizzando DBMS_CLOUD_NOTIFICATION per inviare notifiche Slack da Autonomous Database. Vedere Invia notifiche Slack da Autonomous AI Database.

Strumento E-MAIL:

Nota: lo strumento di posta elettronica invia una notifica di posta elettronica da OCI.

Identificare l'endpoint SMTP. Ad esempio, selezionare uno degli endpoint SMTP:

smtp.us-phoenix-1.oraclecloud.com
smtp.us-ashburn-1.oraclecloud.com
smtp.email.uk-london-1.oci.oraclecloud.com
smtp.email.eu-frankfurt-1.oci.oraclecloud.com

Concedere l'accesso SMTP utilizzando un'ACL. Vedere Configurazione di una connessione SMTP.
Genera le credenziali SMTP per la consegna delle e-mail. Il package UTL_SMTP utilizza le credenziali per l'autenticazione con i server di consegna delle e-mail quando si invia un'e-mail. Per ulteriori informazioni, vedere Generare le credenziali SMTP per un utenti.
Crea i mittenti approvati. Completare questo passaggio per tutti gli indirizzi e-mail utilizzati come indirizzo From con sottoprogramma UTL_SMTP.MAIL. Per ulteriori informazioni, vedere Gestione dei mittenti approvati.
Concedere l'accesso SMTP all'utente aggiungendo la voce di controllo dell'accesso (ACE). Per ulteriori dettagli, vedere Invia e-mail su Autonomous AI Database.

Tipi di strumenti integrati nel package DBMS_CLOUD_AI_AGENT

È possibile registrare gli strumenti integrati utilizzando gli attributi tool_type e tool_params.

Tipo di utensile	Descrizione	Parametri obbligatori
`SQL`	Traduce il linguaggio naturale in query SQL.	`profile_name`
`RAG`	Esegue la Retrieval-Augmented Generation mediante la ricerca vettoriale.	`profile_name`
`NOTIFICATION`	Invia messaggi a un canale Slack o invia e-mail utilizzando SMTP. Opzioni disponibili: `slack` `email`	`notification_type`. Se `notification_type` è `slack`, `credential_name` e `channel` sono obbligatori. Se `notification_type` è `email`, `credential_name`, `recipient`, `sender` e `smtp_host` sono obbligatori.
`WEBSEARCH`	Cerca informazioni dal Web.	`credential_name`

Procedura ENABLE_TOOL

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.ENABLE_TOOL per abilitare uno strumento registrato in precedenza. In questo modo lo stato dello strumento viene modificato in ENABLED, consentendo all'agente di utilizzarlo.

Sintassi

DBMS_CLOUD_AI_AGENT.ENABLE_TOOL(
   tool_name           IN  VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`tool_name`	Nome dello strumento da abilitare. Questo parametro è obbligatorio.

tool_name

Nome dello strumento da abilitare.

Questo parametro è obbligatorio.

Esempio

BEGIN
     DBMS_CLOUD_AI_AGENT.ENABLE_TOOL(
         tool_name    => 'SQL'
     );
END;
/

Procedura DISABLE_TOOL

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.DISABLE_TOOL per disabilitare uno strumento registrato. In questo modo lo stato dello strumento viene modificato in DISABLED, impedendo all'agente di utilizzarlo nei task.

Sintassi

DBMS_CLOUD_AI_AGENT.DISABLE_TOOL(
   tool_name           IN  VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`tool_name`	Nome dello strumento da disabilitare. Questo parametro è obbligatorio.

tool_name

Nome dello strumento da disabilitare.

Questo parametro è obbligatorio.

Esempio

Nell'esempio seguente viene disabilitato uno strumento esistente.

BEGIN
     DBMS_CLOUD_AI_AGENT.DISABLE_TOOL(
         tool_name    => 'SQL'
     );
END;
/

Procedura DROP_TOOL

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.DROP_TOOL per rimuovere uno strumento registrato in precedenza con l'agente. Se il task non esiste, è possibile eliminare l'errore impostando il parametro force su TRUE.

Sintassi

DBMS_CLOUD_AI_AGENT.DROP_TOOL(
   tool_name IN  VARCHAR2,
   force     IN  BOOLEAN DEFAULT FALSE
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`tool_name`	Nome dello strumento da eliminare. Questo è un parametro obbligatorio.
`force`	Se `TRUE`, la procedura ignora gli errori se lo strumento non esiste. Il valore predefinito di questo parametro è `FALSE`.

tool_name

Nome dello strumento da eliminare.

Questo è un parametro obbligatorio.

force

Se TRUE, la procedura ignora gli errori se lo strumento non esiste.

Il valore predefinito di questo parametro è FALSE.

Esempio

BEGIN
     DBMS_CLOUD_AI_AGENT.DROP_TOOL(tool_name => 'SQL');
END;
/

Note sull'uso

Utilizzare force per eliminare uno strumento e ignorare gli errori se lo strumento non esiste.

Procedura CREATE_TEAM

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.CREATE_TEAM per definire un team di agenti AI che lavorano insieme per eseguire task. È possibile specificare gli agenti e i relativi task associati, nonché le modalità di elaborazione dei task.

Sintassi

DBMS_CLOUD_AI_AGENT.CREATE_TEAM(
   team_name    IN VARCHAR2,
   attributes   IN CLOB,
   status       IN VARCHAR2 DEFAULT NULL,
   description  IN CLOB     DEFAULT NULL
);

Parametri

Parametro	Descrizione
`team_name`	Nome univoco per identificare il team dell'agente AI. Questo è un parametro obbligatorio.
`attributes`	Stringa in formato JSON che definisce gli attributi del team come agenti e processo. Vedere Attributi CREATE_TEAM. Questo è un parametro obbligatorio.
`status`	Stato della squadra. Il valore predefinito è `ENABLED`.
`description`	Descrizione definita dall'utente per identificare lo scopo del team. Questo valore viene memorizzato nel database ma non inviato al LLM. Il valore predefinito è NULL.

Esempio

Nell'esempio seguente viene creato un team agente per elaborare la restituzione del prodotto di un cliente.

BEGIN
  DBMS_CLOUD_AI_AGENT.CREATE_TEAM(
    team_name  => 'ReturnAgency',
    attributes => '{"agents": [{"name":"Customer_Return_Agent","task" : "Return_And_Price_Match"}],
                    "process": "sequential"}');
END;
/

Attributi CREATE_TEAM

Questi attributi forniscono la configurazione del team dell'agente AI. Ogni team ha un team_name univoco e utilizza un set di attributi per definire la struttura e la strategia di esecuzione.

Attributi

Nome attributo Valore predefinito Descrizione

Nome attributo	Valore predefinito	Descrizione
`agents`	-	Specifica l'array JSON che elenca gli agenti e i task corrispondenti. Un agente può essere assegnato a più task utilizzando lo stesso nome. Questo è un parametro obbligatorio. Esempio: `[ {"name": "", "task": ""} ]`
`process`	-	Specifica la modalità di esecuzione dei task. Utilizzare `"sequential"` per eseguire i task uno dopo l'altro in ordine.
`long_term_memory_length`	30	Specifica il numero massimo di riepiloghi a livello di task precedenti inclusi nel prompt di sistema come contesto di memoria all'inizio di ogni nuova esecuzione.

agents

Specifica l'array JSON che elenca gli agenti e i task corrispondenti. Un agente può essere assegnato a più task utilizzando lo stesso nome.

Questo è un parametro obbligatorio.

Esempio:

[
{"name": "", "task": ""}
]

process - Specifica la modalità di esecuzione dei task. Utilizzare "sequential" per eseguire i task uno dopo l'altro in ordine.

long_term_memory_length 30 Specifica il numero massimo di riepiloghi a livello di task precedenti inclusi nel prompt di sistema come contesto di memoria all'inizio di ogni nuova esecuzione.

Funzione SET_TEAM

Utilizzare DBMS_CLOUD_AI_AGENT.SET_TEAM per specificare il team dell'agente AI per la sessione corrente.

Una volta impostato un team, solo l'azione select ai agent è abilitata, il sistema non supporta altre azioni Seleziona AI.

Sintassi

DBMS_CLOUD_AI_AGENT.SET_TEAM(
    team_name      IN  VARCHAR2,
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`team_name`	Specifica il nome del team dell'agente AI da utilizzare nella sessione corrente. Il team deve esistere già nel sistema. Questo parametro è obbligatorio.

team_name

Specifica il nome del team dell'agente AI da utilizzare nella sessione corrente. Il team deve esistere già nel sistema.

Questo parametro è obbligatorio.

Esempio

L'esempio seguente imposta il team dell'agente AI specificato dall'utente nella sessione corrente.

EXEC DBMS_CLOUD_AI_AGENT.SET_TEAM('ReturnAgency');

Funzione GET_TEAM

Utilizzare DBMS_CLOUD_AI_AGENT.GET_TEAM per restituire il team dell'agente AI per la sessione corrente.

Sintassi

DBMS_CLOUD_AI_AGENT.GET_TEAM RETURN VARCHAR2;

Esempio

Nell'esempio seguente viene restituito il team dell'agente AI nella sessione corrente.

SELECT DBMS_CLOUD_AI_AGENT.GET_TEAM from DUAL;

Funzione CLEAR_TEAM

Utilizzare DBMS_CLOUD_AI_AGENT.CLEAR_TEAM per cancellare il team dell'agente AI impostato nella sessione corrente. Questa procedura non elimina la squadra.

Sintassi

DBMS_CLOUD_AI_AGENT.CLEAR_TEAM;

Esempio

Nell'esempio seguente viene cancellato il team dell'agente AI nella sessione corrente.

BEGIN
  DBMS_CLOUD_AI_AGENT.CLEAR_TEAM;
END;
/

Funzione RUN_TEAM

Utilizzare DBMS_CLOUD_AI_AGENT.RUN_TEAM per avviare un nuovo team dell'agente AI o riprendere un team sospeso in attesa di input umano. Se si specifica un ID processo esistente e lo stato del processo team associato è WAITING_FOR_HUMAN, la funzione riprende il flusso di lavoro utilizzando l'input fornito come risposta umana.

Sintassi

DBMS_CLOUD_AI_AGENT.RUN_TEAM(
     team_name               IN  VARCHAR2,
     user_prompt             IN  CLOB DEFAULT NULL,
     params                  IN  CLOB DEFAULT NULL,
  );

Parametri

Parametro Descrizione

Parametro	Descrizione
`team_name`	Specifica il nome del team dell'agente AI da utilizzare nella sessione corrente. Il team deve esistere già nel sistema. Questo parametro è obbligatorio.
`user_prompt`	Specifica la query o la risposta dell'utente fornita al task. Se il task si trova nello stato `RUNNING`, l'input funge da segnaposto per `{query}` nell'istruzione del task. Se il task si trova nello stato `WAITING_FOR_HUMAN`, l'input funge da risposta umana.
`params`	Specifica i parametri personalizzati utilizzati durante il processo team agente AI. I parametri supportati includono: `conversation_id`: identifica la sessione di conversazione associata al team dell'agente. Utilizzare questo parametro per le integrazioni delle applicazioni senza conservazione dello stato (ad esempio, Oracle APEX AI Application Generator) per distinguere tra connessioni utente diverse. `variables`: definisce le coppie chiave-valore che forniscono input aggiuntivi al team dell'agente. Queste variabili consentono di personalizzare il comportamento del team durante il processo.

team_name

Specifica il nome del team dell'agente AI da utilizzare nella sessione corrente. Il team deve esistere già nel sistema.

Questo parametro è obbligatorio.

user_prompt

Specifica la query o la risposta dell'utente fornita al task.

Se il task si trova nello stato RUNNING, l'input funge da segnaposto per {query} nell'istruzione del task.

Se il task si trova nello stato WAITING_FOR_HUMAN, l'input funge da risposta umana.

params

Specifica i parametri personalizzati utilizzati durante il processo team agente AI. I parametri supportati includono:

conversation_id: identifica la sessione di conversazione associata al team dell'agente. Utilizzare questo parametro per le integrazioni delle applicazioni senza conservazione dello stato (ad esempio, Oracle APEX AI Application Generator) per distinguere tra connessioni utente diverse.
variables: definisce le coppie chiave-valore che forniscono input aggiuntivi al team dell'agente. Queste variabili consentono di personalizzare il comportamento del team durante il processo.

Esempio

Nell'esempio seguente viene eseguito il team dell'agente AI specificato dall'utente nella sessione corrente.

l_final_answer := DBMS_CLOUD_AI_AGENT.RUN_TEAM(
  team_name => 'ReturnAgency',
  user_prompt => 'I want to return computer desk chair',
  params => '{"conversation_id": "' || l_conversation_id || '"}'
);

Procedura ENABLE_TEAM

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.ENABLE_TEAM per abilitare un team agente AI specificato dall'utente. Lo stato del team viene modificato in ENABLED.

Sintassi

DBMS_CLOUD_AI_AGENT.ENABLE_TEAM(
   team_name           IN  VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`team_name`	Nome da abilitare per il team dell'agente AI. Questo parametro è obbligatorio.

team_name

Nome da abilitare per il team dell'agente AI.

Questo parametro è obbligatorio.

Esempio

L'esempio seguente abilita un team agente AI specificato dall'utente.

BEGIN
     DBMS_CLOUD_AI_AGENT.ENABLE_TEAM(
         team_name    => 'ReturnAgency'
     );
END;
/

Procedura DISABLE_TEAM

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.DISABLE_TEAM per disabilitare un team agente AI esistente. Lo stato del team viene modificato in DISABLED.

Sintassi

DBMS_CLOUD_AI_AGENT.DISABLE_TEAM(
   team_name           IN  VARCHAR2
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`team_name`	Nome del team dell'agente AI da disabilitare. Questo parametro è obbligatorio.

team_name

Nome del team dell'agente AI da disabilitare.

Questo parametro è obbligatorio.

Esempio

Nell'esempio seguente viene disabilitato un team agente AI esistente.

BEGIN
     DBMS_CLOUD_AI_AGENT.DISABLE_TEAM(
         team_name    => 'ReturnAgency'
     );
END;
/

Procedura DROP_TEAM

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.DROP_TEAM per rimuovere un team agente AI creato in precedenza.

Sintassi

DBMS_CLOUD_AI_AGENT.DROP_TEAM(
   team_name IN  VARCHAR2,
   force     IN  BOOLEAN DEFAULT FALSE
);

Parametri

Parametro Descrizione

Parametro	Descrizione
`team_name`	Nome del team da eliminare. Questo è un parametro obbligatorio.
`force`	Se `TRUE`, la procedura ignora gli errori se il team non esiste. Il valore predefinito di questo parametro è `FALSE`.

team_name

Nome del team da eliminare.

Questo è un parametro obbligatorio.

force

Se TRUE, la procedura ignora gli errori se il team non esiste.

Il valore predefinito di questo parametro è FALSE.

Esempio

BEGIN
     DBMS_CLOUD_AI_AGENT.DROP_TEAM(team_name => 'ReturnAgency');
END;
/

Nota per l'uso

Utilizzare force per eliminare un team e ignorare gli errori se il team non esiste.

Funzione DESCRIBE_TOOL

Utilizzare la funzione DBMS_CLOUD_AI_AGENT.DESCRIBE_TOOL per restituire i metadati JSON per uno strumento. Il risultato include il nome dello strumento, la descrizione, gli attributi e le informazioni sullo schema di input che un client compatibile con MCP può utilizzare per la ricerca automatica degli strumenti.

Sintassi

DBMS_CLOUD_AI_AGENT.DESCRIBE_TOOL(
  tool_name IN VARCHAR2
) RETURN CLOB;

Parametri

Parametro	Descrizione
`tool_name`	Nome dello strumento Seleziona agente AI i cui metadati vengono restituiti.

Restituzioni

Restituisce un valore CLOB che contiene metadati e informazioni sugli argomenti dello strumento in formato JSON.

Esempio

DECLARE
  l_result CLOB;
BEGIN
  l_result := DBMS_CLOUD_AI_AGENT.DESCRIBE_TOOL(
    tool_name => 'FETCH_LOG_TOOL'
  );

  DBMS_OUTPUT.PUT_LINE(l_result);
END;
/

Funzione RUN_TOOL

Utilizzare la funzione DBMS_CLOUD_AI_AGENT.RUN_TOOL per chiamare uno strumento creato in base al nome. Il parametro di input passa gli argomenti dello strumento come payload JSON.

Sintassi

DBMS_CLOUD_AI_AGENT.RUN_TOOL(
  tool_name IN VARCHAR2,
  input IN CLOB
) RETURN CLOB;

Parametri

Parametro	Descrizione
`tool_name`	Nome dello strumento Seleziona agente AI da chiamare.
`input`	Payload di input JSON passato allo strumento.

Restituzioni

Restituisce un valore CLOB contenente il risultato dell'esecuzione dello strumento.

Esempio

SELECT DBMS_CLOUD_AI_AGENT.RUN_TOOL(
  tool_name => 'FETCH_LOG_TOOL',
  input => '{"P_SINCE":"2026-01-01"}'
) AS tool_result
FROM dual;

Funzione LIST_TEAMS

Utilizzare la funzione DBMS_CLOUD_AI_AGENT.LIST_TEAMS per enumerare i team agente disponibili per l'utente chiamante. Il risultato può essere utilizzato dai livelli di integrazione compatibili con A2A per la ricerca automatica del team.

Sintassi

DBMS_CLOUD_AI_AGENT.LIST_TEAMS
  RETURN CLOB;

Parametri

Parametro	Descrizione
Nessuno.	Questa funzione non ha parametri.

Restituzioni

Restituisce un valore CLOB che contiene un array JSON. Ogni voce include il nome e la descrizione del team.

Esempio

SELECT DBMS_CLOUD_AI_AGENT.LIST_TEAMS()
FROM dual;

Funzione DESCRIBE_TEAM

Utilizzare la funzione DBMS_CLOUD_AI_AGENT.DESCRIBE_TEAM per restituire i metadati per un team agente. La funzione mappa gli strumenti Seleziona agente AI disponibili per il team nella rappresentazione delle competenze compatibile con A2A.

Sintassi

DBMS_CLOUD_AI_AGENT.DESCRIBE_TEAM(
  team_name IN VARCHAR2
) RETURN CLOB;

Parametri

Parametro	Descrizione
`team_name`	Nome del team agente i cui metadati e funzionalità vengono restituiti.

Restituzioni

Restituisce un valore CLOB che contiene un oggetto JSON con il nome del team, la descrizione, la versione facoltativa e la lista di skill.

Note sull'uso

Le competenze sono una rappresentazione di protocollo degli strumenti per i client compatibili con A2A. Non introduce un nuovo tipo di oggetto database Select AI Agent.

Esempio

SELECT DBMS_CLOUD_AI_AGENT.DESCRIBE_TEAM('SUPPORT_TEAM')
FROM dual;

Funzione GET_TEAM_STATE

Utilizzare la funzione DBMS_CLOUD_AI_AGENT.GET_TEAM_STATE per restituire lo stato di esecuzione più recente per una conversazione del team agente.

Sintassi

DBMS_CLOUD_AI_AGENT.GET_TEAM_STATE(
  team_name IN VARCHAR2,
  params IN CLOB DEFAULT NULL
) RETURN VARCHAR2;

Parametri

Parametro	Descrizione
`team_name`	Nome del team agente il cui stato di esecuzione più recente viene restituito.
`params`	Oggetto JSON facoltativo. Utilizzare `conversation_id` per recuperare lo stato di esecuzione più recente per una conversazione specifica. Se omesso, viene utilizzata la conversazione della sessione corrente.

Restituzioni

Restituisce uno stato di esecuzione VARCHAR2, ad esempio RUNNING, WAITING_FOR_HUMAN, SUCCEEDED o FAILED.

Esempio

SELECT DBMS_CLOUD_AI_AGENT.GET_TEAM_STATE(
  team_name => 'SUPPORT_TEAM',
  params => '{"conversation_id":"<CONVERSATION_ID>"}'
)
FROM dual;

Procedura SET_EXECUTION_STATE

Utilizzare la procedura DBMS_CLOUD_AI_AGENT.SET_EXECUTION_STATE per aggiornare l'esecuzione di un team in attesa a uno stato specificato. Ciò è utile per i flussi di lavoro di chiamata dello strumento agente-diretto in cui l'applicazione controlla quando la sessione interattiva è completata.

Sintassi

DBMS_CLOUD_AI_AGENT.SET_EXECUTION_STATE(
  team_name IN VARCHAR2,
  state IN CLOB DEFAULT 'SUCCEEDED',
  params IN CLOB DEFAULT NULL
);

Parametri

Parametro	Descrizione
`team_name`	Nome del team agente il cui stato di esecuzione è aggiornato.
`state`	Stato esecuzione da impostare. Il valore predefinito è `SUCCEEDED`.
`params`	Oggetto JSON facoltativo. Utilizzare `conversation_id` per identificare la conversazione il cui stato di esecuzione è aggiornato.

Esempio

BEGIN
  DBMS_CLOUD_AI_AGENT.SET_EXECUTION_STATE(
    team_name => 'CUSTOMER_AGENT_ONLY_TEAM',
    state => 'SUCCEEDED',
    params => '{"conversation_id":"<CONVERSATION_ID>"}'
  );
END;
/