Skip to main content
Card is a provider-neutral card document. The distribution compiles it into the provider’s native rich surface — Slack Block Kit, Teams Adaptive Cards, Google Chat cards, and similar. 
from aion.core.agent.invocation.card import Card

​
Import

All public symbols are re-exported from the package root: 
from aion.core.agent.invocation.card import (
    Card,
    Text,
    Field,
    Fields,
    Divider,
    Button,
    Actions,
)

​
Creation Modes

Card supports three mutually exclusive creation modes.

​
Inline JSX

Pass a pre-rendered JSX string when you already have the document: 
Card(jsx="<Card><Text>Hello</Text></Card>")

​
Remote URL

Pass a URL when the card document is hosted remotely: 
Card(url="https://cdn.example.com/cards/deploy.jsx")

​
Builder

Pass a title and chain .add() calls to compose the card from typed components: 
Card("Deployment approved")
    .add(Text("Production rollout is ready."))
    .add(
        Fields()
        .add(Field("Environment", "prod"))
        .add(Field("Run", "#42"))
    )
    .add(Divider())
    .add(
        Actions()
        .add(Button("Approve", id="approve", style="primary"))
        .add(Button("Open run", url="https://example.com/run/42"))
    )
jsx and url are mutually exclusive — passing both raises ValueError. In builder mode the JSX is rendered lazily when the card is serialized.

​
Card Reference

Card(
    title: str | None = None,
    *,
    jsx: str | None = None,
    url: str | None = None,
)
ParameterDescription
titleCard heading rendered as the title attribute on the root <Card> element. Builder mode only.
jsxPre-rendered JSX string. Mutually exclusive with url. Must not be empty.
urlURL of a remotely hosted card document. Must start with http:// or https://. Mutually exclusive with jsx.
PropertyTypeDescription
jsxstr | NoneThe JSX representation. Returns None for URL cards.
urlstr | NoneThe remote URL. Returns None for inline and builder cards.
MethodReturnsDescription
.add(child)CardAppend a component and return self. Builder mode only — raises ValueError when called on a jsx= or url= card.

​
Components

Components are building blocks for builder-mode cards. Each implements .to_jsx() -> str.

​
Text

A prose block inside the card body. 
Text("Production rollout is ready.")

​
Fields and Field

Fields groups compact labeled values. Field is one labeled key-value pair inside a Fields group. 
Fields()
    .add(Field("Environment", "prod"))
    .add(Field("Run", "#42"))

​
Divider

A horizontal rule, typically placed between the body and the Actions section. 
Divider()

​
Button

An interactive control. Use id for server-side callbacks, url for links. The two are mutually exclusive. 
Button("Approve", id="approve", style="primary")
Button("Open run", url="https://example.com/run/42")
ParameterDescription
labelVisible text on the button.
idCallback identifier sent to the agent when clicked. Mutually exclusive with url.
urlURL to open when clicked. Mutually exclusive with id.
styleOptional visual style hint, e.g. "primary" or "danger".

​
Actions

Groups Button controls at the bottom of the card. 
Actions()
    .add(Button("Approve", id="approve", style="primary"))
    .add(Button("Open run", url="https://example.com/run/42"))

​
Full Example

from aion.core.agent.invocation.card import (
    Card, Text, Fields, Field, Divider, Actions, Button,
)

card = (
    Card("Deployment approved")
    .add(Text("Production rollout is ready."))
    .add(
        Fields()
        .add(Field("Environment", "prod"))
        .add(Field("Run", "#42"))
        .add(Field("Commit", "a1b2c3d"))
    )
    .add(Divider())
    .add(
        Actions()
        .add(Button("Approve", id="approve", style="primary"))
        .add(Button("Reject", id="reject", style="danger"))
        .add(Button("Open run", url="https://example.com/run/42"))
    )
)

await thread.reply(card)

​
Transport

When passed to thread.reply() or thread.post(), the SDK converts the card to an A2A TaskStatusUpdateEvent whose message contains a single file part and extensions: ["https://docs.aion.to/a2a/extensions/aion/distribution/cards/1.0.0"].
  • Inline cards (jsx= or builder): raw bytes (base64 in JSON), filename derived from title (e.g. deployment-approved.card.jsx), or card.jsx when no title is set.
  • URL cards: url field only, no raw or filename.
See Distribution/Cards extension for the full wire format.