Installation - Aion Docs

The SDK is one PyPI project, aionto-sdk, and its extras select how much of the stack comes with it: the framework you write agents in, and whether the environment also serves them.

Prerequisites

Python 3.12, 3.13 or 3.14
pip, poetry or uv
Node.js 22+ — required by aion chat, which launches the bundled terminal UI. Not needed for aion serve or the client libraries.

Install

The base install gives you the aion command, the API and MCP clients, and the shared authoring types:

pip install aionto-sdk

To run agents with aion serve, add the extra for the framework they are written in. This is what a project normally installs:

Feature	`pip`	`uv`
Base — the `aion` CLI and client libraries	`pip install aionto-sdk`	`uv add aionto-sdk`
LangGraph agents	`pip install "aionto-sdk[langgraph-server]"`	`uv add "aionto-sdk[langgraph-server]"`
Google ADK agents	`pip install "aionto-sdk[adk-server]"`	`uv add "aionto-sdk[adk-server]"`

Poetry uses the same specifiers:

poetry add "aionto-sdk[langgraph-server]"

To run both frameworks from one environment, name both extras in a single command: pip install "aionto-sdk[langgraph-server,adk-server]".

Choosing an extra

Extra	Adds	Use it when
`langgraph-authoring`	LangGraph, and the Aion toolkit for it	You want the authoring toolkit without the serving layer.
`adk-authoring`	Google ADK, and the Aion toolkit for it	Same, for Google ADK agents.
`server`	The serving layer: HTTP server, durable task storage, telemetry	Rarely on its own — both `*-server` extras include it.
`langgraph-server`	`langgraph-authoring` + `server` + Postgres checkpointing	`aion serve` runs a LangGraph agent.
`adk-server`	`adk-authoring` + `server`	`aion serve` runs a Google ADK agent.

Each *-server extra installs its authoring extra too, so [langgraph-server] covers everything [langgraph-authoring] does.

When an extra is missing

The first call that needs a library from an uninstalled extra raises MissingOptionalDependency, carrying the command that fixes it:

LangGraph authoring requires optional dependencies.
Install them with: pip install "aionto-sdk[langgraph-authoring]"

MissingOptionalDependency is both an AionError and an ImportError, so except ImportError around an SDK import catches it. See Troubleshooting for the full set of messages.

Optional Control Plane Credentials

For deployments hosted by Aion, these values are supplied by the control plane. Set them yourself only when running outside Aion-hosted deployments or when testing a server locally against the Aion control plane. Create .env in your project root when you need to provide them manually:

AION_CLIENT_ID=your_client_id
AION_CLIENT_SECRET=your_client_secret

Without these variables, you can still run aion serve locally and invoke agents through the local A2A and proxy endpoints, but the SDK will not connect to the Aion control plane or register agent manifests automatically. See Environment Variables for full settings.

Minimal `aion.yaml`

aion:
  agents:
    support:
      path: "./agent.py:build_graph"

path is the only field an agent needs. It points at a graph, an agent, or a factory that returns one, and the adapter for the framework you installed picks it up — see the aion.yaml reference.

Verify CLI

aion --version
aion --help
aion serve --help
aion chat --help

​Prerequisites

​Install

​Choosing an extra

​When an extra is missing

​Optional Control Plane Credentials

​Minimal aion.yaml

​Verify CLI

Prerequisites

Install

Choosing an extra

When an extra is missing

Optional Control Plane Credentials

Minimal `aion.yaml`

Verify CLI