Distribution - Aion Docs

Metadata

Field	Value
Canonical URI	`https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0`
Issuer	`aion`
Version	`1.0.0`
Activation	This extension is declarative. It will always be active and does not require activation.
Related Extensions	Event

Overview

Distributions are A2A-protocol adapters for external messaging systems. They let agents use messaging systems as primary IO in four contexts:

User requests: a user sends a message from an external network and the agent responds.
External-service events: an event occurs in an external service and the agent is notified.
Direct A2A communication: a distribution is also an agent and can be called directly over A2A to provide context sourced from an external network.
MCP access: a distribution may expose an MCP server so downstream agents can look up context via tool calls.

What Is A Distribution?

A distribution is the boundary service between an external network and A2A workflows.

Responsibility	Description
Inbound normalization	Maps source-network messages/events into A2A `SendMessage` requests.
Outbound delivery	Maps terminal A2A responses into provider-native outbound actions.
Identity context	Supplies distribution, sender, identity, behavior, and environment metadata.
Agent endpoint	Exposes an agent card URL so agents in the same project can call it directly.
External endpoint	Some distributions may expose an external endpoint as a composite agent.

Out of scope:

A distribution does not execute agent workflows itself.
A distribution does not replace provider-specific APIs for advanced long-tail operations.

Request And Response Flow

All these mechanisms are instrumented with the Aion agent server, which wraps frameworks like LangGraph and normalizes communication in A2A format. Request flow expectations:

Distribution receives a source-network event.
Distribution maps that event to an A2A SendMessage request.
Distribution includes distribution extension metadata in request metadata.
Distribution marks the message as an event using the Event extension metadata in params.message.metadata.
Distribution includes two event DataParts: a normalized payload and a raw source payload.
Agent server runs the target workflow and emits a terminal A2A response.

Response flow expectations:

Distribution receives the terminal A2A response (Message, Task, or terminal TaskStatusUpdateEvent).
Distribution resolves the outbound text/content from that terminal response.
Distribution sends that response back to the originating network and context.

Distribution Payload

Distribution extension data is request-scoped and attached at: params.metadata["https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0"]. This payload is intended for downstream agent consumption. It is not required when sending a request directly to a distribution endpoint. When the payload is present, downstream consumers should expect distribution, behavior, and environment to be included.

Payload Shape

The canonical shape is:

metadata:
  "https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0":
    senderId?: "{source sender id}"
    distribution:
      id: "distribution-uuid"
      endpointType: {Literal("Aion", "Telegram", "A2A", "Playground", "GitHub", "Twitter")}
      url: "https://.../agent-card"
      identities:
        - kind: "principal"
          id: "agent-identity-uuid"
          networkType: "Aion"
          representedUserId?: "aion-user-uuid"
          organizationId: "org-uuid"
          displayName?: "Podcast Generator"
          userName?: "podcastmaxi"
          avatarImageUrl?: "https://..."
          agentType: {Literal("Personal", "Deployed")}
          url?: "https://..."
        - kind: "service"
          id: "external-identity-uuid"
          networkType: "Twitter"
          representedUserId?: "1234567890"
          organizationId: "org-uuid"
          displayName?: "Podcast Maxi"
          userName?: "podcastmaxi"
          avatarImageUrl?: "https://..."
          url?: "https://..."
    behavior:
      id: "behavior-uuid"
      behaviorKey: "myGraph"
      versionId: "version-uuid"
    environment:
      id: "environment-uuid"
      name: "Staging"
      deploymentId: "deployment-uuid"
      configurationVariables: {Map[String, String]}
      systemPrompt?: "You are an agent..."

Data Dictionary

DistributionExtensionPayload

Field	Type	Required	Description
`senderId`	`String`	`optional`	Source-network sender identifier for this request.
`distribution`	`DistributionRecord`	`required if payload present`	Distribution context for the request.
`behavior`	`BehaviorRecord`	`required if payload present`	Behavior context for the active step.
`environment`	`EnvironmentRecord`	`required if payload present`	Environment context for the active step.

