22 agenti AI

In questo capitolo vengono fornite informazioni sulla creazione, il test, la distribuzione e il monitoraggio degli agenti nell'area di lavoro.

Gli agenti sono applicazioni agentic end-to-end. Gli agenti sono definiti attraverso un grafico di passi rappresentati da nodi di diversi tipi (trigger, agenti, guardrail o strumenti). Gli agenti possono essere definiti tramite un generatore di flusso visivo senza codice e tramite codice tramite librerie di terze parti, ad esempio LangGraph.

Oracle AI Data Platform Workbench offre più modelli di strumenti che possono essere configurati per accedere ai dati e adattarsi ai casi d'uso. Gli strumenti supportati sono:

• Strumento personalizzato: lo strumento Codice personalizzato consente agli sviluppatori di agenti di estendere AI Data Platform con il proprio codice Python. L'implementazione dello strumento viene impacchettata come file ZIP, caricata nell'area di lavoro e configurata. L'agente chiama il codice come strumento, con i parametri forniti dall'LLM in fase di esecuzione.
• HTTP: lo strumento Richiesta HTTP consente all'agente di chiamare qualsiasi API REST HTTPS. È possibile configurare la richiesta, inclusi metodo, URL, intestazioni, parametri di query, corpo della richiesta, autenticazione e, facoltativamente, un passo di ottimizzazione della risposta. L'agente richiama quindi l'endpoint in runtime. Lo strumento di richiesta HTTP è disponibile sia nel visual builder che nel generatore di codice. Nel generatore di codice, lo strumento viene configurato tramite la libreria helppUtils Python.
• Prompt: lo strumento prompt consente allo sviluppatore AI di definire un prompt parametrizzato che può essere emesso a un LLM a propria scelta. I casi d'uso comuni per uno strumento di prompt includono le attività di redazione delle e-mail, le attività di traduzione, la conversione dello stile, il messaggio di commit git e le spiegazioni del codice.
• Server MCP remoto: gli sviluppatori di agenti possono connettere i propri agenti ai server MCP (Remote Model Context Protocol) utilizzando lo strumento Server MCP remoto.
• RAG: lo strumento RAG consente agli agenti di estrarre informazioni esterne rilevanti prima di generare una risposta. In AI Data Platform Workbench, lo strumento RAG esegue una query su una knowledge base (23ai Vector Search) e recupera chunk di documenti semanticamente pertinenti. Questi chunk vengono quindi passati all'agente per la generazione della risposta.
• SQL: lo strumento SQL consente agli agenti di eseguire query SQL su origini dati strutturate registrate tramite cataloghi esterni, come Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing o Oracle AI Database. Lo strumento è destinato agli scenari in cui le query SQL sono predefinite e possono essere parametrizzate. L'obiettivo è consentire a un agente di assegnare valori ai parametri. Questo strumento non è uno strumento NL2SQL che genera una query SQL basata su un prompt del linguaggio naturale.

  Nota

  Lo strumento SQL esegue solo query sui dati in un catalogo esterno. Non supporta i dati memorizzati in un catalogo standard.

Nota

È necessario collegare una computazione AI al proprio agente prima di poter eseguire il test di uno strumento di sistema. Se non è collegata alcuna computazione, la scheda Test viene disabilitata.

La creazione di agenti in AI Data Platform Workbench genera un file artifact agente (.aflow) nella cartella dell'area di lavoro selezionata. Impossibile modificare questo file.

Sistemi multiagente e modelli supervisore

Un sistema multi-agente è una progettazione di applicazioni AI in cui una richiesta utente viene gestita da più agenti che collaborano invece di un unico agente generico.

Ogni agente ha il proprio ruolo, le istruzioni, la configurazione del modello, i criteri di memoria e gli strumenti consentiti. Il flusso definisce lo spostamento della richiesta tra tali agenti e la modalità di produzione della risposta finale.

Questo design è utile quando un flusso di lavoro si separa naturalmente in responsabilità specialistiche. Ad esempio, un agente può recuperare i dati, un altro può chiamare un'API, un altro può riepilogare i risultati e un supervisore può decidere quale specialista utilizzare e combinare i risultati in un'unica risposta.

Nota

Come principio di progettazione, è meglio iniziare con la più piccola progettazione dell'agente che soddisfa i requisiti. Aggiungi più agenti quando la separazione dei problemi migliora l'affidabilità, la sicurezza, la manutenibilità o l'osservabilità più di quanto non aumenti i costi e la complessità.

Vantaggi dei sistemi multiagente

I sistemi multiagente sono più adatti per:

• Specializzazione: offrire a ciascun agente un job, un prompt e un set di strumenti mirati anziché un blocco di istruzioni affollato.
• Ciclo e decomposizione: consente a un supervisore di interpretare la richiesta, suddividerla in task secondari e scegliere lo specialista giusto per ogni task secondario.
• Strumento e isolamento dei dati: espone gli strumenti sensibili o ad alto impatto solo agli agenti responsabili dell'utilizzo.
• Governance e risoluzione dei problemi: semplifica l'ispezione di consegne, proprietà degli strumenti, impostazioni della memoria e punti di errore.

Quando scegliere progettazioni agente multiplo o agente singolo

Un singolo agente con più strumenti è spesso il primo design giusto. È più semplice testare, più economico da eseguire e più facile ragionare su quando l'attività ha un obiettivo chiaro e un modello di autorizzazione. Utilizza una progettazione con più agenti quando il flusso di lavoro beneficia di ruoli espliciti, accesso limitato agli strumenti o un supervisore in grado di coordinare più output specialistici.

Domanda progettazione	Usa agenti singoli quando...	Utilizza più agenti quando...
Forma task	La richiesta ha un obiettivo principale e uno stile di risposta.	La richiesta deve essere decomposta, instradata, verificata o sintetizzata tra specialità.
Strumenti e dati	Lo stesso set di istruzioni e modello di autorizzazione possono governare in modo sicuro tutti gli strumenti	Agenti diversi hanno bisogno di strumenti, origini dati o limiti di accesso diversi.
Istruzioni	Il prompt rimane chiaro anche con tutte le regole aziendali e la guida agli strumenti in un unico posto.	Le istruzioni sono più facili da gestire come prompt più piccoli e specifici del ruolo.
Costo e latenza	Si desidera che il percorso più breve dal messaggio utente risponda.	I vantaggi di affidabilità, governance o manutenibilità giustificano un'orchestrazione aggiuntiva.
Risoluzione dei problemi	Gli errori sono semplici da eseguire in un'unica traccia.	Hai bisogno di consegne esplicite, isolamento dello stato e proprietà più chiara per ogni passo.

Pattern supportato: orchestratore/supervisore

L'esperienza tela corrente supporta il pattern orchestratore/supervisore. In questo pattern, il trigger chat riceve il messaggio utente, i guardrail facoltativi valutano l'input e un agente supervisore funge da orchestratore per il resto del flusso.

Il supervisore deve concentrarsi sulla pianificazione, l'instradamento, la delega e la sintesi della risposta finale. Decide quale agente esecutore deve gestire un task, invia all'esecutore un'istruzione definita, esamina il risultato e quindi delega un altro passo o restituisce la risposta finale. Gli agenti esecutori dovrebbero essere specialisti più ristretti: eseguono il lavoro assegnato, utilizzano gli strumenti allegati e restituiscono risultati utili al supervisore.

Informazioni sullo sfondo del flusso visivo

Un agente viene assemblato trascinando nodi e modelli di strumenti dalla tavolozza sinistra sullo sfondo, quindi collegando i nodi nell'ordine in cui la richiesta dovrebbe viaggiare.

La selezione di un nodo consente di aprire un pannello di configurazione nella parte inferiore della schermata.

Elemento sfondo	Scopo
Trigger chat	Punto di accesso per un messaggio utente. Nello screenshot questo nodo è denominato Messaggio e in genere si trova nella parte superiore del flusso. Un nodo trigger chat può essere connesso a un agente, a un agente supervisore o a un nodo guardrail. È consentito un solo trigger chat per area di creazione.
Limiti	Livello di sicurezza e criteri facoltativi posizionati prima o dopo il lavoro del modello. Le politiche dei guardrail includono PII, moderazione dei contenuti e rilevamento rapido dell'iniezione. Un nodo guardrail può filtrare il traffico tra un trigger di chat e un nodo agente, tra un supervisore e gli agenti dell'esecutore o tra i nodi agente e strumento. È consigliabile un singolo nodo di guardrail tra il trigger di chat e il nodo dell'agente.
Agente supervisore	L'orchestratore. Riceve la richiesta dell'utente, decide quale agente o strumento dell'esecutore deve gestire ogni attività e coordina la risposta finale. In uno sfondo è consentito un solo agente supervisore.
Agente	Agente esecutore. Ogni esecutore deve avere una chiara specializzazione, come il recupero dei dati, la ricerca API, il riepilogo o la risposta alle domande sui documenti. Usare un agente/esecutore per un sistema a agente singolo.
Template strumenti	Funzionalità riutilizzabili che possono essere collegate a un singolo esecutore o agente supervisore. I modelli di strumento includono SQL, RAG, Prompt, HTTP, Server MCP remoto e Strumento personalizzato.
Sviluppo / Parco giochi	Selettore di modalità sopra lo sfondo. Lo sviluppo viene utilizzato durante la modifica del sistema Agentic; Playground viene utilizzato per avviare le sessioni di test e ispezionare il comportamento dell'agente. Playground richiede che una computazione AI sia collegata al tuo agente.
Controllo zoom	Selettore zoom sfondo. Gli screenshot mostrano livelli di zoom del 60% e del 90%.

Crea agente

È possibile creare un agente in un'area di lavoro in cui si dispone dell'autorizzazione Gestisci.

1. Nella home page, andare all'area di lavoro.
2. Fare clic su Flussi di agenti nel riquadro di navigazione a sinistra.
3. Fare clic su Crea agente o su Crea in alto a destra.
   
   

   

   
   
4. Fornire il nome e la descrizione dell'agente.
5. Per la modalità di creazione del flusso di agenti, selezionare Costruzione guidata visiva.
   
   

   

   
   
6. Facoltativo: nel menu a discesa Computazione AI selezionare una computazione da utilizzare per l'agente.
7. Fare clic su Crea. Iniziare a creare l'agente trascinando un nodo dalla tavolozza allo sfondo.

   Nota

   Inizia la creazione del tuo primo agente semplice: un trigger di chat, un agente esecutore. Aggiungi complessità dopo un'esecuzione riuscita della tua prima build, come binari di protezione, strumenti aggiuntivi o persino progettazione di sistemi multi-agente.

Aggiungi trigger chat e agente all'area di creazione di Visual Builder

Il primo passo dopo la creazione di un agente con Visual Builder deve essere l'aggiunta di un trigger di chat e di un agente supervisore.

Il trigger riceve il messaggio utente. Il supervisore interpreta la richiesta, pianifica il lavoro e delega ad agenti o strumenti dell'esecutore. È possibile trascinare i nodi nello sfondo, configurarli e connetterli in un secondo momento.

1. Passare all'agente nell'area di lavoro.
2. Fare clic e trascinare un trigger chat dalla tavolozza allo sfondo. Il nodo viene visualizzato nell'area di creazione come messaggio.
3. Fare clic e trascinare un agente supervisore nell'area di creazione.
   
   

   

   
   
4. Fare clic e trascinare l'handle del connettore sul nodo Trigger chat per connetterlo al nodo Agente.

Il badge Agente supervisore visualizza il numero di agenti e strumenti connessi. In una nuova build, l'agente supervisore mostra: Agenti (0) Strumenti (0).

Configurare un agente supervisore

È necessario configurare un agente supervisore aggiunto all'area di creazione di Visual Builder con istruzioni che descrivono il ruolo supervisore.

È possibile configurare un agente supervisore con i campi riportati di seguito.

Campo	Configurazione
Nome agente	Fornire un nome descrittivo per l'agente supervisore. Un buon nome descrittivo sarà utile quando si esegue il debug del comportamento del sistema tramite tracce e log.
Descrizione agente	Fornire una descrizione dello scopo, del ruolo e del comportamento generale dell'agente. Utile ai fini della documentazione.
Area	Scegliere l'area in cui è ospitato il modello di AI generativa OCI utilizzato dall'agente supervisore. Vedere Modelli di intelligenza artificiale generativa per area.
Modello	Scegliere il modello di servizio OCI Generative AI utilizzato dal supervisore. Nell'elenco a discesa sono elencati i modelli disponibili nell'area selezionata.
Istruzioni agente	Descrivere il ruolo supervisore, le regole di instradamento, i criteri di delega, le aspettative di utilizzo degli strumenti e il formato di risposta finale.

1. Passare all'agente nell'area di lavoro.
2. Fare clic sul nodo Agente supervisore nell'area di creazione.
3. Fornire un nome e una descrizione dettagliati per l'agente supervisore.
4. Immettere l'area e il modello per il modello di servizio OCI Generative AI utilizzato dal supervisore.
5. Fornire le istruzioni per l'agente supervisore.

Istruzioni supervisore suggerite

Utilizzare il campo Istruzioni per un agente supervisore per rendere il supervisore responsabile dell'orchestrazione, non per eseguire ogni task stesso.

Mantieni le istruzioni concrete in modo che le decisioni di instradamento siano prevedibili. Per un esempio di serie di istruzioni del supervisore, vedere:

You are the supervisor for a multi-agent system.

Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.

Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.

Configurare la memoria dell'agente supervisore e l'isolamento dello stato

La scheda Memoria per un agente supervisore controlla la quantità di cronologia delle conversazioni e degli output degli strumenti disponibile per il supervisore e la quantità di contesto condivisa con gli agenti esecutore.

È possibile configurare la memoria e lo stato di isolamento per l'agente supervisore con i campi riportati di seguito.

Campo	Configurazione
Abilita memoria agente	Abilita quando gli utenti hanno bisogno di continuità multigiro. Disabilitare per attività isolate e monouso. Impossibile disabilitare questo campo per gli agenti supervisore.
Limita la cronologia delle conversazioni	Abilitare per troncare la finestra di contesto LLM dopo che è stato raggiunto il limite specificato. Disattivare per visualizzare la cronologia completa.
Configurazione troncamento	Se l'opzione Limita cronologia conversazioni è abilitata, utilizzare questo campo per impostare le condizioni di troncamento della finestra di contesto. Le opzioni sono le seguenti: Mantieni ultimi N messaggi Budget token Entrambe
Limite massimo messaggi e budget token	Viene visualizzata una o entrambe le opzioni, a seconda della scelta effettuata per Configurazione di esecuzione. I valori predefiniti sono 20 messaggi e 5000 token. Si consiglia di iniziare con valori moderati e di regolare in base alle esigenze.
Isolamento dello stato per gli agenti esecutori	Selezionare Senza conservazione dello stato, Privato o Condiviso. Senza stato: ogni agente esecutore visualizza solo il task assegnato dal supervisore. Nessuna storia viene riportata tra le chiamate. Selezionare questa opzione se si desidera disporre dell'isolamento più efficace e del contesto con meno agenti incrociati. Privato: ogni agente esecutore visualizza solo le proprie interazioni passate. Non è possibile visualizzare altri agenti esecutore della conversazione utente originale. Selezionare questa opzione se l'esecutore ha bisogno di continuità tra i propri task, ma non deve condividere il contesto con altri agenti. Condiviso: gli agenti esecutore possono visualizzare la cronologia completa delle conversazioni tra agenti e utenti. Tutti gli agenti lavorano da un contesto condiviso. Selezionare questa opzione se è necessaria un'ampia condivisione del contesto e se sono stati esaminati i rischi relativi alla privacy e all'iniezione rapida.

1. Passare all'agente nell'area di lavoro.
2. Fare clic sul nodo Agente supervisore nell'area di creazione.
3. Fare clic sulla scheda Memoria.
4. Scegliere se abilitare Limita cronologia conversazioni. Selezionare una configurazione di esecuzione e impostare i limiti, se abilitati.
5. Scegliere un'opzione per Isolamento degli stati per gli agenti esecutore.

Scheda Parametro modelli

La scheda Parametri modello consente di configurare i parametri specifici del modello disponibili per il modello selezionato.

I parametri del modello possono essere configurati separatamente per gli agenti supervisore ed esecutore. I parametri che è possibile utilizzare includono temperatura, K superiore, P superiore e penalità di frequenza.

Nota

Solo un subset di modelli espone parametri configurabili. Inoltre, i parametri variano a seconda delle famiglie di modelli.

Aggiungi guardrail a un agente

È possibile aggiungere ulteriori livelli di protezione agli agenti aggiungendo uno o più nodi di guardrail all'area di creazione.

Per impostazione predefinita, nessun guardrail viene applicato ai sistemi di autenticazione oltre a ciò che il provider di modelli selezionato sta offrendo pronto all'uso per i propri modelli. I guardrail possono essere posizionati tra il trigger chat e l'agente supervisore in modo che i criteri vengano applicati prima che una richiesta raggiunga l'agente supervisore e prima che l'agente supervisore restituisca una risposta al chiamante.

Limite	Opzioni	Quando utilizzarla
Informazioni di identità personale (PII)	Schede di input e output Caselle di controllo per persona, indirizzo, numero di telefono, e-mail	Utilizzare quando il flusso deve bloccare o mascherare i dati personali sensibili prima o dopo l'elaborazione del modello.
Prevenzione della moderazione dei contenuti	Righe di input e output con opzioni Blocca, Informa e Consenti.	Utilizzare per definire come il flusso gestisce l'odio, i contenuti sessuali, violenti, tossici, dispregiativi o molesti.
Prompt rilevamento iniezione	Riga di input con opzioni Blocco e Consenti.	Utilizzare per ridurre la possibilità che istruzioni dannose sostituiscano le istruzioni del sistema o dell'agente.

Per ulteriori informazioni sulle impostazioni del guardrail, vedere Guardrails.

1. Passare all'agente nell'area di lavoro.
2. Trascinare un nodo Guardrails dalla tavolozza all'area di creazione. Posizionarlo tra il nodo Trigger chat e il nodo Agente supervisore.
3. Eliminare la connessione tra Chat Trigger e Supervisor Agent passando il puntatore del mouse sulla connessione e facendo clic sulla X rossa.
   
   

   

   
   
4. Fare clic e trascinare l'handle del connettore sul trigger di chat nel nodo Guardrail. Quindi fare clic e trascinare l'handle del connettore dal nodo Guardrail all'agente supervisore.
5. Fare clic sul nodo Guardrail per aprire la pagina Configurazione.
6. Configurare i guardrail per selezionare l'azione desiderata per i controlli di input e output.

Aggiunta di agenti e strumenti esecutore a un agente

È possibile aggiungere agenti esecutore agli strumenti per eseguire lavori specializzati per l'agente supervisore.

Nell'esempio seguente, l'agente supervisore delega ad AGENT_1 e AGENT_2. AGENT_1 è connesso agli strumenti SQL_1 e HTTP_1.

1. Passare all'agente nell'area di lavoro.
2. Trascinare un nodo agente dalla tavolozza all'area di creazione. I nodi dell'agente devono essere posizionati sotto un agente supervior.
3. Trascinare Strumenti dalla tavolozza all'area di creazione.
4. Fare clic e trascinare l'handle del connettore sull'agente supervisore per connettersi ai nodi dell'agente.
5. Fare clic e trascinare l'handle del connettore sugli agenti per connettersi ai nodi dello strumento.

Configurazione agente esecutore

I nodi agente possono essere configurati modificando le impostazioni nelle relative schede Configurazione, Memoria e Modello per definire lo scopo di ciascun agente.

Gli agenti devono essere configurati in modo limitato, data una funzione e un obiettivo specifici, in modo che l'agente supervisore possa instradare il lavoro in modo affidabile.

Tabella 22-1: scheda Configurazione agente

Campo	Configurazione
Nome agente	La procedura consigliata consiste nel nominare ciascun agente esecutore in base alla sua specializzazione, ad esempio SQL_AGENT, DOCUMENT_AGENT, API_AGENT o SUMMARY_AGENT. Il nome di ciascun agente esecutore è visibile all'agente supervisore, quindi utilizzare nomi descrittivi.
Descrizione agente	Fornire una descrizione dettagliata di ciascun agente esecutore. La descrizione di ciascun agente esecutore è visibile all'agente supervisore.
Area	Scegliere l'area in cui è ospitato il modello di AI generativa OCI utilizzato dall'agente. Vedere Modelli di intelligenza artificiale generativa per area.
Modello	Scegliere il modello di servizio OCI Generative AI utilizzato dall'agente. Nel menu a discesa sono elencati i modelli disponibili nell'area selezionata. Selezionare un modello adatto al task dell'esecutore. Gli agenti esecutori non devono utilizzare lo stesso modello dell'agente supervisore.
Istruzioni agente	Descrivi esattamente cosa dovrebbe fare l'esecutore, quali strumenti potrebbe utilizzare e quale struttura di output dovrebbe restituire.

Scheda memoria agente esecutore

Nel caso di agenti esecutore connessi a un agente supervisore, la memoria per gli esecutori viene configurata nel nodo supervisore e applicata a tutti gli agenti esecutore.

