Skip to main content

1. Start with a Plain LangGraph Graph

Create agent.py:

2. Configure aion.yaml

3. 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.

4. Start Services

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

5. Optional: Validate Endpoints

6. Test Interactively

7. Optional: Add aion-authoring-langgraph for Deeper Integration

Aion Server integration with LangGraph is designed to work without any framework-specific Aion authoring dependency. A plain LangGraph graph can run behind Aion as long as the server-side adapter is installed. Add aion-authoring-langgraph only if you want deeper Aion-aware protocol integration in your graph code, such as request-scoped runtime context, fluent messaging helpers, custom stream events, and structured response authoring.

8. 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-authoring-langgraph runtime context, event router, fluent messaging helpers, model-service helpers, and MCP tool loading.

9. Introduce AionRuntimeContext When Needed

The aion-authoring-langgraph 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.

10. 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.