Skip to main content

​
What a context entry is

A context entry is a labeled, typed piece of structured data formatted into the AI agent’s system prompt. Unlike traits (simple key-value), context entries can hold complex structures: arrays of objects, nested objects, or any JSON value. 
interface ContextEntry {
  label: string;       // Human-readable header in the AI prompt
  type?: ContextType;  // Semantic hint for formatting
  value: unknown;      // Any JSON value
}

​
Context types

The type field tells the AI formatter how to render the data and gives the AI semantic understanding of what it represents.

​
list

Arrays of items — events, products, features, or any collection. 
ha.setContext("active_events", {
  label: "Active Tracking Events",
  type: "list",
  value: [
    { event_name: "purchase", label: "Purchase Event", status: "active" },
    { event_name: "lead", label: "Lead Submitted", status: "paused" },
    { event_name: "signup", label: "New Signup", status: "active" },
  ]
});
AI sees: 
[Active Tracking Events] (list)
- "Purchase Event" (event_name: purchase) -- active
- "Lead Submitted" (event_name: lead) -- paused
- "New Signup" (event_name: signup) -- active
The formatter intelligently picks label/name/title as the primary descriptor and shows status separately.

​
integration

External service connections and their states. Errors are highlighted. 
ha.setContext("integrations", {
  label: "Connected Integrations",
  type: "integration",
  value: {
    facebook_ads: { connected: true, status: "active" },
    google_ads: { connected: true, status: "error", error: "Token expired" },
    hubspot: { connected: false },
    stripe: { connected: true, status: "active" },
  }
});
AI sees: 
[Connected Integrations] (integration)
- Facebook ads: connected, active
- Google ads: connected, ERROR -- Token expired
- Hubspot: not connected
- Stripe: connected, active

​
error

Active issues or errors the AI should acknowledge and help with. 
ha.setContext("errors", {
  label: "Current Issues",
  type: "error",
  value: [
    { area: "tracking_pixel", message: "Pixel not firing on checkout page", since: "2025-01-15" },
    { area: "data_sync", message: "Sync to warehouse paused due to quota" },
  ]
});
AI sees: 
[Current Issues] (error)
- tracking_pixel: Pixel not firing on checkout page (since 2025-01-15)
- data_sync: Sync to warehouse paused due to quota

​
status

General status indicators about the user or account. 
ha.setContext("account_status", {
  label: "Account Status",
  type: "status",
  value: {
    onboarding: { status: "in_progress", step: "3/5" },
    billing: { status: "active", next_invoice: "2025-02-01" },
    trial: { status: "expired", expired_on: "2025-01-01" },
  }
});
AI sees: 
[Account Status] (status)
- Onboarding: in_progress, Step: 3/5
- Billing: active, Next invoice: 2025-02-01
- Trial: expired, Expired on: 2025-01-01

​
config

Configuration or settings state. 
ha.setContext("settings", {
  label: "User Settings",
  type: "config",
  value: [
    { setting: "notifications", label: "Email Notifications", value: "enabled" },
    { setting: "timezone", label: "Timezone", value: "America/New_York" },
    { setting: "currency", label: "Display Currency", value: "USD" },
  ]
});

​
feature

Feature flags or enabled capabilities. 
ha.setContext("features", {
  label: "Feature Flags",
  type: "feature",
  value: {
    beta_dashboard: true,
    new_analytics: true,
    ai_insights: false,
    custom_reports: { enabled: true, variant: "v2" },
  }
});
AI sees: 
[Feature Flags] (feature)
- Beta dashboard: enabled
- New analytics: enabled
- Ai insights: disabled
- Custom reports: enabled (variant: v2)

​
metric

Numeric KPIs or measurements. 
ha.setContext("usage", {
  label: "Usage Metrics",
  type: "metric",
  value: {
    api_calls_today: 1250,
    api_limit: 5000,
    storage_used_gb: 4.2,
    storage_limit_gb: 10,
    active_users: 23,
  }
});
AI sees: 
[Usage Metrics] (metric)
- Api calls today: 1250
- Api limit: 5000
- Storage used gb: 4.2
- Storage limit gb: 10
- Active users: 23

​
relationship

Entity relationships and cross-references. 
ha.setContext("workspace", {
  label: "Workspace Info",
  type: "relationship",
  value: {
    space_id: "space_789",
    parent_org: "org_123",
    linked_accounts: ["acc_001", "acc_002"],
  }
});

​
custom

Use "custom" (or omit the type entirely) for anything that doesn’t fit the other categories. The formatter auto-detects the best rendering based on the value type. 
ha.setContext("notes", {
  label: "Support Notes",
  type: "custom",
  value: "VIP customer. Handle with extra care. Prefers email for follow-ups."
});

​
No type? No problem

If you omit type, the formatter auto-detects from the value:
  • Array — rendered as a bulleted list
  • Object — rendered as key-value pairs
  • String/number/boolean — rendered as a simple value

​
Best practices

Labels appear as section headers in the AI prompt. Make them clear and specific:
  • Good: "Active Tracking Events", "Connected Integrations"
  • Bad: "Events", "Data", "Stuff"
For lists, include both the machine ID (event_name) and the human label (label). This lets the AI reference items naturally.
When a user asks for help and they have active errors, the AI references them automatically.
Prefer multiple focused entries over one giant blob. Each entry should represent one concept (events, integrations, errors, etc.).
Call setContext() whenever the user’s state changes — connecting an integration, encountering an error, changing a setting. The AI always sees the latest data.

​
Where to go next

Examples

Full real-world examples for common SaaS patterns.

Context Planning

A step-by-step guide to deciding what to send and how to keep it fresh.