query-writing

Productionize LangGraph & ADK agents.

Self-hosted. Open source. No vendor lock-in.

Cloud · Try the demos · Quickstart · Docs · Discord · Book a demo

⭐ If you find this useful, please star the repo. It helps others discover the project.

Why Idun? Teams building agents face a tradeoff: build the production wrapper yourself (FastAPI + traces + guardrails + admin UI — slow), or adopt a SaaS like LangGraph Cloud or LangSmith (sovereignty trade-off). Idun is the third path: pip install a self-sufficient FastAPI process that bundles your agent with chat UI, admin, traces, and guardrails — all open source, all on your infrastructure.

---

Quick start

Prerequisites: Python 3.12 or 3.13.

Create a new directory and install the engine:

mkdir my-agent && cd my-agent
pip install idun-agent-engine langgraph langchain-google-genai

Save the three files below inside my-agent/.

my-agent/agent.py

from typing import Annotated, TypedDict

from idun_agent_engine.mcp import get_langchain_tools_sync
from langchain_google_genai import ChatGoogleGenerativeAI
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition


class State(TypedDict):
    messages: Annotated[list, add_messages]


tools = get_langchain_tools_sync()
llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash").bind_tools(tools)


def chatbot(state: State):
    return {"messages": [llm.invoke(state["messages"])]}


graph = StateGraph(State)
graph.add_node("chatbot", chatbot)
graph.add_node("tools", ToolNode(tools))
graph.add_edge(START, "chatbot")
graph.add_conditional_edges("chatbot", tools_condition)
graph.add_edge("tools", "chatbot")

my-agent/config.yaml

server:
  api:
    port: 8000

agent:
  type: LANGGRAPH
  config:
    name: "my-agent"
    graph_definition: "./agent.py:graph"
    checkpointer:
      type: sqlite
      db_url: "sqlite:///conversations.db"

mcp_servers:
  - name: idun-docs
    transport: streamable_http
    url: https://docs.idun-group.com/mcp

my-agent/.env — get a Gemini key at aistudio.google.com/apikey:

GEMINI_API_KEY=your-key-here

From inside my-agent/, run:

idun init

graph_definition: "./agent.py:graph" is resolved against the directory where you run idun init. Stay inside my-agent/ when you launch it, or use an absolute path.

A browser opens at http://localhost:8000 for the chat UI. The agent already has tools from the Idun docs MCP wired in. Visit /admin to configure more MCP servers, managed prompts, guardrails, observability, messaging integrations, and SSO. Visit /admin/traces for the trace store.

What pip install idun-agent-engine delivers

A single wheel that bundles three Python packages:

• idun_agent_engine — the engine SDK (FastAPI app factory, MCP registry, observability, guardrails).
• idun_agent_standalone — the idun CLI, the admin REST API, and the chat / admin / traces UIs.
• idun_agent_schema — the Pydantic config schemas.

The idun command on your $PATH (setup, serve, init, hash-password, agent serve) is provided by the bundled standalone — it is not a separately published package. You won't see idun-agent-standalone in the engine's declared PyPI dependencies because it ships co-installed inside the wheel, not as a transitive dep.

See docs.idun-group.com/architecture for the full layering.

What's inside

Observability

Langfuse · Arize Phoenix · LangSmith · GCP Trace · GCP Logging

Trace every agent run. Connect multiple providers at the same time through config.

Guardrails

PII detection · Toxic language · Ban lists · Topic restriction · Bias checks · NSFW · 9 more

Apply policies per agent on input, output, or both. Powered by Guardrails AI.

MCP tool governance

Register MCP servers and control which tools each agent can access. Supports stdio, SSE, streamable HTTP, and WebSocket.

Memory and persistence

PostgreSQL · SQLite · In-memory · Vertex AI · ADK Database

Conversations persist across restarts. Pick a backend per agent.

Prompt management

Versioned templates with Jinja2 variables. Assign prompts to agents from the UI or API.

[!NOTE] AG-UI streaming — Every agent gets a standards-based streaming API, compatible with CopilotKit clients. Built-in chat playground for testing.

---

Architecture

Idun ships as one process: idun-agent-standalone. It bundles the engine SDK, a Next.js chat UI, an admin panel, and a traces viewer — your agent runs inside this process, configured from a YAML file and re-loaded live from the admin REST.

flowchart LR
  subgraph Idun["idun-agent-standalone (one process)"]
    direction TB
    UI["Chat UI / Admin / Traces"] --> ENG["Engine SDK"]
    ENG --> DB[(Postgres / SQLite)]
  end
  Users --