O'Reilly Architecture SuperStream

Making Your Data Ready for Agentic AI

Software Architecture and the Age of Agentic AI

Pramod Sadalage

Distinguished Engineer, Thoughtworks

Prem Chandrasekaran

Market Tech Director, Thoughtworks

The consumers of your data are changing

Data for Humans

Dashboards and reports

Analysts bring context from experience

Batch-friendly — nightly refreshes are fine

Forgives ambiguity — humans interpret

Humans smell bad data

Data for Agents

Autonomous action — not just display

Context must be explicit and encoded

Real-time — stale data causes wrong actions

Zero ambiguity — agents take everything literally

Errors cascade silently

"The bottleneck is no longer the model — it's the architecture of your data."

Five attributes of AI-ready data

Trusted

Contextual

Traceable

Governed

Operational

Data Contracts & Quality

Agents can't smell bad data
Trusted

Traceability & Governance

Auditing autonomous agents
Traceable Governed

Semantic Layers

Teaching agents what your data means
Contextual

Searchable to Actionable

Agent-ready data access patterns
Operational

Data Contracts & Quality

Agents Can't Smell Bad Data

Agents treat every value as truth

The scenario:

"What's the current price for Product X?"

Retrieves cached price: $49.99 ✓

▼

Quotes customer $49.99 ✓

▼

Customer buys at $49.99 ✓

▼

Actual price is $59.99 — company loses $10/unit

A human would double-check

"This price doesn't look right — didn't we update it last week?"

Humans have a smell test. They notice when data feels stale, when numbers look off, when something doesn't add up.

Agents have no smell test. They act on stale data with the same confidence as fresh data.

Every step was "correct." The data was the problem.

Let me give you a concrete scenario. A pricing agent is asked for the current price of Product X. Yesterday, the price was updated from $49.99 to $59.99. But the agent's data source hasn't been refreshed — it still shows the old price. The agent doesn't hesitate. It retrieves $49.99, quotes the customer, the customer buys, and the company loses $10 per unit. Every step the agent took was technically correct — it followed its workflow perfectly. The data was the problem. A human sales rep would notice: "Wait, didn't we update this last week?" They'd double-check. They have institutional memory and a smell test. The agent has neither. This is the fundamental challenge: agents treat every value as truth. Errors don't trigger warnings — they cascade silently through the workflow. In a Precisely / Drexel LeBow survey of 565-plus data professionals, only 12% of organizations reported their data was of sufficient quality and accessibility for AI at all — and that bar was set before anyone was handing data to autonomous agents. The real agent-readiness number is almost certainly lower.

Schema is law: Data contracts as code


apiVersion: v3.1.0
kind: DataContract
id: product-pricing
name: Product Pricing
version: 1.0.0
status: active
schema:
  - name: product_pricing
    physicalType: TABLE
    properties:
      - name: product_id
        logicalType: string
        required: true
        primaryKey: true
      - name: price
        logicalType: decimal
        required: true
        quality:
          - type: custom
            expression: "price > 0"
      - name: currency
        logicalType: string
        required: true
        quality:
          - type: library
            metric: invalidValues
            arguments:
              validValues: [USD, EUR, GBP]
            mustBe: 0
      - name: updated_at
        logicalType: timestamp
        required: true
slaProperties:
  - property: freshness
    value: "24"
    unit: hours    # Must be < 24h for agents

{}

Schema enforcement

Types, nullability, constraints — no guessing

⏱

Freshness SLAs

Max staleness per dataset — nightly batch ≠ real-time agent

Quality gates

Validated in CI/CD — deployment blocked on failure

Data Contract CLI — TW Radar Vol. 33
Cleanlab — TW Radar Vol. 33

For agents, schema IS law — null values corrupt vector embeddings, stale data causes wrong actions.

So how do we prevent that? The answer is data contracts — treating schema as law, not a suggestion. This reverses the "schemaless is flexible" trend. For human consumers, loose schemas are inconvenient. For agents, they're dangerous. The YAML on the left is a data contract in Data Contract Specification format — the same format used by Data Contract CLI, which Thoughtworks Radar Volume 33 highlighted. Let's walk through it: the product_pricing schema defines properties with strict logical types, a quality rule that price must be greater than zero, a quality check on currency that rejects any value outside USD, EUR, or GBP, and critically — a freshness SLA that price data must be less than 24 hours old. On the right, three enforcement dimensions: schema enforcement ensures types and constraints are respected; freshness SLAs define max staleness per dataset — nightly batch updates are insufficient when agents answer in real-time; quality gates validate contracts in CI/CD and block deployments on failure. This is the pricing scenario from the previous slide prevented by design. If the price data is older than 24 hours, the contract is violated before the agent ever sees it.

The quarantine pattern

Circuit breaker for data — bad data never reaches the agent

Data In

Raw data from sources

APIs, databases, streams, files

Validate

Contract check

Schema · Freshness · Quality rules

✓ Pass

Agent-ready data

Gold tier · Trusted

✗ Quarantine

Dead letter queue

Human review · Alert

Better for an agent to say "I don't know" than to act on bad data.

The agent gets silence instead of poison. That's a feature, not a bug.

