UI Cards Schema

Standardized UI payloads returned by agents to display results.

Card Types

Summary

Display list of items

Suggestion

Offer actionable choices

Approval

Request user confirmation

Progress

Show ongoing operation

Result

Confirm completion

Error

Display failure message

Summary Card

Display a list of items (messages, events, contacts, etc.)

return {
  type: "summary",
  title: "Your Meetings This Week",
  items: [
    {
      title: "Team Standup",
      subtitle: "Today at 9:00 AM",
      metadata: "Conference Room A",
      icon: "📅"
    },
    {
      title: "Product Review",
      subtitle: "Friday at 2:00 PM",
      metadata: "3 attendees",
      icon: "📅"
    }
  ],
  footer: "2 events found"
};

Schema

Field	Type	Required	Description
`type`	"summary"	Yes	Card type identifier
`title`	string	Yes	Card heading
`items`	array	Yes	List items (title, subtitle, metadata, icon)
`footer`	string	No	Bottom text (e.g., result count)

Suggestion Card

Offer actionable suggestions or choices

return {
  type: "suggestion",
  title: "Schedule meeting?",
  description: "I found an available slot on Friday at 2pm",
  actions: [
    {
      label: "Schedule it",
      action: "create_event",
      params: { start: "2024-03-22T14:00:00Z" }
    },
    {
      label: "Find another time",
      action: "search_availability"
    },
    {
      label: "Cancel",
      action: "cancel"
    }
  ]
};

Approval Card

Request user confirmation (rarely returned directly - use approval.request() instead)

// Usually handled by approval.request() API
// But you can return manually:
return {
  type: "approval",
  title: "Send message to team@company.com?",
  description: "This will send the Q4 report to 3 recipients",
  details: {
    to: ["alice@co.com", "bob@co.com", "carol@co.com"],
    subject: "Q4 2024 Report",
    preview: "Attached is the quarterly report..."
  },
  approveLabel: "Send",
  denyLabel: "Cancel"
};

Progress Card

Show ongoing operation with progress indicator

return {
  type: "progress",
  title: "Analyzing calendar...",
  description: "Finding available meeting times",
  progress: 45,  // 0-100
  status: "Processing 3 of 7 calendars"
};

Result Card

Confirm successful completion

return {
  type: "result",
  title: "✅ Meeting scheduled",
  description: "Created 'Product Review' for Friday at 2pm",
  details: {
    event: "Product Review",
    time: "Friday, March 22 at 2:00 PM",
    attendees: "3 people invited"
  },
  action: {
    label: "View in Calendar",
    url: "metaos://calendar/event/evt_abc123"
  }
};

Error Card

Display error message with optional recovery action

return {
  type: "error",
  title: "Permission denied",
  description: "This agent needs calendar access to schedule meetings",
  errorCode: "CAPABILITY_DENIED",
  action: {
    label: "Grant Permission",
    url: "metaos://settings/capabilities"
  }
};

Deep Links

Use metaos:// URLs in action buttons to link to OS features:

URL Pattern	Opens
`metaos://calendar`	Calendar app
`metaos://calendar/event/:id`	Specific calendar event
`metaos://messages`	Messages app
`metaos://messages/:id`	Specific message thread
`metaos://storage/:path`	File viewer
`metaos://settings/capabilities`	Permission settings
`metaos://agents/:id`	Agent details page

✨ Design Guidelines

Keep titles concise (under 60 characters)
Use emojis sparingly for visual cues (✅ ❌ 📅 📧)
Provide clear action labels ("Schedule Meeting" not "OK")
Include useful metadata (timestamps, counts, locations)
Always offer a way forward (recovery action for errors)