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 runtime.context.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 flow and the adapter rules behind it, Integration Patterns for the three authoring styles, and AionRuntimeContext for the fluent SDK surface.