DistributionRecord

Field	Type	Required	Description
`id`	`UUID`	`required`	Distribution identifier in Aion control plane.
`endpointType`	`String`	`required`	Source/target network type (for example, `Twitter`, `A2A`).
`url`	`String`	`required`	Distribution-facing A2A URL; currently sourced from the principal identity A2A URL.
`identities`	`IdentityRecord[]`	`required`	Identity projections associated with this distribution.

IdentityRecord

distribution.identities is polymorphic:

kind: "principal" is the distribution’s Aion principal agent identity projection.
kind: "service" is the external network/service identity projection.

Field	Type	Required	Description
`kind`	`String`	`required`	Identity type discriminator (`principal` or `service`).
`id`	`UUID`	`required`	Identity record id.
`networkType`	`String`	`required`	Network/provider namespace for the identity.
`representedUserId`	`String`	`optional`	End-user id represented by this identity on its network.
`organizationId`	`UUID`	`required`	Owning organization id.
`displayName`	`String`	`optional`	Display name for rendering.
`userName`	`String`	`optional`	Provider-facing username/handle (normalized).
`avatarImageUrl`	`String`	`optional`	Avatar URL for display.
`url`	`String`	`optional`	Profile URL (`service`) or card/profile URL (`principal`), if available.
`agentType`	`String`	`optional`	Present for `kind: "principal"` only (`Personal` or `Deployed`).

BehaviorRecord

Field	Type	Required	Description
`id`	`UUID`	`required`	Behavior id in Aion control plane.
`behaviorKey`	`String`	`required`	Behavior key/graph key used by the runtime.
`versionId`	`UUID`	`required`	Behavior version id used for this step.

EnvironmentRecord

Field	Type	Required	Description
`id`	`UUID`	`required`	Environment id in Aion control plane.
`name`	`String`	`required`	Human-readable environment name.
`deploymentId`	`UUID`	`required`	Deployment id associated with this environment.
`configurationVariables`	`Map[String, String]`	`required`	Environment configuration key/value pairs.
`systemPrompt`	`String`	`optional`	Runtime system prompt when this value is transmitted.

Optional fields should be omitted when unknown rather than serialized as null.

Metadata Placement Rules

Key aliases used below:

DistributionURI: https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0
EventURI: https://docs.aion.to/a2a/extensions/aion/event/1.0.0

Concern	Location	Required
Distribution extension payload	`params.metadata[DistributionURI]`	`optional`
Event identity (CloudEvents)	`params.message.metadata[EventURI]`	`required` for event messages
Event payload schema pointer	`params.message.parts[i].metadata[EventURI].schema`	`required` for event DataParts
Event payload data	`params.message.parts[i].data`	`required` for event DataParts

Examples:

Distribution id: params.metadata[DistributionURI].distribution.id
Event type: params.message.metadata[EventURI].type
Part schema: params.message.parts[i].metadata[EventURI].schema
Normalized trajectory: params.message.parts[i].data.trajectory

Events

Inbound distribution requests are considered events if they originated programmatically from an external system. Event extension metadata should be attached at params.message.metadata["https://docs.aion.to/a2a/extensions/aion/event/1.0.0"] with:

type
source
id

All event types defined by this extension are inbound to A2A request processing. For clarity: this extension documents the metadata which will be attached to A2A requests. External systems SHOULD NOT attach such metadata to inbound requests themselves. Such requests will be rejected.

Event Types

to.aion.distribution.message.1.0.0: Inbound message context from a messaging integration. Required payloads: InboundMessageEventPayload, SourceSystemEventPayload.
to.aion.distribution.activity.1.0.0: Non-message activity from a connected source system. Required payloads: SourceSystemEventPayload.

Rules:

SourceSystemEventPayload MUST be included for every distribution event type.
InboundMessageEventPayload MUST be included only for to.aion.distribution.message.1.0.0.

