Skip to main content

​
Prerequisites

  • Python 3.12+
  • Docker (for PostgreSQL)

​
Create a project

1

Install the CLI

pip install aegra-cli
2

Initialize a new project

aegra init
The CLI will prompt you for a location, template, and project name. Choose the simple-chatbot template to get started quickly.
3

Configure your environment

cd <your-project>
cp .env.example .env
Open .env and add your OPENAI_API_KEY.
4

Install dependencies and start the server

The generated project uses uv for dependency management. The pyproject.toml created by aegra init defines your project’s dependencies, and uv handles the rest.
uv sync
uv run aegra dev
This starts a PostgreSQL container, applies database migrations, and launches the server with hot reload.
Your server is running at http://localhost:8000. Visit http://localhost:8000/docs to explore the API.
Always install aegra-cli directly — not the aegra meta-package. The aegra package on PyPI is a convenience wrapper that does not support version pinning.

​
Talk to your agent

Your LangGraph code works without changes: 
import asyncio
from langgraph_sdk import get_client


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

    # Each graph in aegra.json gets a default assistant with the same ID
    thread = await client.threads.create()

    async for chunk in client.runs.stream(
        thread_id=thread["thread_id"],
        assistant_id="agent",
        input={"messages": [{"type": "human", "content": "Hello!"}]},
    ):
        print(chunk)


asyncio.run(main())

​
Connect a frontend

Aegra implements the Agent Protocol, so it works with any compatible frontend:

Agent Chat UI

Open-source chat interface for agent interactions.

LangGraph Studio

Visual graph debugger and testing tool.

CopilotKit

In-app AI copilot framework via AG-UI protocol.

​
What’s next

Build your first agent

Hands-on tutorial: build, deploy, and interact with an agent step by step.

Streaming

Understand stream modes, SSE events, and reconnection.

Authentication

Add JWT, OAuth, or Firebase auth to your server.

Deployment

Deploy to Docker, PaaS, or Kubernetes.