Card

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,
)

Parameter	Description
`title`	Card heading rendered as the `title` attribute on the root `<Card>` element. Builder mode only.
`jsx`	Pre-rendered JSX string. Mutually exclusive with `url`. Must not be empty.
`url`	URL of a remotely hosted card document. Must start with `http://` or `https://`. Mutually exclusive with `jsx`.

Property	Type	Description
`jsx`	`str \| None`	The JSX representation. Returns `None` for URL cards.
`url`	`str \| None`	The remote URL. Returns `None` for inline and builder cards.

Method	Returns	Description
`.add(child)`	`Card`	Append 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")

Parameter	Description
`label`	Visible text on the button.
`id`	Callback identifier sent to the agent when clicked. Mutually exclusive with `url`.
`url`	URL to open when clicked. Mutually exclusive with `id`.
`style`	Optional 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.

Python SDK

LangGraph

Google ADK

Import

Creation Modes

Inline JSX

Remote URL

Builder

`Card` Reference

Components

`Text`

`Fields` and `Field`

`Divider`

`Button`

`Actions`

Full Example

Transport

​Import

​Creation Modes

​Inline JSX

​Remote URL

​Builder

​Card Reference

​Components

​Text

​Fields and Field

​Divider

​Button

​Actions

​Full Example

​Transport

​Related Pages

Import

Creation Modes

Inline JSX

Remote URL

Builder

`Card` Reference

Components

`Text`

`Fields` and `Field`

`Divider`

`Button`

`Actions`

Full Example

Transport

Related Pages