Data Layer

Data Contracts

Contracts define what data exists without exposing actual values. The agent uses these schemas to understand available data and reference it via dataRef.

?The Problem

How does an AI agent know what data is available to display? Without contracts:

-Agent might hallucinate data fields that don't exist
-No clear boundary between AI reasoning and data access
-Hard to validate that agent output matches actual data structure

The Solution: Data Contracts

Contracts give the agent a schema-only view of your data:

Agent knows field names, types, and structure
Agent references data via dataRef, not actual values
Renderer resolves references and fetches real data at runtime

How It Works

Define Contracts

Create Zod schemas that describe your data structure:

export const FleetSchema = z.object({
  vehicles: z.array(z.object({
    id: z.string(),
    location: z.object({ lat: z.number(), lng: z.number() }),
    status: z.enum(['active', 'idle', 'offline'])
  })),
  summary: z.object({
    total: z.number(),
    active: z.number(),
    idle: z.number(),
    offline: z.number()
  })
});

Register in Contract Registry

Add to the registry with a human-readable summary for agent context:

contracts['fleet'] = {
  name: 'fleet',
  description: 'Vehicle fleet data',
  endpoint: '/api/contracts/fleet',
  schema: FleetSchema,
  summary: `{
    vehicles[]: { id, location: {lat, lng}, status }
    summary: { total, active, idle, offline }
  }`
};

Agent Uses dataRef

Instead of hardcoding data, agent emits a reference:

{
  type: "Card",
  title: "Store Overview",
  dataRef: {
    source: "stores",
    path: "summary"
  },
  fields: [
    { label: "Open", value: "{{open}}" },
    { label: "Busy", value: "{{busy}}" }
  ]
}

Renderer Resolves Data

The A2UI renderer sees dataRef, fetches from the contract endpoint, and binds the actual values to the intent before rendering.

Available Contracts

stores

/api/contracts/stores

Retail store data including locations and status

stores[]: { id, name, location: {lat, lng}, status, manager?, lastUpdate }
summary: { total, open, busy, closed }

sales

/api/contracts/sales

Sales reports with regional breakdowns

period: { start, end, label }
records[]: { region, revenue, orders, avgOrderValue, growth }
totals: { revenue, orders, avgOrderValue }

systemStatus

/api/contracts/system-status

System health and service status

overall: 'operational' | 'degraded' | 'down'
uptime24h: number
services[]: { name, status, uptime, lastIncident? }
lastChecked: timestamp

inventory

/api/contracts/inventory

Inventory items and stock levels

items[]: { sku, name, category, quantity, reorderPoint, status, lastRestocked? }
summary: { total, inStock, lowStock, outOfStock }

userProfile

/api/contracts/user-profile

Current user profile and preferences

id, name, email, role, avatar?
preferences: { theme, notifications, timezone }
createdAt, lastLogin?

dataRef Schema

interface DataRef {
  source: string;      // Contract name (e.g., "fleet", "sales")
  path?: string;       // JSONPath to specific data (e.g., "summary", "records[0]")
  params?: Record<string, string>;  // Query parameters
}

source - Required. The contract name to reference.

path - Optional. Dot-notation path to specific data within the contract response.

params - Optional. Query parameters to pass to the endpoint (e.g., filtering, pagination).

Examples

{ source: "fleet" }{ source: "fleet", path: "summary" }{ source: "sales", path: "records", params: { region: "NA" } }

Agent Context Integration

Include contract summaries in your agent's system prompt so it knows what data is available:

## Available Data Contracts

You have access to the following data sources.
Reference them using dataRef in your intents.

### fleet
Vehicle fleet data including locations and status
```
vehicles[]: { id, name, location: {lat, lng}, status }
summary: { total, active, idle, offline }
```

### sales
Sales reports with regional breakdowns
```
period: { start, end, label }
records[]: { region, revenue, orders }
totals: { revenue, orders }
```

When emitting an intent that needs data:
- Use dataRef: { source: "contractName", path: "..." }
- Never hardcode actual data values
- The renderer will fetch and bind real data

Try It Out

See contracts in action with the Full Flow Demo experiment, which shows how the agent references contracts and emits dataRef bindings.

View Full Flow Demo