Campo	Configurazione
Abilita memoria agente	Abilita quando gli utenti hanno bisogno di continuità multigiro. Disabilitare per attività isolate e monouso.
Limita la cronologia delle conversazioni	Abilitare per troncare la finestra di contesto LLM dopo che è stato raggiunto il limite specificato. Disattivare per visualizzare la cronologia completa.
Configurazione troncamento	Se l'opzione Limita cronologia conversazioni è abilitata, utilizzare questo campo per impostare le condizioni di troncamento della finestra di contesto. Le opzioni sono le seguenti: Mantieni ultimi N messaggi Budget token Entrambe
Limite massimo messaggi e budget token	Viene visualizzata una o entrambe le opzioni, a seconda della scelta effettuata per Configurazione di esecuzione. I valori predefiniti sono 20 messaggi e 5000 token. Si consiglia di iniziare con valori moderati e di regolare in base alle esigenze.
Isolamento dello stato per gli agenti esecutori	Selezionare Senza conservazione dello stato, Privato o Condiviso. Senza stato: ogni agente esecutore visualizza solo il task assegnato dal supervisore. Nessuna storia viene riportata tra le chiamate. Selezionare questa opzione se si desidera disporre dell'isolamento più efficace e del contesto con meno agenti incrociati. Privato: ogni agente esecutore visualizza solo le proprie interazioni passate. Non è possibile visualizzare altri agenti esecutore della conversazione utente originale. Selezionare questa opzione se l'esecutore ha bisogno di continuità tra i propri task, ma non deve condividere il contesto con altri agenti. Condiviso: gli agenti esecutore possono visualizzare la cronologia completa delle conversazioni tra agenti e utenti. Tutti gli agenti lavorano da un contesto condiviso. Selezionare questa opzione se è necessaria un'ampia condivisione del contesto e se sono stati esaminati i rischi relativi alla privacy e all'iniezione rapida.

Scheda Parametri modello agente esecutore

La scheda Parametri modello consente di configurare i parametri specifici del modello disponibili per il modello selezionato.

Nota

Solo un subset di modelli espone parametri configurabili. I parametri variano anche tra le famiglie di modelli.

Esempi di parametri includono temperatura, K superiore, P superiore e penalità di frequenza. I parametri del modello possono essere configurati separatamente per gli agenti supervisore ed esecutore.

Istruzioni esecutore suggerite

You are the SQL executor agent.

Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.

Lista di controllo per gli agenti tramite Visual Builder

Utilizzare questa lista come guida per assicurarsi di aver incluso e configurato tutti i componenti necessari per un agente creato utilizzando Visual Builder.

Lista di controllo build

• L'agente ha esattamente un punto di ingresso previsto: Chat Trigger / Messaggio.
• I guardrail sono collegati nella posizione prevista e abilitati dove necessario. Si consiglia di inserire i guardrail tra il messaggio di trigger e l'agente.
• L'agente supervisore dispone di un'area selezionata, di un modello selezionato e di istruzioni di orchestrazione. Lo stesso vale per gli agenti esecutori.
• Configurare la memoria del sistema con più agenti nella scheda Memoria dell'agente supervisore. Selezionare l'isolamento dello stato dell'esecutore corrispondente ai requisiti di privacy e continuità.
• Ogni agente esecutore ha una chiara specializzazione e istruzioni strette.
• Ogni strumento è collegato solo all'agente che deve utilizzarlo.
• Nessun nodo disconnesso.
• Al sistema di autenticazione è collegata una computazione AI per testare i singoli strumenti e per eseguire l'esperienza Playground.

Tabella 22-2 Questioni comuni

Problema	Causa probabile	Azione suggerita
Il supervisore non chiama un esecutore	Le istruzioni del supervisore sono troppo vaghe o nessun esecutore è connesso.	Aggiungere regole di instradamento esplicite e confermare che il nodo esecutore è connesso al supervisore.
L'esecutore restituisce risposte ampie o fuori argomento	Le istruzioni dell'esecutore sono troppo generali.	Rendere il ruolo esecutore più ristretto e definire la struttura di output richiesta.
Strumento non utilizzato	Lo strumento è disconnesso o collegato all'agente errato.	Controllare la connessione allo strumento e il badge del conteggio degli strumenti dell'agente.
Guardrail non brucia	La sezione Guardrail è configurata ma non abilitata.	Aprire il nodo guadrails e confermare che l'attivazione della sezione è attiva.
Perdite di contesto tra agenti	L'isolamento dello stato è impostato su Condiviso o la memoria è più ampia del previsto.	Utilizzare l'isolamento senza conservazione dello stato o privato per una separazione più rigorosa.
Le domande di follow-up perdono il contesto	La memoria è disabilitata o il troncamento è troppo aggressivo.	Abilita la memoria e regola il limite massimo di messaggi.

Codice flusso agente

Puoi trasferire la tua base di codice LangGraph agli agenti AI in Oracle AI Data Platform Workbench o creare un nuovo agente LangGraph direttamente sulla piattaforma attraverso l'esperienza di codifica degli agenti.

È possibile utilizzare la libreria Python della utility AI Data Platform Workbench aidputils per configurare il modello di base e importare gli strumenti di sistema nell'agente. Per il riferimento all'API helpputils, vedere API Aidp-utils per Oracle AI Data Platform Workbench.

È possibile creare un agente tramite il codice caricando un file di codice esistente o creando file di codice direttamente nell'agente tramite l'editor in linea.

L'editor di codice in linea negli agenti supporta i seguenti tipi di file di codice:

• Python (.py)
• JSON
• TXT
• CSV
• PSV
• N. spedizione
• Cartella

È possibile visualizzare e spostarsi tra i file di codice disponibili facendo clic sull'elenco a discesa Selettore file.

File di voci e dipendenze

I file di voce sono file di codice con la classe con metodi di impostazione e richiamo previsti per un agente definito come codice. Oracle AI Data Platform Workbench richiede l'impostazione di un file di inserimento per gli agenti tramite codice.

I file delle dipendenze sono file che includono librerie di terze parti richieste dall'agente definito come codice. I file delle dipendenze sono in genere file requirements.txt che contengono una lista delle librerie di terze parti necessarie.

Nota

Le librerie di terze parti vengono installate quando si esegue il test del codice nell'editor facendo clic sul pulsante Riproduci o quando si esegue il test dell'agente tramite la scheda Test. Si consiglia di installare librerie di terze parti eseguendo prima il test del codice. Nella cella di output vengono visualizzati errori durante l'installazione delle librerie.

Classe agente

AgentBasic è una classe modello per l'impostazione e il richiamo di un agente conversazionale semplice utilizzando un flusso di lavoro LangGraph con conservazione dello stato. Dimostra la struttura necessaria per lo sviluppo minimo dell'agente con due metodi principali:

• setup(): inizializza il workflow dell'agente e definisce il grafico.
• invoke(user_query, **kwargs): esegue l'agente su un messaggio utente e restituisce la risposta.

Può essere eseguito e testato direttamente utilizzando una funzione main() prima dell'integrazione in un sistema più grande.

Definizione

class AgentBasic:
    def __init__(self) -> None:
        self.graph = None
    def setup(self) -> None:
        self.graph = StateGraph(MessagesState)
        self.graph.add_node(mock_llm)
        self.graph.add_edge(START, "mock_llm")
        self.graph.add_edge("mock_llm", END)
        self.graph = self.graph.compile()
        system_prompt = "Be a helpful assistant."
    async def invoke(self, user_query: str, **kwargs):
        user_message = HumanMessage(content=user_query)
        messages = {"messages": [dict(user_message)]}
        try:
            return self.graph.invoke(messages)
        except Exception as e:
            import traceback
            logger.error(f"Exception while calling invoke {e}", exc_info=True)
            print("Stack trace:\n", traceback.format_exc()) 

Richiamo test

Questo richiamo del test è ideale per i test funzionali iniziali.

Nota

Includere un punto di ingresso principale per i test standalone.

import asyncio

async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
   asyncio.run(main())

Funzionamento:

• Lo script crea un agente, lo imposta e invia un messaggio utente di esempio.
• L'agente risponde ({"messages": [{"role": "ai", "content": "hello world"}]} in questo esempio).

Guida all'uso

Creare una classe agente con i metodi di impostazione e richiamo.

configurazione()	Inizializza il workflow dell'agente	agent.setup()
richiamo()	Esegue l'agente con un messaggio utente	attendete agent.invoke("La tua domanda")

• Asincrono: invoke() è un metodo asincrono; utilizzarlo con await o eseguirlo in un loop asincrono.
• Test: il controllo main() incluso (if __name__ == "__main__":) semplifica il test dell'agente prima della distribuzione.

Crea un agente tramite codice per caricamento

Puoi creare la tua applicazione agente end-to-end con il codice esistente caricando il codice base LangGraph.

Oracle AI Data Platform Workbench supporta LangGraph versione 1.0.1.

Nota

È possibile caricare singoli file e cartelle fino a un massimo di 500 file, ogni file può avere una dimensione massima di 500 MB. Il caricamento è limitato a una dimensione totale di 5 GB.

1. Passare all'agente nell'area di lavoro. Fare clic sul nome dell'agente.
2. Fare clic su Carica.
   
   

   

   
   
3. Trascinare e rilasciare un file nel riquadro oppure fare clic per sfogliare per selezionare un file.
4. Fare clic su Carica.

Crea un agente tramite codice creando un nuovo codice

Puoi creare la tua applicazione agente end-to-end con il codice esistente creando codice direttamente nel tuo agente tramite l'editor di codice.

L'editor di codice supporta i seguenti tipi di file:

• Python (.py)
• JSON
• TXT
• CSV
• PSV
• N. spedizione
• Cartelle

1. Passare all'agente nell'area di lavoro. Fare clic sul nome dell'agente.
2. Fare clic su Aggiungi nuovo file.
   
   

   

   
   
3. Immettere un nome per il file di codice.
4. Selezionare un tipo di File dall'elenco a discesa.
5. Fare clic su Crea.

Impostare un file di immissione per gli agenti mediante il codice

L'agente AI tramite il codice richiede un file di inserimento con la classe, l'impostazione e i metodi di richiamo richiesti per l'agente.

1. Passare all'agente nell'area di lavoro. Fare clic sul nome dell'agente.
2. Nella scheda Editor di codice, individuare il file di immissione nel riquadro di navigazione a sinistra. Se il file non esiste, è possibile caricarlo facendo clic su Carica oppure crearlo facendo clic su Aggiungi nuovo file.
3. Fare clic con il pulsante destro del mouse sul file di immissione e fare clic su Imposta file di voce. È inoltre possibile selezionare il file e fare clic sul pulsante Imposta file di voce in alto a destra nell'editor di codice.
   
   

   

   
   

Impostare un file di dipendenze per gli agenti mediante il codice

È necessario impostare un file di dipendenza per i flussi di agenti attraverso il codice che contiene librerie di terze parti da cui dipende il codice.

1. Passare all'agente nell'area di lavoro. Fare clic sul nome dell'agente.
2. Nella scheda Editor di codice individuare il file delle dipendenze nel riquadro di navigazione a sinistra, in genere requirements.txt. Se il file non esiste, è possibile caricarlo facendo clic su Carica oppure crearlo facendo clic su Aggiungi nuovo file.
3. Fare clic con il pulsante destro del mouse sul file delle dipendenze e fare clic su Imposta dipendenza. È inoltre possibile selezionare il file e fare clic sul pulsante Imposta file delle dipendenze in alto a destra nell'editor di codice.
   
   

   

   
   

Codice agente test

È possibile eseguire il test del codice utilizzato per l'agente dalla scheda Test per convalidare ed eseguire il debug del codice.

Per eseguire il test, è necessario che all'agente sia collegata una computazione AI.

1. Passare all'agente nell'area di lavoro. Fare clic sul nome dell'agente.
2. Fare clic sulla scheda Area di riproduzione.
   
   

   

   
   
3. Fare clic su Esegui per eseguire il test del file di codice selezionato.
   
   

   

   
   

Una cella di output nella parte inferiore della finestra dell'editor di codice visualizza gli output delle istruzioni di stampa o registrazione nel codice. Gli errori vengono visualizzati anche nella cella di output.

Competenze agente nell'esperienza di codifica

Le competenze agente consentono a un agente di trovare e utilizzare istruzioni specifiche del task, file di riferimento, modelli, asset e script eseguibili facoltativi senza dover codificare la conoscenza del dominio nelle istruzioni dell'agente.

Uno skill viene memorizzato come cartella nel code base dell'agente. Ogni abilità ha un file SKILL.md richiesto che descrive cosa fa l'abilità e come l'agente dovrebbe usarla. Una competenza può anche includere file di supporto quali schemi, esempi, prompt, modelli, asset o script.

Per ulteriori informazioni, vedere Panoramica sulle competenze degli agenti.

Le competenze degli agenti supportano un modello di divulgazione progressiva:

1. L'agente scopre che esiste uno skill.
2. L'agente attiva lo skill solo quando è rilevante.
3. L'agente carica file aggiuntivi dalla cartella skill solo quando necessario.
4. L'agente può eseguire un punto di accesso skill dichiarato in modo esplicito, se lo consente.

Quando utilizzare le competenze agente

Utilizzare Skill quando si desidera raggruppare funzionalità agente riutilizzabili, ad esempio:

• Istruzioni specifiche del dominio
• Flussi di lavoro di codifica o analisi dei dati
• Guida alla generazione di SQL
• playbook dei processi aziendali
• Modelli di file
• Riferimenti schema
• Script riutilizzabili per calcoli, trasformazioni o ricerche sicure

Le competenze sono utili quando l'agente deve avere accesso a conoscenze specializzate e riutilizzabili, ma non si desidera inserire tutte queste conoscenze direttamente nel prompt dell'agente.

Come funzionano le competenze in runtime

In fase di esecuzione, l'applicazione host determina quali directory skill sono disponibili, ad esempio le cartelle skill a livello di progetto e a livello di utente. La piattaforma carica i metadati di ogni skill da SKILL.md e crea un catalogo con chiave per nome skill.

L'agente può quindi utilizzare gli strumenti correlati alle competenze:

Strumento	Scopo
activate_skill(name)	Carica le istruzioni di abilità da SKILL.md.
list_skill_files(name, path)	Elenca i file disponibili all'interno di una cartella skill.
load_skill_file(name, path)	Carica un file di supporto dalla cartella skill.
run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds)	Esegue un punto di ingresso Python dichiarato in modo esplicito, se consentito dalla competenza.

Alcuni ambienti possono anche incorporare un riepilogo delle competenze disponibili direttamente nel prompt di sistema. In questa impostazione, l'agente può individuare le competenze disponibili dal prompt, quindi utilizzare activate_skill quando sono necessarie le istruzioni complete.

Struttura cartella competenze

Uno skill utilizza un layout di cartella di tipo skill agente:

<skills_dir>/
	some-skill/
		SKILL.md
		references/
		...
		scripts/
		...
		assets/
		...

È necessario solo SKILL.md. Le altre cartelle sono facoltative.

Cartella o file	Obbligatorio.	Scopo
SKILL.md	Sì	Metadati e istruzioni delle competenze principali.
references/	N.	Documentazione di supporto, schemi, esempi o modelli.
scripts/	N.	Script Python che possono essere eseguiti solo se dichiarati esplicitamente come punti di ingresso.
assets/	N.	Asset statici utilizzati dalla competenza.

Scrivere SKILL.md

Ogni abilità deve includere il frontmatter YAML nella parte superiore di SKILL.md, seguito da istruzioni Markdown.

Esempio di base

---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
  owner: data-platform
  domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---

# SQL Helper

Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.

Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.

Tabella 22-3 Campi degli elementi anteriori supportati

Campo	Obbligatorio.	Descrizione
name	Sì	Nome univoco dello skill utilizzato dal catalogo e dagli strumenti.
description	Sì	Breve descrizione utilizzata per la ricerca automatica e l'instradamento.
license	N.	Licenza o criterio di utilizzo per lo skill.
Compatibilità	N.	Nota sulla compatibilità per runtime o piattaforme supportate.
metadati	N.	Mappa dei metadati da stringa a stringa.
strumenti consentiti	N.	Lista separata da spazi di strumenti che questa abilità consente.
punti di accesso	N.	Lista di punti di accesso eseguibili dichiarati dallo skill.

Aggiunta di file di supporto

I file di supporto consentono a un'abilità di mantenere contenuti dettagliati al di fuori delle istruzioni principali. Ciò mantiene SKILL.md focalizzato pur offrendo all'agente l'accesso a un contesto più ricco. Ad esempio:

skills/
	sql-helper/
		SKILL.md
		references/
			warehouse_schema.md
			query_style_guide.md
			examples.md

L'agente può esaminare questi file con:

list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")

Utilizzare i file di supporto per contenuti quali:

• Schemi di database
• Esempi API
• Modelli prompt
• Guide stile
• Glossari di dominio
• Playbook dettagliati
• Casi o esempi di test

Creazione di una competenza eseguibile

Facoltativamente, una competenza può esporre un comportamento eseguibile riutilizzabile tramite run_skill_entrypoint. Questo è destinato a operazioni controllate come calcoli, trasformazioni, convalida o recupero di dati strutturati.

Le competenze eseguibili devono soddisfare due requisiti:

1. Lo skill deve includere run_skill_entrypoint negli strumenti consentiti.
2. Lo script deve essere dichiarato esplicitamente nella sezione entrypoints di SKILL.md.

Skill eseguibile di esempio

skills/
	statistics-helper/
		SKILL.md
		scripts/
			summarize_numbers.py

SKILL.it

---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: summarize_numbers
    script: scripts/summarize_numbers.py
    func: run
    description: Returns count, min, max, mean, and median for a list of numbers.
---

# Statistics Helper

Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median

def run(*, values: list[float]) -> dict:
    if not values:
        raise ValueError("values must not be empty")

    return {
        "count": len(values),
        "min": min(values),
        "max": max(values),
        "mean": mean(values),
        "median": median(values),
    }
Example invocation:
run_skill_entrypoint(
  name="statistics-helper",
  entrypoint="summarize_numbers",
  args_json="{\"values\": [10, 20, 30, 40]}",
  timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.

Regole per i punti di accesso eseguibili

I punti di accesso eseguibili sono vincolati intenzionalmente. Nella piattaforma vengono eseguiti solo i file Python elencati di seguito.

• Si trova sotto la directory/script della skill
• Dichiarato nel frontmatter dei punti di ingresso dell'abilità
• Consentito dall'impostazione allowed-tools dello skill

La piattaforma non fornisce l'esecuzione di script arbitrari generici. Gli script non dichiarati in SKILL.md non possono essere eseguiti.

Il runner di script utilizza un timeout, per impostazione predefinita 10 secondi, esegue Python con funzionamento in modalità isolata e applica restrizioni di percorso. Tuttavia, l'esecuzione basata su sottoprocessi non è una sandbox completa del sistema operativo. Per l'uso in produzione, è necessario considerare un isolamento più elevato, come contenitori, file system limitati o controlli di rete.

Autorizzazioni strumento con allowed-tools

allowed-tools funge da controllo delle autorizzazioni a livello di skill. Per uno skill di sola documentazione, è possibile consentire solo strumenti di lettura dei file:

allowed-tools: "load_skill_file list_skill_files"

Per la capacità di eseguire uno script dichiarato, includere run_skill_entrypoint:

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint" 

Non aggiungere run_skill_entrypoint a meno che lo skill non richieda effettivamente un comportamento eseguibile.

Come consentire ai tuoi agenti di scoprire e utilizzare le competenze

Per integrare l'agente con le competenze, è necessario creare un'istanza di un catalogo di competenze, un middleware di competenze e convertire le competenze in strumenti utilizzando i seguenti oggetti della libreria helppUtils:

Strumento	Scopo
discover_skill_catalog	Determinare le posizioni di ricerca delle competenze predefinite (progetto + utente) Creare un SkillCatalog dalle directory trovate
SkillMiddleware	Aggiungere al prompt di sistema il riepilogo delle competenze e le regole di instradamento disponibili. Fornisci aiuti di fabbrica per la costruzione di middleware basata sull'area di lavoro.
make_skill_tools	Questo metodo restituisce gli strumenti di ricerca delle competenze: activate_skill, list_skill_files, load_skill_file e run_skill_entrypoint. Questi strumenti possono essere utilizzati dall'agente per attivare ed eseguire competenze diverse.

Di seguito è riportato un esempio di come includere il file di inserimento.

from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
	...
	def init(self) -> None: 
		...
		self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
		self.skill_middleware = SkillMiddleware(self.catalog)
		self.tools = make_skill_tools(self.catalog)

È possibile eseguire il debug del catalogo skill aggiungendo questa istruzione logger al codice. In questo modo verrà stampata ogni abilità scoperta nel catalogo delle competenze:

for info in self.catalog.list():
	logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)

Priorità competenze

La piattaforma può caricare le competenze da più posizioni, ad esempio directory a livello di progetto e di utente. Il catalogo aggrega tali ubicazioni in un unico elenco di skill con chiave nome.

