Introduzione al livello semantico agentico

In questo post mostriamo come costruire un livello semantico per l’intelligenza artificiale agentica utilizzando EDB Postgres AI. L’agente Strands Agents viene eseguito su Amazon Bedrock AgentCore e interroga il livello semantico per rispondere a domande tipiche di un profilo cliente a 360° (C360). Le pubblicazioni precedenti della serie hanno realizzato lo stesso modello C360 con Stardog, Denodo, AtScale e Strategy Mosaic.

EDB Postgres AI inserisce il livello semantico all’interno del database operativo PostgreSQL grazie all’estensione AIDB. Il significato di business vive accanto ai dati nei normali comandi COMMENT, il grafo di join è ricavato dalle chiavi esterne di PostgreSQL e la governance si basa su GRANT e sulla sicurezza a livello di riga tramite il Model Context Protocol (MCP) fornito con AIDB.

Obiettivi di apprendimento

Al termine della lettura saprai:

    • Come costruire un SemKB (Semantic Knowledge Base) AIDB su uno schema PostgreSQL, utilizzando COMMENT ON e la funzione aidb.createsemanticalias come superficie di authoring, e come le chiavi esterne generano i percorsi di join.
    • Come esporre il catalogo degli strumenti AIDB a un agente esterno tramite l’endpoint MCP integrato, protetto da un Application Load Balancer (ALB) e registrato come target MCP su AgentCore Gateway.
    • Come i ruoli PostgreSQL, i GRANT a livello di colonna e la sicurezza a livello di riga producono risultati diversi per chiamanti diversi, mantenendo invariati prompt, catalogo strumenti e codice agente.
    • Come AIDB cattura tracce OpenTelemetry per ogni esecuzione SQL, salvandole nella schema aidb_otel e rendendole interrogabili con SQL tradizionale.

Le tre componenti di un agente

Un agente che risponde a domande di business su dati in tempo reale necessita di tre livelli:

1. Modello di pianificazione

Il livello modello è rappresentato da Anthropic Claude su Amazon Bedrock, lo stesso modello usato nelle pubblicazioni precedenti (la disponibilità varia per AWS Region).

2. Livello di significato

Qui interviene la novità: un SemKB residente all’interno del database PostgreSQL operativo. Schema e definizioni di business sono indicizzati insieme; i permessi di accesso sono gestiti da GRANT, sicurezza a livello di riga e a livello di colonna, senza ricorrere a prompt di sistema.

3. Runtime

Il runtime è AgentCore, una capacità di Amazon Bedrock AgentCore. AgentCore Gateway gestisce l’autorizzazione in ingresso, mentre AgentCore Identity conserva le credenziali di uscita per i target di strumenti, analogamente a quanto fatto nelle versioni precedenti.

Caso d’uso: C360 su EDB Postgres AI

Il dataset proviene dal Stardog C360 Knowledge Kit, caricato in un’istanza dedicata di EDB Postgres AI all’interno dello schema c360. Il modello dati comprende quattro tabelle e una vista derivata:

    • customers: cid, firstname, lastname, full_name, email, ssn, phone, picture, location (FK a locations.id)
    • locations: id, city, state, zip
    • products: id, name, brand, dept, price
    • purchases: id, cid (FK a customers.cid), pid (FK a products.id), date, quantity, price
    • bigspender (view): cid, fullname, state, largeorders, largestorder

Il grafo di join è semplice: un cliente vive in una location, effettua acquisti, e ogni acquisto è associato a un prodotto. La semantica aggiuntiva, non evidente dai nomi delle colonne, è definita tramite commenti:

    • State non è una colonna del cliente, ma è recuperata da locations tramite la chiave esterna customers.location, con un commento che indica al SemKB dove trovarla.
    • purchases.price rappresenta il totale dell’ordine, non il prezzo unitario; un agente che lo interpreta erroneamente moltiplicerebbe per quantity, generando risultati gonfiati.
    • Il concetto di big spender è definito tramite una COMMENT ON VIEW sulla vista big_spender, garantendo una singola fonte di verità per tutti gli agenti, dashboard e query.

Le domande tipiche poste all’agente includono:

    • Chi sono i primi 10 clienti per spesa totale e in quale stato risiedono?
    • Quanti big spender esistono per stato?
    • Elencare 10 clienti con lo stato di residenza.
    • Quali 10 prodotti hanno venduto più unità?
    • Elencare cinque clienti con i relativi numeri di Social Security (usati per verificare la governance).

Architettura di riferimento

Il diagramma sottostante (non mostrato) descrive il percorso dalla richiesta dell’analista fino al livello semantico in EDB Postgres AI. L’analista si autentica tramite Amazon Cognito e invia una chiamata a AgentCore Gateway** con il JWT come token Bearer. Il gateway valida il token, applica le politiche Cedar e indirizza la chiamata al runtime di AgentCore, dove Claude pianifica e compone la risposta.

Il tool call dell’agente è una richiesta MCP. AgentCore Gateway supporta direttamente target MCP; l’endpoint edb-endpoints di AIDB espone un server HTTP MCP con autenticazione Basic, raggiungibile tramite un ALB con listener HTTPS e certificato ACM. L’ALB URL è registrato come target del gateway.