So we've defined the contract — but what happens when data violates it? You need a circuit breaker. That's the quarantine pattern. Let's walk through the flow: raw data arrives from source systems — APIs, databases, streams. Before it enters the agent-accessible data store, it passes through a contract validation gate. The gate checks three things: does it match the schema, is it within the freshness SLA, and does it pass quality rules? If it passes all three — it enters the Gold tier, agent-ready data. If it fails any check — it's quarantined. Sent to a dead letter queue for human review, with alerts fired. The critical insight: the agent never sees the bad data. It doesn't get poisoned by stale prices or corrupt embeddings. If the pricing data from our scenario hits the quarantine gate and the updated_at timestamp is older than 24 hours, the contract is violated — the data is quarantined. The agent, when asked about the price, says "I don't have current pricing data" instead of confidently quoting the wrong price. That's dramatically better. This is a data architecture pattern, not a model-level fix. You can't prompt-engineer your way out of bad data.

Medallion architecture for agents

Raw → validated → certified → agent-optimized

Bronze

Raw

Immutable ingestion. Full audit trail and lineage preserved.

➔

Silver

Validated

Deduplicated, schema-applied. Contract-validated for agent retrieval.

➔

Gold

Certified

Semantic layer applied. Governed access, trusted metrics.

➔

Adaptive Gold

Agent-curated

Agents monitor queries, materialize optimized datasets.

Adaptive Gold is new

Agents as active participants in data curation, not just consumers. They monitor frequent query patterns and materialize optimized views.

Key principle

Agents should only access Gold or above. Bronze and Silver exist for lineage and debugging — never for agent consumption.

Now that we have a way to quarantine bad data, where does the good data go? That's where the medallion architecture comes in. Microsoft's Cloud Adoption Framework defines this for data platforms. The first three tiers are well-established: Bronze is raw, immutable ingestion — you keep everything for audit trail and lineage. Silver is validated and deduplicated — schema is applied, data contracts are enforced, this is where the quarantine pattern sits. Gold is certified — the semantic layer from Topic 3 is applied here, access is governed, metrics are trusted. The fourth tier — Adaptive Gold — is the novel addition for agentic architectures. This is where agents become active participants in data curation, not just consumers. They monitor their own query patterns, identify frequently accessed data combinations, and materialize optimized datasets. Think of it as agents building their own data warehouse views based on actual usage patterns. The key architectural principle: agents should only access Gold tier or above. Bronze and Silver exist for lineage, debugging, and human investigation. Exposing raw or partially-validated data to agents is asking for the pricing problem we just talked about.

Confidence-threshold routing

Agent processes request
Assesses data quality signals

▼

Confidence score
Based on freshness, completeness, consistency

▼

≥ 85% confidence

Autonomous action

Agent proceeds safely

< 85% confidence

Defer to human

Review → feedback loop

Pricing scenario revisited

Price data is 3 days stale.

Freshness SLA: 24 hours → violated.

Confidence drops below threshold.

"I'm not confident this price is current. Routing to a human for verification."

Key insight: Thresholds should be based on data quality signals (freshness, completeness, consistency) — not just model confidence.

Not every decision needs a human. Not every decision should skip one.

So we have contracts, quarantine, and a medallion architecture. But what about the grey area — when data isn't clearly bad, but isn't fully trustworthy either? That's where confidence-threshold routing comes in. It's the bridge between full autonomy and full human control. Let's walk through the left side: the agent processes a request and assesses data quality signals — not just model confidence, but data-level signals like freshness, completeness, and consistency. If confidence is at or above 85%, the agent proceeds autonomously. If it's below 85%, it defers to a human for review. The threshold number is configurable per use case — pricing might be 90%, internal FAQs might be 70%. On the right, we revisit the pricing scenario. The price data is 3 days stale. The freshness SLA says 24 hours. The SLA is violated, which automatically lowers the confidence score below the threshold — regardless of how confident the model itself feels about the answer. The agent responds: "I'm not confident this price is current. Routing to a human for verification." This is dramatically better than the outcome from our earlier scenario where the agent quoted the wrong price. The key architectural insight: data quality signals should drive confidence thresholds, not just model-level confidence. A model can be very confident about a stale answer. The freshness SLA violation overrides that model confidence.

What you can do Monday morning

Define freshness SLAs

For every dataset agents touch, specify max staleness. Nightly batch ≠ real-time agent. A pricing dataset that's fine at 24h for dashboards may need <1h for a quoting agent.

Implement quarantine gates

Validate before ingestion. Dead letter queue for violations. Never feed bad data to agents. Start with your highest-risk datasets.

Start with Data Contract CLI

Define contracts as code. Validate in CI/CD. Block deployments on contract violations. Version your contracts alongside your schemas.

Add confidence routing

When data quality signals are low, defer to human review instead of autonomous action. Start with a high threshold (90%) and adjust down as trust builds.

Next up: Agents act on quality data — but who's watching? → Traceability & Governance

So those are the patterns — let's make them actionable. Here are four things you can do Monday morning. Step 1: Define freshness SLAs for every dataset that agents touch. The key insight is that the same dataset may have different freshness requirements depending on the consumer. A pricing table that's fine with nightly batch updates for dashboards may need near-real-time updates when a quoting agent is using it. Step 2: Implement quarantine gates. The quarantine pattern we just covered. Validate data against contracts before it enters agent-accessible storage. Anything that violates the contract goes to a dead letter queue for human review. Start with your highest-risk datasets — pricing, inventory, customer records. Step 3: Start with Data Contract CLI. It brings contract governance into your CI/CD pipeline. Define contracts as YAML, validate automatically, block deployments on failure. Treat data contracts with the same rigor as API contracts. Step 4: Add confidence-threshold routing. When data quality signals drop below a threshold — stale data, incomplete records, inconsistent values — defer to a human instead of letting the agent act autonomously. Start with a high threshold like 90% and adjust down as you build trust and track accuracy. So we've covered making data trustworthy for agents. But when agents act autonomously on that data, who's watching? How do you audit what happened? That's what we'll tackle next — Traceability and Governance.