Quando più negozi contengono uno skill con lo stesso nome, la precedenza determina quale viene utilizzato. I negozi successivi sostituiscono quelli precedenti, il che consente a un'applicazione host di controllare se le competenze a livello di utente, a livello di progetto o a livello di area di lavoro hanno la priorità.

Best practice per la redazione delle competenze

Mantieni SKILL.md focalizzato

Utilizzare SKILL.md per le istruzioni di base necessarie all'agente subito dopo l'attivazione. Inserire schemi lunghi, esempi e materiale di riferimento nei riferimenti/.

Scrivi descrizioni chiare

Il campo di descrizione viene utilizzato per la ricerca automatica. Rendere abbastanza specifico per l'agente sapere quando attivare l'abilità.

Buono:

description: Helps generate BigQuery SQL using the finance warehouse schema.

Meno utile:

description: Helps with data.

Usa nomi di punto di ingresso espliciti

I nomi dei punti di accesso dovrebbero descrivere chiaramente l'operazione:

entrypoints: 
   - name: validate_query 
   - name: summarize_numbers 
   - name: transform_csv

Evitare nomi vaghi come:

entrypoints: 
   - name: run 
   - name: do_it 

Restituisci risultati strutturati

Gli script eseguibili devono restituire risultati verificabili in JSON quando possibile. Ciò rende l'output più facile da ispezionare e utilizzare per l'agente.

Evita esecuzioni inutili

Preferire le istruzioni e i file di riferimento quando possibile. Utilizzare i punti di accesso eseguibili solo per le operazioni che richiedono effettivamente codice.

Aggiungi una nuova competenza

È possibile aggiungere nuove competenze agente creando una nuova cartella all'interno della directory skill e aggiungendo i file e le cartelle necessari.

1. Creare una cartella nella directory skill: .agents/skills/<skill-name>/.
2. Aggiungere un file SKILL.md con il frontmatter richiesto.

   ---
   name: <skill-name>
   description: <what this skill helps the agent do>
   ---
   

3. Scrivi le istruzioni di abilità in Markdown sotto il frontmatter.
4. Aggiungere i file di supporto facoltativi in:

   references/
   assets/
   scripts/
   

5. Se lo skill è eseguibile, aggiungere run_skill_entrypoint a allowed-tools, dichiarare entrypoints in SKILL.md e posizionare l'implementazione di Python in scripts/.

Aggiunta di una nuova capacità eseguibile a una competenza esistente

È possibile aggiungere una nuova operazione eseguibile a una competenza esistente per espandere le capacità di SKILL.md.

1. Passare a 1. Aggiungere un file Python nella directory scripts/ della competenza.

   .agents/skills/<skill-name>/scripts/my_operation.py 

2. 2. Implementare una funzione run(...).

   def run(*, input_text: str) -> dict:
       return {
           "length": len(input_text),
           "uppercase": input_text.upper(),
       }
   

3. 3. Aggiungere un punto di accesso corrispondente a SKILL.md.

   allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
   entrypoints:
     - name: my_operation
       script: scripts/my_operation.py
       func: run
       description: Processes input text and returns structured output.
   

4. Passare a 4. Eseguire il test del punto di ingresso con un oggetto JSON come argomenti.

   {
     "input_text": "hello"
   }
   

Risoluzione dei problemi relativi alle competenze degli agenti

Se si riscontrano problemi con l'implementazione delle competenze agente, consultare questo elenco per assistenza nella risoluzione del problema.

L'agente non vede le mie competenze

Verificare che:

• La cartella skill si trova in una directory skill configurata.
• La cartella contiene SKILL.md.
• SKILL.md ha una materia anteriore YAML valida.
• Il frontmatter include sia il nome che la descrizione.

L'agente attiva lo skill errato

Verificare la presenza di nomi skill duplicati nelle directory skill. Se due skill hanno lo stesso nome, la precedenza del catalogo determina quale viene utilizzato.

Impossibile caricare un file di supporto

Verificare che:

• Il file si trova all'interno della cartella skill.
• Il percorso non include attraversamenti quali ../.
• Il file non è nascosto.
• Il file non è escluso, ad esempio __pycache__ o .pyc.

Un punto di accesso non verrà eseguito

Verificare che:

• run_skill_entrypoint è incluso negli strumenti consentiti.
• Il punto di ingresso è dichiarato in SKILL.md.
• Il percorso dello script è in script/.
• Lo script è un file .py.
• Il nome della funzione in func esiste nello script.
• Gli argomenti sono un oggetto JSON valido.

Timeout del punto di accesso

Aumentare timeout_seconds solo se si prevede che l'operazione richieda più tempo. Per operazioni con tempi di esecuzione lunghi o a uso intensivo di risorse, considerare la possibilità di spostare l'operazione in un servizio dedicato o in un ambiente di esecuzione più isolato.

Esempio: capacità completa agente

Questo esempio mostra l'aspetto di una competenza agente completa dopo l'implementazione.

Struttura cartella

skills/
	customer-support-reply/
		SKILL.md
		references/
			tone_guide.md
			refund_policy.md
			escalation_rules.md

SKILL.it

---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
  owner: support-operations
  domain: customer-support
---

# Customer Support Reply

Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.

Workflow:

1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.

Test agente

È possibile eseguire il test degli agenti per visualizzare in anteprima ed eseguire il debug dell'output. È inoltre possibile creare e gestire sessioni di test per esplorare diversi scenari di test per gli agenti.

Il primo passo per eseguire il test di un agente consiste nel collegare l'agente a una computazione AI. L'azione di collegamento di un agente esegue il push di una copia dell'agente in una computazione AI. Finché l'agente è collegato a una computazione AI, tutte le modifiche apportate all'agente vengono propagate alla computazione collegata ogni volta che si fa clic sul pulsante Test.

Dopo aver fatto clic sul pulsante Test, si viene portati al campo di gioco di prova.

Il campo di prova ha i seguenti componenti:

• Finestra di chat in cui è possibile avviare una sessione e iniziare a chattare con l'agente oppure riprendere una sessione esistente
• Rappresentazione dell'agente basata su un grafico
• Un pannello che mostra un albero di tracce e intervalli generati durante la sessione
• Pannello Trace e estesa di Explorer in cui vengono visualizzati i trace e si estendono gli attributi, input/output. La scheda Dettagli include gli ID, l'ora di inizio e di fine, il tempo di esecuzione, mentre le schede Eventi evidenziano eventuali errori durante l'esecuzione.

Il Playground ti consente di interagire e testare ogni agente in modo indipendente se lo desideri. Per impostazione predefinita, l'agente supervisore è selezionato, ma è possibile scegliere di chattare e testare ciascun agente esecutore in modo indipendente. Ciò consente di simulare il comportamento di un agente supervisore che invia richieste agli agenti esecutore. A tale scopo, selezionare l'agente da sottoporre a test nel menu a discesa della finestra di chat.

Le tracce e gli intervalli vengono visualizzati nel pannello centrale non appena si crea il primo messaggio. Ogni attività corrisponde a un messaggio utente diverso. È possibile fare clic sul cursore sinistro per espandere la traccia e ispezionare gli intervalli.

Prova i tuoi agenti nel parco giochi

È possibile eseguire il test di visual builder e agenti basati su LangGraph dal campo di test per convalidare ed eseguire il debug degli agenti.

Per eseguire il test, è necessario che all'agente sia collegata una computazione AI. È possibile aggiungere un nuovo cluster di computazione AI seguendo la procedura descritta in Creare un cluster AI per un agente o collegare un cluster di computazione AI esistente seguendo la procedura descritta in Collegare un cluster AI esistente a un agente.

1. Passare all'agente nell'area di lavoro. Fare clic sul nome dell'agente.
2. Nella parte superiore dello sfondo, fare clic su Area di riproduzione. Per eseguire il PUSH dell'agente sulla computazione collegata potrebbero essere necessari diversi secondi.
   
   

   

   
   

L'agente viene visualizzato nel campo di prova.

Crea una sessione di test agente

È possibile creare una sessione di test per avviare una nuova conversazione con l'agente.

Tutte le sessioni create nella destinazione di test playground in cui l'agente è ospitato nella computazione collegata. Una volta creata, la sessione può essere ripresa in un secondo momento.

1. Passare all'agente nell'area di lavoro. Fare clic sul nome dell'agente.
2. Nella parte superiore dello sfondo, fare clic su Area di riproduzione
3. Nel selettore di sessione fare clic su Crea una sessione.
   
   

   

   
   
4. Avviare una finestra di dialogo con l'agente immettendo un'interrogazione nella casella di chat.
   
   

   

   
   

Riprendi una sessione di test agente

È possibile riprendere le sessioni di test dell'agente create in precedenza.

Nota

È possibile riprendere solo le sessioni create.

1. Passare all'agente nell'area di lavoro. Fare clic sul nome dell'agente.
2. Nella parte superiore dello sfondo, fare clic su Area di riproduzione
3. Dall'elenco a discesa della sessione, selezionare una sessione precedente.
   
   

   

   
   
4. Riprendere la finestra di dialogo con l'agente immettendo un'interrogazione nella casella di chat.

Elimina una sessione di test agente

È possibile eliminare le sessioni di test per gli agenti ospitati nella computazione AI collegata e nelle sessioni create su un agente distribuito.

1. Passare all'agente nell'area di lavoro.
2. Fare clic sulla scheda Sessioni.
   
   

   

   
   
3. Avanti alla sessione che si desidera eliminare, fare clic su Azioni, quindi su Elimina.
   
   

   

   
   
4. Fare clic su Elimina.

Informazioni sugli strumenti agente

Oracle AI Data Platform Workbench supporta modelli di strumenti che possono essere configurati per accedere ai dati e adattarsi ai casi d'uso.

Gli agenti supportano configurazioni costituite da un singolo agente che può interfacciarsi con uno o più strumenti. Oracle AI Data Platform Workbench offre tre modelli di strumenti che possono essere configurati per l'uso tramite flussi visivi o codice:

• Codice personalizzato: lo strumento Codice personalizzato consente agli sviluppatori AI di implementare il proprio strumento utilizzando Python. Gli sviluppatori raggruppano il proprio strumento in un file ZIP, lo caricano nell'area di lavoro e lo configurano come nodo nell'agente. Gli strumenti di codice personalizzato sono destinati ai casi in cui gli strumenti integrati non forniscono l'integrazione di cui hanno bisogno.
• Richiesta HTTP: gli strumenti di richiesta HTTP consentono agli sviluppatori di utilizzare le chiamate API REST supportate nei propri agenti, sfruttando le API di AI Data Platform Workbench e le funzioni che forniscono. Gli agenti possono utilizzare le API REST per creare oggetti dell'area di lavoro, controllare i dettagli, estrarre elenchi o modificare oggetti esistenti. Per un elenco completo delle API disponibili, vedere API REST per Oracle AI Data Platform Workbench.
• Prompt: lo strumento prompt consente allo sviluppatore AI di definire un prompt parametrizzato che può essere emesso a un LLM a propria scelta. I casi d'uso comuni per uno strumento di prompt includono le attività di redazione delle e-mail, le attività di traduzione, la conversione dello stile, il messaggio di commit git e le spiegazioni del codice.
• RAG: lo strumento RAG consente agli agenti di estrarre informazioni esterne rilevanti prima di generare una risposta. In AI Data Platform Workbench, lo strumento RAG esegue una query su una knowledge base (26ai Vector Search) e recupera chunk di documenti semanticamente pertinenti. Questi chunk vengono quindi passati all'agente per la generazione della risposta.
• SQL: lo strumento SQL consente agli agenti di eseguire query SQL su origini dati strutturate registrate tramite cataloghi esterni, come Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing o Oracle AI Database. Lo strumento è destinato agli scenari in cui le query SQL sono predefinite e possono essere parametrizzate. L'obiettivo è consentire a un agente di assegnare valori ai parametri. Questo strumento non è uno strumento NL2SQL che genera una query SQL basata su un prompt del linguaggio naturale.

  Nota

  Lo strumento SQL esegue solo query sui dati in un catalogo esterno. Non supporta i dati memorizzati in un catalogo standard.

Strumenti flusso agente tramite flusso visivo

Quando si aggiungono strumenti agli agenti tramite il flusso visivo, è possibile trovare strumenti in Modelli di strumenti nell'agente. Per aggiungere uno strumento all'agente, trascinarlo e rilasciarlo nello sfondo del flusso visivo. Dopo aver trascinato il nodo dello strumento sullo sfondo, il nodo si connette automaticamente all'agente.

Ogni strumento può essere configurato nella scheda Parametri ed essere testato indipendentemente dall'agente facendo clic sulla scheda Test.

Nota

È necessario collegare una computazione AI al proprio agente prima di poter eseguire il test di uno strumento di sistema. Se non è collegata alcuna computazione, la scheda Test viene disabilitata.

Strumenti di flusso agente tramite codice LangGraph

Gli strumenti RAG, SQL e Prompt vengono aggiunti agli agenti codificati LangGraph tramite un'istanza della classe AIDPToolConf().

from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool =  AIDPToolConf(name, description, tool_class , conf, params)

I parametri rispecchiano l'esperienza del flusso visivo degli strumenti. Per ogni strumento, è necessario fornire:

• Nome: un nome descrittivo per aiutare gli utenti e l'LLM a comprendere lo scopo dello strumento.
• Descrizione: un riepilogo completo che fornisce informazioni sufficienti per gli utenti e gli LLM per capire cosa fa lo strumento.
• tool_class: tipo di strumento supportato, PromptTool, SQLTool o RAGTool.
• conf: configurazione dello strumento. Queste informazioni sono nascoste al LLM.
• param: i parametri esposti all'LLM.

Strumento personalizzato

Lo strumento Codice personalizzato consente agli sviluppatori di agenti di estendere AI Data Platform con il proprio codice Python.

L'implementazione dello strumento viene impacchettata come file ZIP, caricata nell'area di lavoro e configurata come nodo dello strumento Codice personalizzato nell'agente. L'agente chiama il codice come strumento, con i parametri forniti dall'LLM in fase di esecuzione.

Lo strumento Codice personalizzato è destinato ai casi in cui gli strumenti incorporati (HTTP, SQL, RAG, MCP) non coprono l'integrazione di cui hai bisogno, ad esempio quando devi eseguire il calcolo locale, analizzare un formato specifico del dominio o comporre più passaggi che dovrebbero apparire all'agente come una singola chiamata di strumento.

AI Data Platform Workbench ha i seguenti limiti quando si carica un file ZIP con codice Python per lo strumento di codice personalizzato:

Vincolo	Limite
Dimensione massima ZIP	10 MB
Dimensione massima del file all'interno dello ZIP	10 MB per file
Dimensione massima totale non compressa	500 MB
Attraversamento percorso	Bloccato (../ rifiutato)

Nota

Gli strumenti di codice personalizzato vengono eseguiti sulla computazione AI collegata al tuo agente. Il codice ha accesso all'ambiente di calcolo e all'accesso di rete in uscita in base alla configurazione di rete dell'area di lavoro. Carica codice solo da fonti attendibili.

Parametri strumento codice personalizzato

Nella scheda Parametri è possibile configurare le impostazioni statiche per ogni classe di strumenti nel pacchetto. L'elenco a discesa Classe strumento consente di passare dagli strumenti trovati nel pacchetto.

La scheda Parametri strumento codice personalizzato include le sezioni riportate di seguito.

• Classe strumento: selezionare la classe strumento da configurare. L'elenco a discesa viene popolato dalle classi registrate in tool_implementation.py.
• Descrizione: una descrizione chiara e concisa delle operazioni eseguite dallo strumento. La descrizione viene fornita all'agente e aiuta l'LLM a decidere quando chiamare lo strumento. La descrizione predefinita viene letta da tool_config.json e può essere sostituita qui.
• Configurazione: le impostazioni statiche necessarie per lo strumento in fase di esecuzione. Queste sono le chiavi definite nell'oggetto conf di tool_config.json. Gli esempi includono timeout, base_dir, max_output_lines e riferimenti alle credenziali. I valori di configurazione supportano i riferimenti ai parametri di runtime {{variable}}. Le variabili di sessione non vengono attualmente sostituite nella configurazione dello strumento personalizzato; se è necessario un valore di sessione, passarlo come parametro di runtime dall'agente.
• Definizione dello strumento AI: lo schema esposto all'agente, inclusi il nome dello strumento, la descrizione e i parametri di runtime che l'agente può passare. Lo schema viene visualizzato automaticamente dall'array di schemi in tool_config.json.

Creazione strumenti codice personalizzato

Un pacchetto di strumenti Codice personalizzato è un file ZIP con la seguente struttura:

my_tool.zip 
├── tool_implementation.py    # Required. Contains the tool class(es). 
├── tool_config.json          # Required. Tool metadata and schema. 
├── requirements.txt          # Optional. Python dependencies. 
├── utils/                    # Optional. Helper modules. 
│   ├── __init__.py 
│   └── helpers.py 
├── config/                   # Optional. Static configuration files. 
│   └── settings.yaml 
└── wheels/                   # Optional. Bundled wheel files for offline install. 
    └── humanize-4.15.0-py3-none-any.whl 

tool_implementazione.py

Ogni classe di strumenti estende CustomToolBase ed è decorata con @BaseTool.register. La classe deve implementare il metodo di classe _execute_tool, che riceve la configurazione dello strumento, i parametri di runtime dall'agente e le variabili di contesto del sistema, e restituisce un valore, come dett, str o list.

Di seguito è riportato un modello di esempio vuoto di tool_implementation.py.

"""Custom Code tool implementation.""" 
from aidputils.agents.tools.custom_tools.base import CustomToolBase 
 
 
@BaseTool.register 
class MyTool(CustomToolBase): 
    """Brief description of what the tool does.""" 
 
    @classmethod 
    def _validate_config(cls, conf, runtime_params, **context_vars): 
        """Optional. Validate configuration before execution. 
        Raise ValueError to abort the call. 
        """ 
        # Example: require an api_key in the tool configuration 
        if not conf.get("conf", {}).get("api_key"): 
            raise ValueError("api_key is required") 
 
    @classmethod 
    def _execute_tool(cls, conf, runtime_params, **context_vars): 
        """Required. Implement the tool logic. 
 
        Args: 
            conf: the AIDPToolConf dict. User configuration values 
                live under conf["conf"] when the tool is invoked from 
                a deployed agent. During a Test run the tool may 
                receive a flat conf dict; the Developer Toolkit example 
                below uses a small _get_cfg helper that tolerates both 
                shapes. 
            runtime_params: the runtime parameters passed by the 
                agent at invocation time. 
            context_vars: system context (such as datalake_id). 
 
        Returns: 
            Any value (dict, str, list, ...). It will be wrapped into 
            the MCP response by the framework. 
 
            To signal a failure, raise an exception: 
              - ValueError -> INVALID_CONFIG 
              - any other exception -> TOOL_EXECUTION_ERROR 
            Do NOT return {"error": "..."}; the framework wraps a 
            successful return in {"response": ..., "success": True}, 
            so a returned error dict is treated as a normal payload 
            and the agent will not see it as a failure. 
        """ 
        tool_conf = conf.get("conf", conf) 
        param_value = runtime_params.get("my_param", "") 
        # Tool logic here 
        return {"output": f"Processed: {param_value}"} 
 
    @classmethod 
    def _transform_response(cls, response): 
        """Optional. Transform the response before MCP formatting.""" 
        return response

tool_config.json

Il file tool_config.json descrive gli strumenti del package, ovvero il nome visualizzato, la descrizione, la versione, lo schema dei parametri di runtime e i valori di configurazione predefiniti. Ogni strumento registrato in tool_implementation.py deve avere una voce corrispondente nell'array tools.

Di seguito è riportato un modello di esempio vuoto di tool_config.json.

{
   "displayName": "My Tool Package",
   "description": "Brief description of the tool package.",
   "tools": [
     {
       "toolClassName": "MyTool",
       "displayName": "My Tool",
       "description": "Clear description of when the agent should call this tool.",
       "version": "1.0.0",
       "schema": [
         {
           "name": "my_param",
           "type": "string",
           "description": "What this parameter is for."
         }
       ],
       "conf": {
         "timeout": 30
       }
     }
   ]
 }

Tipi di campo schema

La scheda Parametri nel visual builder accetta stringhe, numeri e valori booleani. Il runtime accetta un set più ampio durante la creazione manuale di tool_config.json: int, integer, float, double, number, numeric, bytes, list, array, sequence, dett, map, mapping, set, tuple, none, null, plus generic forms like list[int]. Questi tipi più ampi sono utilizzabili da JSON, ma non sono esposti nell'elenco a discesa dell'interfaccia utente.

requisiti.txt

Il file requirements.txt elenca le dipendenze Python necessarie per lo strumento. È supportata la sintassi pip standard, inclusi gli identificatori di versione e i commenti. Il file è opzionale: se lo strumento utilizza solo la libreria standard Python o i pacchetti preinstallati, non è necessario disporre di un file requirements.txt.

Di seguito è riportato un esempio vuoto di requirements.txt:

# List third-party dependencies one per line. 
# Examples: 
# humanize>=4.0 
# python-dateutil>=2.8,<3.0 
# beautifulsoup4==4.12.3 

