Assistants

An assistant is a configured instance of a LangGraph graph. While graphs define the agent logic, assistants let you create multiple configurations of the same graph with different names, metadata, and settings.

Default assistants

When the server starts, Aegra automatically creates a default assistant for each graph defined in aegra.json. Aegra accepts the graph ID directly in run and cron APIs and resolves it to that default assistant for you, so you can use graph IDs without creating assistants manually.

{
  "graphs": {
    "agent": "./src/my_agent/graph.py:graph"
  }
}

This automatically creates a default assistant for the agent graph that run and cron APIs can target immediately by passing assistant_id="agent".

Creating assistants

Create custom assistants with specific configurations:

import asyncio
from langgraph_sdk import get_client


async def main():
    client = get_client(url="http://localhost:2026")

    # Create an assistant from your graph
    assistant = await client.assistants.create(
        graph_id="agent",
        name="Customer Support Agent",
        description="Handles customer inquiries with web search",
        metadata={"department": "support", "tier": "premium"},
    )
    print(f"Assistant ID: {assistant['assistant_id']}")


asyncio.run(main())

Idempotent creation

Use if_exists to avoid errors when the assistant already exists:

assistant = await client.assistants.create(
    graph_id="agent",
    name="My Agent",
    if_exists="do_nothing",  # Returns existing if already created
)

An assistant has two uniqueness keys: its assistant_id, which is unique across every user, and its graph_id plus config pair, which is unique per owner. Either match counts as “already exists”, so a second create with the same graph and config returns the first assistant rather than a duplicate. Creation is atomic, so callers racing on the same assistant_id — retries, replays, several replicas booting at once — all converge on one stored assistant instead of one of them failing. With the default if_exists="error", a duplicate answers 409. An assistant_id already taken by another user also answers 409: it is never returned to you, even with if_exists="do_nothing".

A client-provided assistant_id must be 1–255 non-blank characters. Omit the field (or send null) to let the server generate a UUID. Longer or blank values are rejected with 422 before they hit PostgreSQL’s btree key limit (~2704 bytes).

The snippets below assume you are inside an async def function with an initialized client — see the example above.

Listing and searching

# List all assistants
assistants = await client.assistants.search()

# Search by graph ID
results = await client.assistants.search(graph_id="agent")

# Search by metadata
results = await client.assistants.search(
    metadata={"department": "support"},
)

# Search by name
results = await client.assistants.search(name="Customer Support")

Updating assistants

assistant = await client.assistants.update(
    assistant_id="your-assistant-id",
    name="Updated Name",
    metadata={"department": "engineering"},
)

Updates are partial: a field you leave out keeps the value it already has. config and context replace, so sending either one explicitly empty clears it:

# Drop the config, and the context that mirrors config["configurable"]
assistant = await client.assistants.update(
    assistant_id="your-assistant-id",
    config={},
)

metadata is different: it merges into the assistant’s existing metadata rather than replacing it, so metadata={} changes nothing and a stored key cannot be removed through this endpoint — only overwritten. name and graph_id are stored as non-null, so supplying either one empty is a 422 rather than a silent no-op. Omit them to leave them unchanged. description is nullable, so an explicit None clears it.

Versioning

Assistants are versioned. Each update creates a new version while preserving the history:

# List all versions
versions = await client.assistants.get_versions(assistant_id)

# Set a specific version as the latest
await client.assistants.set_latest(assistant_id, version=2)

Graph schemas

Retrieve the schemas for an assistant’s graph:

schemas = await client.assistants.get_schemas(assistant_id)
print(schemas["graph_id"])
print(schemas["input_schema"])
print(schemas["output_schema"])
print(schemas["state_schema"])
print(schemas["config_schema"])
print(schemas["context_schema"])  # the graph's run context type

Every key is always present. A schema the server could not derive from the graph is null, so read the value rather than testing for the key.

Graph visualization

Get the graph structure for visualization:

# Basic graph structure (nodes and edges)
graph = await client.assistants.get_graph(assistant_id)

# Detailed view with xray (expands subgraphs)
graph = await client.assistants.get_graph(assistant_id, xray=True)

# Control xray depth
graph = await client.assistants.get_graph(assistant_id, xray=2)

The response includes nodes and edges that can be rendered by LangGraph Studio or custom visualizers.

Subgraphs

If your graph uses subgraphs, you can inspect them:

subgraphs = await client.assistants.get_subgraphs(assistant_id)

# Recursively list all nested subgraphs
subgraphs = await client.assistants.get_subgraphs(assistant_id, recurse=True)

Deleting assistants

await client.assistants.delete(assistant_id)

When authentication is enabled, you can restrict deletion to admin users using authorization handlers. See the authentication guide.

Getting started

Core concepts

Data & storage

Configuration

Contributing

Reference

Default assistants

Creating assistants

Idempotent creation

Listing and searching

Updating assistants

Versioning

Graph schemas

Graph visualization

Subgraphs

Deleting assistants

​Default assistants

​Creating assistants

​Idempotent creation

​Listing and searching

​Updating assistants

​Versioning

​Graph schemas

​Graph visualization

​Subgraphs

​Deleting assistants

Default assistants

Creating assistants

Idempotent creation

Listing and searching

Updating assistants

Versioning

Graph schemas

Graph visualization

Subgraphs

Deleting assistants