Aion API

aion.api connects Python agents and tools to Aion platform APIs. It owns HTTP authentication, typed GraphQL access, model-service configuration, and the capability addressing models the MCP helpers are built on. Use it directly when you need to construct Aion API clients, build capability URLs, or pass typed capability references into framework-specific helpers.

Install

aion.api comes with the base install:

pip install aionto-sdk

Authentication

The client reads Aion API credentials from environment variables:

Variable	Required	Purpose
`AION_CLIENT_ID`	yes	API client identifier.
`AION_CLIENT_SECRET`	yes	API client secret.
`AION_API_HOST`	no	Aion API host. Defaults to the SDK’s production API host, `https://api.aion.to`.
`AION_API_KEEP_ALIVE`	no	WebSocket keep-alive interval in seconds. Defaults to `60`.

Set them and authentication is handled for you: the client acquires and refreshes its own access token, and the rest of the SDK — aion.mcp and the two authoring toolkits — authenticates through the same credentials. Values are read from the process environment or from a .env file in the project root.

Control-plane addressing

The control-plane models describe how to address Aion capabilities without hard-coding URL strings. The core shape is:

CapabilityReference(
    subject=CapabilitySubject | None,
    kind=CapabilityKind,
    key=CapabilityKey,
)

Use a subjectless reference for application-owned surfaces such as the built-in metatools MCP server. Use a subject-qualified reference for capabilities attached to distributions, environments, or agent identities.

from aion.api import (
    AION_METATOOLS_MCP_CAPABILITY_KEY,
    AionControlPlanePaths,
    CapabilityReference,
    CapabilitySubject,
)

paths = AionControlPlanePaths("https://api.aion.to")

metatools = CapabilityReference.global_mcp()
keyed_metatools = CapabilityReference.global_mcp(
    key=AION_METATOOLS_MCP_CAPABILITY_KEY
)
distribution_mcp = CapabilityReference.primary_mcp(
    CapabilitySubject.distribution("distribution-id")
)
concrete_distribution_mcp = CapabilityReference.mcp(
    CapabilitySubject.distribution("distribution-id"),
    key="mcp.twitter.distribution",
)

assert paths.capability_path(metatools) == "/mcp/capabilities/mcp.aion.metatools"
assert paths.capability_path(keyed_metatools) == paths.capability_path(metatools)
assert paths.capability_path(distribution_mcp) == "/distributions/distribution-id/mcp"
assert (
    paths.capability_path(concrete_distribution_mcp)
    == "/distributions/distribution-id/mcp/capabilities/mcp.twitter.distribution"
)

CapabilityReference.global_mcp() addresses the metatools server. Called with no key, it selects AION_METATOOLS_MCP_CAPABILITY_KEY (mcp.aion.metatools), so both forms above resolve to the same path.

Capability subjects

Subject constructor	Route prefix
`CapabilitySubject.distribution(distribution_id)`	`/distributions/{distributionId}`
`CapabilitySubject.environment(agent_environment_id)`	`/environments/{agentEnvironmentId}`
`CapabilitySubject.agent_identity(agent_identity_id)`	`/agents/{agentIdentityId}`
`CapabilitySubject.agent_at_name(agent_at_name)`	`/agents/@{agentAtName}`

Capability kinds and keys

CapabilityKind identifies the protocol surface. HTTP-addressable values include CapabilityKind.MCP_SERVER and CapabilityKind.A2A_ENDPOINT. CapabilityKey identifies either:

the primary capability of that kind for the addressed subject
one concrete capability key declared by the behavior

The primary capability sits at the bare kind route; a concrete key hangs off a capabilities segment under it:

Reference	Path
Primary MCP of a subject	`/{subject}/mcp`
Concrete MCP capability	`/{subject}/mcp/capabilities/{capabilityKey}`
Primary A2A of a subject	`/{subject}/a2a`
Concrete A2A capability	`/{subject}/a2a/capabilities/{capabilityKey}`
Agent card discovery	`/{subject}/a2a/.well-known/agent-card.json`

from aion.api import CapabilityKey, CapabilityReference, CapabilitySubject

primary = CapabilityReference.mcp(
    CapabilitySubject.distribution("distribution-id"),
    key=CapabilityKey.primary(),
)

concrete = CapabilityReference.mcp(
    CapabilitySubject.distribution("distribution-id"),
    key=CapabilityKey.concrete("mcp.twitter.distribution"),
)

Omitting key selects the primary capability. global_mcp() is the one reference with a concrete default: the metatools key.

Runtime capability references

RuntimeCapabilityReference is a template for resolving a reference after an AionRuntimeContext exists. It does not read from thread-local or ambient state. The framework adapter must pass the current request context explicitly, or extract it from the framework’s per-request context object.

from aion.api import CapabilitySubjectSource, RuntimeCapabilityReference

incoming_request_distribution_mcp = RuntimeCapabilityReference.primary_mcp(
    CapabilitySubjectSource.INCOMING_DISTRIBUTION
)

resolved = incoming_request_distribution_mcp.resolve(runtime_context)

CapabilitySubjectSource.INCOMING_DISTRIBUTION means the distribution from the current incoming request’s Aion Distribution extension payload. It is request-scoped, not a global default.

Source	Runtime accessor
`ACTIVE_ENVIRONMENT`	`runtime_context.get_environment()`
`INCOMING_DISTRIBUTION`	`runtime_context.get_distribution()`
`PRINCIPAL_IDENTITY`	`runtime_context.get_principal_identity()`

Principal selectors

PrincipalSelector is request metadata used to tell Aion which runtime principal the call is being made as. It is not a credential by itself; the API still validates the bearer token and the selected principal. For behavior-originated calls back to the control plane, such as MCP or A2A access, AionRuntimeContext.get_principal_selector() derives this metadata from the active request. It prefers the environment’s daemon identity when available and falls back to the environment id. Omitting the selector can make the request look like the broader authenticated subject, which may be denied even when the runtime daemon or environment would be allowed.

from aion.api import PrincipalSelector

selector = PrincipalSelector.agent_environment("environment-id")
headers = selector.to_headers()
graphql_principal = selector.to_gql_value()

Model calls are the strict case: the model service runs work for a runtime principal, so every model call must carry one. A call without a principal is refused with AionModelPrincipalError. The MCP helpers derive the selector from AionRuntimeContext.get_principal_selector() when no explicit selector is supplied.

Python SDK

LangGraph

Google ADK

Install

Authentication

Control-plane addressing

Capability subjects

Capability kinds and keys

Runtime capability references

Principal selectors

​Install

​Authentication

​Control-plane addressing

​Capability subjects

​Capability kinds and keys

​Runtime capability references

​Principal selectors

​Related pages

Install

Authentication

Control-plane addressing

Capability subjects

Capability kinds and keys

Runtime capability references

Principal selectors

Related pages