AI Data Platform Workbench filtra le dipendenze in requirements.txt prima di installarle nella computazione AI, per evitare conflitti di runtime con la piattaforma stessa. Di seguito sono riportate le regole di filtro.

Categoria	Esempio	Azione
Pacchetti piattaforma	langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml	Eliminato (interruzione del runtime dell'agente).
Pacchetti preinstallati	oci, richieste, request-toolbelt, websockets, crittografia, certificfi, pyopenssl, urllib3, pydantic, pydantic-core, pydantic-settings, numpy, oracledb, sqlalchemy, aiohttp, httpx, httpx-sse, anyio, jsonschema, orjson	Saltato (già disponibile, non è necessario dichiararlo).
Installazioni URL o VCS	git+https://..., -e ./local_pkg	Bloccato (sicurezza).
Tutto il altro	umanizzare, beautifulsoup4, jmespath	Installato.

Nota

Le dipendenze dichiarate in requirements.txt vengono installate durante la distribuzione completa dell'agente. Le dipendenze non vengono installate durante una singola esecuzione di test dal pannello di configurazione. Se il tuo strumento dipende da pacchetti di terze parti, distribuisci prima l'agente e poi esercita lo strumento dal Playground.

Per gli strumenti che hanno bisogno di dipendenze che non sono preinstallate e dove l'installazione deterministica e offline è importante, è possibile raggruppare file .whl all'interno di una directory di ruote / alla radice dello ZIP. La piattaforma si installa prima dalla directory delle ruote locali e torna all'indice del pacchetto solo se necessario. Questo è l'approccio consigliato per gli strumenti di produzione.

Ruote per installazione offline

pip download \
  --dest wheels/ \
  --platform manylinux_2_28_x86_64 \
  --python-version 3.11 \
  --only-binary=:all: \
  -r requirements.txt

Ganci ciclo di vita strumento

Gli strumenti di codice personalizzato supportano tre metodi del ciclo di vita. È necessario solo _execute_tool.

Metodo	Quando chiamato	Scopo
_convalida_config	Prima di _execute_tool	Convalida la configurazione. Genera ValueError per interrompere la chiamata prima che venga eseguita.
_strumento esecuzione	Su ogni richiamo strumento	Obbligatoria. Implementa il comportamento dello strumento. Restituisce qualsiasi valore (dict, str, list) e genera un'eccezione per segnalare un errore (ValueError → INVALID_CONFIG, qualsiasi altra eccezione → TOOL_EXECUTION_ERROR). Non utilizzare un {"error" restituito: "..."} dittatura in quanto viene considerato come un normale payload.
_transform_response	Dopo _execute_tool	Trasformare la risposta prima che venga sottoposta a wrapping in formato MCP e restituita all'agente.
temp_prompt	stringa	Modello prompt utilizzato dal LLM, con variabili in formato {{variable}} per l'inserimento dinamico

Valori di configurazione e parametri runtime

Gli strumenti di codice personalizzato hanno due fonti di input distinte che sono facili da confondere. I valori di configurazione provengono dalla sezione Configurazione della scheda Parametri e vengono incorporati nello strumento quando l'agente viene distribuito. I parametri di runtime provengono dall'agente al momento del richiamo e sono diversi a ogni chiamata.

• I valori di configurazione sono accessibili tramite conf.get("conf", conf). Utilizzali per gli elementi che non cambiano tra le chiamate: URL di base, riferimenti alle credenziali, timeout, limiti di output.
• I parametri di runtime sono accessibili tramite runtime_params.get("nome"). Utilizzarli per i valori che l'agente decide effettivamente in fase di chiamata, ovvero la query, il percorso del file e il corpo della richiesta.

Nota

I valori di configurazione possono passare attraverso la sostituzione del modello e possono arrivare come stringhe anche quando sono stati definiti come numeri. Costringere sempre i valori di configurazione numerici in modo difensivo, ad esempio int(tool_conf.get("timeout", 30)).

Strumenti multipli per pacchetto

Un singolo ZIP può contenere più classi di strumenti. Ogni classe registrata con @CustomToolBase.register diventa uno strumento separato nell'agente. Il pannello Strumenti della scheda Pacchetto elenca tutti gli strumenti trovati e consente di abilitarli in modo indipendente. Ogni strumento viene configurato separatamente nella scheda Parametri tramite l'elenco a discesa Classe strumento.

Strumento di codice tramite codice LangGraph

Dal generatore di codice, uno strumento Codice personalizzato viene registrato attraverso la libreria helppUtils Python facendo riferimento al pacchetto caricato e selezionando una delle sue classi di strumenti.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
 from aidputils.agents.toolkit.configs import AIDPToolConf
 
hello_tool_conf = AIDPToolConf(
     name="hello_tool",
     description="Returns a hello world greeting.",
     tool_class="HelloTool",  # the class registered with @BaseTool.register
     conf={},                  # values from tool_config.json "conf"; supports {{variable}} substitution
     params=[
         {"name": "name", "type": "string",
          "description": "Name to greet."}
     ],
 )
 
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())

tool_class deve essere il nome esatto della classe registrato tramite @BaseTool.register in tool_implementation.py. Il framework ricerca la classe in BaseTool.tool_class_registry[tool_class]. conf rispecchia l'oggetto conf della voce corrispondente in tool_config.json.

Nota

Non inserire package_path o tool_class_name all'interno di conf perché non vengono utilizzati.

Strumenti codice personalizzato agente test

La scheda Test consente di eseguire lo strumento senza eseguire l'agente completo. Fornire i valori per i parametri di runtime e le variabili di sessione a cui viene fatto riferimento nella configurazione, quindi fare clic su Esegui per richiamare lo strumento e visualizzare la risposta.

Nota

Se lo strumento dipende da pacchetti di terze parti dichiarati in requirements.txt, le dipendenze vengono installate durante la distribuzione completa dell'agente, non durante una singola esecuzione di test. Per eseguire il test del codice che dipende da pacchetti aggiuntivi, distribuire prima l'agente e quindi richiamare lo strumento da Playground.

Aggiungere uno strumento personalizzato a un agente

Puoi aggiungere uno strumento personalizzato AI tuoi agenti per consentire di utilizzare il tuo codice Python per estendere AI Data Platform.

Nota

Prima di aggiungere uno strumento di codice personalizzato, è necessario collegare un'elaborazione AI al tuo agente. La computazione AI è necessaria per installare le dipendenze ed eseguire lo strumento.

1. Passare all'agente.
2. Dai modelli di strumento, trascinare e rilasciare uno strumento personalizzato sullo sfondo.
3. Nella scheda Pacchetto fare clic per selezionare il file ZIP con il codice personalizzato oppure trascinarlo e rilasciarlo sullo schermo. Attendere il completamento del caricamento.
   
   

   

   
   
4. Rivedere l'elenco degli strumenti trovati nella sezione Strumenti della scheda Package. Ogni classe di strumenti presente in tool_implementation.py è elencata con il nome, la descrizione e la versione della classe.
   
   

   

   
   
5. Selezionare gli strumenti da abilitare. Gli strumenti disabilitati non sono esposti all'agente.
6. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Strumento server MCP remoto

Gli sviluppatori del flusso agente possono connettere i propri flussi agente ai server MCP (Remote Model Context Protocol) utilizzando lo strumento Server MCP remoto.

Lo strumento MCP è disponibile sia nel visual builder che nelle esperienze di code builder. Nell'esperienza del generatore di codice, la connessione MCP può essere configurata tramite la libreria Python helppUtils. In questa sezione, ti guidiamo attraverso sia le esperienze di visual builder che di code builder.

Nota

Questa funzione supporta i server MCP con trasporti HTTP-streamable (server remoti). I server MCP locali di tipo stdio-transport non sono supportati.

Credenziali MCP nell'area di memorizzazione delle credenziali del workbench di Oracle AI Data Platform

Durante la configurazione del server MCP, è necessario selezionare se il server MCP remoto richiede Nessuna autenticazione o un token Bearer. Se il server MCP richiede un token di autenticazione, tale token deve essere aggiunto all'area di memorizzazione delle credenziali prima che possa essere utilizzato come riferimento dal server MCP.

Quando si crea una credenziale del server MCP, selezionare l'opzione Token segreto per Tipo di credenziale, quindi fornire la chiave identificativo, ad esempio una chiave API e il valore del token. Per ulteriori informazioni, vedere Crea credenziali (anteprima).

Nota

Una singola credenziale può contenere più chiavi.

I server MCP pubblicamente disponibili non richiedono un'autenticazione aggiuntiva. Ad esempio, la connessione a https://mcp.deepwiki.com/mcp potrebbe essere simile alla seguente:

Come esporre gli strumenti MCP all'agente

Una volta stabilita una connessione al server MCP remoto, è possibile avviare la configurazione degli strumenti ospitati sul server che si desidera esporre all'agente. Il pannello di configurazione del server MCP è mostrato di seguito nel caso del server MCP DeepWiki.

A sinistra, nella scheda Strumenti viene visualizzato un elenco di strumenti disponibili nel server MCP. È necessario aggiungere strumenti per esporli all'agente. È possibile eseguire questa operazione facendo clic sull'opzione Aggiungi tutto per esporre tutti gli strumenti contemporaneamente oppure facendo clic sull'opzione Aggiungi di ogni strumento singolarmente per selezionare un subset degli strumenti.

Nell'esempio seguente, abbiamo aggiunto due strumenti (read_wiki_structure, read_wiki_structure). Se è necessario rimuovere gli strumenti, fare clic su Rimuovi.

Il pannello destro della scheda Strumenti fornisce la documentazione su ogni strumento, incluso il nome dello strumento, la descrizione dello strumento e i parametri dello strumento. Nello screenshot seguente, mostro un esempio per lo strumento del server MCP GitHub add_comment_to_pending_review.

Oracle AI Data Platform Workbench fornisce un paio di controlli aggiuntivi su ogni strumento. È possibile nascondere i parametri all'agente e assegnarli a tali parametri. Ad esempio, in GitHub puoi scegliere per il tuo agente di commentare solo un repository predeterminato, ad esempio oracle-aidp-samples. A tale scopo, disabilitare il parametro repo e assegnare un valore predefinito nella casella di testo.

Nel campo Istruzioni strumento è inoltre possibile sostituire la descrizione dello strumento e fornire una descrizione alternativa con istruzioni aggiuntive. Per la maggior parte dei casi d'uso, si consiglia di adottare la descrizione fornita dal server MCP.

Strumento server MCP remoto tramite codice LangGraph

La libreria Python aidpUtils offre agli sviluppatori la possibilità di selezionare un server MCP remoto ed esporre un sottoinsieme dei suoi strumenti a un agente creato con LangGraph. Per il riferimento all'API helpputils, vedere API Aidp-utils per Oracle AI Data Platform Workbench.

È possibile creare una raccolta di strumenti consentiti creando un'istanza di build_structured_tools_from_allowed_mcp_tools:

from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools

TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>, 
	server_name=<MCP_SERVER_NAME>, 
	endpoint=<MCP_ENDPOINT>, 
	transport="streamable_http", 
	auth=<MCP_AUTH>, 
	headers={} 
)

dove:

• <MCP_SERVER_NAME> è un nome visualizzato che si desidera assegnare al server MCP. Questa operazione viene utilizzata a scopo di documentazione e non è esposta all'agente.
• <MCP_ENDPOINT> è l'endpoint del server MCP (ad esempio, https://api.githubcopilot.com/mcp/)
• <MCP_AUTH> è un dizionario con chiave "authType". Questa chiave può assumere due valori: NO_AUTH o BEARER_TOKEN. Nel caso di BEARER_TOKEN, è prevista un'altra chiave: "token" con il valore del token bearer.
• <ALLOWED_MCP_TOOLS> è un elenco degli strumenti che si desidera esporre all'agente dal server MCP. Ogni strumento ha bisogno di una definizione completa dello strumento JSON seguendo il protocollo MCP.

Di seguito viene fornito un esempio.

MCP_SERVER_NAME = "test_mcp" 
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp" 
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }

