Dragon Copilot adaptive card specification

Dragon Copilot uses Adaptive Cards to display the UI associated with your AI apps and agents. Adaptive Cards are a JSON-based UI framework that enable you to present information and actions in a consistent, interactive format. Within the card, you control the layout of elements, UI text, logos and other graphics, background colors, and other style definitions. You can also include user actions to enable the user to accept, reject, copy or update their note with the functionality provided by your card.

Each card is an independent resource with its own content, actions, and references.

To get started with sample cards, use the Dragon Copilot Adaptive Card Validator. For more information on using the validation tool, see Test your Dragon Copilot adaptive card.

See also

• For more information, see the Adaptive Cards documentation.

• For information on migrating from version 1 to version 2 of the adaptive card specification, see Adaptive card updates for Dragon Copilot.

Implementation guidelines

Be aware of the following requirements when designing your adaptive cards:

• Card independence: Each card is self-contained and doesn't depend on other cards.

  Each card must have a unique ID to enable interaction tracking.

  Each card has its own actions array. Actions can't be shared between cards.

  Each card has its own references array. References can't be shared between cards.

• Access control: All of the card's external resources must be valid and secure.

  Note references: The Dragon Copilot client must have access to the referenced note sections.

  Section ID validation: The referenced section ID must be present in the note.

  Web references: URIs must be valid and accessible.

  Security: All external references are subject to security validation.

Best practices

We recommend the following design considerations to ensure the best user experience:

• Keep it simple: Use the supported elements efficiently.

• Focus on content: Use rich text presentation with a good layout.

• Plan for growth: Structure your content to work well when you add more elements.

• Test thoroughly: Validate your card against the element and size restrictions before submission.

• To enable copying to the clipboard, use inline copy buttons (the ActionSet UI element in the adaptive card body).

• Validate inputs: Use Input.ChoiceSet for user selections.

VisualizationResource JSON structure

{
  "id": "unique_resource_id",
  "type": "AdaptiveCard",
  "subtype": "note|timeline",
  "sectionId": "optional_section_identifier_within_note",
  "cardTitle": "Display title for the card",
  "partnerLogo": "https://partner.logo.com/logo.png",
  "adaptive_card_payload": {
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.3",
    "body": [...],
    "actions": [
      {
        "type": "Action.Execute",
        "id": "<action ID>",
        "title": "<action title>",
        "verb": "reject|copyToClipboard|appendToNoteSection|mergeWithNote|regenerate",
        "data": {...}
      }
    ]
  },
  "references": [
    {
      "id": "ref-id",
      "type": "Note|Transcript|Web",
      "sectionId|text|url|title": "type_specific_data"
    }
  ],
  "payloadSources": [
    {
      "identifier": "unique_request_id",
      "description": "Service name that generated the card",
      "url": "https://partner-service.com/source"
    }
  ],
  "dragonCopilotCopyData": "metadata_string"
}

VisualizationResource properties

Adaptive card payload schema

This is where you define the layout and behavior of the card that your AI apps and agents display in Dragon Copilot. For information on supported UI elements, see Adaptive card body schema. For information on the user actions you can add to the card, see Adaptive card actions schema.

References schema

The following reference types are supported:

• Web: Link to external resources, documentation, or websites.

• Note: Link to specific sections within the clinical note. The UI shows these references as Note.

• Transcript: Link to transcript content. The UI shows these references as Transcript.

Each reference type has its own schema:

Web

Transcript

Note

Payload sources schema

The payloadSources object enables you to provide information about the services on your side that process the inputs to your extension. You can have multiple services processing different inputs.