Quickstart

Prerequisites

Before you begin, install the following:

Python 3.12+ (python.org)
Docker and Docker Compose (docs.docker.com)
Git (git-scm.com)
uv package manager (docs.astral.sh/uv)

Choose your path

Manager (recommended)
CLI
Manual

The Manager path starts the full platform: PostgreSQL, the FastAPI backend, and the React admin UI.

Clone and configure

git clone https://github.com/Idun-Group/idun-agent-platform.git
cd idun-agent-platform
cp .env.example .env

Start the platform

Make sure the Docker daemon is running before you proceed.

Production (pre-built images)
Development (build from source)

docker compose up -d

docker compose -f docker-compose.dev.yml up --build

Both start PostgreSQL, the Manager API, and the web UI.

Create an agent

Open http://localhost:3000 in your browser.Log in (if you have not configured an auth provider yet, press Login to skip). You land on the agent dashboard.

Click Create to launch the 3-step wizard. Select your framework (LangGraph or ADK), configure framework-specific settings, then review and save.

The CLI provides an interactive TUI to configure and run a standalone agent without the Manager.

Install the engine

pip install idun-agent-engine

Launch the interactive setup

idun init

The TUI walks you through agent configuration: framework, memory, observability, guardrails, and MCP servers. When you finish, it saves the config and starts the agent server.

Verify the agent is running

curl http://localhost:8008/health

Open http://localhost:8008/docs to see the API documentation.

Use this path if you want full control over the configuration file.

Install the engine

pip install idun-agent-engine

Create a config file

Save the following as config.yaml in your project directory. Update graph_definition to point to your agent file and variable.

config.yaml

server:
  api:
    port: 8008

agent:
  type: "LANGGRAPH"
  config:
    name: "my-agent"
    graph_definition: "./agent.py:graph"
    checkpointer:
      type: "memory"

The graph_definition value follows the format path/to/file.py:variable_name. The variable should be a StateGraph (recommended) or CompiledStateGraph. The engine compiles it with the configured checkpointer.

Start the agent

idun agent serve --source file --path config.yaml

Verify the agent is running

curl http://localhost:8008/health

Minimal LangGraph agent example

If you do not have an agent file yet, create agent.py alongside your config:

agent.py

from langgraph.graph import StateGraph, MessagesState

def chatbot(state: MessagesState):
    from langchain_openai import ChatOpenAI
    model = ChatOpenAI(model="gpt-4o-mini")
    return {"messages": [model.invoke(state["messages"])]}

graph = StateGraph(MessagesState)
graph.add_node("chatbot", chatbot)
graph.set_entry_point("chatbot")
graph.set_finish_point("chatbot")

This example requires the OPENAI_API_KEY environment variable. Export it in your shell or add it to your .env file before starting the agent.

Next steps

Frameworks

Configure LangGraph or Google ADK agents in detail

Guardrails

Add PII detection, jailbreak prevention, and content filters

Observability

Connect Langfuse, Phoenix, LangSmith, or GCP Trace

Memory

Set up SQLite or PostgreSQL checkpointing

Templates

Clone a runnable agent template to start faster

Manager tutorial

Full walkthrough of the Manager UI

Getting started

Manager

Agent frameworks

Guardrails

Memory

Observability

Tool governance

Authentication

Integrations

Deployment

Guides

Advanced

Prerequisites

Choose your path

Minimal LangGraph agent example

Next steps

Frameworks

Guardrails

Observability

Memory

Templates

Manager tutorial

Getting started

Manager

Agent frameworks

Guardrails

Memory

Observability

Tool governance

Authentication

Integrations

Deployment

Guides

Advanced

Documentation Index

​Prerequisites

​Choose your path

​Minimal LangGraph agent example

​Next steps

Frameworks

Guardrails

Observability

Memory

Templates

Manager tutorial

Prerequisites

Choose your path

Minimal LangGraph agent example

Next steps