Skip to main content
Metadata
FieldValue
Canonical URIhttps://docs.aion.to/a2a/extensions/aion/distribution/cards/1.0.0
Issueraion
Version1.0.0
ActivationThis page refines the Distribution extension. It does not introduce separate activation.
Related ExtensionsDistribution, Event

​
Overview

This page defines a provider-neutral card document layered on top of the Distribution extension. Different messaging systems expose rich content through different native surfaces: Slack Block Kit, Teams Adaptive Cards, Google Chat cards, Discord components, and similar provider-specific layouts. Rather than transmit each native shape over A2A, Aion uses one small JSX-like card document and lets the distribution compile it into the provider’s native representation. This page defines two things:
  • the outbound card document emitted by an agent
  • the inbound action event emitted when a user activates a card control
Key aliases used below:
  • CardsURI: https://docs.aion.to/a2a/extensions/aion/distribution/cards/1.0.0
  • EventURI: https://docs.aion.to/a2a/extensions/aion/event/1.0.0
Messages that use payloads from this page SHOULD include CardsURI in message.extensions.

​
Events

All event types defined on this page are inbound to A2A request processing. The distribution is responsible for attaching the Event extension metadata; external callers should not construct these messages directly.

​
Card Action

FieldValue
Typeto.aion.distribution.card-action.1.0.0
Required payloadsCardActionEventPayload
Metadataparams.message.metadata[EventURI].type = "to.aion.distribution.card-action.1.0.0"
DetailsUser clicked, submitted, or otherwise activated an action on a previously rendered card.

​
Components

The card document is intentionally small. A distribution MAY degrade components when the provider lacks an equivalent native surface, but SHOULD preserve the overall intent and any plain-text fallback.

​
Card

Card is the top-level container. It defines the card boundary and optional headline metadata such as title. 
<Card title="Deployment approved">
  <Text>Production rollout is ready.</Text>
</Card>

​
Text

Text renders a prose block inside the card body. 
<Text>Production rollout is ready.</Text>

​
Fields

Fields groups compact labeled values such as status, environment, or IDs. 
<Fields>
  <Field label="Environment">prod</Field>
  <Field label="Run">#42</Field>
</Fields>

​
Field

Field is one labeled value inside a Fields group. 
<Field label="Environment">prod</Field>

​
Divider

Divider creates a visual break between body content and a following section such as actions. 
<Divider />

​
Actions

Actions groups interactive controls rendered at the bottom of the card. 
<Actions>
  <Button id="approve" style="primary">Approve</Button>
  <Button url="https://example.com/run/42">Open run</Button>
</Actions>

​
Button

Button represents either a callback-style action or a link. Callback buttons use id; link buttons use url. 
<Button id="approve" style="primary">Approve</Button>

​
Final Example

This example shows the compact document shape the distribution should interpret and render natively for the target provider. 
<Card title="Deployment approved">
  <Text>Production rollout is ready.</Text>
  <Fields>
    <Field label="Environment">prod</Field>
    <Field label="Run">#42</Field>
  </Fields>
  <Divider />
  <Actions>
    <Button url="https://example.com/run/42">Open run</Button>
    <Button id="approve" style="primary">Approve</Button>
  </Actions>
</Card>

​
Payloads

This page defines both inbound action-event payloads and the outbound card document payload.

​
Event Payloads

Event payload schema placement: params.message.parts[i].metadata[EventURI].schema Event payload data placement: params.message.parts[i].data

​
CardActionEventPayload

Schema URI: https://docs.aion.to/a2a/extensions/aion/distribution/cards/1.0.0#CardActionEventPayload This payload represents a user interaction with a previously rendered card. It normalizes callback-style actions across providers that return a developer-defined action identifier along with conversation context.
FieldTypeRequiredDescription
userIdStringrequiredActor who triggered the card action.
contextIdStringrequiredChannel, space, or conversation id where the action occurred.
parentContextIdStringoptionalThread or parent conversation id when nested context exists.
actionIdStringrequiredDeveloper-defined action identifier echoed back by the provider.
Example A2A data part: 
{
  "data": {
    "userId": "U06ABC123",
    "contextId": "C06ROOM123",
    "parentContextId": "1728162100.991118",
    "actionId": "approve"
  },
  "mediaType": "application/json",
  "metadata": {
    "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
      "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/cards/1.0.0#CardActionEventPayload"
    }
  }
}

​
Outbound Payloads

Outbound payloads may appear either in a direct response to a distribution event or in any other agent-authored request sent directly to a distribution. Outbound payload schema placement: message.parts[i].metadata[CardsURI].schema Outbound payload transport: message.parts[i] SHOULD be a file part. Outbound payload document placement: the serialized card document lives in the file-part body referenced by raw or url.

​
CardPayload

Schema URI: https://docs.aion.to/a2a/extensions/aion/distribution/cards/1.0.0#CardPayload This payload represents a card document that the distribution should translate into the provider’s richer message surface when possible.
FieldTypeRequiredDescription
rawStringrequired when inlineInline serialized card document.
urlStringrequired when referencedRemote location of the card document.
filenameStringoptionalDescriptive file name such as deployment-approved.card.jsx.
mediaTypeStringrequiredSerialization type, typically application/vnd.aion.card+jsx.
Exactly one of raw or url SHOULD be present. Example A2A file part: 
{
  "raw": "<Card title=\"Deployment approved\">\n  <Text>Production rollout is ready.</Text>\n  <Fields>\n    <Field label=\"Environment\">prod</Field>\n    <Field label=\"Run\">#42</Field>\n  </Fields>\n  <Divider />\n  <Actions>\n    <Button url=\"https://example.com/run/42\">Open run</Button>\n    <Button id=\"approve\" style=\"primary\">Approve</Button>\n  </Actions>\n</Card>",
  "filename": "deployment-approved.card.jsx",
  "mediaType": "application/vnd.aion.card+jsx",
  "metadata": {
    "https://docs.aion.to/a2a/extensions/aion/distribution/cards/1.0.0": {
      "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/cards/1.0.0#CardPayload"
    }
  }
}

​
Notes

This page intentionally defines a portable card document, not a provider-native rendering contract. The same card may render as Block Kit, an Adaptive Card, a Google Chat card, or another provider-specific surface depending on the distribution. Card responses SHOULD usually include a plain-text part alongside the card so providers with limited rich rendering still receive a readable fallback.