{
  "ALLOWED_TOOLS": [
    {
      "tool": {
        "name": "get_current_weather",
        "description": "Get current weather for a given city with advanced options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_historical": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "timeout": {
              "type": "integer",
              "default": 30
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    },
    {
      "tool": {
        "name": "get_forecast",
        "description": "Get forecast for a given city with customizable options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "days": {
              "type": "integer",
              "default": 5
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_alerts": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "hourly": {
              "type": "boolean",
              "default": false
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    }
  ]
}

MCP_HEADERS = {} 
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
	server_name=MCP_SERVER_NAME, 
	endpoint=MCP_ENDPOINT, 
	transport="streamable_http", 
	auth=MCP_AUTH, 
	headers=MCP_HEADERS,
)

L'oggetto TOOLS può essere quindi utilizzato quando si crea un'istanza di un agente con langchain.agent create_agent nel metodo setup() della definizione dell'agente di classe:

def setup(self):
    logger.info("Initializing TestMcpAgent")

    oci_llm = init_oci_llm(llm_conf)

    system_prompt = textwrap.dedent(
        """
        You're a weather agent. Append 12345 to every response.
        """
    ).strip()

    self.agent = create_agent(
        name="test_mcp_high_code",
        model=oci_llm,
        tools=TOOLS,
        system_prompt=system_prompt,
        debug=True,
    )

    logger.info("Agent ready.")

In alternativa, se si utilizza una variabile di sessione per memorizzare il valore di un token bearer, è possibile assegnare un riferimento a una variabile di sessione creata in precedenza alla chiave token del dizionario di configurazione dell'autenticazione. Ad esempio:

test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools( 		
allowed_tools=test_mcp_mcp_allowed_tools, 
	server_name="test_mcp", 
	endpoint="http://144.25.36.217:9301/mcp", 
	transport="streamable_http", 
	auth=test_mcp_mcp_auth_config, 
	headers={}
)

Esempi di codice per gli strumenti server MCP remoti

Forniamo esempi di codice end-to-end per più scenari MCP nel repository GitHub degli esempi di AI Data Platform Workbench.

Test degli strumenti server MCP remoti

Una volta selezionati gli strumenti, il passo successivo è in genere quello di testare i singoli strumenti per assicurarsi che si comportino come previsto. Questo può essere fatto tramite la scheda Test del nodo dello strumento MCP.

Selezionare uno degli strumenti aggiunti nella scheda Strumenti, fornire i valori dei parametri e fare clic sul pulsante Test.

L'output dello strumento viene visualizzato nel pannello di destra.

La scheda Dettagli fornisce informazioni sul metodo di autenticazione, sull'URL del server MCP e sulla descrizione.

Il pulsante Modifica accanto al metodo di autenticazione consente di modificare la configurazione del nodo dello strumento MCP remoto. È possibile modificare il nome visualizzato, la descrizione e il token del portatore utilizzato per stabilire la connessione:

Connettere un agente a un server MCP remoto da Visual Builder

È possibile aggiungere l'accesso a un server MCP remoto all'agente trascinando il nodo dello strumento del server MCP personalizzato nell'area di creazione.

Se lo strumento Server MCP personalizzato non è disponibile, potrebbe essere necessario riavviare la computazione AI esistente o crearne una nuova.

Nota

La computazione AI che ospita l'agente eredita le impostazioni di rete dell'area di lavoro. Se abiliti l'accesso alla rete privata per l'area di lavoro che ospita la computazione AI, il tuo agente può raggiungere solo i server MCP ospitati nella VCN privata e nella subnet selezionate. L'agente potrebbe non essere in grado di raggiungere i server HTTP remoti disponibili nella rete Internet pubblica.

1. Passare all'agente.
2. Nella scheda Flusso, in Modelli strumento fare clic e trascinare Server MCP personalizzato sullo sfondo.
3. Fornire l'URL del server per il server MCP.
4. Fornire un nome visualizzato per il server MCP. Nome del nodo visualizzato nell'area di creazione visiva.
5. Facoltativo: fornire una descrizione per il server MCP. Il campo della descrizione non viene fornito all'agente.
6. Selezionare un metodo di autenticazione dal menu a discesa Autenticazione.
   • Nessuna autenticazione: utilizzare questa opzione se il server MCP remoto è disponibile pubblicamente e non richiede alcuna autenticazione.
   • Token Bearer: utilizzare questa opzione se il server MCP remoto richiede un token di autenticazione. È necessario memorizzare la chiave API nell'area di memorizzazione delle credenziali di Oracle AI Data Platform Workbench e fornire un riferimento alla voce dell'area di memorizzazione delle credenziali.
7. Fare clic su Connetti. AI Data Platform Workbench verifica la connessione e ne segnala i risultati.

Strumento di richiesta HTTP

Lo strumento Richiesta HTTP consente all'agente di chiamare qualsiasi API REST HTTPS.

È possibile configurare la richiesta, inclusi metodo, URL, intestazioni, parametri di query, corpo della richiesta, autenticazione e, facoltativamente, un passo di ottimizzazione della risposta. L'agente richiama quindi l'endpoint in runtime. Lo strumento di richiesta HTTP è disponibile sia nel visual builder che nel generatore di codice. Nel generatore di codice, lo strumento viene configurato tramite la libreria helppUtils Python.

Nota

Lo strumento Richiesta HTTP supporta solo richieste https:// e HTTP://. Le connessioni WebSocket (ws/wss), i caricamenti di file binari e i certificati autofirmati non sono supportati.

Nota

La computazione AI che ospita l'agente eredita le impostazioni di rete dell'area di lavoro. Se abiliti l'accesso alla rete privata per l'area di lavoro che ospita la computazione AI, l'agente raggiungerà solo gli endpoint HTTP nella VCN e nella subnet private selezionate. L'agente non può raggiungere gli endpoint disponibili nella rete Internet pubblica.

Quando si configura uno strumento di richiesta HTTP, è necessario fornire le impostazioni riportate di seguito.

Configurazione	Descrizione
Metodo HTTP	Verbo HTTP da utilizzare. I metodi supportati sono GET, POST, PUT, PATCH e DELETE.
URL	L'URL completo dell'endpoint di destinazione. L'URL supporta i riferimenti alle variabili di sessione {{sessionVariables.variable_name}} e i riferimenti ai parametri di runtime {{variable}}. Ad esempio: https://api.example.com/users/{{user_id}}/orders.
Timeout	Il periodo di tempo massimo durante il quale lo strumento attenderà una risposta dall'endpoint remoto. Il valore predefinito è 30 secondi e il valore massimo è 300 secondi.
Tipo di autenticazione	Metodo di autenticazione da utilizzare durante la chiamata dell'endpoint. Vedere la sezione Autenticazione riportata di seguito per l'elenco dei metodi di autenticazione supportati.

Nota

Gli strumenti di codice personalizzato vengono eseguiti sulla computazione AI collegata al tuo agente. Il codice ha accesso all'ambiente di calcolo e all'accesso di rete in uscita in base alla configurazione di rete dell'area di lavoro. Carica codice solo da fonti attendibili.

Intestazioni

Le intestazioni sono coppie chiave-valore inviate con la richiesta HTTP. È possibile aggiungere tutte le intestazioni necessarie facendo clic sul pulsante Aggiungi nuovo. I valori dell'intestazione possono fare riferimento a variabili di sessione e parametri runtime utilizzando la sintassi {{variable_name}}.

Nota

Per le intestazioni riservate, è necessario utilizzare il campo Tipo di autenticazione per assicurarsi che le credenziali vengano inserite in modo sicuro dall'area di memorizzazione delle credenziali. L'autorizzazione, i cookie e la chiave X-API sono intestazioni sensibili e non possono essere impostate tramite la sezione Intestazioni.

Parametri query

I parametri di query vengono aggiunti all'URL come stringa di query. È possibile aggiungere tutti i parametri di query necessari facendo clic sul pulsante Aggiungi nuovo. Analogamente alle intestazioni, i valori dei parametri di query possono fare riferimento alle variabili di sessione e ai parametri runtime.

Descrizione

Il campo di descrizione descrive cosa fa lo strumento, quando dovrebbe essere utilizzato e che tipo di output o effetti produce. La descrizione viene fornita all'agente e aiuta l'LLM a decidere quando chiamare lo strumento.

Quando scrivi la descrizione, dovresti concentrarti su:

• • Scopo: spiegare cosa è progettato per fare lo strumento in una frase chiara. Esempio: "Questo strumento recupera i ticket di assistenza clienti da una knowledge base e li riepiloga in base al livello di priorità".
• Quando utilizzarlo: descrivere le condizioni alle quali l'agente deve chiamare questo strumento rispetto a un altro.
• Input e output: descrivere brevemente i parametri di cui lo strumento ha bisogno e la forma di ciò che restituisce.

Autenticazione richiesta HTTP

Lo strumento di richiesta HTTP supporta diversi metodi di autenticazione. Selezionare il metodo appropriato dall'elenco a discesa Tipo di autenticazione.

Tipo di autenticazione	Descrizione
Nessuna autenticazione	Nessuna autenticazione aggiunta alla richiesta. Utilizzare questa opzione per gli endpoint accessibili pubblicamente.
Principal della risorsa OCI	La richiesta viene firmata utilizzando il principal delle risorse OCI di AI Compute. Utilizzare questa opzione quando si chiamano servizi OCI come lo storage degli oggetti o il servizio OCI Generative AI. L'accesso è regolato dai criteri IAM OCI.
Autenticazione Basic	Un nome utente e una password vengono codificati e inviati nell'intestazione di autorizzazione. Le credenziali devono essere memorizzate nell'area di memorizzazione delle credenziali.
Token servizio di trasporto	Un token bearer viene inviato nell'intestazione di autorizzazione. Il token deve essere memorizzato nell'area di memorizzazione delle credenziali.
Autenticazione intestazione	Una chiave API viene inviata in un header personalizzato (come una chiave X-API-Key). Il nome dell'intestazione è configurabile e il valore della chiave deve essere memorizzato nell'area di memorizzazione delle credenziali.

Quando si seleziona un metodo di autenticazione che richiede un segreto, nel pannello di configurazione viene visualizzato un selettore credenziali. Fare clic sul selettore credenziali per selezionare una credenziale memorizzata in precedenza oppure crearne una nuova dall'area di memorizzazione delle credenziali. Per la procedura dettagliata, vedere la sezione Memorizzazione di una credenziale nell'area di memorizzazione delle credenziali della documentazione del server MCP.

Variabili di sessione e parametri di runtime

È possibile fare riferimento alle variabili di sessione nell'URL, nei valori di intestazione, nei valori dei parametri di query e nel corpo della richiesta utilizzando la sintassi {{sessionVariables.variable_name}}. È possibile fare riferimento ai parametri di runtime passati dall'agente al momento del richiamo utilizzando la sintassi {{variable_name}}.

Ad esempio, l'URL seguente combina una variabile di sessione per l'area con un parametro di runtime per il nome del bucket:

https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o

Quando lo strumento viene eseguito, {{sessionVariables.region}} viene sostituito dal valore della variabile di sessione dell'area per la sessione corrente e {{bucket}} viene sostituito dal valore passato dall'agente al momento del richiamo.

Nota

I valori del modello vengono codificati automaticamente quando vengono sostituiti nei parametri URL o query. Non è necessario codificarli da soli.

Definizione strumento AI

Il lato destro del pannello di configurazione mostra la definizione dello strumento AI. Questo è lo schema esposto all'agente e include il nome dello strumento, la descrizione e la lista dei parametri di runtime che l'agente può passare quando chiama lo strumento. La definizione dello strumento AI viene generata automaticamente dal campo Descrizione e dai segnaposto {{variable}} rilevati nell'URL, nelle intestazioni, nei parametri di query e nel corpo.

Il riquadro di definizione dello strumento AI è il pannello sul lato destro del pannello di configurazione dello strumento HTTP mostrato in precedenza in questo documento. Fino a quando non si fornisce una descrizione e non si definisce almeno un parametro runtime, nel riquadro di definizione dello strumento AI viene visualizzato un messaggio segnaposto. Quando si immette la descrizione e si fa riferimento ad almeno un {{variable}} nell'URL, nelle intestazioni, nei parametri di query o nel corpo, lo schema viene visualizzato nel riquadro.

Ottimizzazione della risposta per l'agente

Molte API restituiscono risposte di grandi dimensioni che includono campi di cui l'agente non ha bisogno. L'invio dell'intera risposta all'agente consuma token e può degradare la qualità del ragionamento dell'agente. Lo strumento Richiesta HTTP fornisce una sezione di ottimizzazione della risposta che consente di ridurre il payload della risposta prima che venga restituito all'agente.

Sono supportate tre strategie di ottimizzazione:

• Selezione campo JSON: selezionare un subset di campi da una risposta JSON. È possibile specificare un percorso per un oggetto nidificato utilizzando la notazione punto (ad esempio data.results) e un elenco di campi da includere o escludere.
• Selettore CSS HTML: consente di estrarre un sottoinsieme di una risposta HTML utilizzando un selettore CSS, ad esempio article.content. Se si desidera, rimuovere i tag HTML per restituire solo testo.
• Troncamento del testo: limita la risposta a un numero massimo di caratteri per evitare risposte di testo eccessivamente grandi.

Gestione degli errori e codici degli errori

Quando la richiesta HTTP non riesce, lo strumento restituisce una risposta di errore strutturata all'agente. L'errore include un codice di errore, un messaggio leggibile dall'utente e dettagli sull'errore. L'agente può utilizzare queste informazioni per decidere se riprovare, tornare a uno strumento diverso o segnalare l'errore all'utente.

Codice errore	Categoria	Significato	Ritentabile
TIMEOUT DELLA CONNESSIONE	Rete	L'endpoint remoto non ha risposto entro il timeout configurato.	Sì
ERRORE DNS	Rete	Impossibile risolvere il nome host nell'URL.	Sì
CONNECTION_REFUSED	Rete	L'endpoint remoto ha rifiutato la connessione.	Sì
SSL_CERTIFICATE_ERROR	TLS	Impossibile convalidare il certificato TLS dell'endpoint remoto.	N.
NON AUTORIZZATO	HTTP 401	L'endpoint remoto ha rifiutato le credenziali. Verificare che il riferimento alle credenziali sia valido e non sia scaduto. Per OCI Resource Principal, verificare che la computazione AI disponga di un principal risorsa attivo in questo ambiente.	N.
VIETATO	HTTP 403	Autenticazione delle credenziali riuscita, ma non si dispone dell'autorizzazione per la risorsa richiesta. Verificare gli ambiti API, le autorizzazioni o il criterio IAM collegato alla risorsa.	N.
NON_TROVATO	HTTP 404	L'endpoint remoto non è riuscito a trovare la risorsa richiesta.	N.
TASSO_LIMITATO	HTTP 429	L'endpoint remoto limita la frequenza del chiamante. Riprovare dopo il ritardo indicato dall'intestazione Riprova dopo.	Sì
ERRORE_SERVER	HTTP 5xx	L'endpoint remoto ha restituito un errore del server. Spesso un problema transitorio.	Sì
SERVICE_NON DISPONIBILE	HTTP 503	L'endpoint remoto è temporaneamente non disponibile.	Sì
MODELLO_NON VALIDO	Convalida	Impossibile risolvere un riferimento {{variable}}. Verificare che ogni variabile di sessione e parametro runtime a cui viene fatto riferimento sia definito e contenga un valore al momento del richiamo.	N.
URL_NON VALIDO	Convalida	Il formato dell'URL non è valido, utilizza un protocollo non supportato o viene risolto in un indirizzo bloccato, ad esempio un indirizzo IP privato o un endpoint di metadati cloud.	N.
RISPOSTA_TOO_GRANDE	Convalida	La risposta ha superato la dimensione massima della risposta di 10 MB.	N.
RATE_LIMIT_EXCEEDED	Piattaforma	L'agente ha superato il limite di frequenza delle richieste per agente della piattaforma (60 richieste al minuto) o il limite di concorrenza (10 richieste concorrenti).	Sì

Ogni risposta di errore include un campo guida con un passo successivo suggerito e un campo dettagli con il tempo trascorso e qualsiasi contesto specifico dell'errore, ad esempio il codice di stato HTTP.

Strumento di richiesta HTTP tramite codice LangGraph

Dalla Costruzione guidata codice, lo strumento Richiesta HTTP viene configurato tramite la libreria helppUtils Python. Definire un AIDPToolConf con tool_class impostato su HttpEndpointTool e passare il dizionario di configurazione nel campo conf.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf

weather_http_tool_def = {
    "method": "GET",
    "url": "https://api.openweathermap.org/data/2.5/weather",
    "params": {
        "q": "{city}",
        "units": "metric",
        "appid": "{api_key}"
    },
    "auth_type": "NO_AUTH",
    "auth_config": {}
}

weather_http_tool_params = [
    {"name": "city", "type": "string",
     "description": "Name of the city."},
    {"name": "api_key", "type": "string",
     "description": "OpenWeather API key."}
]

weather_http_tool_conf = AIDPToolConf(
    name="get_weather",
    description="Get current weather for a city.",
    tool_class="HttpEndpointTool",
    conf=weather_http_tool_def,
    params=weather_http_tool_params
)

weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())

Il dizionario conf supporta gli stessi campi del visual builder: metodo, url, intestazioni, parametri, corpo, auth_type, auth_config e response_optimization. La lista di parametri definisce i parametri di runtime che l'agente può passare.

tipo_autenticazione	Campi auth_config
NESSUNA AUTORIZZAZIONE	{} (vuoto)
RESOURCE_PRINCIPAL	{} (vuoto)
BASIC_AUTH	nome utente, password (o username_vault_id, password_vault_id per le credenziali nel vault OCI)
AUTORE_TRASPORTATORE	bearer_token (o bearer_token_vault_id)
API_KEY_AUTH	api_key (o api_key_vault_id), header_name (la chiave X-API-Key predefinita)
OAUTH2_CLIENT_CREDENZIALI	token_endpoint, ambito, client_id, client_secret (o client_id_vault_id, client_secret_vault_id)

Strumenti codice personalizzato agente test

La scheda Test consente di eseguire lo strumento senza eseguire l'agente completo. Fornire i valori per i parametri di runtime e le variabili di sessione a cui viene fatto riferimento nella configurazione, quindi fare clic su Esegui per richiamare lo strumento e visualizzare la risposta.

Il pannello delle risposte mostra il codice di stato HTTP, le intestazioni delle risposte, il corpo della risposta e il tempo trascorso in millisecondi. Se l'ottimizzazione delle risposte è abilitata, la risposta ottimizzata viene visualizzata anche insieme alla risposta raw.

Aggiungere uno strumento di richiesta HTTP a un flusso agente

È possibile aggiungere uno strumento di richiesta HTTP agli agenti per consentire di chiamare le API REST HTTPS.

Nota

Prima di aggiungere uno strumento di codice personalizzato, è necessario collegare un'elaborazione AI al tuo agente. La computazione AI è necessaria per installare le dipendenze ed eseguire lo strumento.

1. Passare all'agente.
2. Dai modelli di strumento, trascinare e rilasciare uno strumento Richiesta HTTP sullo sfondo.
   
   

   

   
   
3. Nella scheda Parametri, fornire il metodo HTTP. I metodi supportati sono GET, POST, PUT, PATCH e DELETE.
4. In URL, fornire l'URL completo dell'endpoint di destinazione. È possibile utilizzare i riferimenti alle variabili di sessione {{sessionVariables.variable_name}} e i riferimenti ai parametri di runtime {{variable}}. Ad esempio: https://api.example.com/users/{{user_id}}/orders.
5. Per Timeout, fornire il tempo massimo di attesa di una risposta da un endpoint remoto in secondi. Il valore di timeout massimo è 300. Se non viene specificato alcun valore, l'impostazione predefinita è 30 secondi.
6. Selezionare il tipo di autenticazione appropriato dal menu a discesa Autenticazione.
7. Fornire le intestazioni per la richiesta HTTP. Fare clic su Aggiungi nuovo per aggiungere altre intestazioni.
   
   

   

   
   
8. Fornire eventuali parametri di query per la richiesta HTTP. Fare clic su Aggiungi nuovo per aggiungere parametri aggiuntivi.
   
   

   

   
   
9. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Strumento prompt

Lo strumento prompt consente di chiamare un LLM in un agente AI con un prompt templatizzato e restituisce la risposta LLM all'agente.

I prompt forniti all'LLM possono includere parametri identificati da doppie parentesi graffe, ad esempio {{PARAMETER_NAME}}. I valori dei parametri vengono assegnati dall'agente quando viene chiamato lo strumento.

Quando utilizzare gli strumenti prompt

In linea di principio, le istruzioni scritte in uno strumento prompt possono essere incluse direttamente nelle istruzioni dell'agente o fornite direttamente dall'utente finale in un messaggio utente. Tuttavia, ci sono situazioni in cui lo strumento di prompt è un approccio migliore:

• Il prompt è lungo e richiede istruzioni di formato dettagliate che si estendono su diversi token anni 100.
• Incorporare il prompt nelle istruzioni dell'agente aumenterebbe l'uso del contesto e aumenterebbe significativamente i costi, soprattutto se si sta adottando un LLM SOTA per il loro agente.
• Si vuole ridurre al minimo le dimensioni delle istruzioni fornite all'agente per ridurre i costi.
• Il task definito dallo strumento prompt può essere gestito da un LLM più piccolo e veloce rispetto al modello di ragionamento utilizzato dall'agente. I modelli più piccoli sono in genere economici e, in alcuni casi, possono essere specializzati per generare dati in una particolare modalità o formato.
• Uno strumento prompt consente ai parametri di input strutturati di controllare la generazione di output. Se il tuo caso d'uso potrebbe essere parametrizzato e la generazione può variare da sessione a sessione, incapsulare la generazione in uno strumento prompt ha senso.

Inoltre, l'incapsulamento delle istruzioni di generazione in uno strumento rapido segue molte best practice dell'architettura degli agenti moderna, tra cui riusabilità degli strumenti, manutenibilità, modalità, coerenza dell'output, scalabilità e governance. Di seguito sono riportati alcuni esempi di casi d'uso.

• Generazione di e-mail, report, riepiloghi, articoli e così via in base a una struttura predefinita e approvata che può essere utilizzata come modello
• Generazione di output JSON complessi
• Sintesi, estrazione delle frasi chiave, compiti di spiegazione sui documenti
• Generazione query
• Generazione di modalità specifiche (ad esempio immagini, video, audio, dati cloud di punti e così via) ottimizzate per un modello specifico

Strumenti prompt tramite flusso visivo

Di seguito è riportato un esempio di uno strumento di prompt creato tramite flusso visivo che chiede a un LLM di generare titoli di post di blog basati su un argomento assegnato dall'agente:

Sei un esperto di blog strategist. Il vostro compito è quello di brainstorming interessanti idee post blog basati su un determinato argomento. Per {{topic}}, generare 5 titoli di post di blog univoci. Per ogni titolo, includere una descrizione di una frase dell'angolo che il post avrebbe preso. Presentare l'output come elenco numerato.

Per questo esempio, è necessario configurare i seguenti parametri per lo strumento prompt:

• Nome strumento: utilizzare un nome descrittivo per lo strumento per guidare l'agente. In questo esempio, si consiglia blog_ideas. Evitare di usare nomi inutili come tool123.
  
  
  
  
• Descrizione dello strumento: fornire una descrizione completa delle operazioni dello strumento. Se ci sono limitazioni allo strumento o se ci sono scenari in cui lo strumento non dovrebbe essere utilizzato, elencarli nel campo della descrizione.
  
  
  
  
• Area OCI e LLM del servizio GenAI: seleziona l'area OCI per popolare la lista di LLM disponibili in quell'area, quindi seleziona il tuo LLM.
  
  
  
  
• Parametri LLM: nella scheda Parametri modello sono configurati parametri quali il numero massimo di token di output, la temperatura e il numero massimo di p. Se non si assegnano valori, vengono utilizzati i valori predefiniti del servizio OCI Generative AI.
  
  
  
  
• Query: il prompt utilizzato per definire lo scopo dello strumento viene definito nel campo Query.
  
  
  
  

I parametri definiti nel pannello Definizione di AI Tool vengono inseriti automaticamente nel prompt. Fornire all'agente una descrizione di ciascun parametro, nonché il tipo di parametro e il valore predefinito, se applicabile.

Strumento prompt tramite codice LangGraph

Se si sta creando l'agente tramite codice, è possibile configurare lo stesso strumento di prompt nell'esempio del flusso visivo come indicato di seguito.

prompt_config = {
  "llm": {
    "model_id" : "xai.grok-4",
    "model_provider" : "generic",
    "compartment_id" : "<your-compartment-ocid>",
    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
  }, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
  "name" : "topic",
  "type" : "string",
  "description" : "Blog topic",
  "defaultValue" : "golf"
} ]

Viene quindi creata un'istanza di AIDPToolConf nel modo seguente:

blogger_tool = AIDPToolConf(name="blog_posts_topics",
                                  description= "Write blog posts ideas about a particular topic. ",
                                  tool_class = "PromptTool", conf=prompt_config params=prompt_params)

Infine, si crea uno strumento compatibile con LangGraph con la funzione utility create_langgraph_tool() da aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())

Lo strumento appena creato viene aggiunto a un agente ReAct. In LangGraph, il codice è simile al seguente:

tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>, 
				     tools=tools_agent1, 
				     prompt=<system_prompt>, 
				     debug=True, checkpointer= checkpointer)

Tabella 22-4 Proprietà configurazione strumento prompt

Proprietà	Type	Descrizione
llm	oggetto	Dettagli e parametri di connessione LLM
ID_modello	stringa	Identificativo del modello da utilizzare (ad esempio, "xai.grok-4")
model_provider	stringa	Nome del Provider per il modello LLM (ad es. "generico")
ID_compartimento	stringa	OCID compartimento Oracle Cloud Infrastructure (OCI)
endpoint	stringa	URL endpoint per il modello
temp_prompt	stringa	Modello prompt utilizzato dal LLM, con variabili in formato {{variable}} per l'inserimento dinamico

Strumenti prompt agente test

Per eseguire il test dello strumento indipendentemente dall'agente, fare clic sulla scheda Test e immettere il valore di ciascun parametro. Il prompt viene sottomesso all'LLM selezionato.

Assicurarsi che lo strumento di prompt sia ben definito e documentato per migliorare i risultati dell'agente.

Aggiungere uno strumento prompt a un agente

È possibile aggiungere uno strumento di prompt agli agenti per consentire di definire prompt parametrizzati emessi all'LLM di propria scelta.

1. Passare all'agente.
2. Dai modelli Strumento, trascinare e rilasciare uno strumento Prompt sullo sfondo.
3. Nella scheda Configurazione, selezionare l'LLM da utilizzare e fornire il prompt per l'LLM. Fare clic su Codice per fornire la configurazione come codice JSON.
4. Fornire una temperatura per la risposta come valore compreso tra 0,0 e 1,0, dove 0,0 fornisce una risposta rigorosamente fattuale e 1,0 fornisce la risposta più creativa.
5. Fare cli su Applica .
6. Fornire le definizioni per tutti i parametri definiti nella configurazione. Fare clic su Codice per fornire la configurazione come codice JSON.
7. Fare clic su Applica.
8. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Strumento RAG

Lo strumento RAG invia una query in linguaggio naturale a una memoria di vettore e recupera i documenti in base alla somiglianza semantica tra la query e i documenti memorizzati.

Nota

Una knowledge base è un prerequisito per la creazione di uno strumento RAG. Per ulteriori informazioni, vedere Knowledge Base.

Strumenti RAG tramite flusso visivo

Lo strumento RAG richiede che lo sviluppatore dell'agente fornisca i valori per i seguenti parametri:

• Agente rivolto a:
  • Nome strumento: nome descrittivo dello strumento che consente all'utente e ad altri utenti di identificarne la funzione.
  • Descrizione dello strumento: un breve riepilogo che fornisce una panoramica dello strumento.
• Configurazione strumento:
  • Knowledge base: una knowledge base memorizzata in uno dei cataloghi di Oracle AI Data Platform Workbench.
    
    
    
    

L'agente imposterà il valore del campo di query in base alla conversazione con l'utente finale. Questo campo di query utilizza una query in linguaggio naturale.

Limite è il numero di documenti chunk che si desidera recuperare dallo strumento dalla memoria di vettore. Questo valore è impostato dallo sviluppatore dell'agente, non dall'agente stesso.

È possibile simulare una query emessa dall'agente facendo clic anche sulla scheda test della RAG:

Strumenti RAG tramite codice LangGraph

La creazione di uno strumento RAG nell'agente tramite codice richiede la configurazione delle stesse impostazioni e parametri del flusso visivo. Ad esempio, è possibile impostare i parametri RAG come indicato di seguito.

