Creare flussi di lavoro agenziali

Modifica online

Un flusso di lavoro agenziale definisce un insieme di attività e controlli collegati tra loro, progettati per raggiungere uno scopo o un obiettivo aziendale specifico.

I flussi di lavoro agenziali non vengono eseguiti se non è disponibile un modello LLM. Se i modelli non sono configurati, un amministratore deve aggiungere i modelli necessari prima di eseguire i flussi di lavoro agenziali. Per ulteriori informazioni, consulta le sezioni "Scelta di un modello di base" e "Gestione di modelli di linguaggio grandi personalizzati tramite AI Gateway ".

Informazioni su questa attività

Quando si crea un flusso di lavoro agenziale, si inizia con un nodo iniziale e un nodo finale. Il nodo iniziale è il punto di ingresso del flusso di lavoro agenziale. Definisce gli input necessari per avviare l'esecuzione, come i valori forniti da un utente o da un sistema esterno. Inoltre, inizializza le variabili del flusso di lavoro agenziale che vengono utilizzate durante l'avanzamento del flusso di lavoro agenziale. Il nodo finale è il punto di uscita del flusso di lavoro agenziale. Definisce l'output che viene restituito quando il flusso di lavoro agenziale completa l'esecuzione.

L'ordine di creazione del flusso di lavoro agenziale dipende da voi. Se si conoscono i tipi di attività che si vogliono includere nella sequenza, si può iniziare ad aggiungerle.

Flussi di lavoro agenziali che vengono eseguiti in modo asincrono e possono essere di lunga durata. Quando si esegue uno strumento di flusso di lavoro agenziale in una chat, si forniscono gli input del flusso di lavoro agenziale, ma gli output del flusso di lavoro agenziale potrebbero non essere immediatamente disponibili. Utilizzare lo strumento di utilità Get flow status fornito per verificare lo stato dello strumento in qualsiasi momento e per recuperare le uscite dello strumento.

Suggerimento:

Se hai aggiunto un campo di input nel flusso di lavoro dell'agente e vuoi assicurarti che l'agente richieda tale input, contrassegna il campo come obbligatorio. Se si dispone di tipi di input nidificati, contrassegnare l'input come richiesto per le proprietà nidificate che si desidera che l'agente richieda. Se un input o una proprietà hanno un valore predefinito, l'agente potrebbe utilizzare il valore predefinito invece di richiedere all'utente un valore.

Creare un flusso di lavoro agenziale

Un flusso di lavoro agenziale può essere creato per un agente specifico o aggiunto direttamente al sistema.

Per creare un flusso di lavoro agenziale nel sistema:

  1. Dal menu Menu, seleziona " Build ".

  2. Spostarsi su Tutti gli strumenti.

    In un ambient IBM Cloud, seleziona dall'elenco degli spazi di lavoro quello in cui desideri creare il flusso di lavoro.

    Puoi scegliere un'area di lavoro globale o un'area di lavoro privata, oppure crearne una nuova, a seconda dei tuoi ruoli e delle autorizzazioni a livello di area di lavoro. Tutti i flussi di lavoro creati sono associati e visibili esclusivamente all'interno dell'area di lavoro selezionata.

  3. Selezionare uno strumento esistente o fare clic su Crea strumento + per aggiungere un nuovo strumento.

  4. Selezionare il flusso di lavoro agenziale.

  5. Inserisci un nome significativo per il flusso di lavoro.

  6. Clicca su Inizia a costruire. Si aprirà l'editor dei flussi; da qui potrai iniziare a creare il tuo flusso di lavoro Agent.

Per creare un flusso di lavoro agenziale per un agente:

  1. Dal menu Menu, seleziona " Build ".

  2. Spostarsi su Tutti gli agenti.

    In un ambient IBM Cloud, seleziona l'area di lavoro associata al tuo agente dall'elenco delle aree di lavoro.

  3. Trovate e fate clic sul vostro agente.

  4. Dal set di strumenti dell'agente, nella sezione Set di strumenti, fare clic su Aggiungi strumento.

  5. Fare clic su Flusso di lavoro agenziale.

  6. Inserisci un nome significativo per il flusso di lavoro.

  7. Clicca su Inizia a costruire. Si aprirà l'editor dei flussi; da qui potrai iniziare a creare il tuo flusso di lavoro Agent.

Modifica i dettagli del flusso di lavoro di Agent