Traceability & Governance

Auditing Autonomous Agents

The audit gap

Trade finance scenario

Agent processes letter of credit: checks customer KYC, verifies compliance rules, approves $2.4M transaction — all in 30 seconds.

6 months later…

A regulator asks: "Why was this approved?"

Can you answer with full reasoning chains? Or just timestamps and table names?

Traditional audit

"What" happened — which tables were accessed, timestamps, user IDs

Agentic audit

"Why" — which sources did the agent consult, what reasoning chain led to the decision, what alternatives were considered and rejected

The gap between these two is where regulatory risk lives.

Let's look at a real-world example that shows why this matters. DBS Bank built their agentic AI for trade finance, and governance architecture was the key innovation. Imagine: an agent processes a letter of credit — it checks KYC data, verifies the customer isn't on a sanctions list, evaluates credit terms, and approves a $2.4 million transaction. All in 30 seconds. Six months later, a regulator asks: "Why was this approved?" Traditional audit logs can answer "what happened" — which database tables were queried, at what time, by which service account. But they can't answer "why" — why did the agent decide to check the sanctions list before the credit terms? Why did it approve despite a minor discrepancy in the documentation? What alternatives did it consider? The gap between "what" and "why" is where regulatory risk lives. The EU AI Act's Article 12 requires high-risk systems to keep automatic logs precisely so this kind of "why" can be answered after the fact.

Agentic lineage

Not just "what was accessed" — but "WHY the agent decided to access it"

▶ Trace: Process letter of credit #LC-4892

Retrieved customer KYC data
source: compliance DB → result: verified

Checked sanctions list
source: OFAC API → result: clear

Evaluated credit terms
source: policy engine → result: within limits

✓

Decision: APPROVE
confidence: 94% · reasoning: "All compliance checks passed, credit within policy limits"

Traces

End-to-end agent workflow, like a distributed request

Spans

Individual steps — data access, reasoning, decisions

Annotations

Confidence scores, reasoning chains, sources consulted

Langfuse Arize OpenTelemetry for AI

So how do we close that audit gap? With agentic lineage — which extends traditional data lineage. Traditional lineage tracks "which sources were accessed." Agentic lineage tracks "WHY the agent decided to access X because it found Y in source Z." The left side shows a concrete trace for our trade finance scenario. The trace represents the end-to-end workflow: processing letter of credit LC-4892. Within the trace, each span represents an individual step. Span 1: retrieved customer KYC data from the compliance database — result: verified. Span 2: checked sanctions list via the OFAC API — result: clear. Span 3: evaluated credit terms against the policy engine — result: within limits. The final span is the decision: APPROVE, with a 94% confidence score and the reasoning chain. This is exactly what a regulator needs. Not just "the agent accessed the compliance database at 14:32:07" — but "the agent checked KYC first, then sanctions, then credit terms, and approved because all three checks passed." The traces/spans model is adapted from distributed systems observability — engineers already understand this mental model from tools like Jaeger and Zipkin. Langfuse, Arize, and OpenTelemetry for AI are the emerging tools for agentic observability.

€15M

or 3% global turnover — EU AI Act penalty
for record-keeping breaches

Articles 12 & 19 requirements

Automatically log events (Art. 12) — traceable, not just timestamps

Retain 6+ months (Art. 19) — full audit trail with decision context

Explain "why" — which data sources, what logic, what alternatives were considered

Not just EU — similar regulations emerging in US (NIST AI RMF), UK, Singapore

And this isn't theoretical — there are real regulatory teeth behind it. The EU AI Act is the most specific regulation on the books. Article 12 requires high-risk AI systems to automatically log events over their lifetime so their operation can be traced, and Article 19 requires providers to keep those logs for at least 6 months. Breaching these record-keeping obligations sits in the Act's middle penalty tier — up to 15 million euros or 3% of global annual turnover, whichever is higher. The headline 35-million / 7% figure you sometimes see is real, but it's for a different tier — the outright prohibited AI practices — not record-keeping. Even so, 3% of a major bank's global turnover runs into the hundreds of millions. In practice this means three things: first, automatically log events, enough to reconstruct not just "what happened" but "why"; second, retain those logs for at least 6 months, which means your observability infrastructure needs to handle long-term storage; third, be able to explain the "why" — which data sources were consulted, what logic was applied, what alternatives were considered and rejected. This isn't just an EU issue. The US has the NIST AI Risk Management Framework. The UK has its AI Safety Institute. Singapore has its Model AI Governance Framework. The direction is clear globally: if you deploy autonomous AI systems, you will need to explain what they did and why.

Staged autonomy

Trust is earned, not assumed

Shadow mode

Agent recommends, human decides. Full logging of what agent would have done.

▼

Supervised

Agent acts, human approves before execution. Full audit trail.

▼

Autonomous with guardrails

Agent acts within defined boundaries. Alerts on exceptions.

▼

Full autonomy

Agent acts independently. Continuous monitoring, spot-check audits.

The analogy

Like onboarding a new employee. You don't give them the corporate credit card on day one.

New hire starts with supervision, earns autonomy as trust builds. Same principle for agents.

