Skip to main content
Metadata
FieldValue
Canonical URIhttps://docs.aion.to/extensions/aion/distribution/1.0.0
Issueraion
Version1.0.0
ActivationThis extension is declarative. It will always be active and does not require activation.
Related ExtensionsEvent

​
Overview

Distributions are A2A-protocol adapters for external messaging systems. These are intended to allow agents to use these messaging systems as their primary user IO within three contexts:
  1. User Requests: a user sends a message and the agent responds. This is the classic request-response loop most agent frameworks are designed for.
  2. Event-based Messages: an agent triggers an event during its workflow that results in an outbound message being sent.
  3. MCP: agents use the A2A messaging adapter as tools, allowing the agent to generatively determine when and where to send a message.
All these mechanisms are instrumented with the Aion agent server, which wraps frameworks like Langgraph and normalizes communication in an A2A format:

​
Extensions

Distribution-related functionality, as with all augmentations to the A2A protocol, is wrapped in extensions. These document supported functionality and give servers the ability to communicate about their capabilities. The operations and events defined on this page are categorized in the distributions/base extension: Extension: distributions/base.

​
Domain

The shared concepts among external messaging APIs are normalized into the following domain. Many messaging systems have unique features which are not covered here. This approach helps us get 90% of the necessary integration functionality. If other calls are needed, they can be made available through additional SDK libraries or the developer may need to implement the messaging service’s SDK directly.
ConceptDefinition
DistributionProxy for an external messaging API that maps requests to A2A messages.
Message
ContextConversation or thread; may be nested for chat rooms, forums, or threaded replies.
Timeline
Reaction
PostSingle message from a user or agent within a conversation or thread.
Additional details about distributions:
  • The Aion server maps requests into framework-specific interactions (for example, Langgraph or ADK).
  • Requests include a distributionId that identifies their origin.
  • Outbound requests can be sent over the GraphQL API using this id or via HTTP at the Distribution’s A2A URI endpoint.

​
Messages

These operations provide the baseline for interaction among most networks, but they are not comprehensive. Some mediums, such as voice, have additional events. These will be useful for a developer attempting to optimize interactions on such networks. However, Aion’s control plane, servers, and SDKs are designed to minimize integration work. Our primary goal is that your agent can simply follow a standard request-response loop to operate in most mediums. In other words, your agent receives a message and optionally replies to it.

​
Receive Message

Inbound: Distribution → Agent Sent to the agent when a new message is received by the distribution. A message can be received in several contexts. Message responses will be sent back to the requesting user on the same channel on which it was received. It’s unnecessary to send a message event similar to Send Message when replying to a message. The agent’s response, if any, will be considered the reply. For A2A, this means including a Text MessagePart as part of a Message in the RPC’s terminal event. A terminal event can be a Message, Task, or terminal TaskStatusUpdateEvent (any task state that isn’t submitted or working). For a task, we will take the last Message in the history property. For a task status update event, we will take the message in its status property. 
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": 123,
  "params": {
    "message": {
      "kind": "message",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "What's the weather like in Reno today?"
        },
        {
          "kind": "file",
          "file": {
            "name": "document.pdf",
            "mimeType": "application/pdf",
            "uri": "http://images.google.com/dfad321"
            }
        },
        {
          "kind": "data",
          "data": {
            "userId": "3jkjdacmm31aeee4",
            "messageId": "bbb7dee1-cf5c-4683-8a6f-4114529da5eb",
            "contextId": "bbb7dee1-cf5c-4683-8a6f-4114529da5eb",
            "parentContextId": "bbb7dee1-cf5c-4683-8a6f-4114529da5eb"
            "trajectory": "direct-message"
          },
          "metadata": {
            "aion:event": "message/inbound"
          }
        }
      ],
      "messageId": "bbb7dee1-cf5c-4683-8a6f-4114529da5eb"
    },
    "metadata": {
      "aion:network": "telegram"
      "aion:distribution": {
        id: "bbbsdaee1-cf5c-4683-8a6f-4114529da5eb"
        ...
      }
    }
  }
}

​
Event Payload

{explain the parameters in the aion:event}
TrajectoryDefinition
direct-messageThe agent received a direct message.
replyA user replied to an agent’s post.
timelineIn an inbound message, someone @mentioned the agent.
conversationPosted in a conversation the agent participates in; nested threads include parentConversationId.

​
Send Message

Outbound: Agent → Distribution Outbound messages are sent to a distribution endpoint. Aion provides two transport options:
  • GraphQL: Send a message as a GraphQL subscription query through our API over WebSockets. Aion’s SDKs use this mechanism.
  • HTTP SSE: Distributions have an A2A-compatible HTTP endpoint. This uses the standard JSON-RPC format.
Outbound messages share a similar format as inbound messages with the addition of targeting data on where or who the message should be addressed to. 
{
  "jsonrpc": "2.0",
  "method": "message/send",
  "id": 123,
  "params": {
    "message": {
      "kind": "message",
      "role": "agent",
      "parts": [
        {
          "kind": "text",
          "text": "The weather is a balmy 72"
        },
        {
          "kind": "file",
          "file": {
            "name": "document.pdf",
            "mimeType": "application/pdf",
            "uri": "http://images.google.com/dfad321"
            }
        },
        {
          "kind": "data",
          "data": {
            "userId": "[email protected]",
            "messageId": "bbb7dee1-cf5c-4683-8a6f-4114529da5eb",
            "contextId": "bbb7dee1-cf5c-4683-8a6f-4114529da5eb",
            "trajectory": "conversation"
          },
          "metadata": {
            "aion:event": "message/outbound"
          }
        }
      ],
      "messageId": "bbb7dee1-cf5c-4683-8a6f-4114529da5eb"
    },
    "metadata": {
      "aion:network": "email"
      "aion:distribution": {
        id: "bbbsdaee1-cf5c-4683-8a6f-4114529da5eb"
        ...
      }
    }
  }
}

​
Event Payload

{explain the parameters in the aion:event}
TrajectoryDefinition
direct-messageDirect message to a user; requires userId.
replyReply to a user’s message; requires messageId.
timelinePost to the agent identity’s timeline.
conversationPost to a conversation the agent participates in; requires contextId.

​
Get Conversation

Outbound: Agent → Distribution To get conversation history, use the Extension: contexts/get extension.

​
Outstanding Qs

  • Should we make the event payload part of the message metadata instead of a message part?
  • For long-tail API interactions, if they do not include this “trajectory,” should the distribution fulfill the request as best as possible (e.g., moderation actions)? If so, should the message’s role be “human” instead of “agent”?