Per modificare i dettagli del flusso di lavoro agenziale:

  1. Dal menu Menu, seleziona " Build ".

  2. Spostarsi su Tutti gli strumenti.

    In un ambient IBM Cloud, selezionare l'area di lavoro associata al flusso di lavoro dall'elenco delle aree di lavoro.

  3. Seleziona il flusso di lavoro, fai clic sull'icona Opzioni e seleziona icona dell'opzione Modifica dettagli.

  4. Nella scheda Panoramica, aggiorna il nome e inserisci una descrizione dello strumento.

  5. Fare clic sulla scheda Parametri per configurare gli ingressi e le uscite dello strumento.

  6. Fare clic su Aggiungi ingressi per definire l'ingresso. Per istruzioni dettagliate, vedere Aggiunta di ingressi

  7. Fare clic su Aggiungi uscite per definire l'uscita. Per le istruzioni dettagliate, vedere Aggiunta di uscite

  8. Fare clic su Eseguito.

Esempio di flussi di lavoro agentici

È possibile scaricare esempi di flussi di lavoro agentici dal sito https://github.com/IBM/ibm-watsonx-orchestrate-adk/tree/main/examples/flow_builder. Per informazioni su come importare i flussi di lavoro nel proprio ambiente di " watsonx Orchestrate ", consultare la sezione "Creazione di flussi di lavoro basati su agenti" nella documentazione dell'ADK.

Configura impostazioni di flusso di lavoro

Le impostazioni del flusso di lavoro consentono di associare automaticamente la cronologia delle chat agli input dei nodi e di personalizzare il modo in cui i dati vengono sintetizzati nelle conversazioni di grandi dimensioni.

Per configurare le impostazioni del flusso di lavoro:

  1. Nel generatore di flussi di lavoro, clicca impostazioni sul lato destro del sottotitolo.

  2. L'opzione Auto-map chat history to inputs è impostata su ON per impostazione predefinita, in modo da mappare automaticamente gli ultimi cinque turni di conversazione dalla chat history come input del nodo.

  3. Se si sceglie di personalizzare le istruzioni di riepilogo, fare clic su Modifica accanto a Istruzioni di riepilogo personalizzate.

    1. Inserire l' istruzione di riepilogo. Fornire indicazioni, ad esempio indicando quali elementi fondamentali devono rimanere invariati e quali contenuti possono essere tranquillamente omessi per ridurre le dimensioni.

    2. Fare clic su Salva.

Aggiungi strumenti

È possibile aggiungere strumenti a un flusso di lavoro agentico per estendere le capacità di un agente. Per ulteriori informazioni, vedere Aggiunta di strumenti.

Aggiungere agenti

È possibile aggiungere agenti a un flusso di lavoro agentico per gestire azioni specifiche all'interno del flusso. Per ulteriori informazioni, vedere Aggiunta di agenti.

Configurare i controlli del flusso di lavoro agenziale

I controlli del flusso di lavoro agenziale definiscono il percorso di esecuzione di un flusso di lavoro agenziale. Configurando i controlli dei flussi di lavoro agenziali, è possibile impostare condizioni, diramazioni e cicli che determinano il modo in cui i dati si spostano tra i nodi.

Aggiungere un controllo di diramazione

Un ramo controlla il percorso seguito in un flusso di lavoro agenziale. Il percorso viene definito in base alle condizioni specificate. È possibile definire più percorsi e condizioni di percorso per la diramazione. Se nessuna delle condizioni è soddisfatta, il flusso di lavoro agenziale segue il percorso predefinito.

Per aggiungere un ramo al flusso di lavoro agenziale:

  1. Per creare un ramo, o:

    • Clicca sull'icona Icona Aggiungi . Dalla scheda Nodi di flusso, fare clic e trascinare il controllo Ramo sulla tela. È possibile rilasciare il controllo direttamente su una linea del connettore o in qualsiasi punto dell'area di disegno.

    • Clicca sulla linea di collegamento tra i nodi iniziale e finale. Seleziona Aggiungi un controllo di flusso > Ramo. Una diramazione viene inserita automaticamente sulla linea del connettore.

  2. Il ramo è preconfigurato con un'istruzione if-else.

Aggiungi percorsi

Per aggiungere un percorso a un ramo:

  1. Fare clic sul ramo.

  2. Nella finestra del ramo, selezionare Aggiungi percorso.

Aggiungi condizioni di percorso