Le credenziali del ruolo PostgreSQL sono gestite da AgentCore Identity**, che le inserisce come Basic Auth in ogni chiamata in uscita. L’agente non vede direttamente le credenziali.

Per l’osservabilità, AgentCore invia tracce a Amazon CloudWatch Transaction Search, mentre AIDB registra tracce OpenTelemetry in aidb_otel, interrogabili con SQL una volta attivata la telemetria sul database.

Flussi di comunicazione tra AgentCore e EDB Postgres AI

Flusso in ingresso

1. Il client chiama AgentCore Gateway con un token JWT rilasciato da un pool Amazon Cognito.

2. Il gateway verifica il token tramite l’URL di discovery di Cognito e applica la policy Cedar per determinare i tool autorizzati.

3. La chiamata viene instradata al runtime di AgentCore, dove Claude genera il piano di query.

Flusso in uscita verso il livello semantico

1. L’agente invoca un tool MCP. AgentCore Gateway tratta l’endpoint edb-endpoints come server MCP target.

2. L’ALB riceve la richiesta, la instrada a un’istanza EC2 che esegue il server MCP di AIDB.

3. AIDB risponde con i risultati del SemKB, applicando i permessi definiti da ruoli, GRANT a livello di colonna e sicurezza a livello di riga.

4. Le tracce di esecuzione SQL sono salvate in aidb_otel per analisi successiva.

Costruzione del livello semantico

Le seguenti istruzioni assumono che AIDB sia installato e attivo sull’istanza EDB Postgres AI e che i quattro CSV del kit C360 siano stati caricati nello schema c360 con le chiavi primarie e esterne illustrate in precedenza.

Poiché il livello semantico risiede nello stesso database dei dati, non è necessario un secondo sistema né un catalogo da sincronizzare. La definizione semantica avviene interamente in SQL.

Passaggi chiave:

    • Creare il SemKB indicizzando lo schema con aidb.createsemanticalias e aggiungendo COMMENT ON per colonne e viste.
    • Definire alias semantici per concetti come “state”, “totalprice” e “bigspender” tramite commenti e alias.
    • Abilitare la sicurezza impostando ruoli PostgreSQL, GRANT a livello di colonna e politiche di sicurezza a livello di riga (ROW LEVEL SECURITY).
    • Esportare il catalogo come endpoint MCP tramite edb-endpoints, configurando l’ALB e registrando l’URL nel gateway.
    • Abilitare la telemetria con SELECT aidb.enable_telemetry(); per raccogliere tracce OpenTelemetry.

Esempio di definizione semantica

Di seguito un estratto di SQL che mostra come commentare le colonne e creare alias semantici:

COMMENT ON COLUMN c360.customers.location IS 'location_fk: collegamento a locations.id per ottenere lo stato del cliente';

COMMENT ON COLUMN c360.purchases.price IS 'order_total: totale dell’ordine, non prezzo unitario';


COMMENT ON VIEW c360.big_spender IS 'Definizione di big spender: clienti con spesa totale > 10000';


SELECT aidb.createsemanticalias('state', 'SELECT l.state FROM c360.locations l WHERE l.id = customers.location');


SELECT aidb.createsemanticalias('total_spent', 'SELECT SUM(p.price) FROM c360.purchases p WHERE p.cid = customers.cid');

Questi commenti guidano AIDB nella costruzione del grafo semantico e nella generazione di percorsi di join automatici.

Gestione di ruoli e governance

Supponiamo due ruoli PostgreSQL:

    • analyst_role: ha GRANT SELECT su tutte le colonne eccetto ssn.
    • compliance_role: ha GRANT SELECT su tutte le colonne, incluso ssn, ma è soggetto a una policy di sicurezza a livello di riga che filtra i record per regione.

L’agente utilizza lo stesso prompt e lo stesso catalogo di tool, ma le risposte variano a seconda del ruolo con cui il tool MCP è autenticato. L’analista non vedrà i numeri di SSN, mentre il compliance officer li potrà visualizzare ma solo per i clienti della propria regione.

Osservabilità e diagnostica

Le tracce OpenTelemetry generate da AIDB vengono inserite nella tabella aidbotel.sqltraces. Un tipico interrogazione per analizzare le query più lente è:

SELECT query, avg(durationms) AS avgms, count(*) AS exec_count

FROM aidbotel.sqltraces


GROUP BY query


ORDER BY avg_ms DESC


LIMIT 10;

Queste informazioni consentono di ottimizzare il modello semantico, aggiungere indici o ristrutturare le viste per migliorare le performance dell’agente.

Conclusioni

Integrando EDB Postgres AI con Amazon Bedrock AgentCore, è possibile creare un livello semantico robusto e governato direttamente all’interno del database operativo. La combinazione di commenti SQL, alias semantici, sicurezza nativa di PostgreSQL e l’interfaccia MCP consente agli agenti di accedere a dati ricchi di significato senza dipendere da sistemi esterni di catalogo o da prompt di governance. Inoltre, la traccia end‑to‑end tramite CloudWatch e OpenTelemetry offre una visibilità completa per il monitoraggio e l’ottimizzazione.

Questo approccio dimostra come la composizione di componenti cloud‑native e di estensioni database avanzate possa semplificare l’architettura, ridurre la latenza e garantire una governance rigorosa, aprendo la strada a future implementazioni di AI agentica su scala aziendale.