> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aion.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run a LangGraph agent behind the Aion A2A server.

## 1. Start with a Plain LangGraph Graph

Create `agent.py`:

```python theme={null}
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`

```yaml theme={null}
aion:
  agents:
    support:
      path: "./agent.py:build_graph"
      framework: "langgraph"
      name: "Support Agent"
      capabilities:
        streaming: true
```

## 3. Optional: Add Control Plane Credentials to `.env`

```bash theme={null}
# .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](/sdk/python/configuration/environment-variables).

## 4. Start Services

```bash theme={null}
poetry run aion serve
```

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

## 5. Optional: Validate Endpoints

```bash theme={null}
# 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

```bash theme={null}
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.

```bash theme={null}
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, 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:

```python theme={null}
from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.runtime import Runtime

from aion.core.runtime import AionRuntimeContext
from aion.langgraph.authoring 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](/sdk/langgraph/message-mapping) for the
high-level flow, [Integration Patterns](/sdk/langgraph/guides/integration-patterns)
for the three authoring styles, and
[AionRuntimeContext](/sdk/langgraph/api/runtime-context) for the fluent
SDK surface.

For the lower-level adapter details, see
[LangGraph Message Mapping](/sdk/python/frameworks/langgraph/message-mapping).