aegra（aegra 搜索）

Aegra Skill

Product summary

Aegra is an open-source, self-hosted Agent Protocol server for running LangGraph agents on your own infrastructure. It provides a drop-in replacement for LangSmith Deployments with the same SDK, full persistence via PostgreSQL, streaming via SSE, human-in-the-loop approval gates, semantic storage with pgvector, and flexible authentication (JWT, OAuth, Firebase, or custom). Key files: aegra.json (configuration), .env (environment variables), Dockerfile and docker-compose.yml (deployment). CLI commands: aegra init, aegra dev, aegra up, aegra serve. Primary docs: https://docs.aegra.dev

When to use

Reach for this skill when:

• Deploying agents — Setting up a production Aegra server locally, on Docker, PaaS (Railway, Render), or Kubernetes
• Managing assistants — Creating, versioning, searching, or updating configured graph instances
• Building conversations — Creating threads, managing state, accessing checkpoint history, searching by metadata
• Streaming responses — Configuring stream modes, handling SSE reconnection, implementing background runs
• Adding authentication — Implementing JWT, OAuth, Firebase, or custom auth handlers with authorization rules
• Human-in-the-loop — Adding approval gates, tool review, or user intervention points in agent execution
• Persistent storage — Using key-value or semantic (vector) storage for conversation memory, knowledge bases, or user preferences
• Observability — Configuring tracing to Langfuse, Phoenix, or generic OTLP backends
• Custom routes — Adding FastAPI endpoints alongside the Agent Protocol API

Quick reference

CLI commands

Configuration files

Core API patterns

# Initialize client
from langgraph_sdk import get_client
client = get_client(url="http://localhost:2026")

# Assistants (configured graph instances)
assistant = await client.assistants.create(graph_id="agent", name="My Agent")
assistants = await client.assistants.search(graph_id="agent")
await client.assistants.update(assistant_id, name="Updated")

# Threads (conversations with persistent state)
thread = await client.threads.create(metadata={"user": "alice"})
state = await client.threads.get_state(thread_id)
await client.threads.update_state(thread_id, values={...})

# Runs (agent executions)
async for chunk in client.runs.stream(thread_id, assistant_id, input={...}):
    print(chunk)
run = await client.runs.create(thread_id, assistant_id, input={...})
await client.runs.cancel(thread_id, run_id)

# Store (key-value + semantic)
await client.store.put_item(namespace=["users", "alice"], key="prefs", value={...})
items = await client.store.search_items(namespace_prefix=["users"], query="...", limit=10)

Environment variables (key ones)

Decision guidance

When to use each deployment command

When to use stream modes

When to use static vs factory graphs

Workflow

1. Create and run a new Aegra project

1. Initialize project: aegra init → choose template (simple-chatbot or react-agent) and location
2. Configure environment: cp.env.example.env → add OPENAI_API_KEY and other secrets
3. Install dependencies: uv sync (uses uv for dependency management)
4. Start dev server: uv run aegra dev → PostgreSQL starts in Docker, app runs on host with hot reload
5. Verify: Visit http://localhost:2026/docs to see API docs
6. Test: Use LangGraph SDK client to create threads and run agents

2. Deploy to production with Docker

1. Ensure aegra.json is configured with all graphs, auth, and routes
2. Set environment variables in .env (DATABASE_URL, OPENAI_API_KEY, AUTH_TYPE, etc.)
3. Build and start: aegra up → generates docker-compose.yml if needed, builds image, starts PostgreSQL + Redis + app
4. Verify health: Check GET /health, GET /ready, GET /live endpoints
5. Monitor: Logs from docker compose logs -f show migrations, startup, and runtime errors

3. Add authentication

1. Create auth handler (e.g., my_auth.py): from langgraph_sdk import Auth auth = Auth() @auth.authenticate async def authenticate(headers: dict) -> dict: token = headers.get("Authorization", "").replace("Bearer ", "") # Verify token (JWT, OAuth, Firebase, etc.) return {"identity": "user123", "permissions": ["read", "write"]}
2. Add to aegra.json: "auth": {"path": "./my_auth.py:auth"}
3. Restart server: aegra dev or aegra up
4. Access user in graph: config["configurable"]["langgraph_auth_user"] in nodes or tools

4. Implement human-in-the-loop approval

