> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# AionRuntimeContext

> Framework-agnostic invocation context populated by Aion Server for each agent invocation.

`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.

```python theme={null}
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`](#messageeventpayload) \| [`ReactionEventPayload`](#reactioneventpayload) \| [`CommandEventPayload`](#commandeventpayload) \| [`CardActionEventPayload`](#cardactioneventpayload) \| `None` | Normalized event payload with provider-neutral fields                                 |
| `raw`     | [`SourceSystemEventPayload`](#sourcesystemeventpayload) \| `None`                                                                                                                                                  | Verbatim provider payload (`provider` + `event` dict), `None` for direct A2A requests |

```python theme={null}
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.

## Related Pages

* [LangGraph AionRuntimeContext](/sdk/langgraph/api/runtime-context)
* [Google ADK Invocation Context](/sdk/google-adk/api/invocation-context)
* [Artifact Builders](/sdk/python/messaging/artifacts)
* [Card](/sdk/python/messaging/card)