Each stage requires

• More trust — proven reliability at the previous level

• More observability — increasing monitoring scope

• More governance — stronger audit trails and controls

So the regulations are clear — you need audit trails and reasoning chains. But how do you actually roll this out? You don't deploy an agent with full autonomy on day one — just like you don't give a new employee unrestricted access. Stage 1: Shadow mode — the agent recommends actions but doesn't execute them. A human makes the final decision. The agent's recommendations are fully logged, so you can track accuracy over time. This is the lowest-risk starting point. Stage 2: Supervised — the agent prepares the action but waits for human approval before executing. The human reviews and clicks "approve" or "reject." Full audit trail of both the agent's proposal and the human's decision. Stage 3: Autonomous with guardrails — the agent acts within defined boundaries. Transactions under $10K might be auto-approved, but anything above triggers a human review. Alerts fire on exceptions. Stage 4: Full autonomy — the agent acts independently with continuous monitoring and periodic spot-check audits. This is earned — you get here only after the agent has proven reliable at each previous stage. The analogy resonates with any manager: you wouldn't give a new hire the corporate credit card on day one. They start with purchase requests, graduate to supervised spending, then eventually earn a card with limits. Agents should follow the same trust-building path.

Delegated access & JIT credentials

✗ Broad service account

Agent uses shared credentials

Accesses all customer data

Persistent tokens — never expire

"Who did this?" — no attribution

✓ Delegated + JIT

Agent inherits user's permissions

Scoped access — only Alice's data

Short-lived token — expires after task

Full attribution — who, what, why

🔒

Delegated access

Agents inherit invoking user's permissions, not broad service accounts

⏱

Just-in-time credentials

Short-lived tokens issued per task, expire on completion

↓

Least privilege

Minimum access needed for the specific task — nothing more

As agents earn more autonomy through those stages, the question becomes: what permissions should they actually have? Two critical security patterns address this. First: delegated access. When Alice asks the agent to check her account, the agent should act with Alice's permissions — not a broad service account that can see all customer data. If the agent uses a shared service account, you lose attribution. When the regulator asks "who accessed this customer's data?", the answer is "the service account" — which tells you nothing. With delegated access, the answer is "Alice's agent, acting on Alice's behalf, with Alice's permissions." Second: just-in-time credentials. Instead of giving the agent a persistent API key that never expires, you issue a short-lived token for each specific task. The agent needs to check the sanctions list? Issue a token that grants OFAC API read access, scoped to the specific customer, valid for 5 minutes. When the task completes, the token expires. No persistent credentials sitting around waiting to be compromised. Third: least privilege. The agent gets the minimum access needed for the specific task. Processing a letter of credit doesn't need access to HR systems or marketing data. These three patterns together solve the attribution and scope problems that plague most current agentic deployments.

What you can do Monday morning

Instrument from day one

Add traces and spans to every agent workflow. Use Langfuse, Arize, or OpenTelemetry. Retrofitting observability is 10x harder than building it in.

Start in shadow mode

Deploy agents that recommend but don't act. Build the audit trail before you need it. Measure accuracy before granting autonomy.

Implement delegated access

Agents inherit user permissions, not service accounts. Issue JIT credentials for every task. No persistent tokens.

Build for the regulator

Design audit trails to answer "why did the agent do this?" not just "what did the agent do?" Think EU AI Act Article 12.

Next up: Now that data is trusted and governed, agents need context. → Semantic Layers

So those are the governance patterns — here are four things you can do Monday morning. Step 1: Instrument from day one — the single most important action. Adding observability after deployment is dramatically harder than building it in. Every agent workflow should emit traces with spans for each step, including the reasoning and data sources consulted. Use Langfuse, Arize, or OpenTelemetry for AI — the tooling is mature enough for production. Step 2: Start in shadow mode — the lowest-risk, highest-learning starting point. Deploy agents that recommend actions but don't execute them. A human reviews and decides. This builds the audit trail before you need it for compliance, and it lets you measure agent accuracy before granting autonomy. Step 3: Implement delegated access — agents should inherit the invoking user's permissions, not use broad service accounts. Issue just-in-time credentials for every task with short expiry windows. No persistent tokens sitting around waiting to be compromised. Step 4: Build for the regulator — even if you're not in a regulated industry today, designing your audit trail to answer "why" makes your systems more debuggable, more trustworthy, and more defensible. When regulations arrive — and they will — you'll be ready instead of scrambling. We've now established that data needs to be trusted and that agent actions need to be auditable. But agents still need context — they don't carry the institutional knowledge that human analysts have. That's what semantic layers solve.

Semantic Layers

Teaching Agents What Your Data Means

Your agent doesn't know what "revenue" means

The agent receives:

"What was Q3 revenue for Product X?"

It doesn't know:

→ Which table to query

→ Gross sales or net of returns?

→ What "Q3" maps to in your fiscal calendar

→ Which joins connect products → orders → revenue

Your analyst knows all of this

Two years of institutional knowledge, absorbed through osmosis, tribal docs, and Slack threads.

Your agent has none of it.

What a semantic layer actually is

A declarative translation layer between business language and data

📐

Metric Definitions

How "revenue" is calculated — order_amount - discount_amount

🔗

Entity Relationships

How customers → orders → products connect — join paths, foreign keys, cardinality

📏

Business Rules

Fiscal calendars, access controls, valid dimensions per metric, time grains

Version-controlled Peer-reviewed CI/CD testable