Per aggiungere una condizione a un percorso:

  1. Fare clic sul ramo.

  2. Individuare il percorso e selezionare Modifica condizione. Scegliere una delle seguenti opzioni per definire una condizione:

    • Per creare una condizione utilizzando il costruttore di condizioni :

      1. Nella finestra "Condition builder Builder condizioni ", fare clic su icona plus e selezionare una variabile dall'elenco a discesa " Variabili disponibili ".

      2. Fai clic su icona plus e seleziona un operatore dall'elenco a discesa.

      3. Fai clic icona plus e inserisci un valore.

      4. Premere Invio. Per aggiungere più di una condizione, selezionare Aggiungi condizione.

    • Per creare una condizione utilizzando l' editor di espressioni :

      1. Seleziona l'editor di Editor espressioniespressioni.

      2. Fare clic su Inserisci espressione e inserire l'espressione Python.

  3. Fare clic su Indietro.

Modifica o elimina una condizione

Per modificare le condizioni di un percorso:

  1. Fare clic sul ramo.

  2. Individuare il percorso e selezionare Modifica condizione. Scegliere una delle seguenti opzioni per modificare una condizione:

    • Per modificare una condizione utilizzando il costruttore di condizioni :

      1. Aggiornare la variabile, l'operatore e il valore.

      2. Fare clic su Invio.

    • Per modificare una condizione utilizzando l' editor di espressioni :

      1. Seleziona l'editor di Editor espressioniespressioni.

      2. Fare clic sull'espressione per aprire la finestra dell'editor e aggiornare l'espressione Python.

Per eliminare la condizione di un percorso:

  1. Fare clic sul ramo.

  2. Individuare il percorso e selezionare Modifica condizione.

  3. Fai clic su "Elimina condizione elimina".

Modifica percorsi

È possibile gestire i percorsi del ramo modificandone l'ordine, rinominando un percorso o eliminandolo.

Per modificare l'ordine dei percorsi:

  1. Fare clic sul ramo.

  2. Fai clic su "Altre azioni Altre azioni".

  3. Seleziona Sposta su o Sposta giù dall'elenco per modificare l'ordine.

È inoltre possibile modificare l'ordine dei percorsi cliccando e trascinando sposta l'icona accanto al percorso.

Per modificare un percorso:

  1. Fare clic sul ramo.

  2. Fai clic su "Altre azioni Altre azioni".

  3. Selezionare Modifica nome percorso e inserire il nuovo nome.

Per eliminare un percorso:

  1. Fare clic sul ramo.

  2. Fai clic su "Altre azioni Altre azioni".

  3. Selezionare Elimina.

Aggiungi un controllo Per ciascuno

A Per ogni controllo esegue una serie di azioni per ogni elemento di un elenco. La variabile iteratore rappresenta l'elemento corrente dell'elenco e la variabile indice indica la sua posizione, a partire da zero. È possibile utilizzarli per accedere ed elaborare ogni elemento dell'elenco.

Per creare un controllo For each, procedere in uno dei seguenti modi:

  • Clicca sull'icona Icona Aggiungi . Dalla scheda Nodi di flusso, fare clic e trascinare il controllo Per ciascuno sul riquadro. È possibile rilasciare il controllo direttamente su una linea del connettore o in qualsiasi punto dell'area di disegno.

  • Clicca sulla linea di collegamento tra i nodi iniziale e finale. Seleziona Aggiungi un controllo di flusso > Per ciascuno. Un Per ogni controllo viene inserito automaticamente nella linea di connessione.

È possibile scaricare un esempio di flusso di lavoro agentico relativo al controllo «For each» all'indirizzo https://github.com/IBM/ibm-watsonx-orchestrate-adk/tree/main/examples/flow_builder/recent_transactions. Per ulteriori informazioni, consultare la sezione "Esempi di flussi di lavoro agentici".

Elenco di selezione

Per selezionare un elenco per ogni controllo:

  1. Fare clic sul pulsante Per ogni controllo.

  2. Utilizzare una delle seguenti opzioni per selezionare un elenco:

    • Per impostazione predefinita, la funzione "auto-map" mappa automatica è abilitata e seleziona un oggetto elenco dall'input del flusso di lavoro di Agent.

Tuttavia, è possibile modificare questo comportamento predefinito e configurare l'oggetto elenco scegliendo le opzioni di variabile o di espressione.

  • Per configurare un oggetto elenco utilizzando una variabile, selezionare Variabile e scegliere una variabile dall'elenco Variabili disponibili.

  • Per configurare un oggetto elenco utilizzando un'espressione, selezionare Espressione e fare clic su "Inserisci espressione" nella sezione "Seleziona un campo elenco" per aprire la finestra dell'editor e aggiornare l'espressione " Python ".

