Skip to main content

1. Install

This brings LangGraph, the Aion authoring toolkit, the A2A server and the Postgres checkpointer. See Installation for the other combinations.

2. Start with a Plain LangGraph Graph

Create agent.py:

3. Configure aion.yaml

4. Optional: Add Control Plane Credentials to .env

For Aion-hosted deployments, these are provided by the control plane. Add them to .env only when running outside Aion-hosted deployments or when testing local control plane connectivity. For more information, see Environment Variables.

5. Start Services

This starts agent process(es) plus a proxy process with dynamic ports.

6. Optional: Validate Endpoints

The proxy prints its address on startup — by default the first free port from 8000:

7. Test Interactively

8. Optional: Reach for aion.langgraph.authoring

The graph above runs behind Aion as a plain LangGraph graph. Reach into aion.langgraph.authoring when you want deeper Aion-aware protocol integration in your graph code — request-scoped runtime context, fluent messaging helpers, custom stream events, structured response authoring. It ships with [langgraph-server], so it is already importable.

9. Choose an Authoring Mode

There are three useful ways to write LangGraph agents behind Aion:
  1. Plain LangGraph Use state.messages and let Aion infer the reply from normal LangGraph output.
  2. Hybrid A2A Read a2a_inbox and set a2a_outbox when you want direct protocol control.
  3. SDK-aware LangGraph Use the aion.langgraph.authoring runtime context, event router, fluent messaging helpers, model-service helpers, and MCP tool loading.

10. Introduce AionRuntimeContext When Needed

The aion.langgraph.authoring authoring surface is designed to live in LangGraph’s invocation-scoped runtime context instead of forcing transport metadata into your graph state:
This keeps LangGraph state focused on model-facing data such as state.messages while Aion-specific routing, history, and outbound buffering stay request-scoped.

11. Understand Message Mapping

Once the graph is running, Aion will:
  1. accept inbound A2A requests from clients or distributions
  2. map conversational text into state.messages
  3. optionally expose request-scoped Aion context through LangGraph runtime context and hybrid A2A surfaces
  4. use the SDK response buffer first, then a2a_outbox, then framework-native fallback to determine the outbound reply
  5. return the final A2A response to the caller or distribution
Continue to Message Mapping for the high-level flow, Integration Patterns for the three authoring styles, and AionRuntimeContext for the fluent SDK surface. For the lower-level adapter details, see LangGraph Message Mapping.