Agents & BI Consumers

Natural language queries, dashboards, APIs

▲ governed access ▼

Semantic Layer

Metrics · Entities · Rules · Access controls

Defined as YAML in Git — single source of truth

▲ abstracts ▼

Raw Data Layer

Tables, schemas, views, warehouses

Change "revenue" once → propagates everywhere

Metrics as code


semantic_models:
  - name: orders
    entities:
      - name: order_id
        type: primary
      - name: customer_id
        type: foreign
    measures:
      - name: revenue
        agg: sum
        expr: order_amount - discount_amount
    dimensions:
      - name: order_date
        type: time
        type_params:
          time_granularity: day

Agent asks:

"What was Q3 revenue for Product X?"

▼ semantic layer resolves to


SELECT SUM(order_amount - discount_amount)
  FROM orders o
  JOIN products p ON o.product_id = p.id
 WHERE p.name = 'Product X'
   AND o.order_date
       BETWEEN '2025-07-01'
           AND '2025-09-30'

dbt MetricFlow — similar patterns in Cube.js, Snowflake Semantic Views, Databricks Metric Views

Let's see what this looks like in practice. The YAML on the left defines a semantic model — and notice that the business logic lives right here: revenue equals order_amount minus discount_amount. It's not buried in a BI tool or a SQL view somewhere. On the right side: the agent receives a natural language question, and the semantic layer resolves it to correct, constrained SQL. The agent doesn't guess table names or join paths — it uses the definition. This is dbt MetricFlow syntax — worth noting that dbt is evolving this toward a separate metrics definition, but the core concept is the same: define your business logic declaratively. Cube.js, Snowflake, and Databricks all follow similar patterns. The tool matters less than the discipline of getting this into version-controlled code.

Same question, very different SQL

"What was Q3 revenue for Product X?"

Without semantic layer


-- Agent guesses table names
SELECT SUM(amount)
  FROM sales_data
 WHERE product = 'Product X'
   AND quarter = 'Q3'

Wrong table · Uses gross amount not net · No fiscal calendar mapping · Missing join to products

With semantic layer


-- Constrained by metric definition
SELECT SUM(order_amount
         - discount_amount)
  FROM orders o
  JOIN products p
    ON o.product_id = p.id
 WHERE p.name = 'Product X'
   AND o.order_date
       BETWEEN '2025-07-01'
           AND '2025-09-30'

Correct table · Net revenue formula · Fiscal Q3 resolved · Valid join path

How agents use it

🤖 Agent

NL question

"Revenue by region, Q3"

🧠 Semantic Layer MCP

Metric lookup

Definitions, valid dimensions, join paths, access rules

→

Constrained SQL

Only valid dimensions — no guessing

🗃️ Data Warehouse

Query execution

Runs constrained SQL against governed tables

← Result returns to agent with lineage — which definition was used, how it was calculated, full audit trail

The semantic layer constrains the LLM — only valid dimensions appear for selected metrics. That's a feature, not a bug.

So we've seen the before and after — now let's look at how this actually flows end to end. The agent sends a natural language question — step 1. The semantic layer — that's the center box with the green glow — is where the magic happens: it looks up metric definitions, valid dimensions, join paths, and access rules via MCP — that's step 2 — then generates constrained SQL in step 3. Both happen inside the same component. The data warehouse executes the query (step 4). The result flows back to the agent with full lineage metadata (step 5, dashed return path). The critical architectural insight: the semantic layer CONSTRAINS what the agent can ask for. dbt's semantic layer dynamically shows only the dimensions applicable to selected metrics. This prevents the agent from generating plausible-sounding but incorrect queries. Step 5 is the foundation for the traceability we covered in Topic 2.

What you can do Monday morning

Audit your tribal knowledge

Identify your top 10-15 business metrics. Document how they're actually calculated today. You'll find 2-3 conflicting definitions for the important ones.

Define metrics as code

Pick a tool that fits your stack:
dbt → MetricFlow Standalone → Cube.js
Snowflake → Semantic Views

Expose it to your agents

Connect via MCP server or API. The agent queries the semantic layer, never the raw schema.

Test with adversarial questions

Ask ambiguous terms, edge cases, cross-domain joins. Every hallucination = a gap in your semantic definitions.

Anti-pattern: Don't boil the ocean — start with the metrics your first use case needs, not a full warehouse model.

So how do you get started with all of this? Step 1: Most organizations have conflicting definitions for their most important metrics. Revenue is the classic — gross vs. net, with or without returns. Find these conflicts. That's your biggest agent risk and quick win. Step 2: The tool matters less than the discipline. If you're already using dbt, MetricFlow is natural. If you need standalone, Cube.js is excellent. Snowflake and Databricks native features are maturing fast. Step 3: dbt, Cube, and AtScale all have MCP servers. The agent should never touch your raw schema. Step 4: Best way to find gaps is adversarial testing. Every hallucination points to a missing definition. Fix the definition, not the prompt. Anti-pattern: Don't boil the ocean. Start with the metrics your first agent use case needs.

Next level: Knowledge Graphs

When relationships matter more than metrics

"Which customers bought Product X but churned after we changed the pricing in Q2?"

Multi-hop reasoning across entities, events, and time — flat tables can't answer this.

GraphRAG — TW Radar: Trial
Graphiti — TW Radar: Assess · Temporally-aware

Customer

bought

Product X

churned after

Pricing Change

3 entities · 2 relationships · multi-hop traversal

