Uma camada semântica que vive dentro do banco de dados
A AWS publicou um tutorial detalhado mostrando como construir uma camada semântica para IA agêntica usando o EDB Postgres AI em conjunto com o Amazon Bedrock AgentCore. O caso de uso central é o padrão Customer 360 (C360) — respostas sobre clientes, compras e produtos a partir de dados reais em um banco Postgres.
Este post faz parte de uma série que já explorou o mesmo padrão C360 com outras tecnologias: o grafo de conhecimento da Stardog, a plataforma de virtualização de dados da Denodo, o modelo dimensional da AtScale e os modelos vinculados da Strategy Mosaic. O diferencial desta abordagem é que a camada semântica não é um sistema separado — ela vive dentro do próprio banco de dados operacional, por meio da extensão AIDB.
Com o AIDB, o significado de negócio fica ao lado dos dados em instruções padrão COMMENT do Postgres, o grafo de joins vem das chaves estrangeiras e a governança usa GRANT e Row-Level Security (RLS — Segurança em Nível de Linha) através do endpoint MCP (Model Context Protocol — Protocolo de Contexto de Modelo) que já vem embutido no AIDB.
As três camadas que um agente precisa
Um agente que responde perguntas de negócio a partir de dados ao vivo precisa de três camadas trabalhando juntas:
- Camada de modelo: planeja e gera as consultas. Neste caso, é o Anthropic Claude no Amazon Bedrock (disponibilidade varia por região da AWS).
- Camada de significado: diz ao agente o que os dados representam. Aqui é uma SemKB (Base de Conhecimento Semântico) que vive dentro do banco Postgres operacional.
- Camada de runtime: hospeda o agente e controla identidade e acesso. É o AgentCore Runtime, com o AgentCore Gateway gerenciando autorização de entrada e o AgentCore Identity armazenando credenciais de saída para os alvos das ferramentas.
O post sobre Stardog desta série introduziu esse enquadramento de três camadas. O que muda neste post é a camada de significado: em vez de um sistema externo, ela é uma SemKB que vive dentro do banco de dados operacional, com schema e definições de negócio indexados juntos.
O conjunto de dados: C360 no EDB Postgres AI
O dataset utilizado é o Stardog C360 Knowledge Kit, carregado em uma instância EDB Postgres AI em um schema dedicado chamado c360. O modelo de dados tem quatro tabelas e uma view derivada: customers, locations, products, purchases e a view big_spender.
Três ideias de negócio importantes não ficam evidentes pelos nomes das colunas. O estado (state) não está na linha do cliente — está em locations, acessado via chave estrangeira. A coluna purchases.price registra o total do pedido, não o preço unitário — um agente que interprete errado e multiplique por quantidade retornará $502.529 para o cliente topo, em vez dos corretos $27.991,66. E “big spender” é um termo de negócio que precisa ser capturado em uma view com definição centralizada.
Construindo a camada semântica
Comentários nas colunas e views
A tarefa mais simples e de maior impacto é adicionar comentários onde o agente vai buscar contexto. Esses comentários melhoram significativamente a precisão do text-to-SQL:
COMMENT ON COLUMN c360.purchases.price IS 'Total amount the customer paid for the entire order, in US dollars. Not the unit price.';
COMMENT ON COLUMN c360.purchases.cid IS 'Customer who placed the order. Joins to customers.cid.';
COMMENT ON COLUMN c360.customers.location IS 'Home address of the customer. Joins to locations.id. State is in locations.state.';
COMMENT ON COLUMN c360.customers.ssn IS 'US Social Security number. Sensitive, column-level grant required.';A view big_spender centraliza a definição do termo de negócio:
CREATE VIEW c360.big_spender AS
SELECT c.cid, c.full_name, l.state,
count(*) AS large_orders,
max(pu.price) AS largest_order
FROM c360.purchases pu
JOIN c360.customers c ON c.cid = pu.cid
JOIN c360.locations l ON l.id = c.location
WHERE pu.price > 250
GROUP BY c.cid, c.full_name, l.state;
COMMENT ON VIEW c360.big_spender IS 'Big spenders. A big spender is a customer with at least one order over 250 US dollars. '
'Use this view for any question about big spenders.';Com a definição em um único lugar, qualquer agente, dashboard ou consulta lê a mesma regra. Se o negócio mudar a definição de “big spender”, basta um CREATE OR REPLACE VIEW.
Criando a base de conhecimento semântico (SemKB)
A SemKB indexa o schema do Postgres — não os dados. Ela embute a definição de cada tabela, view e coluna (junto com os textos dos COMMENT ON) em um vector store que o agente pode buscar em linguagem natural:
SELECT aidb.create_semantic_kb(
name => 'c360_kb',
model => 'bge-small-en-v1.5-f16',
schemas => ARRAY['c360'],
auto_processing => 'Live'
);O modelo de embedding padrão é um modelo local llama.cpp que vem com a AMI (Amazon Machine Image — Imagem de Máquina Amazon) do AIDB. Para usar um modelo remoto, como o Amazon Titan Text Embeddings no Amazon Bedrock, basta registrá-lo com aidb.create_model e passar seu nome como parâmetro.
O parâmetro auto_processing aceita Disabled, Live ou Background. No modo Live, mudanças no schema disparam event triggers do Postgres automaticamente. A SemKB também rastreia chaves estrangeiras e as converte em relacionamentos — a chave estrangeira purchases.cid se torna um caminho de join que o agente pode descobrir por significado, não pelo nome da coluna.
Aliases semânticos para perguntas recorrentes
Um alias semântico é um SELECT parametrizado, somente leitura, com uma descrição em linguagem natural que a SemKB indexa junto com os metadados do schema. O agente o encontra por significado, chama com parâmetros e retorna uma resposta governada:
SELECT aidb.create_semantic_alias(
name => 'big_spenders_by_state',
description => 'Count big spenders grouped by state, ordered from most to fewest.',
query_text => $$SELECT state, count(*) AS big_spenders
FROM c360.big_spender
GROUP BY state
ORDER BY big_spenders DESC, state$$,
params => '[]'
);Para um guia completo de text-to-SQL, a documentação da EDB tem um walkthrough detalhado.
Governança via primitivos do Postgres
A governança nessa arquitetura corre inteiramente por primitivos do Postgres. O endpoint MCP do AIDB não tem sistema de permissões próprio: como a referência do endpoint MCP declara, “os grants do Postgres decidem o que cada agente pode executar”. Cada requisição MCP autentica com usuário e senha Postgres em sua própria conexão — o current_user dentro de cada chamada de ferramenta é o papel do agente.
O exemplo define dois papéis de login que diferem apenas em um GRANT em nível de coluna:
CREATE ROLE mcp_agent_full LOGIN PASSWORD '...';
CREATE ROLE mcp_agent_restricted LOGIN PASSWORD '...';
GRANT USAGE ON SCHEMA c360 TO mcp_agent_full, mcp_agent_restricted;
GRANT aidb_users TO mcp_agent_full, mcp_agent_restricted;
-- Papel completo vê todas as colunas
GRANT SELECT ON ALL TABLES IN SCHEMA c360 TO mcp_agent_full;
-- Papel restrito vê tudo, exceto customers.ssn
GRANT SELECT ON c360.locations, c360.products, c360.purchases, c360.big_spender TO mcp_agent_restricted;
GRANT SELECT (cid, first_name, last_name, email, phone, picture, location, full_name)
ON c360.customers TO mcp_agent_restricted;Rodando a mesma pergunta pelos dois papéis: o agente com mcp_agent_restricted não consegue projetar a coluna ssn — no momento em que tenta, o Postgres retorna “permission denied for column ssn” e o endpoint MCP repassa esse erro sem alteração. O agente então responde que não pode ler SSNs. O prompt, o catálogo de ferramentas, a SemKB e o código do agente são idênticos. A única diferença é a credencial que o AgentCore Identity injeta no header Basic auth de saída.
O mesmo padrão se aplica ao RLS: basta habilitar Row-Level Security em uma tabela e definir políticas USING por papel. O endpoint MCP do AIDB vê as mesmas linhas que o papel veria em uma conexão direta via psql.
Considerações de IA responsável
A superfície de governança no banco de dados controla o que o agente pode executar na camada de dados. Para complementar, recomenda-se combinar com o Amazon Bedrock Guardrails no lado do modelo — filtros de conteúdo, listas de tópicos negados e redação de PII (Informação Pessoalmente Identificável). As duas camadas se complementam: o GRANT do Postgres impede o agente de ler SSNs na camada de dados; o Guardrails ajuda a evitar que padrões de PII vazem por outros caminhos na resposta do modelo.
Arquitetura de referência e fluxo de identidade
O fluxo de requisição vai do analista até o AgentCore e depois à camada semântica dentro do EDB Postgres AI. O analista autentica com o Amazon Cognito e chama o AgentCore Gateway com o JWT (JSON Web Token) emitido como Bearer token. O Gateway roteia para o AgentCore Runtime, que planeja com Claude no Amazon Bedrock. O agente chama ferramentas MCP pelo Gateway, que encaminha para um Application Load Balancer (ALB) na VPC (Virtual Private Cloud — Nuvem Privada Virtual) do EDB Postgres AI e daí para o servidor MCP edb-endpoints dentro do AIDB.
Dois fluxos cruzam a fronteira entre AgentCore e EDB Postgres AI:
- Entrada: O cliente chama o AgentCore Gateway com um bearer token emitido por um pool de usuários do Amazon Cognito. O autorizador JWT de entrada valida o token e o Gateway avalia sua política Cedar para decidir quais ferramentas o agente pode invocar.
- Saída para a camada semântica: A chamada de ferramenta do agente é uma requisição MCP. O AIDB fala MCP HTTP streamável com autenticação HTTP Basic, o que permite ao Gateway tratá-lo diretamente como um alvo de servidor MCP sem camada de tradução. Um ALB com listener HTTPS e certificado do AWS Certificate Manager (ACM) expõe o
edb-endpoints. O provedor de credenciais do AgentCore Identity armazena a credencial do papel Postgres e a injeta como Basic auth em cada requisição de saída — o código do agente nunca vê a credencial Postgres.
Para observabilidade, o AgentCore emite traces para chamadas de ferramentas, chamadas ao LLM (Large Language Model — Modelo de Linguagem de Grande Escala) e uso de tokens para o CloudWatch Transaction Search. O AIDB captura traces OpenTelemetry para execução SQL como linhas no schema aidb_otel dentro do Postgres, consultáveis com SQL comum após habilitar a telemetria no banco de dados. Não é necessário AWS Lambda nessa arquitetura — o AIDB já fala MCP nativamente.
Expondo a camada e executando o agente
Habilitar o endpoint MCP do AIDB requer dois parâmetros Postgres e um restart: definir edb.endpoints_mcp_enabled = on no postgresql.conf, adicionar aidb a shared_preload_libraries e reiniciar (habilitando o endpoint). Para acessar de fora da instância EC2, defina edb.endpoints_mcp_host para um endereço não-loopback como 0.0.0.0, escolha uma porta com edb.endpoints_mcp_port (padrão: 8765) e forneça o par TLS (Transport Layer Security — Segurança da Camada de Transporte) com edb.endpoints_mcp_tls_cert e edb.endpoints_mcp_tls_key (configurando o endpoint).
Para produção, recomenda-se usar um ALB interno com VPC egress do AgentCore Gateway para manter a conectividade entre o Gateway e o ALB privada.
O agente em si é um script Python curto. Ele usa o Strands Agents para conectar um BedrockModel apontando para o Claude Sonnet mais recente a um MCPClient. O MCPClient conecta à URL do Gateway pelo transporte MCP HTTP streamável com o token de acesso do Cognito como Bearer header. O system prompt instrui o agente a chamar semantic_kb_search primeiro para contexto de schema, passando kb_name => 'c360_kb', e depois execute_sql para rodar a query gerada. O starter toolkit do AgentCore Runtime com Strands tem um exemplo funcional de como hospedar um agente desse tipo em produção. Também se recomenda ativar o Amazon Bedrock prompt caching para o system prompt do agente, já que a mesma instrução e o mesmo catálogo de ferramentas são reutilizados em cada chamada.
Exemplos de queries e verificação
Query 1: Top 10 clientes por gasto total e estado
Sem o comentário em purchases.price, um agente configurado apenas com uma ferramenta de execução SQL leria price como preço unitário e multiplicaria por quantidade. O cliente topo viria com aproximadamente $502.529 — errado. Com um único comentário de coluna indexado pela SemKB, o resultado correto é:
full_name | state | spent
--------------------+----------------+----------
Carolyn Inworth | Wisconsin | 27991.66
Marlane Shadwick | Florida | 22677.05
Isaac Popping | Pennsylvania | 20085.96
Bria McKellar | Texas | 19588.80
Mike Laydel | Louisiana | 18651.28
...Query 2: Quantos big spenders por estado
O agente encontra a view big_spender via semantic_kb_search porque o COMMENT ON VIEW corresponde à pergunta em linguagem natural. A definição de negócio fica em um único lugar:
state | big_spenders
---------------------+--------------
Florida | 46
Texas | 46
California | 42
District of Columbia | 24
New York | 23
...Query 3: 10 clientes e o estado onde vivem
O estado está em locations, não em customers. O caminho de join está codificado na chave estrangeira customers.location e no comentário da coluna, ambos indexados pela SemKB. O agente gera corretamente:
SELECT c.cid, c.full_name, l.state
FROM c360.customers c
JOIN c360.locations l ON l.id = c.location
ORDER BY c.cid
LIMIT 10;Query 4: 10 produtos mais vendidos em unidades
Uma agregação direta que roda dentro do Postgres ao lado dos dados, retornando produtos como Markers (160 unidades), Cleaning Wipes (155) e Playset Girl’s (146).
Reexecução com governança: listar clientes com SSN
A mesma pergunta roda duas vezes. Com mcp_agent_full, o agente retorna cinco linhas de clientes com os valores de ssn preenchidos. Com mcp_agent_restricted, a chamada falha com o erro do Postgres “permission denied for column ssn” e o agente responde que SSNs não estão acessíveis para esse chamador. A falha é imposta pelo GRANT em nível de coluna, não pelo prompt nem pelo modelo. O AIDB captura o trace OpenTelemetry da execução SQL no aidb_otel, permitindo que um revisor consulte a linha do trace para confirmar a decisão de governança posteriormente.
Extensão para outras fontes de dados
Para cargas analíticas que extrapolam o banco operacional, o EDB Postgres Analytics Accelerator (PGAA) permite que o Postgres leia tabelas Apache Iceberg, Delta Lake e Parquet em object storage através de um catálogo Iceberg REST. A visão geral de analytics do EDB Postgres AI cobre o setup completo. As tabelas PGAA aparecem no Postgres como tabelas comuns, então a mesma SemKB continua funcionando contra a cópia analítica sem mudanças no catálogo de ferramentas do agente.
Para federação com fontes relacionais externas, os foreign data wrappers do Postgres tornam uma tabela externa acessível como se fosse local. A camada semântica permanece inalterada em ambos os casos, pois definições de negócio, comentários de colunas e aliases semânticos vivem no Postgres.
Opções de implantação
Duas formas de implantar essa arquitetura são apresentadas. A primeira é autogerenciada no Amazon EC2, usando a AMI EDB Postgres AI Agent Factory do AWS Marketplace — o cliente controla a VPC, a subnet, o ciclo de versões e as atualizações do software EDB Postgres AI. A segunda é gerenciada pela EDB no Amazon EC2, por meio do EDB Managed Database, onde especialistas da EDB cuidam da administração do banco de dados. O lado do AgentCore permanece igual nas duas opções.
Conclusão
A arquitetura apresentada demonstra que analytics agêntico confiável precisa de três elementos trabalhando juntos: um modelo de fundação para planejar e gerar queries, uma camada semântica que fornece uma visão de negócio governada dos dados, e um runtime de agente que hospeda o agente e gerencia identidade. O Amazon Bedrock fornece o modelo, o Amazon Bedrock AgentCore fornece o runtime, e o EDB Postgres AI fornece uma camada semântica que vive dentro do banco de dados Postgres operacional.
Significado de negócio, caminhos de join e governança vêm de primitivos do Postgres já presentes no schema. Não há catálogo separado para manter sincronizado. A auditoria vive no mesmo banco: o schema aidb_otel guarda um span por chamada de ferramenta, ao lado dos dados que foram consultados.
Fonte
Build a semantic layer for agentic AI with EDB Postgres AI and Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/build-a-semantic-layer-for-agentic-ai-with-edb-postgres-ai-and-amazon-bedrock-agentcore/)
Leave a Reply