Configurare e usare un agente nella chat

In ALIDA è possibile esporre un endpoint per ogni agente. La chat della BDA può essere collegata, tramite questi endpoint, a più agenti usando una variabile d'ambiente contenente la relativa configurazione JSON. Le variabili d'ambiente si impostano dal pannello Personalizzazione Variabili d'ambiente.

Che cos'è un agente, e che cosa non lo è

Un agente è un Service ALIDA, ma non tutti i Service possono essere usati come agenti. Un Service è utilizzabile come agente quando ha entrambe queste caratteristiche:

• è long-running: resta attivo per tutta la vita del workflow e continua a rispondere alle richieste, invece di eseguire una volta e terminare;
• espone porte REST: un endpoint di invocazione e, normalmente, un endpoint di streaming, che la chat richiama.

Un normale Service batch, che legge un dataset, lo trasforma e termina, non può essere usato come agente, anche se il workflow che lo contiene ha un URL. Non resta in esecuzione e non parla il protocollo della chat. Lo stesso vale per un workflow la cui esecuzione è già terminata.

Gli agenti attualmente distribuiti con ALIDA sono l'agente OpenCode e l'ADK Agent. Per usarne uno, inserirlo in un workflow, configurarne le porte e avviare il workflow: gli endpoint esistono solo finché quel workflow è in esecuzione.

Come leggere l'URL dell'endpoint

L'URL di un agente in esecuzione si presenta così:

https://alida.devng.alidalab.it/events/bda/11150/11152/v1
└──────────── istanza ────────┘           └─┬─┘ └─┬─┘ └┬┘
                                            │     │    └── suffisso di protocollo, solo OpenAI
                                            │     └─────── id del Service agente
                                            └───────────── id del workflow in esecuzione (BDA)

I due numeri non sono valori da scegliere o da cercare in un catalogo: identificano uno specifico agente all'interno di una specifica esecuzione di un workflow. Cambiano solo quando il workflow viene modificato o ricreato: fermare e riavviare il workflow senza apportare modifiche non ne cambia gli id. Dopo una modifica o una ricreazione, però, la configurazione va aggiornata. Copiare l'URL dal Workflow Designer invece di scriverlo a mano, come descritto in Recuperare gli URL dell'agente.

Prima di iniziare

Verificare di disporre di:

• Un agente in esecuzione all'interno di un workflow. Gli endpoint esistono solo finché il workflow è in esecuzione: un agente il cui workflow è stato fermato o eliminato risponde con 404 – bda-id <id> has not been initialized.
• L'accesso al Workflow Designer di quel workflow, per copiare l'URL dell'endpoint.
• Il protocollo API esposto dall'agente, OpenCode oppure OpenAI.
• L'accesso al pannello di personalizzazione dell'environment dell'istanza ALIDA, dove viene salvata la configurazione.

Configurazione a livello di istanza

La configurazione dell'agente non è per utente: viene scritta nel file di environment dell'istanza ALIDA ed è quindi condivisa da tutti gli utenti di quell'istanza. Farla puntare a un workflow destinato a restare in esecuzione, perché se quel workflow viene fermato l'agente smette di funzionare per tutti.

Recuperare gli URL dell'agente

URL di invocazione (url)

L'agente viene invocato tramite un endpoint REST esposto dal workflow, esattamente come qualsiasi altra porta di tipo REST API. Aprire il workflow nel Workflow Designer, selezionare l'agente e copiare l'URL dell'endpoint cliccandoci sopra nel pannello di destra.

Output storage della porta

Prima di avviare il workflow, la porta che espone l'endpoint deve avere selezionato un output storage di tipo Remote. Cliccare sul pallino che rappresenta la porta sull'agente, quindi scegliere per essa un output storage di tipo Remote. Se l'output storage non è di questo tipo, il workflow viene eseguito come un batch: attende la terminazione del Service prima di proseguire, ma un Service agente long-running non termina mai, quindi il workflow non arriva mai a esporre l'endpoint.

L'URL copiato ha questa forma:

https://alida.devng.alidalab.it/events/bda/11150/11152

Per capire come ALIDA espone e protegge questi endpoint, consultare Porte I/O: Endpoint REST API.

Protocollo OpenAI

Per un agente che espone API compatibili con OpenAI, come l'ADK Agent, aggiungere il suffisso /v1 all'URL copiato:

https://alida.devng.alidalab.it/events/bda/11150/11152/v1

URL di streaming (streamingUrl)

L'endpoint di streaming non ha un pulsante di copia nel Workflow Designer: va costruito a partire dall'URL copiato, inserendo streaming/ subito dopo /events/bda/ e lasciando invariato il resto del percorso.

URL copiato:      https://alida.devng.alidalab.it/events/bda/11150/11152
URL di streaming: https://alida.devng.alidalab.it/events/bda/streaming/11150/11152

Il suffisso /v1 usato per l'invocazione compatibile con OpenAI non va aggiunto all'URL di streaming.

Scrivere la configurazione

La configurazione è un oggetto JSON salvato nel file di environment dell'istanza, dal pannello descritto in Personalizzazione Variabili d'ambiente.