Una volta selezionato l'oggetto elenco, le variabili iteratore e indice vengono fornite automaticamente.

Aggiungi variabili locali

Le variabili locali vengono utilizzate solo all'interno di un controllo For each e non sono accessibili al di fuori di esso. Ogni iterazione del metodo For può memorizzare risultati intermedi specifici per quell'iterazione. Questi valori sono memorizzati al loro interno e non possono essere condivisi tra le diverse iterazioni.

Per aggiungere variabili locali al controllo Per ogni controllo:

  1. Fare clic sul pulsante Per ogni controllo.

  2. Fai clic Modifica dettagli nella sezione Variabili locali.

  3. Selezionare Aggiungi nella finestra Variabili locali.

  4. Scegliere il tipo di variabile dall'elenco a discesa.

  5. Inserire il nome e la descrizione.

  6. Selezionare la casella di controllo Elenco di {object type} se si desidera memorizzare un elenco di valori nella variabile.

  7. Fare clic su Aggiungi.

Per aggiungere più di una variabile locale, clicca su Aggiungi.

Modifica o elimina una variabile locale

Per modificare una variabile locale:

  1. Fare clic sul pulsante Per ogni controllo.

  2. Fai clic Modifica dettagli nella sezione Variabili locali.

  3. Passa il mouse sulla variabile e seleziona Modifica.

  4. Aggiornare il nome e la descrizione nella finestra Aggiorna output.

  5. Fare clic su Salva.

Per eliminare una variabile locale:

  1. Fare clic sul pulsante Per ogni controllo.

  2. Fai clic Modifica dettagli nella sezione Variabili locali.

  3. Passa il mouse sulla variabile e seleziona Elimina.

Configura attività

Le attività definiscono le azioni che un flusso di lavoro agenziale può eseguire. È possibile configurare diversi tipi di x in base all'attività che si desidera svolgere.

Attività degli utenti

È possibile utilizzare l'attività dell'utente per creare interazioni basate su chat per raccogliere input e visualizzare i risultati all'interno di un flusso di lavoro agenziale. Per ulteriori informazioni, consultare la sezione "Aggiunta di attività utente".

Per un video dimostrativo su come aggiungere attività utente, consulta la sezione "Creazione di un flusso di lavoro autonomo con attività utente" all'indirizzo watsonx Orchestrate nella sezione Video.

Blocchi logici

È possibile utilizzare il blocco logico per aggiungere una logica personalizzata di " Python " direttamente all'interno di un flusso di lavoro agentico. Per ulteriori informazioni, consultare la sezione "Aggiunta di blocchi logici".

Spunti generativi

È possibile utilizzare un prompt generativo quando si ha bisogno di aiuto per compiti che richiedono la comprensione del linguaggio naturale. Funziona utilizzando un modello linguistico di grandi dimensioni (LLM) per generare testo o contenuti strutturati. Per i prompt generativi nei flussi di lavoro agenziali, è possibile aggiungere nuovi modelli attraverso l'AI Gateway. Per ulteriori informazioni, consulta la sezione "Aggiunta di prompt generativi".

Per un video dimostrativo su come aggiungere prompt generativi, consulta la sezione "Creazione di un flusso di lavoro autonomo con prompt generativi" all'indirizzo watsonx Orchestrate nella sezione Video.

Classificatori di documenti

È possibile aggiungere classificatori di documenti ai flussi di lavoro agenziali per identificare automaticamente i tipi di documenti. Per ulteriori informazioni, consultare la sezione "Aggiunta di classificatori di documenti".

Estrattori di documenti

È possibile aggiungere estrattori di documenti ai flussi di lavoro agenziali per estrarre campi o entità come date, nomi e altro dai documenti. Per ulteriori informazioni, consultare la sezione "Aggiunta di estrattori di documenti".

Estrattori di testo

È possibile utilizzare un estrattore di testo in un flusso di lavoro agenziale per estrarre il testo da un documento. Per ulteriori informazioni, consultare la sezione "Aggiunta di estrattori di testo".

Ispettore di flusso

Flow Inspector offre una panoramica completa della cronologia di esecuzione dei flussi di lavoro degli agenti, consentendoti di verificare come si è svolto un flusso di lavoro dall'inizio alla fine. È possibile esaminare le sequenze di esecuzione, analizzare i dati scambiati tra le fasi e individuare errori o comportamenti imprevisti. Per informazioni dettagliate sulle caratteristiche e le funzionalità di Flow Inspector, consultare la sezione "Ispezione dei flussi di lavoro degli agenti".

