Aegra Skill

Product summary

Aegra is an open-source, self-hosted Agent Protocol server for running LangGraph agents on your own infrastructure. It's a drop-in replacement for LangSmith Deployments with the same SDK, no vendor lock-in, and full control over your data. Agents run on PostgreSQL with optional Redis for multi-instance deployments. Key files: aegra.json (configuration), .env (environment variables), pyproject.toml (dependencies). CLI commands: aegra init (create project), aegra dev (local development), aegra serve (production), aegra up (Docker). Primary docs: https://docs.aegra.dev

When to use

Use this skill when:

• Setting up a new agent project — Initialize with aegra init, configure graphs in aegra.json, and start developing with aegra dev
• Configuring authentication — Add JWT, OAuth, Firebase, or custom auth handlers to protect API endpoints
• Managing agent conversations — Create threads, inspect state, update state, browse checkpoint history, search threads by metadata
• Implementing real-time features — Stream agent responses with SSE, handle interrupts for human-in-the-loop workflows, reconnect after network drops
• Scheduling recurring tasks — Create cron jobs with timezone support, manage stateless or thread-bound scheduled runs
• Persisting data — Store key-value data or semantic embeddings for knowledge retrieval, user preferences, conversation memory
• Deploying to production — Deploy to Docker, PaaS (Railway, Render, Fly.io), or Kubernetes with proper auth, observability, and scaling
• Debugging agent behavior — Inspect thread state at checkpoints, replay from specific points, modify state for testing

Quick reference

CLI commands

Configuration file (aegra.json)

{
  "graphs": {
    "agent": "./src/agent/graph.py:graph"
  },
  "auth": {
    "path": "./my_auth.py:auth"
  },
  "http": {
    "app": "./custom_routes.py:app",
    "cors": {
      "allow_origins": ["https://example.com"],
      "allow_credentials": true
    }
  },
  "store": {
    "index": {
      "dims": 1536,
      "embed": "openai:text-embedding-3-small"
    }
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "default_ttl": 43200
    }
  }
}

Core API patterns

Environment variables (key ones)

Decision guidance

When to use X vs Y

Workflow

1. Initialize and configure a project

1. Run aegra init and choose a template (simple-chatbot or react-agent)
2. Open aegra.json and verify your graph paths under graphs
3. Create .env from .env.example and add API keys (OPENAIAPIKEY, etc.)
4. If using auth, create my_auth.py with @auth.authenticate handler and reference it in aegra.json
5. If using semantic store, add store.index config with embedding model and dimensions

2. Develop and test locally

1. Run aegra dev to start PostgreSQL and the server with hot reload
2. Visit http://localhost:2026/docs to explore the API
3. Create a thread: client.threads.create()
4. Stream a run: client.runs.stream(threadid, assistantid, input={...})
5. Inspect state: client.threads.getstate(threadid)
6. Modify graph code; server auto-reloads

3. Implement human-in-the-loop (if needed)

1. In your graph, call interrupt({payload}) at decision points
2. Client receives interrupt and displays payload to user
3. User responds with command={"resume": [{"type": "accept|edit|response|ignore", "args": ...}]}
4. Resume the run with the command; graph continues from interrupt point

4. Add scheduled tasks (if needed)

1. Create a cron: client.crons.create(assistant_id, schedule="0 9 *", input={...})
2. For thread-bound crons: client.crons.createforthread(thread_id, ...)
3. Update schedule: client.crons.update(cron_id, schedule="...")
4. Disable without deleting: client.crons.update(cron_id, enabled=False)

5. Deploy to production

1. Choose deployment target (Docker, PaaS, Kubernetes)
2. Set up PostgreSQL (managed or self-hosted) and get DATABASE_URL
3. For multi-instance: set up Redis and REDISBROKERENABLED=true
4. Set ENV_MODE=PRODUCTION for JSON logging
5. Use aegra serve as the start command
6. Verify health: GET /health, GET /ready, GET /live

6. Verify before submitting

• All graphs in aegra.json are valid Python import paths
• .env has all required API keys (OPENAIAPIKEY, etc.)
• Auth handler (if configured) returns identity field
• Threads can be created and runs can stream without errors
• State updates persist across runs
• Crons (if used) fire on schedule
• Store operations work (put, get, search)
• Health checks pass: /health, /ready, /live

Common gotchas

• Graph import paths must be exact — ./src/agent/graph.py:graph means the variable graph in that file. Typos silently fail at startup.
• Auth handlers run on every request — Keep them fast. Slow auth blocks all API calls.
• Cron delivery is at-least-once — If a worker crashes between claiming and committing, the cron fires again. Make runs idempotent.
• Stateless cron threads delete by default — Set onruncompleted="keep" if you need to inspect them; clean up manually or use thread TTL.
• Store values must be JSON objects — Strings, numbers, and primitives are rejected. Wrap them: {"value": "text"}.
• Namespace scoping is automatic — User data is isolated under ["users", <user_id>] by default. Configurable scopes share data by org/team/region.
• Stream mode debug is always on — Checkpoint and task events are sent internally but only forwarded to client if explicitly requested.
• **Interrupt before/after "*" pauses at every node** — Use specific node names for targeted interrupts.
• Factory graphs are called per-request — Expensive operations (DB queries, API calls) in factories slow down every run. Cache or defer to graph nodes.
• PostgreSQL must have pgvector — Use pgvector/pgvector:pg18 image. Semantic store won't work without it.
• Redis is optional but recommended for production — Without it, runs execute as in-process asyncio tasks. Multi-instance deployments need Redis for job queue and SSE streaming.
• LangGraph Studio auth can be disabled — Set disablestudioauth: true in config to allow Studio connections without auth (useful for local dev).
• Custom routes don't inherit auth by default — Set enablecustomroute_auth: true to apply Aegra auth to all custom FastAPI routes.

Verification checklist

Before deploying or submitting work:

• Run aegra dev and verify server starts without errors
• Create a thread and stream a run successfully
• Inspect thread state and verify it persists
• If using auth, test with valid and invalid tokens
• If using crons, verify at least one fires on schedule
• If using store, put and retrieve an item
• If using semantic search, verify embeddings are created
• If using human-in-the-loop, trigger an interrupt and resume
• Check logs for warnings or deprecations
• Verify GET /health returns 200 with all components healthy
• Test with LangGraph Studio or Agent Chat UI if available
• Confirm .env has no secrets committed to version control

Resources

• Full documentation navigation: https://docs.aegra.dev/llms.txt
• Configuration reference: https://docs.aegra.dev/reference/configuration
• Authentication guide: https://docs.aegra.dev/guides/authentication
• Streaming and real-time features: https://docs.aegra.dev/guides/streaming

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