Semantic layers → structured metrics | Knowledge graphs → relationship reasoning | Together → institutional memory

Next up: Agents understand your data — but can they act on it? → From Searchable to Actionable

Semantic layers are great for structured metric queries — "what was revenue by region." But some agent tasks need richer relationship reasoning — traversing connections across entities, events, and time. The graph on the right shows the multi-hop query: Customer bought Product X, then churned after a Pricing Change. This requires traversing three entities and two relationships — flat tables can't do this. GraphRAG uses community detection for abstract queries traditional RAG can't handle. Graphiti builds temporally-aware knowledge graphs for evolving facts. Thoughtworks Radar Vol. 32: GraphRAG at Trial, Graphiti at Assess. Semantic layers plus knowledge graphs together give agents institutional memory. That's where this is heading. By institutional memory I mean the kind of knowledge that experienced employees carry — how things connect, what happened before, why certain decisions were made. Semantic layers encode the "what" — how metrics are defined. Knowledge graphs encode the "how things relate" — the connections between customers, products, events, and decisions over time. Together, they give agents the context that would normally take a new hire months to absorb. So now agents have trusted data, governance, and context. But can they actually act on it? That's our final topic — from searchable to actionable.

From Searchable to Actionable

Agent-Ready Data Access

Your agent can read, but it can't act

The scenario:

"I see that all the payments for the PO's are not yet received for Party Foo."

Retrieve troubleshooting guide ✓

▼

Check live PO service status ✗

▼

Create helpdesk ticket ✗

Traditional RAG stops at step 1

RAG can search documents — it retrieves the right troubleshooting guide.

But it can't query live systems to check if the PO's are actually received for Party Foo right now.

And it can't take action — no ticket creation, no status update, no workflow trigger.

Agentic AI needs data that's not just searchable — it's actionable.

The data access spectrum

Three tiers — most organizations are stuck at Tier 1

Tier 1 · Read

Retrieval

RAG, vector search, document lookup

PO System: retrieve troubleshooting guide

Embeddings Vector DB

Tier 2 · Real-time

Structured queries

Live APIs, database reads, service status

PO System: check payment status NOW

MCP-Read APIs

Tier 3 · Write-back

Controlled mutations

Create records, trigger workflows, update state

PO System: create helpdesk ticket

MCP-Write Tools

Most orgs are stuck at Tier 1. Agentic AI requires all three.

So what does the full spectrum of data access look like? This framing comes from Microsoft's Cloud Adoption Framework for AI, which formalizes it as RAG plus MCP-Read plus MCP-Write. Tier 1 is where most organizations are today — retrieval-augmented generation, vector search, document lookup. The agent can find relevant content. Tier 2 adds real-time structured access — the agent can query live systems, check service status, read from databases in real-time. Tier 3 is the most powerful and the most dangerous — write-back. The agent can create tickets, update records, trigger workflows. Each tier adds capability but also adds risk. The PO scenario maps cleanly: retrieve the guide (Tier 1), check PO payment status (Tier 2), create the ticket (Tier 3). Most organizations have only deployed Tier 1. The shift to agentic AI requires all three — and that's what the rest of this topic addresses.

MCP: USB-C for AI

"One protocol to connect any AI model to any data source or tool."

— Anthropic, Model Context Protocol specification

BEFORE: N × M

⤫ ⤫ ⤫ ⤫ ⤫ ⤫

9 custom integrations

➔

AFTER: N + M

┃ ┃ ┃

MCP

┃ ┃ ┃

6 standard connections

97M

SDK Downloads / mo

Official MCP SDKs, early 2026 (from ~2M/mo at launch)

10K+

MCP Servers

Community and vendor-built integrations

⚖

Agentic AI Foundation

Joined Dec 2025 (hosted by Linux Foundation) — open governance

Adopted by:

Anthropic OpenAI AWS Google Microsoft

So how do agents actually connect to all these data sources and tools across the three tiers? That's where MCP comes in. MCP — Model Context Protocol — is the emerging standard for connecting AI models to data sources and tools. The USB-C analogy works well: before USB-C, every device had its own connector. You needed N times M custom integrations — every model paired with every tool. MCP reduces this to N plus M — each model speaks MCP, each tool speaks MCP, and they all interoperate. The numbers are real: by early 2026 the official MCP SDKs were seeing roughly 97 million downloads a month — up from about 2 million a month at launch — with thousands of community- and vendor-built servers in the ecosystem. And in December 2025 the protocol moved to the Agentic AI Foundation, hosted by the Linux Foundation and co-founded by Anthropic, Block, and OpenAI, putting it under open, vendor-neutral governance. Every major AI provider has adopted it — Anthropic, OpenAI, AWS, Google, Microsoft. This isn't proprietary — it's an industry standard. Thoughtworks Radar Volume 33 highlighted MCP as a dominant theme across multiple blips. Worth mentioning: Google's A2A — Agent-to-Agent protocol — is a complementary standard focused on agent-to-agent communication rather than agent-to-tool. It's still early days for A2A though — adoption isn't nearly as ubiquitous as MCP, so we're focusing on MCP today as the more mature and widely supported protocol.

Three primitives, one protocol

Resources

Read

Expose data for agents to read. Structured, discoverable, schema-described.

PO System: troubleshooting docs, config data

Safe — read-only

➔

Prompts

Templates

Reusable interaction patterns. Shape how agents approach tasks.

PO System: IT triage workflow template

Shapes behavior

➔