Input e output

Gli input sono i valori esterni che vengono passati al flusso di lavoro dell'agente durante l'esecuzione. Forniscono le informazioni iniziali necessarie affinché il flusso di lavoro agentico possa iniziare la propria esecuzione. Gli input possono includere valori forniti dall'utente, valori di sistema o dati ricevuti da altri processi.

Gli output sono i risultati generati al termine dell'esecuzione di un flusso di lavoro autonomo. Essi definiscono le informazioni restituite dal flusso di lavoro dell'agente, quali i dati elaborati o le risposte destinate ai nodi a monte. I risultati rendono disponibili i risultati del flusso di lavoro agentico per il riutilizzo in altri processi, strumenti o flussi di lavoro.

Aggiunta di dati

Per aggiungere input al flusso di lavoro agenziale:

  1. Fare clic sul nodo di avvio.

  2. Nella finestra Ingressi, fare clic su Aggiungi.

  3. Seleziona un tipo di input dall'elenco.

  4. Inserire un nome e una descrizione.

  5. Opzionale: selezionare la casella di controllo Elenco di {data type} per memorizzare un elenco di valori nell'input.

  6. Opzionale: attivare l'interruttore Set default values (Imposta valori predefiniti) per impostare l'input con un valore predefinito.

  7. Inserisci un valore e clicca Fine sul campo del valore predefinito.

  8. Fare clic su Aggiungi.

    • Se selezioni la casella di controllo "Elenco dei valori predefiniti" ( {data type} ), puoi inserire più di un valore predefinito nel campo "Elenco dei valori predefiniti".

    • La casella di controllo Elenco di {data type} non è disponibile per gli input di file e l'opzione Imposta valore predefinito non è disponibile per gli input di file e oggetti.

    • Per il tipo di dati "oggetto", è possibile scegliere tra la vista "Semplice" e la vista "JSON" per visualizzare le proprietà dell'oggetto.

Aggiunta di uscite

Per aggiungere le uscite del flusso di lavoro agenziale:

  1. Fare clic sul nodo finale.

  2. Nella finestra Uscite, fare clic su Aggiungi.

  3. Selezionare il tipo di uscita dall'elenco.

  4. Opzionale: selezionare la casella di controllo Elenco di {data type} per generare un elenco di valori come output.

  5. Fare clic su Aggiungi.

    • La casella di controllo " Elenco di {data type} " non è disponibile per gli input di file.

    • Per il tipo di dati "oggetto", è possibile scegliere tra la vista "Semplice" e la vista "JSON" per visualizzare le proprietà dell'oggetto.

Variabili di flusso in un flusso di lavoro agenziale

Le variabili di flusso vengono utilizzate durante l'esecuzione di un flusso di lavoro agenziale. È possibile selezionare le opzioni disponibili o definire variabili personalizzate. Consentono la condivisione dei dati tra i nodi, con valori intermedi conservati e disponibili in diverse fasi. Le variabili di flusso sono accessibili in tutto il flusso di lavoro agenziale e possono essere condivise e aggiornate tra i nodi.

Aggiunta di variabili di flusso

Per aggiungere variabili di flusso:

  1. Fai clic variabili di flusso sull'icona situata sul lato sinistro della finestra del flusso di lavoro agentico.

  2. Fare clic su Aggiungi e selezionare il tipo di variabile dall'elenco.

  3. Inserire un nome e una descrizione.

  4. Opzionale: selezionare la casella di controllo Elenco di {data type} per memorizzare un elenco di valori nella variabile.

  5. Opzionale: attivare l'interruttore Imposta valori predefiniti per impostare la variabile con un valore predefinito.

  6. Inserisci un valore e clicca Fine sul campo del valore predefinito.

  7. Fare clic su Aggiungi.

    • Se selezioni la casella di controllo "Elenco dei valori predefiniti" ( {data type} ), puoi inserire più di un valore predefinito nel campo "Elenco dei valori predefiniti".

    • L'opzione Imposta valore predefinito non è disponibile per le variabili file, oggetto e utente.

    • Per il tipo di dati "oggetto", è possibile scegliere tra la vista "Semplice" e la vista "JSON" per visualizzare le proprietà dell'oggetto.

Tipi di ingresso, uscita e variabili

La tabella seguente elenca gli ingressi, le uscite e i tipi di variabili disponibili in un flusso di lavoro agenziale:

Immettere

Descrizione

Booleano

Per definire ingressi, uscite o variabili che richiedono un valore vero o falso

Data/ora