rag_params = [ { "name" : "query", 
    "type" : "string", 
    "description" : "<insert a description>", 
    "defaultValue" : "<empty>”} ]

È quindi possibile impostare la configurazione RAG:

rag_config = { "catalog": "<catalog>", 
		  "schema": "<schema>", 
		  "knowledgeBase": "<knowledge-base-name>", 
		  "top_k": <number-of-documents-retrieved>, 
		  "llm": { 
			    "model_id" : "<model-name>",
			    "model_provider" : "<model-provider>", 
			    "compartment_id" : "<your-compartment-OCID>", 
			    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" } 
}

Infine, si crea uno strumento compatibile con LangGraph con la funzione utility create_langgraph_tool() da aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "RAGTool", 
			   conf=rag_config, 
			   params=rag_params) 
rag_tool = create_langgraph_tool(rag_conf.model_dump())

Tabella 22-5 Proprietà di configurazione dello strumento RAG

Proprietà	Type	Descrizione
llm	oggetto	Dettagli connessione LLM
catalog	stringa	Identificativo Data Catalog
schema	stringa	Schema all'interno del catalogo
knowledge base	stringa	Nome o chiave della knowledge base da cercare
top_k	Intero	Numero di primi documenti corrispondenti da recuperare

Strumenti RAG agente test

È possibile eseguire il test dello strumento RAG dalla scheda Test dopo aver collegato l'agente a un cluster di computazione AI. Per ulteriori informazioni, vedere Allegare un cluster AI esistente a un agente.

Aggiungere uno strumento RAG a un agente

È possibile aggiungere uno strumento di retrieval augmented generation (RAG) agli agenti per consentire all'agente di acquisire conoscenze esterne pertinenti durante la generazione di una risposta.

1. Passare all'agente.
2. Dai modelli di strumento, trascinare e rilasciare uno strumento RAG sullo sfondo.
3. Nella scheda Configurazione, selezionare la knowledge base da cui lo strumento RAG estrae le informazioni e fornire il prompt per definire le informazioni da estrarre. Fare clic su Codice per fornire la configurazione come codice JSON.
4. Fare cli su Applica .
5. Fornire le definizioni per tutti i parametri definiti nella configurazione. Fare clic su Codice per fornire la configurazione come codice JSON.
6. Fare clic su Applica.
7. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Strumento SQL

Lo strumento SQL consente agli sviluppatori del flusso di agenti di eseguire query SQL predefinite su tabelle registrate in un catalogo di Oracle AI Data Platform.

È possibile scrivere la query in fase di progettazione e definire le variabili di runtime necessarie. L'agente fornisce i valori per tali variabili quando chiama lo strumento e i risultati vengono restituiti come righe strutturate che l'agente può riepilogare o passare a un nodo a valle.

Lo strumento SQL supporta due dialetti di query. Spark SQL viene eseguito su tabelle di catalogo standard memorizzate in AI Data Platform e richiede un cluster Spark. Oracle SQL viene eseguito su un database esterno come Oracle Autonomous AI Database. Si sceglie il dialetto per strumento, e il resto della configurazione è lo stesso per entrambi.

Nota

Lo strumento SQL è destinato alle query di lettura. Uno strumento tipico esegue un'istruzione SELECT e restituisce le righe. Il catalogo, lo schema e la query configurati sono privati dello strumento e non sono esposti all'agente. Solo il nome dello strumento, la descrizione e la definizione dello strumento AI (le variabili di runtime) sono visibili all'agente.

Nota

Lo strumento di query SQL non avvia automaticamente i cluster arrestati. Di conseguenza, il cluster Spark utilizzato per lo strumento di query Spark SQL deve avere una durata di Forever. Se al cluster è consentito attivare un timeout di inattività, le query SQL Spark smettono di funzionare in produzione una volta arrestato il cluster.

Query statiche e dinamiche

Una query statica restituisce esattamente ciò che si specifica, senza alcuna decisione di runtime da parte dell'agente. Una query dinamica include uno o più segnaposto {{variable}} che segnalano all'agente che il valore è impostato in fase di esecuzione. Per ogni segnaposto è possibile specificare un nome, un tipo, un valore predefinito facoltativo e una descrizione utilizzata dall'agente per scegliere il valore.

Ad esempio, la query statica seguente restituisce un set di risultati fisso:

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = 2025 
ORDER BY customer_name 

La sostituzione del valore con un segnaposto {{year}} lo trasforma in una query dinamica che l'agente può parametrizzare:

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = {{year}} 
ORDER BY customer_name 

Quando si aggiungono segnaposto, il riquadro delle definizioni di AI Tool viene popolato con ogni variabile in modo da poter impostare il tipo, il valore predefinito e la descrizione.

I segnaposto possono essere visualizzati in qualsiasi punto della query, incluse le funzioni interne. La query SQL Spark seguente corrisponde a un valore di severità senza distinzione tra maiuscole e minuscole:

SELECT incident_id, project_id, incident_date, incident_type, 
       severity, description, workers_involved, days_lost, 
       root_cause, corrective_action, reported_by, status 
FROM safety_incidents 
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')

Fornire a ciascuna variabile una descrizione chiara e un valore predefinito ragionevole. La descrizione indica all'agente quali valori sono validi e il valore predefinito viene utilizzato quando l'agente non ne fornisce uno.

Nota

I nome segnaposto fanno distinzione tra maiuscole e minuscole. Un segnaposto scritto come {{SEVERITY}} e uno scritto come {{severity}} vengono trattati come due variabili diverse, a meno che non si utilizzi costantemente lettere minuscole.

Modifica della configurazione come JSON

È possibile modificare la configurazione dello strumento SQL direttamente come JSON utilizzando il pulsante di attivazione/disattivazione della vista codice. Ciò è utile per copiare uno strumento tra i flussi o apportare modifiche di massa.

{ 
  "catalogKey": "construction_data", 
  "schemaKey": "admin", 
  "query": "SELECT project_id, project_name, client_name, ...", 
  "isRowLimitEnabled": null, 
  "maxRows": null 
}

Limiti riga

È possibile limitare il numero di righe restituite dallo strumento selezionando Numero massimo di righe da restituire e immettendo un valore limite. I limiti di riga proteggono le prestazioni e controllano la quantità di dati inviati all'agente.

Impostare questo valore in relazione al modello utilizzato dall'agente. Valori più grandi possono causare errori dell'agente quando le query restituiscono righe o colonne di grandi dimensioni con valori di testo. Se si verificano errori imprevisti dell'agente, iniziare riducendo maxRows.

Il limite di righe viene applicato alla query SQL stessa prima dell'esecuzione della query. La maggior parte dei modelli rileva il limite e lo affiora all'utente finale. Per un'interrogazione statica, il limite restituisce le prime n righe disponibili.

Nota

Se non si desidera visualizzare i limiti di riga per gli utenti finali, indicare l'agente di conseguenza nelle relative istruzioni.

Esempi di query

È possibile visualizzare esempi di query e una guida per la scrittura di query degli strumenti SQL dal pulsante Visualizza esempi di query e guida.

La guida mostra pattern di query diversi e fornisce suggerimenti diversi sui parametri di query.

Strumenti SQL tramite codice LangGraph

Proprio come con il flusso visivo, si inizia a creare uno strumento SQL per l'agente tramite il codice LangGraph creando una query:

sql_config = { "catalogKey": "adw23ai_phx", 
	  "schemaKey": "gold", 
	  "query": """Select ... from ... limit {{max_number}}""" }

Ogni parametro della query SQL nell'argomento dei parametri viene documentato con un nome, un tipo, una descrizione e, facoltativamente, un valore predefinito.

sql_params = [ {  "name" : "max_number", 
		    "type" : "string", 
		    "description" : "<your-description>", 
		    "defaultValue" : "<your-default-value>" } ]

Infine, si crea uno strumento compatibile con LangGraph con la funzione utility create_langgraph_tool() da aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "SQLTool", 
			   conf=sql_config,
			   params=sql_params) 
sql_tool = create_langgraph_tool(sql_conf.model_dump())

Tabella 22-6 Proprietà di configurazione dello strumento SQL

Proprietà	Type	Descrizione
chiave catalogo	stringa	Identificativo per la connessione al catalogo o al database
chiave schema	stringa	Nome schema all'interno del catalogo/database
query	stringa	Stringa di query SQL, che può includere segnaposto in {{}}

Strumenti SQL agente di test

La scheda Test esegue lo strumento da solo, senza eseguire il flusso completo dell'agente. I test funzionano allo stesso modo per entrambi i dialetti. Aprire la scheda Test, fornire un valore per ciascun parametro runtime (o utilizzare i valori predefiniti), quindi fare clic su Sottometti per eseguire la query e visualizzare la risposta.

Nota

Il test di uno strumento richiede che l'agente sia collegato a una computazione AI. Una computazione AI viene collegata se l'etichetta di computazione AI è verde con la computazione AI selezionata in stato ACTIVE.

Riferimento comando SQL

Le query degli strumenti SQL sono query di lettura create dalle clausole SQL standard. Il dialetto Oracle SQL segue Oracle SQL rispetto al database esterno. Il dialetto SQL Spark è destinato alle tabelle di catalogo standard, ovvero le tabelle Delta Lake; il catalogo standard attualmente esegue Spark 3.5 con Delta Lake 3.2.0. La maggior parte delle clausole sono scritte allo stesso modo in entrambi i dialetti, perché entrambe seguono SQL standard. La differenza principale è come ogni dialetto limita il numero di righe. Nella tabella seguente sono elencate le clausole e le parole chiave utilizzate più spesso nelle query degli strumenti SQL, con il formato per ogni dialetto.

Parola chiave o clausola	Scopo	SQL Oracle	Spark SQL
SELECT	Scegliere le colonne da restituire	SELECT col1, col2
DISTINCT	Restituisci solo righe univoche	SELECT DISTINCT col	SELECT DISTINCT col
FROM	Assegnare un nome alla tabella di origine	FROM table_name	FROM table_name
WHERE	Filtra righe per condizione	WHERE col = value	WHERE col = value
E O NO	Combina o annulla condizioni	a AND b OR NOT c	a AND b OR NOT c
In	Corrispondenza con qualsiasi valore in un elenco	col IN (a, b, c)	col IN (a, b, c)
BETWEEN	Corrispondenza con un intervallo inclusivo	col BETWEEN x AND y	col BETWEEN x AND y
LIKE	Corrispondenza di un pattern di testo	col LIKE 'A%'	col LIKE 'A%'
IS NULL	Test per valori mancanti	col IS NULL	col IS NULL
ORDER BY	Ordina il risultato	ORDER BY col DESC	ORDER BY col DESC
RAGGRUPPA IN	Raggruppa righe per l'aggregazione	GROUP BY col	GROUP BY col
HAVING	Filtra righe raggruppate	HAVING COUNT(*) > 1	HAVING COUNT(*) > 1
PARTECIPA	Combina righe da due tabelle	a JOIN b ON a.id = b.id	a JOIN b ON a.id = b.id
AS	Alias di una colonna o tabella	col AS name	col AS name
UNION ALL	Combina due set di risultati	q1 UNION ALL q2	q1 UNION ALL q2
CASE	Restituisce un valore in modo condizionale	CASE WHEN c THEN x END	CASE WHEN c THEN x END
Aggregati	Riepiloga righe	COUNT SUM AVG MIN MAX	COUNT SUM AVG MIN MAX
Limite righe	Capire il numero di righe	FETCH FIRST n ROWS ONLY	LIMIT n

Nota

Normalmente non si scrive il limite di riga da soli. L'impostazione Numero massimo di righe da restituire la applica automaticamente. I moduli FETCH FIRST e LIMIT sono utili solo quando si desidera un limite esplicito all'interno della query.

Per una grammatica SQL completa e i motori di query dietro ogni dialetto, vedere i seguenti riferimenti:

SQL di Oracle AI Data Platform

• Grammatica SQL
  • Grammatica SQL catalogo
  • Grammatica SQL schema
  • Grammatica SQL volume
  • Grammatica SQL tabella
  • Query DML

SQL Spark e Delta Lake (catalogo standard)

Le tabelle catalogo standard sono le tabelle Delta Lake. Il catalogo standard attualmente esegue Spark 3.5 con Delta Lake 3.2.0.

• Sintassi SQL di Apache Spark: istruzioni DML Query SQL Spark e sintassi dell'istruzione DML.
• Delta Lake: la tabella elimina, aggiorna e unisce le operazioni DELETE, UPDATE e MERGE sulle tabelle Delta.
• Delta Lake: comandi della utility Table Operazioni della utility quali OPTIMIZE e VACUUM.
• Delta Lake: Usa clustering liquido per tabelle Delta Clustering liquido per il layout della tabella Delta.

Aggiungere uno strumento SQL a un agente

È possibile aggiungere uno strumento SQL agli agenti per consentire all'agente di eseguire query SQL su origini dati strutturate nei cataloghi esterni registrati.

1. Passare all'agente.
2. Dai modelli di strumento trascinare e rilasciare uno strumento SQL nell'area di creazione.
3. Fare clic e trascinare l'handle del connettore sull'agente per connettersi al nodo dello strumento.
   
   

   

   
   
4. Fare doppio clic sul nodo SQL per aprire il pannello di configurazione.
5. Fornire un nome e la descrizione dello strumento. La descrizione viene fornita all'agente e lo aiuta a decidere quando chiamare lo strumento.
6. Scegliere il dialetto query:
   • Spark SQL scrive query sui cataloghi AI Data Platform standard.
   • Oracle SQL scrive le query sui cataloghi di AI Data Platform esterni.

   Nota

   Spark SQL richiede un cluster Spark in esecuzione nell'area di lavoro di AI Data Platform Workbench.
   
   

   

   
   
7. Dall'elenco a discesa Cluster selezionare un cluster Spark in esecuzione. Fare clic su Crea cluster per eseguire il provisioning di un nuovo cluster Spark. Per istruzioni sulla creazione di un nuovo cluster, vedere Creare un cluster personalizzato.

   Nota

   Lo strumento di query SQL non avvia automaticamente i cluster arrestati. Di conseguenza, il cluster Spark utilizzato per lo strumento di query Spark SQL deve avere una durata di Forever. Se al cluster è consentito attivare un timeout di inattività, le query SQL Spark smettono di funzionare in produzione una volta arrestato il cluster.

   
   

   

   
   
8. In Sfoglia catalogo, utilizzare il campo di ricerca per individuare un catalogo in base al nome oppure fare clic su Catalog Manager per individuare il catalogo.
   
   

   

   
   
9. Nel campo Query immettere la query. Fare clic su Visualizza esempi e guida query per aprire un pannello contenente pattern pronti da copiare o adattare.
   
   

   

   
   
10. Selezionare Numero massimo di righe da restituire per limitare il numero di righe restituite dai risultati della query.

    Nota

    Se la query può restituire più righe di questo limite, considerare la possibilità di aggiungere parametri di ricerca come {{customer_name}} o {{region}} in modo che l'agente possa trovare dati più specifici.
11. Nel riquadro Definizione dello strumento AI, impostare il tipo, il valore predefinito e la descrizione delle variabili impostate nella query.
    
    

    

    
    
12. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Memoria agente

La memoria agente fa parte di un sistema agente AI che consente all'agente di conservare e riutilizzare le informazioni tra turni, task o sessioni.

A differenza della finestra di contesto del modello, che è temporanea e limitata al prompt corrente, la memoria può mantenere fatti, preferenze, decisioni precedenti, output degli strumenti, piani intermedi o osservazioni sull'ambiente.

Memoria agente in AI Data Platform

AI Data Platform fornisce memoria a breve termine limitata alla durata di una sessione. È possibile configurare gli elementi che possono essere conservati in memoria nella scheda Memoria dell'agente.

Configurazione memoria agente singolo

La configurazione della memoria di un singolo sistema agente è disponibile nella scheda Memoria del nodo agente.

Configurazione memoria	Descrizione
Abilita memoria agente	Questa impostazione abilita la memoria dell'agente. Se disabilitato, l'agente è essenzialmente un sistema senza conservazione dello stato. Ogni turno viene trattato in modo indipendente e non è possibile porre alcuna domanda di follow-up. Si consiglia di abilitare la memoria.
Limita la cronologia delle conversazioni	Quando questa selezione è disabilitata, i giri precedenti riempiranno la memoria fino a quando il modello non esaurisce il contesto e viene restituito un errore. Se sono previste sessioni brevi, è possibile disabilitare questa impostazione. Tuttavia, per la maggior parte dei casi d'uso si consiglia di limitare la cronologia delle conversazioni.
Configurazione troncamento	Se si sceglie di limitare la cronologia delle conversazioni, è possibile decidere di troncare la cronologia mediante: Mantenere solo gli ultimi N messaggi (utente + agente) Impostazione di un budget token complessivo (first in, first out) O entrambi, a seconda di quale evento si verifichi per primo attiva il troncamento della memoria dell'agente
Limite massimo messaggi	Se si sceglie di mantenere gli ultimi N messaggi, è possibile impostare un valore di N.
Budget token	In alternativa, è possibile impostare un budget token complessivo. I primi token vengono eliminati per mantenere in memoria quelli più recenti.

Configurazione memoria di sistema con più agenti (modello supervisore)

La memoria di un sistema con più agenti viene configurata nella scheda Memoria dell'agente supervisore.

La memoria per un sistema con più agenti viene applicata e non può essere disabilitata e le opzioni di troncamento della memoria visualizzate nel nodo dell'agente supervisore vengono applicate solo alla memoria dell'agente supervisore. Ogni criterio di troncamento della memoria dell'agente esecutore può essere configurato nella scheda Memoria del nodo esecutore in base al criterio di isolamento dello stato selezionato per l'intero sistema.

La configurazione della memoria di sistema multi-agente consente inoltre di selezionare il criterio di condivisione della memoria degli agenti esecutore. Sono possibili tre opzioni: Stateless, Private e Shared. Tenere presente che il criterio viene applicato a tutti gli agenti esecutore.

Isolamento dello stato per gli agenti esecutori	Descrizione
Senza conservazione dello stato	Ogni agente esecutore vede solo il task assegnato dal supervisore. Nessuna storia viene riportata tra le chiamate. Nessuna richiesta di follow-up può essere effettuata all'agente supervisore dall'agente esecutore. Se si seleziona senza conservazione dello stato, la memoria di ciascun agente esecutore viene disabilitata.
Privata	Ogni agente esecutore vede solo le proprie interazioni passate. Non è possibile visualizzare altri agenti esecutore o la conversazione utente originale con l'agente supervisore.
Condivise	Gli agenti esecutori possono visualizzare la cronologia completa delle conversazioni tra agenti e utenti. Tutti gli agenti lavorano da un contesto condiviso. Se condiviso è selezionato, è possibile configurare il criterio di troncamento della memoria separatamente per ogni agente esecutore in ogni scheda di memoria del nodo agente.

Variabili di sessione

È possibile utilizzare variabili di sessione personalizzate definite dall'agente per fornire datapoint contestuali aggiuntivi agli agenti durante una sessione utente.

Descrizione delle variabili di sessione

Le variabili di sessione personalizzate definite dall'agente forniscono all'agente datapoint contestuali aggiuntivi durante una sessione utente. Le variabili possono essere utilizzate per una serie di scopi, tra cui l'impostazione di valori di parametri negli strumenti, fornendo istruzioni generali a un agente e fornendo informazioni contestuali sul chiamante e/o sull'applicazione in cui è incorporato l'agente.

Ecco uno scenario semplificato in cui stiamo creando un agente di assistenza clienti. L'agente di assistenza clienti è integrato all'interno di un sito Web di vendita al dettaglio. Quando un utente accede al sito Web retail, le informazioni su tale utente vengono acquisite dall'applicazione client (ID utente, nome utente, posizione geografica, dispositivo utilizzato, ID carrello della spesa, ecc.) e tali informazioni potrebbero essere utilizzate dall'agente di supporto a valle. Esaminiamo un esempio di come questi parametri di sessione potrebbero essere utilizzati nel campo delle istruzioni dell'agente in AIDP:

You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.  
A few guidelines before your start:  
    You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}?  

Nell'esempio precedente vengono utilizzate tre variabili di sessione:

• userName
• Formula di anticipo preferita
• utente correnteGeo

L'agente non ha alcuna conoscenza preliminare dell'utente che interagisce con il sito web di vendita al dettaglio, non sa quale sia la posizione dell'utente o non ha alcun contesto su ciò che è nel carrello dell'utente. In linea di principio, l'applicazione client potrebbe conoscere tutti o un sottoinsieme di tali valori e passare tali valori in una richiesta all'agente. Ecco un esempio di come potrebbe essere una richiesta all'agente, inclusi i parametri della sessione.

Nota

In questo esempio viene illustrato l'aspetto di questa richiesta. Non è rappresentativo di una decisione di implementazione.

"input": [  
{ "role": "user", 
         "content": [  
{ "type": "input_text”,  
	  "text": "What material is the belt Mr Outcast made of?", 
	  “variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]  
} 
  ]  
} 
] 

L'agente avrebbe risposto: "Ciao signor Paul, com'è il tempo oggi a Cancun, Mx?"

Un altro uso di questi parametri di sessione è l'impostazione dei valori dei parametri negli strumenti. Ad esempio, una query SQL potrebbe recuperare il contenuto di un carrello utilizzando il parametro di sessione {{sessionParam.CartID}}:

Select productID, productName, productDescription, 
productPrice from cartTable where cartID == 
{{sessionVariable.cartID}}  

Le variabili di sessione vengono definite dallo sviluppatore agente quando crea i propri agenti e i valori di tali attributi vengono impostati dall'applicazione client quando viene creata o ripresa una sessione.

È possibile configurare le seguenti impostazioni quando si crea una nuova variabile di sessione:

Impostazione	Descrizione
Variabile obbligatoria	Abilitare per rendere necessaria questa variabile di sessione per ogni chiamata di richiamo dell'agente. La disabilitazione rende la variabile di sessione facoltativa per ogni chiamata di richiamo.
Variabile di log	Consente di acquisire il valore della variabile di sessione nei log e nei trace. La disabilitazione impedisce la visualizzazione della variabile nei log. Si consiglia di disabilitare questa impostazione per le variabili con dati riservati.
Nome	Nome della variabile di sessione. Utilizzare un nome descrittivo per semplificare la determinazione dello scopo della variabile da parte dell'utente e di altri utenti.
Valore predefinito	Se definito, il valore predefinito viene assegnato alla variabile di sessione se nella chiamata di richiamo non è definito un altro valore. Se lasciato vuoto, un valore deve essere assegnato come parte della chiamata di richiamo.
Descrizione	Descrizione della variabile di sessione. Fornire una descrizione utile in modo che tu e gli altri utenti siate in grado di comprendere la funzione della variabile di sessione.