Tools

Write

Functions agents can invoke. Real-world side effects.

check_po_payment_status()
create_ticket()

Real-world consequences

Risk escalates left to right: safe → shapes behavior → real-world consequences

Now that we know what MCP is, let's look at how it works. MCP has three primitives — and understanding them is critical for your data architecture decisions. Resources are read-only — they expose data for agents to discover and consume. Think of them as the agent equivalent of a GET endpoint. Prompts are reusable templates that shape how agents approach tasks — like an IT triage workflow that guides the agent through diagnostic steps. Tools are functions agents can invoke — they have real-world side effects like creating tickets, updating records, or triggering workflows. The risk escalates left to right: Resources are safe (read-only), Prompts shape behavior (they influence agent decisions), and Tools have real-world consequences (they change state). This maps directly to Microsoft's framing: RAG corresponds to Resources, MCP-Read adds structured real-time access, MCP-Write corresponds to Tools. For our PO payment scenario: Resources provide the troubleshooting docs, the Prompt guides the triage workflow, and Tools execute check_po_payment_status() and create_ticket().

Anti-pattern: Naive API-to-MCP

Thoughtworks Technology Radar Vol. 33 — HOLD · Design capabilities, not endpoints.

✗ 1:1 endpoint wrapping


# 50 REST endpoints = 50 MCP tools
@tool def get_po_payment_status_chicago(): ...
@tool def get_po_payment_status_nyc(): ...
@tool def get_po_payment_status_london(): ...
@tool def create_po_payment_ticket(): ...
@tool def create_po_payment_ticket_network(): ...
# ... 44 more tools

50 tools → agent can't choose correctly
No business context · Tool sprawl kills accuracy

✓ Business capabilities


# 3 capabilities with rich descriptions
@tool
def check_service_status(
    service: str, location: str
) -> ServiceStatus:
    """Check real-time health of any
    infra service by name & location."""

@tool
def create_support_ticket(
    category: str, priority: str
) -> Ticket: ...

3 tools → clear agent decisions
Rich descriptions · Parameterized · Composable

LLMs are bad at choosing from large tool sets. 5-10 well-described capabilities beat 50 thin wrappers.

Now here's a critical warning. This is one of the most common mistakes we see. Organizations take their existing REST APIs and do a 1-to-1 wrapping as MCP tools — every endpoint becomes a tool. The result is tool sprawl. On the left, we have 50 tools with names like get_po_payment_status, create_ticket_po_payment, create_ticket_po_payment_network. The agent has to choose from 50 tools with minimal context — and LLMs are demonstrably bad at this. Accuracy drops significantly as tool count increases. Thoughtworks Radar Volume 33 placed "naive API-to-MCP conversion" on HOLD — meaning don't do this. On the right, the same functionality is exposed as 3 well-designed capabilities with rich descriptions and parameterized inputs. check_service_status takes a service name and location — one tool handles all services and all locations. create_support_ticket is parameterized with category, priority, and description. The descriptions are detailed enough for the LLM to understand when to use each tool. The principle: design capabilities, not endpoints. 5-10 well-described business capabilities will outperform 50 thin API wrappers every time.

MCP + A2A: The full protocol stack

🤖

IT Support Agent

A2A

🤖

Ops Agent

A2A

🤖

Ticketing Agent

┃ MCP

Knowledge Base

Docs · Runbooks

Monitoring APIs

Status · Logs · Metrics

ServiceNow

Tickets · Workflows

"Build with any framework. Equip with MCP. Communicate with A2A."

— Google, Agent-to-Agent Protocol announcement · 150+ supporting organizations

MCP = vertical (agent ↔ tools) | A2A = horizontal (agent ↔ agents)

So we've talked about MCP connecting agents to tools. But what about agents talking to each other? That's where A2A comes in. The key insight for data architects: there are two protocols emerging as standards. MCP is vertical — it connects agents to tools and data sources below them. A2A — Agent-to-Agent Protocol — is horizontal — it connects agents to each other for multi-agent collaboration. In our PO payment scenario, the IT Support Agent might delegate to a PO Ops Agent (via A2A) to run deeper diagnostics, while each agent connects to its own tools and data via MCP. Google announced A2A with 150+ supporting organizations. The data architecture lesson: your data and APIs need to be designed for machine consumers regardless of which protocol carries the traffic. The properties that make data agent-ready — rich descriptions, parameterized access, clear schemas — are universal.

End to end: PO Payment scenario

Retrieve

RAG lookup

PO System troubleshooting guide, payment status, known issues, request payments steps, etc.

Resource

Query

check_po_payment_status()

Payment system DOWN since 08:47. Affects 23 PO's.

Tool (read)

Act

create_po_payment_ticket()

Priority: High. Auto-routed to ITOps. 23 affected users linked.

Tool (write)

↩

"The Payment System is currently down (since 08:47). I've created ticket INC-4892, priority High, assigned to ITOps. 23 PO's are affected. Here's the troubleshooting guide while we wait for resolution."

3 data tiers. 2 MCP primitives. 1 coherent action. ~30s vs ~45min manual.