Per definire una data, un'ora o un valore composto da data e ora. I valori relativi alla data utilizzano il formato mm/gg/aaaa. I valori relativi all'ora utilizzano il formato hh:mm con un selettore AM/PM. Per l'ora e la data, puoi anche selezionare un fuso orario dall'elenco fornito.

Decimale

Per definire valori numerici che includono punti decimali

File

Per definire un file che può essere trasferito all'interno o all'esterno di un flusso. Può essere utilizzato per caricare o scaricare file, elaborare documenti o trasferire file da o verso uno strumento all'interno del flusso.

Numero intero

Per definire i valori dei numeri interi

Oggetto

Per definire le proprietà degli oggetti di input, output o variabili utilizzando lo schema JSON

Stringa

Per definire ingressi, uscite o variabili basate sul testo

Utente

Per definire variabili che memorizzano dettagli relativi all'utente
Suggerimento:

  • Il tipo di dati Utente è disponibile solo per le variabili di flusso e attualmente non è supportato per gli ingressi o le uscite di flusso.

Prerequisiti per l'utilizzo del tipo di dati utente in un flusso di lavoro agentico

È possibile utilizzare il tipo di dati utente per definire variabili che contengono i dettagli degli utenti tenant. Prima di poter elencare gli utenti tenant in un flusso di lavoro agentico, è necessario configurare l'accesso alle API della piattaforma IBM Cloud.

In qualità di amministratore inquilino, completa i seguenti passaggi per configurare l'accesso:

  1. Crea un ID servizio o un utente che rappresenti la tua applicazione o il tuo flusso di lavoro. Per ulteriori informazioni, consultare la sezione Gestione degli ID dei servizi.

  2. Genera una chiave API per l'ID servizio. Per ulteriori informazioni, consultare la sezione "Gestione delle chiavi API dell'ID servizio ".

  3. Assegna i seguenti ruoli all'ID servizio o all'utente:

    • Ruolo di amministratore, limitato al tenant di destinazione wxO come risorsa

    • Ruolo di visualizzatore per tutti i servizi di gestione account IAM

Per ulteriori informazioni sull'assegnazione dei ruoli, consultare la sezione "Gestione dell'accesso alle risorse". Dopo aver assegnato questi ruoli, registra la chiave API dell'ID servizio o dell'utente come connessione con l'ID WXO_PLATFORM_USER_APIapplicazione predefinito.

Questo prerequisito è richiesto solo per i tenant di watsonx Orchestrate ospitati su IBM Cloud.

Configurazione connessione

Dopo aver completato i prerequisiti, segui questi passaggi per configurare la connessione:

  1. Attiva il tuo ambiente tenant.

    orchestrate env activate

  2. Aggiungi la connessione.

    orchestrate connections add -a WXO_PLATFORM_USER_API

  3. Configura la connessione per gli ambienti di bozza e live.

    orchestrate connections configure -a WXO_PLATFORM_USER_API --env draft -t -k <api_key> orchestrate connections configure -a WXO_PLATFORM_USER_API --env live -t -k <api_key>
  4. Imposta le credenziali della chiave API.

    orchestrate connections set-credentials -a WXO_PLATFORM_USER_API --env draft --api-key <api_key> orchestrate connections set-credentials -a WXO_PLATFORM_USER_API --env live --api-key <api_key>

Una volta completata la configurazione, il tuo flusso di lavoro agentico potrà accedere in modo sicuro ai dettagli degli utenti del tenant utilizzando il tipo di dati "utente".

Aggiunta di proprietà a un tipo di dati oggetto

È possibile aggiungere proprietà a un tipo di dati oggetto per input, output e variabili.

Per aggiungere proprietà a un tipo di dati oggetto:

  1. Selezionare il tipo di dati Oggetto dall'elenco.

  2. Inserire un nome e una descrizione.

  3. Opzionale: selezionare la casella di controllo Elenco di oggetti per memorizzare un elenco di valori nel tipo di dati oggetto.

  4. Fare clic su più accanto al nome dell'oggetto nell'albero degli oggetti oppure fare clic su Aggiungi + nella sezione Proprietà oggetto.

  5. Selezionare una proprietà dall'elenco.

  6. Inserire un nome e una descrizione.

  7. Opzionale: selezionare la casella di controllo Elenco di {data type} per memorizzare un elenco di valori nella proprietà dell'oggetto.

  8. Opzionale: attivare l'interruttore Imposta valori predefiniti per impostare le proprietà con un valore predefinito.

  9. Inserisci un valore e clicca Fine sul campo del valore predefinito.

  10. È possibile scegliere tra la visualizzazione semplice e la visualizzazione JSON per visualizzare le proprietà dell'oggetto.

  11. Fare clic su Salva.