Campo	Cosa inserire
type	agent, per dichiarare la voce come agente della chat.
name	Testo libero. È il nome mostrato all'utente al momento della scelta dell'agente nella chat.
url	L'URL di invocazione copiato dal Workflow Designer, con il suffisso /v1 quando il protocollo è OpenAI.
streamingUrl	L'URL di streaming derivato dall'URL copiato, come descritto sopra. Lasciare vuoto se l'agente non espone lo streaming.
token	Lasciare vuoto (""): l'autenticazione dell'utente collegato è gestita da extra.queryParams.
protocol	Il protocollo esposto dall'agente: OpenCode per l'agente OpenCode, OpenAI per qualsiasi agente con API compatibili con OpenAI, come l'ADK Agent.
contextPage	L'elenco delle pagine ALIDA in cui l'agente è utilizzabile nella chat, come voci {"path": "<percorso-pagina>"}, ad esempio /services per la pagina Services. Lasciare l'elenco vuoto per rendere l'agente disponibile in ogni pagina di ALIDA.
extra.queryParams	Parametri aggiuntivi della chiamata. Mantenere "token": "NaN": il segnaposto viene sostituito a runtime con il token dell'utente collegato, che autentica la chiamata all'endpoint.

Il segnaposto del token non è un'API key

Questo token è diverso dall'API key di Ollama o di MLflow. È il token di autenticazione fornito dalla piattaforma ALIDA per l'utente collegato, usato per autorizzare le chiamate tra i componenti interni — in questo caso, dalla chat all'endpoint dell'agente. Non sostituire il segnaposto con una propria chiave: lasciarlo come NaN.

Esempi di configurazione

Negli esempi che seguono, sostituire i segnaposto con i valori del proprio workflow in esecuzione: <bda-id> è l'id del workflow in esecuzione (BDA), mentre <service-id> è l'id del Service relativo all'agente avviato — si trova nella sezione Services di quel workflow. Invece di comporre l'URL a mano, aprire il workflow nel Workflow Designer e copiare l'URL dell'endpoint cliccandoci sopra, come descritto in Recuperare gli URL dell'agente: l'URL copiato contiene già entrambi gli id.

OpenCode

{
  "type": "agent",
  "name": "Custom Coding Agent",
  "url": "https://<url-istanza-alida>/events/bda/<bda-id>/<service-id>",
  "streamingUrl": "https://<url-istanza-alida>/events/bda/streaming/<bda-id>/<service-id>",
  "token": "",
  "protocol": "OpenCode",
  "contextPage": [
    {
      "path": "/services"
    }
  ],
  "extra": {
    "queryParams": {
      "token": "{{alida-token}}"
    }
  }
}

Endpoint compatibile con OpenAI

Usare questa configurazione per qualsiasi agente che espone API compatibili con OpenAI. L'ADK Agent è uno degli agenti che integra questo tipo di endpoint.

{
  "type": "agent",
  "name": "Alida Agent",
  "url": "https://<url-istanza-alida>/events/bda/<bda-id>/<service-id>/v1",
  "streamingUrl": "https://<url-istanza-alida>/events/bda/streaming/<bda-id>/<service-id>",
  "token": "",
  "protocol": "OpenAI",
  "contextPage": [
    {
      "path": "/services"
    }
  ],
  "extra": {
    "queryParams": {
      "token": "{{alida-token}}"
    }
  }
}

La stessa configurazione, compilata con gli URL copiati da un workflow in esecuzione, si presenta così:

{
  "type": "agent",
  "name": "Alida Agent",
  "url": "https://alida.devng.alidalab.it/events/bda/11150/11152/v1",
  "streamingUrl": "https://alida.devng.alidalab.it/events/bda/streaming/11150/11152",
  "token": "",
  "protocol": "OpenAI",
  "contextPage": [
    {
      "path": "/services"
    }
  ],
  "extra": {
    "queryParams": {
      "token": "{{alida-token}}"
    }
  }
}

Prima richiesta

1. Raggiungere la pagina indicata in contextPage, ad esempio /services.
2. Aprire la chat, selezionare l'agente tramite il name indicato nella configurazione e formulare una richiesta coerente con il contesto.
3. Verificare il risultato prima di usare o distribuire gli artefatti prodotti.

Risoluzione dei problemi

Sintomo	Causa e soluzione
404 – bda-id <id> has not been initialized	Il workflow che espone l'agente non è in esecuzione, oppure l'URL punta a un workflow non più esistente. Avviare il workflow e copiare di nuovo l'URL dal Workflow Designer.
L'agente non compare nella chat	La pagina corrente non è tra quelle dichiarate in contextPage. Raggiungere una delle pagine dichiarate, oppure lasciare contextPage vuoto per rendere l'agente disponibile ovunque.
La risposta arriva tutta insieme, o lo streaming fallisce	Verificare streamingUrl: streaming/ deve seguire /events/bda/ e l'URL non deve terminare con /v1.
La chiamata viene rifiutata come non autorizzata	Verificare che extra.queryParams.token contenga NaN e che l'utente abbia i permessi per accedere al workflow che espone l'agente.