Payload Schemas

InboundMessageEventPayload

Schema URI: https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0#InboundMessageEventPayload This payload is the normalized representation of an inbound message context. It is sent for any integration that behaves as a messaging service, regardless of provider-specific event schema.

Field	Type	Required	Description
`userId`	`String`	`required`	Sender identifier on the source network.
`messageId`	`String`	`required`	Source-network message id.
`contextId`	`String`	`required`	Source-network conversation/thread id.
`parentContextId`	`String`	`optional`	Parent context id when nested threads are used.
`trajectory`	`String`	`required`	Routing context for the message.

Trajectory values:

Trajectory	Definition
`direct-message`	The agent received a direct message.
`reply`	A user replied to an agent post/message.
`timeline`	A user mentioned the agent in a feed/timeline context.
`conversation`	Message arrived in a shared conversation context.

SourceSystemEventPayload

Schema URI: https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0#SourceSystemEventPayload This payload is provided when a distribution is connected to an external service that emitted the event being handled. It preserves the original source-system event for provider-specific inspection.

Field	Type	Required	Description
`provider`	`String`	`required`	Source provider name (for example, `twitter`).
`event`	`Object`	`required`	Verbatim event payload from the source system.

Messages

These operations provide the baseline interaction model across most networks. Some mediums may have additional semantics, but Aion normalizes request and response flow through A2A.

Receive Message

Inbound: Distribution -> Agent This request is emitted by the distribution when a new source-network message arrives. If an agent responds with a message, text/data/file parts are translated into an outbound provider message.

{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "id": "req-123",
  "params": {
    "message": {
      "messageId": "msg-6a0dbe8a",
      "role": "ROLE_USER",
      "extensions": [
        "https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0",
        "https://docs.aion.to/a2a/extensions/aion/event/1.0.0"
      ],
      "metadata": {
        "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
          "type": "to.aion.distribution.message.1.0.0",
          "source": "aion://distribution/f1eb53f6-8a2d-4a8f-9f8d-f0f01b0a9d11",
          "id": "evt-1901234567890"
        }
      },
      "parts": [
        {
          "text": "What's the weather like in Reno today?"
        },
        {
          "data": {
            "userId": "2244994945",
            "messageId": "1901234567890",
            "contextId": "tw-dm-334455",
            "parentContextId": "tw-dm-root-334455",
            "trajectory": "direct-message"
          },
          "mediaType": "application/json",
          "metadata": {
            "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
              "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0#InboundMessageEventPayload"
            }
          }
        },
        {
          "data": {
            "provider": "twitter",
            "event": {
              "data": {
                "id": "1901234567890",
                "text": "What's the weather like in Reno today?",
                "author_id": "2244994945",
                "conversation_id": "1901234567800"
              },
              "matching_rules": [
                {
                  "id": "1888888888888",
                  "tag": "direct-message-proxy"
                }
              ]
            }
          },
          "mediaType": "application/json",
          "metadata": {
            "https://docs.aion.to/a2a/extensions/aion/event/1.0.0": {
              "schema": "https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0#SourceSystemEventPayload"
            }
          }
        }
      ]
    },
    "metadata": {
      "https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0": {
        "senderId": "twitter:user:2244994945",
        "distribution": {
          "id": "f1eb53f6-8a2d-4a8f-9f8d-f0f01b0a9d11",
          "endpointType": "Twitter",
          "url": "https://api.aion.to/agents/distributions/f1eb53f6-8a2d-4a8f-9f8d-f0f01b0a9d11/card",
          "identities": [
            {
              "kind": "principal",
              "id": "f08bc0a3-9466-4b0f-9de9-2c9dcad2c9cf",
              "networkType": "Aion",
              "organizationId": "df0f52f8-2d35-4bc7-ae9f-3eb2fd352f18",
              "displayName": "Podcast Generator",
              "userName": "podcastmaxi",
              "agentType": "Deployed"
            },
            {
              "kind": "service",
              "id": "2c72f45f-f5f2-4332-9baf-f3d68d85d0a9",
              "networkType": "Twitter",
              "representedUserId": "2244994945",
              "organizationId": "df0f52f8-2d35-4bc7-ae9f-3eb2fd352f18",
              "displayName": "Podcast Maxi",
              "userName": "podcastmaxi",
              "url": "https://x.com/podcastmaxi"
            }
          ]
        },
        "behavior": {
          "id": "bc4d48d9-8ea0-4fe9-8a61-d298b2ef1e2c",
          "behaviorKey": "podcast_assistant",
          "versionId": "7f9f3cd8-f2f3-4e5e-a1e6-6623ab5f0f6b"
        },
        "environment": {
          "id": "2fbe9acc-6bf6-4b0a-9f5f-f7a1e1f093aa",
          "name": "Staging",
          "deploymentId": "9e2bfad3-cf13-45c8-9f45-2ecbc09d8f32",
          "configurationVariables": {
            "REGION": "us-east-1"
          },
          "systemPrompt": "You are a helpful assistant."
        }
      }
    }
  }
}