L'opzione Imposta valore predefinito non è disponibile per le variabili oggetto.

Tipi di dati degli oggetti

Quando si definisce un oggetto, occorre considerare i seguenti elementi. Un oggetto include un nome, una descrizione facoltativa e un insieme di proprietà definite utilizzando un sottoinsieme semplificato dello standard dello schema JSON. Per ulteriori informazioni, consultare la documentazione relativa allo schema JSON.

Le proprietà possono essere esse stesse oggetti con proprietà annidate proprie. Possono anche essere elenchi, definiti utilizzando il tipo di array dello schema JSON.

Ecco un esempio che mostra le proprietà di un oggetto Employee definito utilizzando lo schema JSON

{
    "id": {
        "type": "integer",
        "description": "Unique identifier for the employee"
    },
    "firstName": {
        "type": "string",
        "description": "Employee's first name"
    },

    "lastName": {
        "type": "string",
        "description": "Employee's last name"
    },
    "email": {
        "type": "string",
        "description": "Employee's email address"
    },
    "department": {
        "type": "string",
        "description": "Employee's department"
    },
    "salary": {
        "type": "number",
        "description": "Employee's salary"
    },
    "isActive": {
        "type": "boolean",
        "description": "Whether the employee is currently active"
    },
    "startDate": {
        "type": "string",
        "format": "date",
        "description": "Employee's start date"
    },
    "badges": {
        "type": "array",
        "items": {
            "type": "string"
        },
        "description": "Employee's badges"
    },
    "address": {
        "type": "object",
        "properties": {
            "street": {
                "type": "string"
            },
            "city": {
                "type": "string"
            },
            "zipCode": {
                "type": "string"
            }
        }
    }
}

Lo schema dell'oggetto dipendente include le seguenti proprietà:

  • id, email, salary isActive, e startDate sono semplici proprietà che contengono valori interi, stringhe, decimali, booleani e date.

  • address è una proprietà dell'oggetto con proprietà nidificate: strada, città e zipCode.

  • badges è un elenco, espresso come array JSON Schema di valori stringa.

È possibile scaricare un esempio di flusso di lavoro Agentics relativo al tipo di dati Object all'indirizzo https://github.com/IBM/ibm-watsonx-orchestrate-adk/tree/main/examples/flow_builder/Employee_information. Per ulteriori informazioni, consultare la sezione "Esempi di flussi di lavoro agentici".

mappatura dei dati

I nodi di un flusso di lavoro agenziale possono richiedere dati in ingresso. Questi dati possono provenire dagli input del flusso di lavoro agenziale, dagli output dei nodi a monte e dal contesto della sessione di chat.

Quando un flusso di lavoro agenziale viene completato, può anche produrre dati come output. I dati prodotti dal flusso di lavoro agenziale possono provenire dagli input del flusso di lavoro agenziale o dai nodi all'interno del flusso di lavoro agenziale.

Per impostazione predefinita, quando un nodo richiede dati in ingresso, il motore del flusso di lavoro agenziale tenta di identificare potenziali fonti di dati. Se il motore del flusso di lavoro agenziale individua un'origine, mappa automaticamente i dati nel nodo. Tuttavia, è possibile ignorare questo comportamento predefinito e fornire una mappatura sui nodi o sull'output del flusso di lavoro agenziale. Per sovrascrivere il comportamento di mappatura dell'output del flusso di lavoro agenziale, selezionare il nodo Fine del flusso di lavoro agenziale.

Per modificare la mappatura dei dati in un worklow agenziale, selezionare il nodo e fare clic su Modifica mappatura dati.

Sono disponibili le seguenti opzioni di mappatura dei dati:

  • Mappatura automatica: Un flusso di lavoro agenziale mappa automaticamente i dati tra le fasi, collegando gli ingressi dei nodi alle uscite di altri nodi o agli ingressi del flusso di lavoro agenziale stesso. Se un dato richiesto non viene prodotto da nessun nodo del flusso di lavoro agenziale, è possibile definire un input a livello di flusso di lavoro agenziale con lo stesso nome e tipo. Il motore del flusso di lavoro agenziale lo mappa automaticamente, garantendo così un trasferimento dei dati senza soluzione di continuità nell'intero flusso di lavoro agenziale.

Utilizzo del contesto della sessione di chat nella mappatura automatica