Esempio: utilizzo delle variabili di sessione nella configurazione di Tools

È possibile utilizzare una variabile di sessione in una configurazione dello strumento SQL come parte della query SQL stessa.

In questo esempio, la variabile di sessione geo viene utilizzata per filtrare il risultato della query SQL:

È possibile utilizzare variabili di sessione e parametri degli strumenti all'interno della stessa query. Nell'esempio seguente, il parametro titleID viene impostato dall'agente mentre la variabile di sessione geo viene fornita dall'applicazione chiamante.

Variabili di sessione generate dal sistema

Le variabili di sessione vengono generate automaticamente quando un server MCP remoto è connesso a un agente e tale server MCP richiede l'autenticazione, come un token bearer.

La variabile di sessione contiene il valore del token bearer. Il nome di questa variabile di sessione generata dal sistema non può essere modificato ed è una variabile obbligatoria. La variabile di sistema viene eliminata quando il nodo MCP viene rimosso dallo sfondo.

In Playground, si fornisce un valore per la variabile di sessione generata dal sistema. In questo caso, è necessario fornire un token bearer per utilizzare il server MCP. È possibile selezionare lo stesso token (o un token diverso) utilizzato durante la configurazione del nodo MCP.

Lo stesso vale se si distribuisce l'agente. Sarà necessario fornire un token di autorizzazione. Per ulteriori informazioni, vedere Assegnare valori alle variabili di sessione dall'area di esecuzione.

Esempio: assegnazione di valori alle variabili di sessione durante la chiamata di un endpoint distribuito

In questo esempio, sono disponibili due variabili di sessione: userLocation e UserName. L'applicazione client passa i valori delle variabili di sessione tramite il campo metadata di body. Dimostreremo come è possibile assegnare valori tramite Python e l'interfaccia CLI OCI.

Se si utilizza la libreria di richieste Python, il payload è il seguente:

body = { 

            "isStreamEnabled" : False, 

            "trace" : False, 
            "input" :[{ 
                "role":"User", 
                "content":[{ 
                    "type" : "INPUT_TEXT", 
                    "text" : “Hello how can you help me?”                  
                }] 
            }], 

            "metadata": { 
            "sessionvariables.userLocation": "Canada",  
            "sessionvariables.UserName": "George" 
        } 
        } 

response = requests.post( 
url = <insert-chat-url>,  
params = None,  
auth = <insert-oci-signer>, 
json = body, 
headers={“x-session-id": <insert-a-session-key>,} 
)  

In alternativa, se si utilizza l'interfaccia CLI OCI, il payload è il seguente:

oci raw-request \ 
  --http-method POST \ 
  --auth security_token \ 
  --request-body '{ 
    "isStreamEnabled": false, 
    "input": [ 
      { 
        "role": "user", 
        "content": [ 
          { 
            "type": "INPUT_TEXT", 
            "text": "Hello how can you help me?" 
          } 
        ] 
      } 
    ], 
    "metadata": { 
      "sessionvariables.userName": "George", 
      "sessionvariables.userLocation": "Canada"}" 
    } 
  }' \ 
  --request-headers '{ 
    "x-session-id": "george-session-may11" 
  }' \ 
  --target-uri "<insert-your-agent-flow-uri>" 

Crea una variabile di sessione nella scheda Variabili agente

È possibile creare una nuova variabile di sessione e aggiungerla all'agente dalla scheda Variabili.

1. Passare all'agente a cui si desidera aggiungere una variabile di sessione.
2. Fare clic sulla scheda Variabili.
   
   

   

   
   
3. Fare clic su Aggiungi variabile di sessione.
   
   

   

   
   
4. Selezionare se la variabile di sessione è una variabile obbligatoria.
5. Selezionare se il valore della variabile di sessione deve essere registrato nei log e nei trace. Lasciare questa impostazione disabilitata per i dati riservati.
6. Fornire un nome e la descrizione significativi per la variabile di sessione.
7. Fornire un valore predefinito per la variabile di sessione. Il valore predefinito viene assegnato alla variabile di sessione se non viene assegnato alcun altro valore nell'ambito della chiamata di richiamo.
8. Fare clic su Crea.

Fare riferimento alle variabili di sessione nelle istruzioni del flusso agente

È possibile fare riferimento alle variabili di sessione nelle istruzioni dell'agente e nelle configurazioni degli strumenti, inclusa la query degli strumenti SQL e Prompt.

1. Passare al flusso dell'agente.
2. Fare clic sul nodo dello strumento SQL o Prompt nell'area di esecuzione.
   
   

   

   
   
3. Nel campo Query, iniziare a digitare {{sessionvariables.
4. Selezionare la variabile di sessione dall'elenco delle variabili di sessione esistenti.

Visualizzare agenti e strumenti utilizzando una variabile di sessione

È possibile visualizzare una lista di agenti e strumenti utilizzando una variabile di sessione specifica dalla scheda Variabile nel flusso dell'agente.

1. Passare a un flusso agente utilizzando la variabile di sessione per la quale si desidera visualizzare gli agenti e gli strumenti correlati.
2. Fare clic sulla scheda Variabile.
3. Avanti, fare clic sul menu a discesa Utilizzato in: per la variabile di sessione. Viene visualizzato un elenco di agenti e strumenti che utilizzano la variabile di sessione.

Assegna valori a variabili di sessione da Playground

È possibile assegnare valori alle variabili di sessione in qualsiasi momento dalla scheda Playground.

1. Passare al flusso dell'agente.
2. Nella parte superiore dell'area di gioco, fare clic su Parametri sessione. Viene visualizzato un elenco di tutte le variabili di sessione nel flusso dell'agente.
   
   

   

   
   
3. Modificare le variabili di sessione. Dopo aver ripreso la sessione di Playground, vengono utilizzati i valori delle ultime variabili di sessione assegnate.
   
   

   

   
   

Limiti

I guardrail sono meccanismi di sicurezza per guidare e controllare il comportamento degli agenti AI.

In Oracle AI Data Platform Workbench, i guardrail sono configurati per impedire la generazione o il consumo di contenuti tossici e dannosi da parte dei flussi degli agenti. Le guardie impediscono anche la fuoriuscita di informazioni di identificazione personale (PII) dal flusso dell'agente. I guardrail specifici disponibili nel workbench della piattaforma dati AI si applicano alla moderazione dei contenuti, all'iniezione rapida e alle informazioni di identificazione personale.

Nota

I guardrail offerti da Oracle AI Data Platform Workbench sono disponibili solo in inglese.

I guardrail offerti in AI Data Platform Workbench vengono implementati dal team del servizio OCI Generative AI. Consulta Guardrails per OCI Generative AI. In base alla configurazione del guardrails, il servizio AI Data Platform Workbench richiama l'API Applica Guardrails all'interno della tenancy OCI.

Parapetti in Visual Flow Canvas

Per impostazione predefinita, nessun guardrail viene applicato al sistema oltre i controlli di sicurezza nativi del fornitore del modello. Per aggiungere i guardrail, è necessario trascinare un nodo dei guardrail nel generatore di flusso visivo dell'agente e collegarlo all'agente.

Un nodo guardrail può filtrare il traffico tra un trigger di chat e un nodo agente, tra un supervisore e gli agenti dell'esecutore o tra i nodi agente e strumento. Per la maggior parte degli scenari, è consigliabile un singolo nodo di guardrail tra il trigger di chat e il nodo dell'agente. Ciò garantirà che tutti i messaggi dell'utente in entrata e i messaggi generati dall'agente vengano filtrati attraverso i guardrail.

Il nodo guardrails può essere inserito solo tra:

• Un nodo trigger chat e un agente (supervisore o esecutore)

Quali custodie sono disponibili?

Il diagramma riportato di seguito mostra una semplice interazione tra un utente finale e un agente. In questo scenario, vengono applicate tutte le guadrails (moderazione dei contenuti – CM, prevenzione rapida dell'iniezione – PI e rilevamento delle PII – PII). Il PI viene applicato solo alla query utente.

Dopo il secondo messaggio emesso dall'utente finale, è stato rilevato un tentativo PI e il messaggio utente è stato bloccato in seguito all'azione selezionata dallo sviluppatore dell'agente sul rilevamento PI (blocco).

Moderazione contenuto

La moderazione dei contenuti è un'implementazione comune dei guardrail nella maggior parte dell'AI generativa. Senza controllo, gli LLM possono generare contenuti dannosi, promuovere contenuti violenti, razzisti e sessualmente espliciti. È fondamentale dare agli sviluppatori degli agenti piena visibilità e controllo su come le interazioni degli utenti con gli agenti vengono monitorate e scansionate per contenuti potenzialmente dannosi. La moderazione dei contenuti impedisce che contenuti offensivi, sessuali, violenti, tossici, dispregiativi o basati su molestie siano considerati o generati dal flusso dell'agente. Il nostro modello di guardrail classifica i contenuti lungo le sei categorie e contrassegna i contenuti appartenenti a una di queste categorie.

È possibile scegliere di eseguire un'azione sulla query di input utente o sulla risposta del modello:

• Blocco: si impedisce all'agente di elaborare l'input utente e generare una risposta. Gli utenti ricevono una risposta di errore dal flusso dell'agente.
• Inform.: consente al flusso dell'agente di elaborare l'input dell'utente e generare una risposta. L'agente notifica all'utente che l'input o la risposta contenevano contenuti che soddisfacevano i criteri del guardrail.
• Consenti: consente l'elaborazione e/o la generazione di contenuti potenzialmente dannosi da parte del flusso dell'agente.

L'azione Blocca viene selezionata per la moderazione del contenuto quando si crea un flusso agente. Oracle consiglia di mantenere Blocca come guardrail selezionato per la moderazione dei contenuti.

Richiedi iniezione

I guardrail ad iniezione rapida per gli agenti AI sono un meccanismo protettivo che rileva, previene e mitiga istruzioni dannose o non intenzionali incorporate negli input dell'utente. Gli attacchi di iniezione rapida tentano di sostituire o sovvertire le istruzioni, i criteri o gli obiettivi originali dell'agente inserendo testo nascosto che indica al modello di ignorare le regole precedenti, di esfiltrare i segreti o di eseguire azioni non autorizzate.

È possibile scegliere le stesse azioni che possono essere eseguite per la moderazione del contenuto: bloccare, informare o consentire. I guardrail per iniezione rapida si applicano solo alla query di input dell'utente.

• Blocco: si impedisce all'agente di elaborare l'input utente. Gli utenti ricevono una risposta di errore dal flusso dell'agente.
• Inform.: consente al flusso dell'agente di elaborare l'input dell'utente. L'agente notifica all'utente che l'input contiene contenuto che soddisfa i criteri di guardrail.
• Consenti: consente l'elaborazione di contenuti potenzialmente dannosi da parte del flusso dell'agente.

L'azione Blocca viene selezionata per l'inserimento rapido quando si crea un flusso di agenti. Oracle consiglia di mantenere Blocco come guardavia selezionato per un'iniezione rapida.

Informazioni di identificazione personali (PII)

I guardrail delle PII rilevano, bloccano o mascherano automaticamente le PII dalle query di input dell'utente o dalle risposte degli agenti. Questo guardrail impedisce all'agente di esporre informazioni sensibili degli utenti in modi che violano le normative sulla privacy o le politiche organizzative.

I guardrail PII supportano quattro tipi di entità:

• E-mail
• Telephone number
• Indirizzo fisico
• Nome persona

Per ciascuna di queste quattro entità, è possibile scegliere di applicare le azioni seguenti eseguite dall'agente nella query dell'utente di input o nella risposta dell'agente:

• Blocco: si impedisce all'agente di elaborare l'input dell'utente e generare una risposta. Gli utenti ricevono una risposta di errore dal flusso dell'agente.
• Inform.: consente al flusso dell'agente di elaborare l'input dell'utente e generare una risposta. L'agente notifica all'utente che l'input o la risposta contenevano informazioni di identificazione personale.
• Maschera: si consente al flusso dell'agente di elaborare l'input e generare una risposta mascherata. Qualsiasi PII utilizzato è protetto per prevenire l'esposizione.
• Consenti: è possibile consentire l'elaborazione e/o la generazione di dati PII in base al flusso dell'agente.

In un nuovo flusso agente, le informazioni PII sono consentite sia nell'input utente che nella risposta per impostazione predefinita. Oracle consiglia di selezionare attentamente il guardrail per le informazioni PII in base alle proprie esigenze di sicurezza.

Abilita guardrail specifici in un nodo

È possibile scegliere i guardrail da abilitare e la modalità di configurazione quando si aggiunge un nodo guardrail allo sfondo visivo.

1. Passare al flusso dell'agente nell'area di lavoro.
2. Trascinare un nodo Guardrails dalla tavolozza all'area di creazione.
3. Fornire un nome e la descrizione significativi per il nodo.
   
   

   

   
   
4. Attivare un guardrail per abilitarlo e iniziare la configurazione. Se si preme nuovamente l'interruttore, il guardrail e le relative configurazioni vengono disabilitati.
   
   

   

   
   
5. Selezionare la configurazione di guardrail necessaria per ogni categoria.
   
   

   

   
   

Creare un cluster AI per un agente

È possibile creare un nuovo cluster AI direttamente dall'interfaccia agente e collegarlo immediatamente.

Per ulteriori informazioni, consulta AI Compute.

1. Nella home page, andare all'agente.
2. Fare clic su Computa, quindi su Crea una nuova computazione AI.
3. Fornire il nome e la descrizione del cluster di computazione AI.
4. Selezionare il numero di OCPU e la dimensione della memoria per il cluster di computazione AI.
5. Fare clic su Crea.

Collega un cluster AI esistente a un agente

È possibile collegare un cluster AI creato in precedenza a un agente per il quale si dispone almeno delle autorizzazioni USE.

1. Nella home page, andare all'agente.
2. Fare clic su Computa, quindi su Collega a AI Compute.
3. Fare clic sul cluster che si desidera utilizzare dalla lista.
   L'agente mostra AIcompute: (ClusterName) in esecuzione quando è stato collegato correttamente. Questa operazione può richiedere fino a diversi minuti.

Scollega un agente dalla computazione AI

Puoi scollegare un agente da una computazione AI. Lo scollegamento della computazione AI rimuove il codice agente in esecuzione nella computazione collegata e impedisce il test.

Nota

Lo scollegamento di un agente dalla computazione AI non elimina l'agente. Puoi riprendere la creazione e il test dell'agente collegandolo alla stessa o a un'altra computazione AI.

1. Nella home page, andare all'agente.
2. Fare clic su Computa, quindi su Scollega da AI Compute.
   
   

   

   
   

Distribuzione agente A2A

Il protocollo A2A (Agent2Agent) è uno standard aperto per la comunicazione tra agenti AI indipendenti, inclusi agenti creati con framework diversi, ospitati da fornitori diversi o eseguiti come sistemi remoti opachi.

Il suo scopo è quello di fornire a questi agenti un modello di interazione condivisa in modo che possano scoprire le rispettive capacità, negoziare formati di input/output supportati, delegare o collaborare alle attività e scambiare informazioni in modo sicuro senza esporre memoria interna, strumenti o dettagli di implementazione. Per ulteriori informazioni, vedere il protocollo Agent2Agent (A2A).

A2A ha lo scopo di risolvere l'interoperabilità dell'agente: invece di personalizzare ogni integrazione dell'agente, un client o un altro agente può interagire con qualsiasi agente remoto conforme ad A2A utilizzando un set comune di concetti e operazioni. La specifica è incentrata su messaggi, attività, parti, artefatti, aggiornamenti in streaming e notifiche push; supporta risposte sincrone, lavoro asincrono a lungo termine, streaming e pattern di autenticazione/sicurezza in stile enterprise.

In Oracle AI Data Platform, a tutti gli agenti distribuiti viene fornito un percorso di richiamo /A2A che può essere richiamato dalle applicazioni client A2A.

Cos'è una scheda agente?

Una scheda agente è un documento di metadati JSON pubblicato da un server A2A. In AIDP, il server A2A è la computazione AI che ospita la distribuzione dell'agente.

La scheda descrive l'identità dell'agente, l'endpoint del servizio, i protocolli/trasport supportati, le capacità, le competenze, le modalità di input/output supportate e i requisiti di autenticazione; i client la utilizzano per scoprire se l'agente è adatto e come chiamarlo. Una scheda agente correttamente documentata è un requisito del protocollo A2A.

Le schede agente in AI Data Platform Workbench sono in stato Bozza, ovvero l'agente non è stato distribuito o Pubblicato, il che significa che la scheda è stata distribuita insieme all'agente.

Azioni carta agente

Durante lo sviluppo di un agente, la scheda è disponibile nel menu Azioni dell'agente.

Sono accessibili due schede agente:

• La bozza di carta riflette lo stato corrente dell'agente in fase di sviluppo.
• La scheda pubblicata corrisponde a un'istantanea della scheda acquisita al momento della distribuzione dell'agente. La scheda pubblicata riflette lo stato dell'agente distribuito.

Campi scheda agente

AI Data Platform Workbench supporta un subset dei campi della scheda agente del protocollo A2A correnti, disponibili qui: Protocollo A2A - scheda agente.

Campo	Obbligatorio.	Descrizione
name	Sì	Nome leggibile dall'utente per l'agente. Esempio: "Agente ricetta"
description	Sì	Una descrizione leggibile dall'uomo dell'agente, che assiste gli utenti e altri agenti nella comprensione del suo scopo. Esempio: "Agente che aiuta gli utenti con ricette e cucina".
Agent Version	Sì	La versione dell'agente. Esempio: "1.0.0"
Documentation URL	N.	URL che fornisce documentazione aggiuntiva sull'agente.
Provider - Organization	N.	Il provider di servizi dell'agente.
Provider - URL	N.	L'URL del provider di servizi.
Capabilities	Sì	Capacità A2A impostata supportata dall'agente. È possibile configurare solo streaming (True/False)
Skills	Sì	Le competenze rappresentano le capacità di un agente. È in gran parte un concetto descrittivo, ma rappresenta un insieme più focalizzato di comportamenti che l'agente è probabile che abbia successo. Le competenze rappresentano un array di AgentSkill.

Ogni AgentSkill è composto da diversi campi che documentano le capacità dell'agente. La definizione delle competenze dell'agente nella scheda agente è l'operazione che richiede più tempo ed è un processo iterativo. Le competenze possono essere modificate (insieme al resto della scheda agente) nella bozza della scheda agente prima della distribuzione.

Nota

inputModes, outputModes e securityRequirements sono forniti da AI Data Platform Workbench e non possono essere modificati.

Campo	Obbligatorio.	Descrizione
Skill ID	Sì	Identificativo univoco per lo skill dell'agente.
Skill Name	Sì	Nome leggibile dall'utente per la competenza.
Description	Sì	Una descrizione dettagliata dello skill.
Tags	Sì	Insieme di parole chiave che descrivono le capacità dell'abilità.
Examples	N.	Prompt di esempio o scenari che questa skill può gestire.

Percorso A2A endpoint distribuzione agente

Un percorso /a2a è esposto nell'URL di un agente distribuito oltre a /chat.

Ad esempio, un agente esporrà questi percorsi ai client esterni:

• https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chat
• https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a

Entrambi i percorsi (/chat e /a2a) possono essere utilizzati da client separati.

Variabili di sessione in A2A

I valori delle variabili di sessione possono essere passati a un agente A2A nel campo del messaggio metadata. Lo snippet JSON riportato di seguito mostra il payload di un messaggio utente inviato all'agente a2a con tre variabili di sessione: userName, geoLocation e os:

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "contextId": "session_12345",
    "taskId": "task_67890",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "What is the current status of my order?",
        }
      ],
      "metadata": {
        "sessionvariables.userName": "George",
        "sessionvariables.geoLocation": “Dallas, TX”,
        "sessionvariables.os": "mobile_ios"
      }
    }
  },
  "id": "rpc-99821"
}

Esempio: richiamo di un agente A2A con OCI CLI (non in streaming)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": "<your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<your-user-principal>"
  }' \
  --target-uri " <your-a2a-agent-endpoint-url>"

Esempio: richiamo di un agente A2A con OCI CLI (Streaming)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/stream",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": " <your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<user-principal>"
  }' \
  --target-uri "<your-a2a-agent-endpoint-url>"

Esempio: SDK client A2A

import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
    AgentCard,
    Message,
    Part,
    Role,
    TextPart,
    SendMessageRequest,
    MessageSendParams,
    MessageSendConfiguration,
    Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)

class OCIAuth(httpx.Auth):
    """httpx auth implementation using OCI signer via requests auth adapter."""

    def __init__(self, signer: oci.signer.AbstractBaseSigner):
        self._requests_auth = _OCIRequestsAuth(signer)

    def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
        req = RequestsRequest(
            method=request.method,
            url=str(request.url),
            headers=dict(request.headers),
            data=request.content,
        )
        prepared: RequestsPreparedRequest = req.prepare()
        prepared = self._requests_auth(prepared)
        request.headers.update(dict(prepared.headers))
        yield request



