Core Pattern

Shared State

How the frontend and agent maintain synchronized state using STATE_SNAPSHOT and STATE_DELTA events.

What is Shared State?

In traditional architectures, the frontend and backend maintain separate state. With Shared State, both sides reference the same state object, synchronized via the AG-UI Protocol.

Loading diagram...

Traditional Pattern

Frontend state ≠ Backend state

Request → Response → Manual sync

State can drift between systems

Shared State Pattern

Frontend state === Agent state

Bidirectional sync via protocol

Single source of truth

SharedState Schema

// src/lib/shared-state/schemas.ts
export const SharedStateSchema = z.object({
  // Shopping intent
  persona: z.enum(['hunter', 'gatherer']),
  context: ShoppingContextSchema,

  // Generated content
  currentLayout: LayoutResponseSchema.nullable(),
  inventoryContext: InventoryContextSchema,

  // Adaptation history
  refinementHistory: z.array(RefinementEntrySchema),

  // Agent status
  agentStatus: AgentStatusSchema,
  agentMessage: z.string().optional(),
  errorMessage: z.string().optional()
});

AG-UI Protocol Events

STATE_SNAPSHOT

Full state synchronization. Sent when agent completes processing to ensure frontend has complete, consistent state.

{
  "type": "STATE_SNAPSHOT",
  "state": { /* complete SharedState object */ }
}

STATE_DELTA

Incremental state updates using JSON Patch (RFC 6902). Efficient for small changes like inventory updates or status changes.

{
  "type": "STATE_DELTA",
  "delta": [
    { "op": "replace", "path": "/inventoryContext/prod_001", "value": 0 },
    { "op": "replace", "path": "/agentStatus", "value": "updating" }
  ]
}

Architecture

Spotify Loop