ADK Agent
L'ADK Agent è un agente personalizzato, implementato con ADK e pensato come esempio di scaffolding per ALIDA. È un servizio a esecuzione continua che espone sia le API native di ADK sia un wrapper compatibile con le API OpenAI. La sua struttura iniziale può essere adattata modificando il prompt e integrando server MCP, per creare agenti dedicati a compiti specifici oppure un orchestratore di funzionalità esterne.
Può assumere il ruolo di orchestratore, ma non è il suo unico impiego. La personalizzazione del prompt e l'integrazione con server MCP consentono di raccogliere informazioni, coordinare strumenti remoti o combinare le funzionalità esposte da uno o più servizi ALIDA configurati per svolgere il ruolo di server MCP.
L'agente può collegarsi a servizi ALIDA esposti come server MCP, quali BraveSearch, GitLab o altri agenti ADK. Può inoltre essere esposto come server MCP, così da poter essere utilizzato da altri agenti, ad esempio dall'agente OpenCode. Il comportamento dipende dai servizi MCP collegati, dalla personalizzazione del prompt e dalle decisioni dell'agente durante l'esecuzione.
Le API native di ADK consentono di invocare direttamente l'agente e di gestirne sessioni e stato. L'esempio seguente invia un messaggio all'endpoint /run; sostituire AGENT_URL con l'URL base dell'istanza e memory_agent con il nome dell'applicazione ADK configurata.
curl -X POST "$AGENT_URL/run" \
-H "Content-Type: application/json" \
-d '{
"appName": "memory_agent",
"userId": "alice",
"sessionId": "session-001",
"newMessage": {
"role": "user",
"parts": [{"text": "Come mi chiamo?"}]
}
}'
Il wrapper OpenAI permette invece di usare client e interfacce già compatibili con questo standard, come Open WebUI e LangChain. Per ottenere i modelli disponibili:
Per inviare un messaggio tramite l'endpoint OpenAI-compatible /v1/chat/completions:
curl -X POST "$AGENT_URL/v1/chat/completions" \
-H "Content-Type: application/json" \
-d '{
"model": "memory_agent",
"messages": [
{"role": "user", "content": "Come mi chiamo?"}
],
"user": "alice",
"session_id": "session-001"
}'
I campi aggiuntivi user e session_id non fanno parte dello standard OpenAI: il wrapper li usa per associare la richiesta a un utente e mantenerne la memoria conversazionale.
La UI di sviluppo dell'agente è disponibile all'URL della BDA con il suffisso /dev-ui/:
Ad esempio:
Slash finale obbligatorio
L'URL della UI deve terminare con /. L'indirizzo senza slash finale potrebbe non caricare correttamente le risorse dell'interfaccia.
Dopo il deploy e l'avvio dell'agente, collegarne l'endpoint compatibile con le API OpenAI alla chat della BDA seguendo Configurare un agente nella chat. Per il tracciamento e la governance delle richieste, vedere Osservabilità con MLflow.