def getOCIAuth():
    conf = oci.config.from_file(profile_name="DEFAULT")
    token_file = conf['security_token_file']
    token = None
    with open(token_file, 'r') as f:
        token = f.read()
    private_key = oci.signer.load_private_key_from_file(conf['key_file'])
    signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
    auth = OCIAuth(signer=signer)
    return auth


async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
    """Call an agent using the A2A protocol."""
    try:
        # Initialize OCI signer
        #headers = {"dh-user-principal": "dh-user"}
        headers = {"Accept": "*/*",
                   "dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

        async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
            agent_card = await _get_agent_card(agent_url,auth)
            print(f"Agent card is {agent_card}")

            client =  A2AClient(httpx_client=hc, agent_card=agent_card)
            # Create message
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
                metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
            )
            request = SendMessageRequest(
                id=str(uuid.uuid4()),  # Add the required id field
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            #json_string = json.dumps(message, indent=4)
            print(f"Send request : {request}")

            response = await client.send_message(request)

            logging.info("Received response from A2A server: %s", response.root.result)
            # Extract response
            result = response.root.result
            # Handle different response types


            if isinstance(result, Task):
                # Task response
                if result.artifacts:
                    # Extract text from artifacts
                    texts = []
                    for artifact in result.artifacts:
                        for part in artifact.parts:
                            if hasattr(part, "root") and hasattr(part.root, "text"):
                                texts.append(part.root.text)
                    return "\n".join(texts) if texts else "Task completed with no text response"
                elif result.status and result.status.message:
                    logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
                    if  result.status.state== "failed":
                        print("Failure observed in Task invocation")
                        for m_part in result.status.message.parts:
                           print(f"Error message  { m_part.root.text}")

                    return get_message_text(result.status.message)
                else:
                    return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"

            elif isinstance(result, Message):
                return get_message_text(result)
            else:
                logging.warning(f"Unexpected response type: {type(result)}")
                return "Received response but unable to extract text"
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"


async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
    """Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
    try:
        async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
            agent_card = await _get_agent_card(agent_url)
            if not agent_card:
                return "No Agent Card Found"
            print(f"Agent card is {agent_card}")

            client = A2AClient(httpx_client=hc, agent_card=agent_card)
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
            )
            request = SendStreamingMessageRequest(
                id=str(uuid.uuid4()),
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            print("Invoking Remote Agent request (beautified JSON):")
            print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
            # Expected event types:
            # - TaskStatusUpdateEvent (working/in-progress)
            # - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
            final_artifact_text_parts: list[str] = []

            async for event in client.send_message_streaming(request):
                # Print each SSE event as-is (SDK object)
                print(f"[A2A stream event] {event}")

                try:
                    result = getattr(event.root, "result", None)
                    if not result:
                        continue

                    # TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
                    # extract by attribute presence.
                    artifact = getattr(result, "artifact", None)
                    if artifact and getattr(artifact, "parts", None):
                        for part in artifact.parts:
                            root = getattr(part, "root", None)
                            txt = getattr(root, "text", None)
                            if txt:
                                final_artifact_text_parts.append(txt)
                except Exception:
                    # Keep streaming even if an event can't be parsed
                    continue

            return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"

Modifica una bozza di scheda agente

È possibile modificare la scheda agente per un agente non ancora distribuito.

1. Passare all'agente.
2. Fare clic su Azioni, quindi su Visualizza scheda agente e Bozza scheda agente.
   
   

   

   
   
3. Fare clic Modifica.
   
   

   

   
   
4. È possibile cambiare vista facendo clic su Modulo o JSON in alto a destra. La vista JSON è più completa, ma di sola lettura. È possibile modificare solo i campi nella vista Form.
   
   

   

   
   
5. Modificare i campi in base alle esigenze.
6. Fare clic su Aggiungi una competenza per aggiungere le competenze che si desidera esporre ai client A2A.
   
   

   

   
   
7. Fare clic su Save.

Modifica una scheda agente pubblicata

È possibile modificare una scheda agente pubblicata senza annullare la distribuzione o ridistribuire un agente.

La scheda pubblicata corrisponde a un'istantanea della bozza di scheda al momento della distribuzione.

Nota

Le modifiche apportate a una scheda pubblicata si riflettono immediatamente nel file agent-card.json accessibile ai client A2A.

1. Passare all'agente.
2. Fare clic su Azioni, quindi su Visualizza scheda agente e Scheda agente pubblicata.
   
   

   

   
   
3. È possibile cambiare vista facendo clic su Modulo o JSON in alto a destra. La vista JSON è più completa, ma di sola lettura. È possibile modificare solo i campi nella vista Form.
4. Fare clic Modifica.
   
   

   

   
   
5. Modificare i campi in base alle esigenze.
6. Fare clic su Aggiungi una competenza per aggiungere le competenze che si desidera esporre ai client A2A.
   
   

   

   
   
7. Fare clic su Pubblica modifiche.

Le schede agente pubblicate non sono disponibili pubblicamente. Un utente deve essere autenticato e avere la giusta autorizzazione (READ) per ispezionare il contenuto di agent-card.json. Altri agenti possono trovare le funzionalità e i metadati degli agenti tramite una richiesta GET HTTP nel percorso standard:

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.json

Distribuzione agente

La distribuzione di un agente trasforma l'agente in un'applicazione hosted.

Puoi distribuire un agente nella stessa computazione AI collegata al suo ambiente di gioco o a un'altra computazione AI. Quando distribuisci le modifiche più recenti all'agente nella computazione AI collegata, l'agente distribuito rappresenta uno snapshot dell'agente al momento della distribuzione. Per aggiornare l'agente distribuito alla versione più recente, è necessario ridistribuire l'agente.

Ogni agente dispone di un URL di distribuzione stabile che dipende dalla chiave agente univoca. La ridistribuzione dell'agente più volte sovrascrive l'agente dietro l'URL di distribuzione.

La distribuzione degli agenti ha le seguenti limitazioni:

• Un agente può essere distribuito solo in un cluster di computazione AI in qualsiasi momento.
• La distribuzione dello stesso agente più volte nello stesso cluster di computazione AI sovrascrive l'iterazione distribuita in precedenza dell'agente.

Dopo aver distribuito un agente, è possibile recuperare l'URI della chat per emettere query a livello di programmazione e recuperare le risposte dall'agente dalla scheda Dettagli dell'agente.

L'URL dell'endpoint è stabile ed è collegato a ciascun agente. L'URL include l'ID agente univoco assegnato a ciascun agente. In altre parole, se si annulla la distribuzione di un agente e lo si distribuisce di nuovo, l'URL rimane invariato. Il vantaggio è che non è necessario modificare il codice client che richiama l'endpoint, lo svantaggio è che è possibile sovrascrivere un agente in produzione.

L'URL ha la seguente struttura:

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}

dove:

• oci-region corrisponde all'area dell'istanza di AI Data Platform;
• agentId è l'ID univoco associato all'agente
• protocol è il protocollo di comunicazione: chat che segue il formato OpenAI Responses API e a2a che segue il protocollo di comunicazione agente-agente. Entrambi i protocolli sono disponibili per ogni endpoint dell'agente. Per ulteriori informazioni, vedere Distribuzione agente A2A.

Nota

Nella scheda Dettagli sono elencati due calcoli AI. Il comando Collegato a AI Compute viene utilizzato per eseguire il test dell'agente nell'area di esecuzione. L'agente distribuito Distribuito in AI Compute ospita l'agente distribuito.

Il campo URL endpoint viene popolato dopo la distribuzione dell'agente. È possibile chiamare questo URL endpoint dall'applicazione di produzione.

Distribuisci un agente

È possibile distribuire gli agenti creati e configurati in modo che altri utenti siano in grado di visualizzarli e utilizzarli nell'istanza di AI Data Platform.

1. Nella home page, andare alla cartella contenente l'agente che si desidera distribuire.
2. Accanto all'agente, fare clic su Azioni e fare clic su Distribuisci. È inoltre possibile fare clic sul nome dell'agente e fare clic su Distribuisci in alto a destra.
   
   

   

   
   
3. Selezionare la computazione AI da collegare all'agente distribuito.
4. Selezionare Workbench AIDP per il tipo di autorizzazione.
5. Selezionare un criterio di conservazione dei dati della sessione.
   • Per Periodo di conservazione, specificare per quanti giorni verranno conservati i dati della sessione.
   • Per Limite dimensione sessione, fornire la dimensione massima che una sessione può raggiungere.
   • Per Limite di conteggio thread, fornire il numero massimo di thread di sessione conservati.
6. Fare clic su Distribuisci.

Distribuire un agente con OAuth2

È possibile distribuire gli agenti creati e configurati per utilizzare l'autenticazione OAuth2 per connettersi ai provider di identità esterni.

1. Nella home page, andare alla cartella contenente l'agente che si desidera distribuire.
2. Accanto all'agente, fare clic su Azioni e fare clic su Distribuisci. È inoltre possibile fare clic sul nome dell'agente e fare clic su Distribuisci in alto a destra.
   
   

   

   
   
3. Selezionare la computazione AI da collegare all'agente distribuito.
4. Selezionare OAuth2 per il tipo di autorizzazione.
5. Fornire la richiesta di audience. Il workbench di AI Data Platform popola automaticamente questo campo, ma è possibile sostituirlo con una richiesta di audience del provider di identità.
6. Fornire la richiesta dell'emittente e l'URI per recuperare JWKS. Queste informazioni derivano dal provider di identità in uso.
7. Selezionare un criterio di conservazione dei dati della sessione.
8. Fare clic su Distribuisci.

Richiama un agente distribuito

È possibile richiamare l'URL dell'endpoint dell'agente dall'applicazione di produzione.

Indipendentemente dall'interfaccia programmatica utilizzata per richiamare l'endpoint dell'agente, è necessario essere autenticati con OCI e disporre delle autorizzazioni pertinenti. Nel caso degli endpoint del flusso dell'agente, il chiamante deve disporre almeno dell'autorizzazione USE sull'endpoint dell'agente.

L'URI endpoint è documentato nella scheda Dettagli dell'interfaccia utente dell'agente. È possibile copiare l'URI endpoint nel codice per richiamare l'agente.

Metodi per richiamare gli URI endpoint

È possibile richiamare l'URI dell'endpoint dell'agente mediante strumenti, SDK e interfacce CLI diversi.

I metodi seguenti consentono di richiamare l'URI dell'endpoint negli agenti di Oracle AI Data Platform Workbench.

Richiama con OCI CLI

L'esempio fornito mostra come utilizzare l'interfaccia CLI OCI e eseguire l'autenticazione con un token di sicurezza. Sostituire <your-agent-flow-endpoint-uri> con l'URI dell'endpoint dell'agente e <security_token> con il token di sicurezza OCI.

oci raw-request
--http-method POST
--target-uri <your-agent-flow-endpoint-uri>
--request-body '{"query":"Tell me about the Ryder Cup in 1985"}'
--auth <security_token>

Richiama con libreria di richieste Python

Puoi utilizzare l'SDK Python OCI per creare un firmatario da autenticare con OCI. La libreria di richieste Python può essere utilizzata per inviare una richiesta all'URI dell'endpoint dell'agente e restituire una risposta. L'esempio riportato di seguito mostra come utilizzare il principal utente tramite i file di configurazione e chiave privata OCI.

import oci import requests import json import uuid from contextlib import closing from requests import Request, Response
class AuthHelper: """ AuthHelper allows creating an OCI signer with either API key or security_token (which are short term sessions) """ def init(self, oci_profile: str, use_security_token:bool = True): config = oci.config.from_file(file_location="/Volumes/jr/default/misc/config",profile_name=oci_profile) if use_security_token: with open(config["security_token_file"], 'r') as f: token = f.read() private_key = oci.signer.load_private_key_from_file(config["key_file"])
 self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key) else: self.signer = oci.signer.Signer( tenancy=config["tenancy"], user=config["user"], fingerprint=config["fingerprint"], private_key_file_location=config["key_file"], #pass_phrase=config.get("pass_phrase"), #private_key_content=config.get("key_content") )
@property
def Signer(self):
    return self.signer
 
class MyRawJsonRpcClient: """ Simple class using requests lib to post JSON to chat endpoint using OCI signing """ def init(self, chat_url:str, oci_profile: str, sessionKey:str, use_security_token:bool = True): self.authhelper = AuthHelper(oci_profile=oci_profile, use_security_token=use_security_token) self.authsigner = self.authhelper.Signer self.chat_url = chat_url self.sessionKey = sessionKey
def send(self, input:str) -> Response:
    body = {
        "isStreamEnabled" : False,
        "sessionKey" : self.sessionKey,
        "trace" : False,
        "input" :[{
            "role":"User",
            "content":[{
                "type" : "INPUT_TEXT",
                "text" : input                   
            }]
        }]
    }

    response:Request = requests.post(
        url =self.chat_url,
        params = None,
        auth = self.authsigner,
        json=body,
        headers={}
    )
    return response

È possibile chiamare l'URI dell'endpoint dell'agente creando un'istanza della classe MyRawJsonRPCClient e fornendo un valore di profilo OCI (che si trova nel file di configurazione OCI), l'URI dell'endpoint dell'agente (chat_url) e una sessionKey. È possibile fornire qualsiasi sessionKey arbitrario. sessionKey è l'identificativo univoco della sessione utente con l'agente. Se si continua a riutilizzare lo stesso sessionKey, i messaggi utente e le risposte dell'agente vengono aggiunti alla stessa conservazione.

client = MyRawJsonRpcClient(chat_url="<your-agent-flow-endpoint-uri>",
   oci_profile = "DEFAULT",
   sessionKey= “<your-session-key>”,
   use_security_token = False )

È inoltre possibile fornire un messaggio utente e utilizzare il client per inviare il messaggio all'URI dell'endpoint agente:

user_input = f"Hello, tell me a good dad joke."
r = client.send(input = user_input)
response_json = r.json()

Attraverso APEX

È possibile utilizzare l'esempio di codice disponibile nel repository Github di esempi di workbench di AI Data Platform. L'esempio descrive il processo di chiamata di un endpoint di distribuzione agente da un'applicazione APEX.

Attraverso Streamlit

È possibile utilizzare l'esempio di codice disponibile nel repository Github di esempi di workbench di AI Data Platform. L'esempio guida l'utente nel processo di chiamata di un endpoint di distribuzione agente da un'applicazione Streamlit.

Procedure ottimali - Risposte asincrone e non asincrone

Si consiglia di scrivere il codice client presumendo risposte asincrone. Ad esempio:

import httpx 
 
async def fetch_data(): 
    async with httpx.AsyncClient() as client: 
        response = await client.get(URL) 
        return response.json()

Annulla distribuzione di un agente

È possibile scegliere di annullare la distribuzione degli agenti per i quali si dispone delle autorizzazioni di gestione, rendendoli non disponibili per l'uso.

1. Nella home page andare alla cartella contenente l'agente che si desidera annullare la distribuzione.
2. Accanto all'agente, fare clic su Azioni e fare clic su Annulla distribuzione.
   
   

   

   
   
3. Fare clic su Annulla distribuzione.

Monitora agenti

È possibile monitorare i dettagli relativi alle sessioni e alle metriche degli agenti per visualizzare informazioni su come vengono utilizzati, sulle risorse utilizzate e altro ancora.

Nell'agente sono presenti più schede per la registrazione dei dettagli d'uso, la scheda Sessioni, la scheda Metriche e la scheda Attività. È possibile trovarli nella parte superiore dello sfondo dell'agente.

Traccia e intervalli

I trace forniscono l'osservabilità per gli agenti acquisendo e visualizzando il flusso di richieste agente. Gli intervalli sono gli oggetti che costituiscono una traccia. Ogni intervallo è un passo diverso del flusso, ad esempio i prompt chat di un utente, i richiami agente e i task del flusso di lavoro.

È possibile visualizzare i trace per la sessione corrente, l'esecuzione di test o le sessioni precedenti. Per visualizzare la traccia della sessione corrente, andare alla scheda Flusso e fare clic su Playground. Nel riquadro Dettagli nella parte inferiore della pagina viene visualizzato il trace della sessione corrente nel riquadro a sinistra. È possibile fare clic sugli oggetti nel trace per espanderli o visualizzare informazioni più dettagliate. Nel riquadro destro è possibile fare clic sulle schede Informazioni, Dettagli o Eventi per ulteriori informazioni sull'oggetto intervallo selezionato.

È possibile visualizzare i trace per le sessioni precedenti nella scheda Sessioni facendo clic sul nome della sessione.

Sessioni

Nella scheda Sessioni è possibile visualizzare una cronologia delle sessioni per questo agente. È possibile vedere se ogni sessione è riuscita o non è riuscita, l'origine URI, quando la sessione è stata avviata, la durata della sessione e i token utilizzati nella sessione. È possibile fare clic sull'ID sessione per ulteriori dettagli specifici sulla sessione e per visualizzare i trace per le sessioni specifiche.

È possibile filtrare le sessioni visualizzate utilizzando la barra di ricerca per filtrare in base all'ID sessione o all'origine URI, utilizzando i filtri data per visualizzare solo un intervallo di date specifico e il menu a discesa Stato sessione per filtrare in base all'esito positivo o negativo di una sessione.

Metriche

La scheda Metriche mostra un riepilogo dei dati di utilizzo per tutte le sessioni agente. L'elenco a discesa Intervallo di date filtra il periodo di tempo che si desidera visualizzare riepilogato nelle schede visualizzate. La selezione URI filtra l'origine di selezione URI per la quale si desidera visualizzare i dettagli. È possibile modificare le schede visualizzate e se includono o meno i grafici come rappresentazioni visive di utilizzo.

Attività

Nella scheda Attività viene visualizzato un riepilogo dello stato di distribuzione dell'agente. La colonna Operazione specifica il tipo di operazione di distribuzione (Distribuzione o Annulla distribuzione) e la colonna Stato specifica il risultato dell'operazione (Operazione riuscita, Errore, Avvertenza, Non riuscita). È possibile vedere chi ha avviato l'operazione e quando, nonché il messaggio di stato associato al risultato dell'operazione.

Visualizza sessioni agente

È possibile visualizzare una cronologia delle sessioni per l'agente e filtrare i risultati per visualizzare le tendenze e fornire assistenza per la risoluzione dei problemi.

1. Nella home page, andare all'agente.
2. Fare clic sulla scheda Sessioni.
3. Utilizzare i filtri per modificare le sessioni visualizzate.

Visualizza metriche agente

È possibile visualizzare i dettagli riepilogati dell'agente utilizzato, ad esempio l'uso del token, la durata delle sessioni, la latenza e altro ancora.

1. Nella home page, andare all'agente.
2. Fare clic sulla scheda Metriche.
3. Selezionare opzioni diverse dall'elenco a discesa Intervallo date per vedere le differenze tra le metriche e le sequenze temporali.
4. Selezionare opzioni diverse dall'elenco a discesa Selezione URI per filtrare le origini URI specifiche.

Sposta un agente

È possibile spostare gli agenti di cui si è proprietari o per i quali si dispone delle autorizzazioni di gestione.

1. Nella home page, andare alla cartella contenente l'agente che si desidera spostare.
2. Accanto all'agente che si desidera modificare, fare clic su Azioni e fare clic su Sposta.
3. Selezionare la nuova posizione dell'area di lavoro per l'agente. Fare clic su Sposta.

Copia un agente

È possibile copiare un agente di proprietà dell'utente o disporre delle autorizzazioni di gestione per un'altra posizione di un'area di lavoro disponibile.

È possibile copiare gli agenti nella stessa cartella o in una cartella diversa. I flussi agente possono essere copiati in cartelle in aree di lavoro diverse a cui si ha accesso. La configurazione dell'agente, nonché le impostazioni degli strumenti e del guardrail, vengono copiate. I collegamenti dei cluster di computazione AI non vengono copiati e devi collegare l'agente a un nuovo cluster di computazione AI per riprendere lo sviluppo.

1. Nella home page, andare alla cartella contenente l'agente che si desidera spostare.
2. Accanto all'agente che si desidera modificare, fare clic su Azioni e fare clic su Copia nell'area di lavoro.
3. Fornire un nuovo nome e una nuova descrizione per l'agente copiato, se necessario.
4. Fare clic su Sfoglia e selezionare una nuova posizione nell'area di lavoro in cui copiare l'agente. Fare clic su Seleziona.
5. Fare clic su·Copia.

Scarica file agente

È possibile scaricare i file agente e i relativi file di guardrail che contengono le definizioni per l'agente.

I file agente sono file JSON con estensione AFLOW e contengono le definizioni per l'agente. I file dei guardrail hanno l'etichetta _guardrails.JSON e contengono le definizioni dei guardrail per l'agente.

1. Passare alla cartella dell'agente nell'area di lavoro.
2. Fare clic sul nome dell'agente da scaricare.
   
   

   

   
   
3. Accanto al file AFLOW dell'agente, fare clic su Azioni, quindi fare clic su Scarica. Il file viene scaricato nel computer locale.
4. Accanto al file _guardrails.JSON, fare clic su Azioni, quindi su Scarica. Il file viene scaricato nel computer locale.