Response Example

Agents are generally expected to respond to inbound requests. A distribution translates this A2A response back to the source network.

{
  "jsonrpc": "2.0",
  "id": "req-123",
  "result": {
    "message": {
      "messageId": "agent-msg-991",
      "contextId": "tw-dm-334455",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "text": "The weather in Reno is a balmy 72F right now."
        }
      ]
    }
  }
}

Send Message

Outbound: Agent -> Distribution Outbound messages are sent to the distribution’s A2A endpoint defined in its Agent Card.

{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "id": "req-123",
  "params": {
    "message": {
      "messageId": "agent-msg-991",
      "role": "ROLE_AGENT",
      "parts": [
        {
          "text": "The weather in Reno is a balmy 72F right now."
        },
        {
          "data": {
            "trajectory": "direct-message",
            "userId": "2244994945",
            "contextId": "tw-dm-334455",
            "replyToMessageId": "1901234567890"
          },
          "mediaType": "application/json"
        }
      ]
    }
  }
}

OutboundMessageTargetPayload

Schema URI: https://docs.aion.to/a2a/extensions/aion/distribution/1.0.0#OutboundMessageTargetPayload This payload specifies where the outbound message should be delivered in the target network.

Field	Type	Required	Description
`trajectory`	`String`	`required`	Target delivery mode.
`contextId`	`String`	`required`	Target conversation/thread context.
`userId`	`String`	`optional`	Target user for direct messages; required for direct messages.
`replyToMessageId`	`String`	`optional`	Provider message id being replied to.

Trajectory requirements:

Trajectory	Required Fields	Description
`direct-message`	`trajectory`, `contextId`, `userId`	Direct message to a target user/context.
`reply`	`trajectory`, `contextId`, `replyToMessageId`	Reply to a specific prior message.
`timeline`	`trajectory`, `contextId`	Post to the identity timeline/feed context.
`conversation`	`trajectory`, `contextId`	Post to a shared conversation context.

Get Conversation

Outbound: Agent -> Distribution When additional context is needed out-of-band, clients can use distribution.url from this extension payload as the distribution agent card URL and communicate directly to the distribution. Typically, distribution-level context will be available via natural language A2A requests or parameterized MCP tool calls.

Aion Extensions

​Overview

​What Is A Distribution?

​Request And Response Flow

​Distribution Payload

​Payload Shape

​Data Dictionary

​DistributionExtensionPayload

​DistributionRecord

​IdentityRecord

​BehaviorRecord

​EnvironmentRecord

​Metadata Placement Rules

​Events

​Event Types

​Payload Schemas

​InboundMessageEventPayload

​SourceSystemEventPayload

​Messages

​Receive Message

​Response Example

​Send Message

​OutboundMessageTargetPayload

​Get Conversation