Context - Aion Docs

Metadata

Field	Value
Canonical URI	`https://docs.aion.to/a2a/extensions/aion/context/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 Methods	`GetContexts`, `GetContext`, `DeleteContext`

Overview

The Context extension provides one caller-scoped conversation-history contract with three operations over JSON-RPC and HTTP+JSON:

Method	Purpose
`GetContexts`	List the authenticated caller’s visible contexts by latest activity.
`GetContext`	Retrieve one visible context with its messages, artifacts, and latest status.
`DeleteContext`	Remove the caller’s access; the last recorded caller triggers cancellation and graph deletion.

All three methods belong to the same extension and use the same canonical URI. An Aion-served agent card declares the extension once. HTTP+JSON paths below are relative to the addressed agent or distribution’s A2A endpoint.

Agent Card Declaration

This unified contract is provided by Aion control-plane endpoints. The Python SDK’s standard agent server does not advertise this extension or implement its summaries and DeleteContext lifecycle. Its internal, non-advertised GetContext and GetContexts helpers have a separate read-only contract. A server should declare the unified URI only when it implements the contract documented here.

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://docs.aion.to/a2a/extensions/aion/context/1.0.0",
        "description": "List, retrieve, and delete caller-visible conversation contexts.",
        "required": false
      }
    ]
  }
}

Activation

This extension is declarative. It will always be active and does not require activation. Clients do not need to send the URI in A2A-Extensions or a2a-extensions. When a client does send it, the server preserves it as ordinary request extension metadata.

Authentication and Isolation

Contexts belong to the receiving AgentIdentity within the addressed edge agent environment. Separate bindings associate admitted callers by exact principal identifier and type. Ordinary caller reads use those bindings and return the complete visible context history, including other admitted participants. Knowing a contextId or belonging to the same organization is not authorization to join it. Verified provider participants can share a provider conversation. Account and guest clients cannot join an occupied private context simply by supplying its ID. New roots receive a private downstream identifier instead of blindly forwarding an untrusted caller-provided string. A verified anonymous-session bearer identifies one guest and can authorize its bound contexts on public A2A endpoints. A bare shared anonymous principal cannot. Session access does not make a private distribution or the authenticated GraphQL catalog public. See Caller Authentication for creation, renewal, and token boundaries. Binding writes are best effort and do not delay message forwarding. Failed writes can leave history unavailable until a later authorized message repairs access; there is no guaranteed durable retry. Provider room departures and membership revocations are not yet synchronized. An explicitly authorized receiving-agent history request is distinct from ordinary caller access; it does not allow every caller to read all conversations owned by that agent.

GetContexts

GetContexts returns lightweight caller-visible conversations from most to least recent.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "id": "list-contexts-1",
  "method": "GetContexts",
  "params": {
    "historyLength": 50,
    "historyOffset": 0
  }
}

params may be omitted to use the defaults.

Field	Type	Required	Description
`historyLength`	`Integer`	optional	Contexts to return. Defaults to `50`; maximum `100`.
`historyOffset`	`Integer`	optional	Newest contexts to skip. Defaults to `0`.
`metadata`	`Object`	optional	Request metadata.

JSON-RPC Success

{
  "jsonrpc": "2.0",
  "id": "list-contexts-1",
  "result": [
    {
      "contextId": "conversation-123",
      "title": "Reno weather forecast",
      "summary": "The caller requested the current weather in Reno. The agent returned a forecast and temperature.",
      "lastActivityAt": "2026-09-10T18:42:11.532Z"
    },
    {
      "contextId": "conversation-456",
      "title": null,
      "summary": null,
      "lastActivityAt": "2026-09-09T09:15:04.107Z"
    }
  ]
}

The result is a raw array rather than an object wrapper.

Field	Type	Description
`contextId`	`String`	Opaque caller-visible context identifier.
`title`	`String \| null`	Generated current subject, when available and enabled by organization policy.
`summary`	`String \| null`	Generated conversation summary, when available and enabled by organization policy.
`lastActivityAt`	RFC 3339 timestamp	Latest visible-context task activity, reported in UTC.

lastActivityAt uses the latest persisted task update. If an admitted edge task does not yet have a local task projection, its creation time is used.

HTTP+JSON Binding

POST /contexts:get
Content-Type: application/json
Authorization: Bearer <aion-token>

The request body uses the same parameter object. The response body is the same raw summary array.

GetContext

GetContext returns one caller-visible context. History is chronological; pagination selects a newest-relative slice before the server returns it in chronological order.

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "id": "get-context-1",
  "method": "GetContext",
  "params": {
    "contextId": "conversation-123",
    "historyLength": 10,
    "historyOffset": 0
  }
}

Field	Type	Required	Description
`contextId`	`String`	required	Non-blank caller-visible context identifier.
`historyLength`	`Integer`	optional	History messages to return. Defaults to `50`; maximum `100`.
`historyOffset`	`Integer`	optional	Newest history messages to skip. Defaults to `0`.
`metadata`	`Object`	optional	Request metadata.

JSON-RPC Success

{
  "jsonrpc": "2.0",
  "id": "get-context-1",
  "result": {
    "contextId": "conversation-123",
    "title": "Reno weather forecast",
    "summary": "The caller requested the current weather in Reno. The agent returned a forecast and temperature.",
    "history": [
      {
        "messageId": "msg-1",
        "role": "ROLE_USER",
        "parts": [
          {
            "text": "What's the weather like in Reno today?"
          }
        ]
      },
      {
        "messageId": "msg-2",
        "role": "ROLE_AGENT",
        "parts": [
          {
            "text": "The weather in Reno is 72 degrees Fahrenheit."
          }
        ]
      }
    ],
    "artifacts": [],
    "status": {
      "state": "TASK_STATE_COMPLETED"
    },
    "lastActivityAt": "2026-09-10T18:42:11.532Z"
  }
}

Field	Type	Description
`contextId`	`String`	Caller-visible context identifier.
`title`	`String \| null`	Generated current subject, when available and enabled by organization policy.
`summary`	`String \| null`	Generated conversation summary, when available and enabled by organization policy.
`history`	`Message[]`	Chronological A2A messages in the selected history page.
`artifacts`	`ContextArtifact[]`	Up to 50 latest durable artifacts, newest first, each qualified by task.
`status`	`TaskStatus`	Latest visible-context task status.
`lastActivityAt`	RFC 3339 timestamp	Latest visible-context task activity, reported in UTC.

The result combines messages across the context’s tasks; it is not an array of complete tasks. Artifact selection is independent of message pagination. Each artifact has the usual A2A artifact fields plus taskId, the caller-facing task identifier:

{
  "taskId": "task-123",
  "artifactId": "report",
  "name": "Weather report",
  "parts": [{ "text": "The weather in Reno is 72 degrees Fahrenheit." }]
}

Artifact identity is the pair (taskId, artifactId). Two tasks can both return an artifact named report. Aion selects at most 50 artifacts before loading their parts, orders them by latest update with a stable row-id tie break, and excludes aion:thinking-delta and aion:stream-delta. This is a recent-artifact window, not an exhaustive artifact export or a bound on individual artifact bytes. If the caller has no visible projection for contextId, the server returns ContextNotFound (code 1000, HTTP 404) without revealing whether another caller uses that identifier.

HTTP+JSON Binding

POST /context:get
Content-Type: application/json
Authorization: Bearer <aion-token>

The request and response bodies use the same parameter and result objects shown above.

Generated Context Summaries

title and summary are optional generated metadata. They are nullable because generation is best effort and controlled by the organization that owns the addressed agent. When that organization disables conversational summarization, both fields are returned as null even if a previously generated value remains stored. Generation may send bounded conversation text to an external model service. Organizations that must keep conversational information within their own network should leave conversational summarization disabled. Clients must not assume that generated values exist or that they include the newest task. Aion first attempts generation after the caller’s first completed task, then after each additional ten-task checkpoint. The title reflects the latest summarized task window. The summary combines the previous generated summary with that bounded window, so the full conversation does not need to be sent again as the context grows. Generation and catch-up are asynchronous. A failed attempt leaves the previous values unchanged, and a later terminal task can cause Aion to catch up one checkpoint at a time. Context reads never wait for this work.

DeleteContext

DeleteContext first removes the requesting caller’s binding. If other recorded bindings remain, it returns success without canceling tasks or deleting the graph. The receiving-agent owner field is not itself a binding; a genuine agent self-call can have a binding like any other caller. When the last recorded binding is removed, Aion records a durable DELETING state, which prevents new task admission. Existing tasks can still publish observations so cancellation and completion can settle. Final deletion prevents subsequent payload projection from recreating the retired history. Cancellation uses the ordinary A2A task-control path. Cancellation proceeds in bounded groups and checks task state when the outcome is uncertain. For last-binding deletion, success is returned only after all tasks are terminal and the graph-deletion transaction commits. A task may also complete naturally while cancellation is being attempted. Terminal states are:

TASK_STATE_COMPLETED
TASK_STATE_FAILED
TASK_STATE_CANCELLED
TASK_STATE_REJECTED

JSON-RPC Request

{
  "jsonrpc": "2.0",
  "id": "delete-context-1",
  "method": "DeleteContext",
  "params": {
    "contextId": "conversation-123"
  }
}

Field	Type	Required	Description
`contextId`	`String`	required	Non-blank caller-visible context identifier.
`metadata`	`Object`	optional	Request metadata.

JSON-RPC Success

{
  "jsonrpc": "2.0",
  "id": "delete-context-1",
  "result": {
    "contextId": "conversation-123"
  }
}

Deletion is idempotent. The server returns the same success for a context that is already absent or not visible to the caller. This avoids disclosing another caller’s context.

Deletion In Progress

{
  "jsonrpc": "2.0",
  "id": "delete-context-1",
  "error": {
    "code": 1001,
    "message": "Context deletion is in progress",
    "data": {
      "contextId": "conversation-123",
      "retryable": true,
      "deletionOperationId": "b92fe461-b3e8-4b89-a736-573154338f23"
    }
  }
}

An outstanding cancellation, transient failure, or request timeout does not imply deletion success or permanent failure. Once deletion is durable, Aion keeps the context fenced, returns this retryable result, and can recover the operation after a restart. Retry DeleteContext with the same caller and context id; do not create a replacement task in that context while it is deleting. deletionOperationId is optional diagnostic metadata, not an additional request parameter. If cancellation is definitively refused, Aion drains the outstanding attempts before restoring the context to ACTIVE and returning non-retryable ContextNotDeletable (code 1002). Work already canceled is not restarted or rolled back. An active task alone is not a definitive refusal. The removed caller binding is not silently restored; stale grant retries cannot re-admit it.

HTTP+JSON Binding

POST /context:delete
Content-Type: application/json
Authorization: Bearer <aion-token>

The request body is the DeleteContext parameter object. The success body is {"contextId":"conversation-123"}. Lifecycle conflicts use HTTP 409 Conflict problem details, with the same context id, retryability, and optional deletion-operation id as JSON-RPC.

Deletion Scope

Only last-binding finalization soft-deletes the receiving-agent edge context, its bindings, edge-task mappings, linked local native and projected tasks, messages, artifacts, parts, callback routes, and owned push notification configurations. Task traces and referenced Files are not soft-deleted by this action. It does not:

remove another caller’s recorded binding through an ordinary caller-delete request;
send a context-deletion command to a remote agent;
claim that a remote agent erased its own conversation memory; or
prevent a later request from reusing the same contextId.

Clients should treat success as confirmation that the caller’s current Aion history is no longer available through GetContexts or GetContext. If another recorded binding remains, the context still exists and a private caller cannot rejoin merely by sending its ID. After actual graph deletion, a later send using that caller-facing ID creates a new mapping with a fresh downstream identifier, not a continuation of the retired graph. Because grant recording is best effort, an unrecorded participant may still be using a context when the last recorded binding is removed. The graph can then be deleted. This accepted limitation is not a guarantee that every currently active participant appears in the binding table.

Retention And Files

Background retention removes complete context graphs, not individual expired task siblings. For an active context, recent activity or nonterminal work in any linked task protects the whole graph. An explicitly deleted context instead ages from its deletion timestamp. Each eligible context is rechecked and physically purged in its own transaction, including payload children, callback routes, task traces, task roots, and the context mapping. This removes Aion’s stored native and downstream-projection history, not an external server’s retained data. After that commit, Aion requests best-effort deletion of locally managed Files owned by the graph’s organization. A surviving reference, including one in another soft-deleted context, preserves the File. Remote and cross-organization File references do not authorize automatic deletion. File storage billing continues until the File service performs its normal lifecycle deletion; hiding conversation history alone does not stop File billing.

Errors

Condition	JSON-RPC code	HTTP status	Lifecycle retryable
Missing authentication	`-32010`	`401 Unauthorized`	Not supplied
Blank `contextId` or invalid pagination	`-32602`	`400 Bad Request`	Not supplied
Context is not visible during `GetContext`	`1000`	`404 Not Found`	`false`
Durable deletion remains in progress	`1001`	`409 Conflict`	`true`
Definitive cancellation refusal prevents deletion	`1002`	`409 Conflict`	`false`

Context lifecycle errors carry sanitized contextId and retryable fields in JSON-RPC error.data. The HTTP+JSON binding exposes them as problem-detail extensions. Its problem type is the canonical Context extension URI followed by #context-not-found, #context-deletion-in-progress, or #context-not-deletable, respectively. Provider error payloads and internal row identifiers are not included. Error objects otherwise follow the JSON-RPC 2.0 specification.

​Overview

​Agent Card Declaration

​Activation

​Authentication and Isolation

​GetContexts

​JSON-RPC Request

​JSON-RPC Success

​HTTP+JSON Binding

​GetContext

​JSON-RPC Request

​JSON-RPC Success

​HTTP+JSON Binding

​Generated Context Summaries

​DeleteContext

​JSON-RPC Request

​JSON-RPC Success

​Deletion In Progress

​HTTP+JSON Binding

​Deletion Scope

​Retention And Files

​Errors

Overview

Agent Card Declaration

Activation

Authentication and Isolation

GetContexts

JSON-RPC Request

JSON-RPC Success

HTTP+JSON Binding

GetContext

JSON-RPC Request

JSON-RPC Success

HTTP+JSON Binding

Generated Context Summaries

DeleteContext

JSON-RPC Request

JSON-RPC Success

Deletion In Progress

HTTP+JSON Binding

Deletion Scope

Retention And Files

Errors