AionRuntimeContext

AionRuntimeContext lives in aion-core and is shared across all frameworks. It carries the inbound A2A state for a single invocation: the inbox, the typed event, and the distribution extension payload.

from aion.core.runtime import AionRuntimeContext

Properties

Property	Purpose
`inbox`	Raw `A2AInbox` — escape hatch for direct access to the underlying A2A structures.
`event`	Typed inbound Aion event, or `None` for direct A2A requests without an Aion event envelope.
`distribution_extension_payload`	Parsed Distribution extension payload when the request includes one.
`graph_kwargs`	Extra values passed through from the graph framework runtime.

The context stores the Distribution extension payload in its protocol shape. It does not project distribution, behavior, or environment fields onto an identity object.

Event

context.event is None for direct A2A requests that carry no Aion event envelope. When present, it exposes a typed view of the inbound event.

Field	Type	Description
`kind`	`EventKind`	Event type: `message`, `reaction`, `command`, or `card_action`
`id`	`str`	Producer-specified event ID for idempotency
`source`	`str`	Logical origin URI of the event
`payload`	`MessageEventPayload` \| `ReactionEventPayload` \| `CommandEventPayload` \| `CardActionEventPayload` \| `None`	Normalized event payload with provider-neutral fields
`raw`	`SourceSystemEventPayload` \| `None`	Verbatim provider payload (`provider` + `event` dict), `None` for direct A2A requests

event = context.event

if event is not None:
    # Normalized payload — provider-neutral fields
    context_id = event.payload.context_id

    # Verbatim provider payload — Slack, Telegram, etc.
    if event.raw is not None:
        slack_body = event.raw.event  # original dict from the provider

`MessageEventPayload`

Normalized inbound message (DM, mention, thread reply, or channel message).

Field	Type	Description
`user_id`	`str`	Sender identifier on the source network
`context_id`	`str`	Conversation, room, or thread ID
`message_id`	`str`	Source-network message ID
`trajectory`	`str`	Routing context: `direct-message`, `reply`, `conversation`, or `timeline`
`parent_context_id`	`str \| None`	Parent context ID when nested threads are used

`ReactionEventPayload`

Reaction or emoji-style activity applied to an existing message.

Field	Type	Description
`user_id`	`str`	Actor who added or removed the reaction
`context_id`	`str`	Conversation, room, or thread ID
`message_id`	`str`	Target message ID on the source network
`reaction_key`	`str`	Provider-stable reaction identifier
`action`	`str`	Reaction transition: `added` or `removed`
`display_value`	`str \| None`	Human-readable emoji or provider label
`is_custom`	`bool \| None`	Whether the reaction is provider-specific rather than a standard emoji
`parent_context_id`	`str \| None`	Parent context ID when nested threads are used

`CommandEventPayload`

Command-style invocation sent through a messaging provider (slash commands, app commands).

Field	Type	Description
`user_id`	`str`	Actor who invoked the command
`context_id`	`str`	Room, channel, thread, or DM context where the command ran
`command`	`str`	Provider-visible command token, e.g. `/deploy`
`arguments`	`str \| None`	Raw argument string supplied after the command token
`invocation_id`	`str \| None`	Provider-native command invocation ID when available
`parent_context_id`	`str \| None`	Parent context ID when nested threads are used

`CardActionEventPayload`

User interaction with a previously rendered card (click, submit, or activate).

Field	Type	Description
`user_id`	`str`	Actor who triggered the card action
`context_id`	`str`	Channel, space, or conversation ID where the action occurred
`action_id`	`str`	Developer-defined action identifier echoed back by the provider
`parent_context_id`	`str \| None`	Thread or parent conversation ID when nested context exists

`SourceSystemEventPayload`

Verbatim provider event preserved for inspection beyond the normalized payload. Available as event.raw when the request was routed through a messaging distribution.

Field	Type	Description
`provider`	`str`	Source provider name, e.g. `slack` or `telegram`
`event`	`dict`	Verbatim event payload from the source system

Distribution Accessors

Use these methods when a request includes a Distribution extension payload:

Method	Returns
`get_distribution()`	Distribution model for the current invocation, or `None`.
`get_behavior()`	Behavior model for the invoked agent implementation, or `None`.
`get_environment()`	Environment model for the runtime configuration, or `None`.
`get_principal_identity()`	Principal identity associated with the distribution, or `None`.
`get_service_identity()`	Service identity associated with the distribution, or `None`.

get_principal_identity() and get_service_identity() are intentionally separate helpers. The principal identity is the Aion principal that owns the distribution when one exists. The service identity represents an external network identity associated with the distribution when one exists.

​Properties

​Event

​MessageEventPayload

​ReactionEventPayload

​CommandEventPayload

​CardActionEventPayload

​SourceSystemEventPayload

​Distribution Accessors

​Related Pages