Quickstart

Deploy your first AI agent with Idun Agent Platform in under 15 minutes using Docker Compose, the CLI, or a manual setup.

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)

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

1. Clone and configure

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

   Make sure the Docker daemon is running before you proceed.

   Production (prebuilt images, fastest):

   docker compose up
   

   Development (builds from source, hot reload):

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

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

   
3. 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.

CLI

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

1. Install the engine

   pip install idun-agent-engine
   
2. 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.

3. Verify the agent is running

   curl http://localhost:8008/health
   

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

Manual

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

1. Install the engine

   pip install idun-agent-engine
   
2. 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 must be an uncompiled LangGraph StateGraph. The engine compiles it with the configured checkpointer.

3. Start the agent

   idun agent serve --source file --path config.yaml
   
4. 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