Let's bring it all together with our PO payment scenario end to end. Step 1, RETRIEVE: the agent uses RAG to look up the PO system troubleshooting guide for the Party Foo. This is a Resource — read-only, safe. Step 2, QUERY: the agent calls check_po_payment_status() — a Tool that reads live system data. It discovers the Payment System has been down since 08:47, affecting 23 PO's. This is real-time structured access — Tier 2. Step 3, ACT: the agent calls create_po_payment_ticket() — a Tool that writes. It creates a high-priority ticket, auto-routes it to ITOps, and links all 23 affected PO's. This is write-back — Tier 3. The dashed return path shows the agent's coherent response to the employee — combining all three tiers into one natural answer. The whole process takes about 30 seconds. Manually, the employee would wait in a queue, explain the issue, the support agent would check the monitoring dashboard, create the ticket — 15 minutes minimum. Three data tiers, two MCP primitives (Resources and Tools), one coherent action.

What you can do Monday morning

Map your data access tiers

Pick your top 3 agent use cases. For each, classify what's needed: read-only retrieval, real-time structured access, or write-back actions. Most gaps are in Tiers 2 and 3.

Design capabilities, not endpoints

Group your APIs into 5-10 business capabilities with rich descriptions. Think "what can this agent do?" not "what endpoints exist?"

Start with MCP Resources

Read-only first — lowest risk, immediate value. Expose knowledge bases and configuration data. Graduate to Tools only after governance is in place.

Instrument from day one

Log every tool invocation: who triggered it, what was called, when, and on behalf of whom. You'll need this for audit and debugging.

We've covered all four pillars. Next → The reference architecture that ties it all together.

So those are the patterns — here are four things you can do Monday morning. Step 1: Map your data access tiers. Take your top 3 agent use cases and classify what each one actually needs — is it just retrieval, does it need real-time structured access, or does it need write-back? Most organizations will find their gaps are in Tiers 2 and 3. Step 2: Design capabilities, not endpoints. This is the anti-pattern lesson. Group your existing APIs into 5-10 well-described business capabilities. Rich descriptions matter — they're what the LLM uses to decide which tool to call. Step 3: Start with MCP Resources — read-only access. This is the lowest risk entry point. Expose your knowledge bases, configuration data, documentation as Resources. Graduate to Tools only after you have governance in place. Step 4: Instrument from day one. Before you deploy any agent with write access, log every tool invocation — who triggered it, what was called, when, and critically: on behalf of whom. This is the foundation for the audit trail we covered earlier. So we've now covered all four pillars — data contracts, traceability, semantic layers, and actionable data access. Let's bring it all together into the reference architecture.

The AI-ready data stack

Every layer depends on the one below it

Observability Layer

Traces, agentic lineage, reasoning chains, governance controls

Traceable Governed

Topic 2

▲

Agent Access Layer

MCP, function-calling APIs, A2A, capability-oriented tools

Operational

Topic 4

▲

Semantic Context Layer

Semantic layer, knowledge graphs, metadata, metric definitions

Contextual

Topic 3

▲

Data Foundation

Contracts, quality gates, medallion architecture, freshness SLAs

Trusted

Topic 1

So here's how it all fits together. The four topics we covered form a layered architecture — and the order matters. At the bottom: the Data Foundation. Contracts, quality gates, medallion architecture, freshness SLAs. This is what makes your data Trusted. Without it, nothing above works. Layer 2: the Semantic Context Layer. Semantic layer, knowledge graphs, metadata, metric definitions. This is what makes your data Contextual. You can't provide meaningful context if the underlying data isn't trusted. Layer 3: the Agent Access Layer. MCP, function-calling APIs, A2A, capability-oriented tools. This is what makes your data Operational. You can't have safe agent access without semantic context to constrain it. Layer 4: the Observability Layer. Traces, agentic lineage, reasoning chains, governance controls. This is what makes your data Traceable and Governed. You can't have meaningful observability without governed access to observe. Each layer depends on the one below it. Skip a layer, and the layers above collapse. This is why so many agentic AI projects fail — they jump straight to the agent access layer without building the foundation underneath.

Four things to take home

Context over models

Semantic layers are the highest-ROI investment. The <20% → 95%+ accuracy gap isn't about the model — it's about the context you give it.

Read before write

Start with MCP Resources (read-only), graduate to Tools (write) with governance. Staged autonomy, not all-or-nothing.

Contract everything

Freshness SLAs, schema enforcement, quarantine bad data. Agents can't smell bad data — your architecture has to.

Instrument from day one

Traces and spans in every agent workflow. Retrofitting observability is 10x harder. Build for the regulator before they ask.

"When agents become your primary data consumers, the architecture of your data IS the architecture of your AI."

So if you remember four things from this session. First: Context over models. The semantic layer is the highest-ROI investment you can make. The AtScale benchmark showed less than 20% to over 95% accuracy — same model, different context. Second: Read before write. Start with MCP Resources — read-only access. Graduate to Tools only after governance is in place. Use staged autonomy — shadow mode first, then supervised, then autonomous with guardrails. Don't go from zero to full autonomy overnight. Third: Contract everything. Define freshness SLAs for every agent-facing dataset. Enforce schemas strictly. Quarantine bad data before it reaches agents. Your architecture has to provide the smell test that agents lack. Fourth: Instrument from day one. Add traces and spans to every agent workflow from the start. Retrofitting observability after deployment is 10x harder. Build audit trails that answer "why" — you'll need them for debugging today and for regulators tomorrow. And it all comes back to this: when agents become your primary data consumers, the architecture of your data IS the architecture of your AI. You can't separate the two.

O'Reilly Architecture SuperStream

Thank You

Pramod Sadalage

Distinguished Engineer, Thoughtworks

Prem Chandrasekaran

Market Tech Director, Thoughtworks