Skip to main content

​
1. Start with a Plain LangGraph Graph

Create agent.py: 
from typing import Annotated, TypedDict

from langchain_core.messages import AIMessage, AnyMessage
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages


class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]


def reply_node(state: State) -> dict:
    inbound = state["messages"][-1]
    return {"messages": [AIMessage(content=f"Echo: {inbound.content}")]}


def build_graph():
    graph = StateGraph(State)
    graph.add_node("reply", reply_node)
    graph.add_edge(START, "reply")
    graph.add_edge("reply", END)
    return graph

​
2. Configure aion.yaml

aion:
  agents:
    support:
      path: "./agent.py:build_graph"
      framework: "langgraph"
      name: "Support Agent"
      capabilities:
        streaming: true

​
3. Optional: Add Control Plane Credentials to .env

# .env
AION_CLIENT_ID=your_client_id
AION_CLIENT_SECRET=your_client_secret
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

poetry run aion serve
This starts agent process(es) plus a proxy process with dynamic ports.

​
5. Optional: Validate Endpoints

# Server health check
curl http://localhost:10000/health/
# Server agent manifest
curl http://localhost:10000/.well-known/manifest.json
# A2A agent card for the "support" agent
curl http://localhost:10000/agents/support/.well-known/agent-card.json

​
6. Test Interactively

poetry run aion chat

​
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. 
pip install aion-authoring-langgraph

​
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 and fluent helpers such as thread.reply(...), thread.post(...), and thread.history(...).

​
9. Introduce Aion Runtime Context 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: 
from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.runtime import Runtime

from aion.core.runtime import AionRuntimeContext
from aion.langgraph.authoring.runtime import Thread


async def reply_node(state: MessagesState, runtime: Runtime[AionRuntimeContext]):
    thread = Thread.from_context(runtime.context)
    await thread.reply("I received that.")
    return {}


builder = StateGraph(MessagesState, context_schema=AionRuntimeContext)
builder.add_node("reply", reply_node)
builder.add_edge(START, "reply")
builder.add_edge("reply", END)
graph = builder.compile()
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 Runtime Context for the fluent SDK surface. For the lower-level adapter details, see LangGraph Message Mapping.