In precedenza, i flussi di lavoro agenziali non avevano accesso automatico alle informazioni inserite nella chat prima dell'attivazione del flusso di lavoro. Per rendere disponibili le informazioni al flusso di lavoro, è stato necessario definire gli input del flusso e istruire l'agente a popolarli dal contesto della chat. Questo processo non è più necessario e i flussi di lavoro possono ora accedere facilmente alle informazioni più recenti nel contesto della chat.

L'attivazione del contesto della sessione di chat include gli ultimi 5 turni di conversazione presenti nella cronologia della chat. Un turno di conversazione si riferisce a un singolo scambio tra un utente e l'agente in una chat.

I flussi di lavoro di tipo "agentico" supportano questa funzionalità per impostazione predefinita. Se desideri disattivarla o vuoi verificare se è abilitata per il tuo flusso di lavoro specifico:

  1. Aprire il flusso di lavoro agenziale.

  2. Fai clic sull'icona Icona ImpostazioniImpostazioni.

  3. Utilizzare l'interruttore Mappa automatica cronologia chat su ingressi per attivare o disattivare la funzione.

Se la mappatura automatica non ha successo, è possibile chiedere all'utente di fornire l'input richiesto in una chat. Per abilitare questo comportamento, impostare l'interruttore Chiedi all'utente l'input se la mappatura automatica non ha successo su on quando si automatizzano i dati.

Mappatura automatica

  • Parametri vuoti: per impostare un parametro come vuoto, disattivare l'opzione "Mappa automatica" per il parametro del nodo. Se i parametri di input per un nodo di un flusso di lavoro agenziale sono lasciati vuoti o in bianco, non viene passato alcun valore al parametro di input in tutto il flusso di lavoro agenziale.

Parametro vuoto

  • Python espressioni: È possibile aggiungere le espressioni di Python per i parametri dei nodi in un flusso di lavoro agenziale.

Espressione

  • Variabili: È possibile aggiungere variabili per i parametri dei nodi in un flusso di lavoro agenziale.

Variabili

  • Valori letterali: È possibile aggiungere un valore letterale specifico per l'esecuzione del flusso di lavoro agenziale, come un numero o una data, ai parametri dei nodi di un flusso di lavoro agenziale. Per aggiungere un valore letterale, chiudere l'opzione Auto-map per il parametro del nodo. L'opzione di impostare un valore predefinito non è disponibile per i parametri che sono mappati su valori letterali.

Valore letterale

  • Valori predefiniti: È possibile aggiungere un valore predefinito specifico ai parametri dei nodi in un flusso di lavoro agenziale. L'opzione di impostare un valore predefinito non è disponibile per i parametri che sono mappati su valori letterali.

Valore predefinito

Formato data/ora per blocchi di codice ed espressioni

Quando si definiscono valori di data e ora nei blocchi di codice o nelle espressioni della mappa dei dati, utilizzare il formato standard ISO 8601 con supporto dei fusi orari IANA:

Formato ISO 8601 : YYYY-MM-DDThh:mm:ss±hh:mm[timezone/location]

Esempio : 2026-02-19T07:15:00+05:00[Europe/London]

Suddivisione per formato :

  • Data : YYYY (Anno), MM (Mese), DD (Giorno)

  • Ora : hh (Ore), mm (Minuti), ss (Secondi)

  • Separatore : una "T" separa la data e l'ora

  • Fuso orario : «Z» (UTC) o un ±hh:mm differenziale

  • Posizione del fuso orario : identificatore IANA del fuso orario tra parentesi quadre (ad esempio, [Europe/London])

L'indicazione del fuso orario è consigliata, ma può essere omessa. Questo formato garantisce un ordinamento logico, elimina ogni ambiguità e assicura il riconoscimento a livello internazionale.

Cosa fare successivamente

Il flusso di lavoro agenziale è stato creato. È possibile utilizzare l'anteprima della chat per testare il flusso di lavoro agenziale.

Un'attività utente consiste in una o più interazioni basate sulla chat per raccogliere input e visualizzare risultati all'interno di un flusso di lavoro agenziale.

Un blocco logico aggiunge una logica personalizzata come logic Python a all'interno del flusso di lavoro dell'agente.

Un prompt generativo utilizza le capacità dei modelli linguistici di grandi dimensioni (LLM) per i compiti.

Un classificatore di documenti identifica automaticamente i tipi di documenti.

Un estrattore di documenti ottiene campi ed entità dai documenti.

Un estrattore di testo ricava il testo da un documento.