Aggiunta di un'estensione all'assistente

Dopo aver creato un'estensione personalizzata, è necessario aggiungerla all'assistente prima che sia accessibile alle azioni.

L'aggiunta dell'estensione all'assistente configura l'estensione per l'uso in un particolare ambiente e la rende disponibile in modo che possa essere richiamata dalle azioni.

È possibile utilizzare dettagli di configurazione diversi per ogni ambiente. Ad esempio, si potrebbe voler utilizzare URL per un server di prova nell'ambiente di bozza, ma per un server di produzione nell'ambiente live.

Per informazioni su come creare un'estensione personalizzata, vedere Creazione di un'estensione personalizzata.

Aggiunta dell'estensione all'ambiente di progetto

Per aggiungere un'estensione personalizzata all'assistente, procedere come segue:

Nella pagina delle integrazioni di ', scorrere la sezione Estensioni e trovare il riquadro dell'estensione personalizzata che si desidera aggiungere.
Fare clic su Aggiungi. Esaminare la panoramica dell'estensione e fare clic su Conferma per configurarla per l'assistente.

Quando si aggiunge per la prima volta un'estensione a un assistente, le impostazioni di configurazione fornite vengono applicate solo all'ambiente della bozza. È necessario completare la configurazione dell'ambiente di bozza prima di poter aggiungere l'estensione nell'ambiente live. Leggere la sezione Configurazione dell'estensione per l'ambiente live per sapere come aggiungere l'estensione personalizzata all'ambiente live o ad altri ambienti.
Leggete le informazioni contenute nel passo Iniziare, quindi fate clic su Avanti.
Nel passaggio Autenticazione, specificare le informazioni di autenticazione e del server che si desidera che l'assistente utilizzi quando chiama il servizio.
- Nel campo Tipo di autenticazione, selezionare il tipo di autenticazione da utilizzare (o Nessuna autenticazione se l'API non è autenticata). I tipi di autenticazione disponibili sono determinati dagli schemi di sicurezza definiti nel documento OpenAPI.
- Specificare le informazioni aggiuntive richieste per il tipo di autenticazione selezionato (ad esempio, nome utente e password, chiave API, token portatore o dettagli OAuth 2.0 ).
  
  Per ulteriori informazioni sulla configurazione dell'autenticazione OAuth 2.0, vedere Autenticazione OAuth 2.0.
- Nel campo Server, selezionare il server URL da utilizzare.
  
  Se il sito URL selezionato contiene delle variabili, specificare anche i valori da utilizzare. A seconda di come ogni variabile è definita nel documento OpenAPI, è possibile selezionare da un elenco di valori validi o digitare il valore da utilizzare nel campo.
  
  Il messaggio Generated URL mostra l'intero URL utilizzato dall'assistente, compresi i valori delle variabili.
Fare clic su Avanti.
La tabella delle operazioni di revisione mostra le operazioni che l'assistente può richiamare da una fase d'azione. Un' operazione è una richiesta effettuata con un particolare metodo HTTP, come GET o POST, su una particolare risorsa.

Rivedere la tabella delle operazioni

Per ogni operazione, una riga della tabella riporta le seguenti informazioni:
- Operazione: Descrizione dell'operazione, derivata dal " summary (se presente) o dal " description del file OpenAPI.
- Metodo : Il metodo HTTP utilizzato per inviare la richiesta API per l'operazione.
- Risorsa: Il percorso della risorsa su cui agisce l'operazione.
Per visualizzare ulteriori informazioni su un'operazione, fare clic sull'icona " accanto alla relativa riga nella tabella. Sono visualizzati i seguenti dettagli:
- Parametri della richiesta: L'elenco dei parametri di ingresso definiti per l'operazione, insieme al tipo di ciascun parametro e al fatto che il parametro sia obbligatorio o opzionale.
- Proprietà della risposta: Le proprietà del corpo della risposta che sono mappate su variabili a cui l'assistente può accedere.
Fare clic su Fine.
Fare clic su Chiudi per tornare alla pagina delle integrazioni.

L'estensione è ora collegata all'assistente e disponibile per le azioni nell'ambiente di bozza.

Gestione dell'estensione

Dopo aver aggiunto l'estensione personalizzata all'ambiente, è possibile rivedere o sostituire il documento OpenAPI e aggiornare il tipo di autenticazione.

Nell'estensione, fare clic su Apri.
Selezionare l'ambiente in cui si desidera gestire l'estensione personalizzata e fare clic su Conferma.
Nella fase Gestisci estensione, è possibile rivedere e sostituire il documento OpenAPI importato, se necessario. Per ulteriori informazioni sulla sostituzione del documento OpenAPI, vedere Sostituzione del documento OpenAPI.

Nella scheda Autenticazione vengono visualizzate le informazioni sui metodi di autenticazione definiti nel documento OpenAPI. La tabella '. Campi della scheda Autenticazione La tabella fornisce dettagli sui campi della scheda Autenticazione:

Nome campo	Descrizione	Valori
Tipo di autenticazione	Il tipo di autenticazione impostato nello script OpenAPI.	- `OAuth 2.0` - `Basic Auth` - `API key auth` - `Bearer auth`
Nome utente	La credenziale del nome utente nello script OpenAPI.	Ad esempio, `user`
Password	La password di credenziale impostata nello script OpenAPI.	Ad esempio, `Password@123`
Server	Il link al server definito nel documento Open API per connettersi all'estensione API.	Ad esempio, `https://custom-extension-server.xyz`

Autenticazione OAuth 2.0

Se si configura l'autenticazione OAuth 2.0, le informazioni da fornire dipendono dal tipo di concessione.

Per ulteriori informazioni su OAuth 2.0, vedere OAuth 2.0.

Per completare l'impostazione dell'autenticazione OAuth, procedere come segue:

Se non l'avete ancora fatto, registrate la vostra applicazione con l'API esterna a cui volete accedere. Copiare l'ID e il segreto del client forniti dall'API esterna.
Nel campo Tipo di sovvenzione, selezionare il tipo di sovvenzione che si desidera utilizzare. I tipi di sovvenzione disponibili sono determinati dai flussi definiti nell'oggetto 'securitySchemes del documento OpenAPI. Sono supportati i tipi di codice di autorizzazione, credenziali del cliente, password e sovvenzioni personalizzate che iniziano con 'x-.

Il tipo di sovvenzione personalizzata OAuth2 " x-<any custom name> è utilizzato dal meccanismo di autenticazioneIBM IAM e da watsonx.

Specificare i valori richiesti che sono stati forniti dall'API esterna quando si è registrata l'applicazione. I valori richiesti dipendono dal tipo di sovvenzione:

Tipi di concessione
Tipo di autorizzazione	Valori richiesti
Codice di autorizzazione	ID client Segreto client
Credenziali client	ID client Segreto client
Password	ID client Segreto client Nome utente Password
`x-<any custom name>`	Un elenco di campi segreti citati nel file spec di openAPI

Se si utilizza il tipo di sovvenzione Codice di autorizzazione, procedere come segue:
1. Copiare il reindirizzamento URL dalla pagina delle impostazioni dell'estensione AI assistant builder e incollarlo nel campo appropriato della pagina di registrazione dell'applicazione per l'API esterna. (Il reindirizzamento URL è talvolta chiamato callback URL )
2. Fare clic su Concedi accesso. Si viene reindirizzati alla pagina di autorizzazione del sito web del servizio esterno. Verificare che sia stato concesso l'accesso corretto e fare clic su Approva. Si viene quindi reindirizzati alla pagina di impostazione dell'estensione utilizzando il reindirizzamento URL.
Nel campo Autenticazione client, specificare se le credenziali di autenticazione sono inviate in un'intestazione HTTP o come parte del corpo della richiesta. (Le credenziali inviate nel corpo della richiesta utilizzano il tipo di contenuto " x-www-form-urlencoded ) Selezionare l'opzione prevista dal servizio esterno.
Nel campo Prefisso dell'intestazione, specificare il prefisso che precede il token di accesso nell'intestazione 'Authorization. (Il prefisso predefinito è " Bearer, tipico della maggior parte delle applicazioni)
Se si utilizza il tipo di sovvenzione personalizzata 'x-<any custom name> (ad esempio, x-apikey), seguire questi passaggi:
1. Aggiungere i valori segreti associati ai campi segreti.
2. Aggiungere i valori dei parametri opzionali, se presenti.

Se il servizio esterno supporta il tipo di concessione Refresh Token, il costruttore di assistenti AI ottiene automaticamente un nuovo token di accesso alla scadenza di quello vecchio. Se il documento OpenAPI definisce l'attributo refreshUrl , viene utilizzato l'attributo URL specificato; altrimenti, viene utilizzato tokenUrl URL.

Configurazione dell'estensione per l'ambiente live

Per configurare l'estensione per l'ambiente live, procedere come segue:

Nella pagina delle integrazioni di ', scorrere la sezione Estensioni e trovare il riquadro dell'estensione personalizzata che si desidera aggiungere.
Fare clic su Open. Si apre la finestra Apri estensione personalizzata.
Nel campo Ambiente, selezionare Vivi. Fare clic su Conferma.
Ripetere la procedura di configurazione, specificando i valori che si desidera utilizzare per l'ambiente live.

Se si utilizzano più ambienti, seguire la stessa procedura per configurare l'estensione per ogni ambiente. Per ulteriori informazioni, vedere Aggiunta e utilizzo di ambienti multipli.

L'estensione è ora disponibile negli ambienti configurati e può essere richiamata dall'assistente. Per ulteriori informazioni su come chiamare un interno da un'azione, vedere Chiamare un interno personalizzato.