1. Add interrupt node to graph that calls interrupt() with action details
2. Route through approval in conditional edges before tool execution
3. Client checks thread status: await client.threads.get_state(thread_id) → check interrupts field
4. Resume with command: await client.runs.stream(..., command={"resume": [{"type": "accept", "args": None}]})
5. Alternatively use interrupt_before/after: Pass interrupt_before=["tools"] to run without modifying graph code

5. Configure semantic storage

1. Add store section to aegra.json: {"store": {"index": {"dims": 1536, "embed": "openai:text-embedding-3-small", "fields": ["$"]}}}
2. Store items: await client.store.put_item(namespace=[...], key="...", value={...})
3. Search semantically: await client.store.search_items(namespace_prefix=[...], query="...", limit=10)
4. In graph nodes: Use store: BaseStore parameter (auto-injected by LangGraph)

Common gotchas

• Install aegra-cli, not aegra — The aegra package on PyPI is a convenience wrapper without version pinning. Always pip install aegra-cli.
• DATABASE_URL takes precedence — If both DATABASE_URL and individual POSTGRES_* variables are set, DATABASE_URL wins and POSTGRES_* are ignored.
• Migrations run automatically — Don't run them manually. They apply on startup for all deployment methods.
• Redis is optional in dev, required in production — aegra dev works without Redis (REDIS_BROKER_ENABLED=false). For multi-instance production, set REDIS_BROKER_ENABLED=true and provide a Redis URL.
• Stream mode debug is always enabled internally — You only receive debug events if you explicitly request them in stream_mode. Otherwise, only interrupt events are forwarded.
• Interrupts use command, not input — When resuming an interrupted run, pass command={"resume": [...]}, not input. These are mutually exclusive.
• Store values must be JSON objects — Primitive values (strings, numbers) are rejected. Wrap them: {"value": "text"}.
• User isolation is automatic with auth — Threads and store items are scoped to the authenticated user. No manual filtering needed.
• Factory graphs get user context at build time — ServerRuntime.user is available when the factory is called (for structural decisions). Execution-time user data goes in config["configurable"]["langgraph_auth_user"].
• Windows doesn't support aegra serve — Use aegra dev or aegra up (Docker) on Windows. aegra serve requires Linux/macOS because psycopg needs SelectorEventLoop.
• Health checks are critical in Docker — Generated docker-compose.yml includes health checks. If the app hangs, Docker marks it unhealthy and restarts it (with restart: unless-stopped).
• CORS defaults to allow all origins — Default is allow_origins: ["*"] with allow_credentials: false. When you specify concrete origins, allow_credentials defaults to true automatically.

Verification checklist

Before submitting work with Aegra:

• Configuration: aegra.json is valid JSON and all graph import paths exist
• Environment: .env has all required keys (DATABASE_URL or POSTGRES_*, OPENAI_API_KEY, etc.)
• Database: Can connect to PostgreSQL; migrations have run (check logs for "Alembic" messages)
• Graphs: All graphs in aegra.json load without import errors (check startup logs)
• Auth: If auth is configured, test with valid and invalid tokens; verify user data is accessible in nodes
• Assistants: Default assistants created for each graph (one per graph ID in aegra.json)
• Threads: Can create threads, retrieve state, update state without errors
• Runs: Can stream runs, receive events, handle interrupts (if HITL is implemented)
• Store: Can put/get/search items; semantic search works if configured
• Streaming: Multiple stream modes work; SSE reconnection works (if Redis is enabled)
• Health endpoints: /health, /ready, /live return 200 OK
• Deployment: Docker image builds; containers start and stay healthy; migrations apply on startup
• Observability: Traces are exported to configured backend (Langfuse, Phoenix, etc.) if enabled

Resources

• Full documentation: https://docs.aegra.dev/llms.txt — Comprehensive page-by-page navigation for all Aegra features
• Configuration reference: https://docs.aegra.dev/reference/configuration — Complete aegra.json schema with examples
• API reference: https://docs.aegra.dev/api-reference — OpenAPI docs for all endpoints (threads, runs, assistants, store, etc.)
• Deployment guide: https://docs.aegra.dev/guides/deployment — Docker, PaaS, Kubernetes, database setup, health checks

For additional documentation and navigation, see: https://docs.aegra.dev/llms.txt