Skip to content
Back to search

idun-agent-platform

🟪 Open-source runtime that ships any LangGraph or Google ADK agent as a production-ready FastAPI service. Bundled , AG-UI copilotkit API, chat UI, 15+ guardrails, MCP, OpenTelemetry, OIDC. One pip install. Self-hosted, no vendor lock-in.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/idun-group--idun-agent-platform/badge.svg)](/listings/idun-group--idun-agent-platform)

HTML

<a href="/listings/idun-group--idun-agent-platform"><img src="/api/listings/idun-group--idun-agent-platform/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **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](https://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](http://localhost:8000) for the chat UI. The agent already has tools from the Idun docs MCP wired in. Visit [/admin](http://localhost:8000/admin) to configure more MCP servers, managed prompts, guardrails, observability, messaging integrations, and SSO. Visit [/admin/traces](http://localhost:8000/admin/traces) for the trace store.

<p align="center"> </p>

<p align="center"> </p>

> **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](https://docs.idun-group.com/architecture) for the full layering.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 385 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img alt="Idun Agent Platform" src="docs/images/readme/banner.png">
  3. <p>
  4. <strong>English</strong> | <a href="docs/readme/README.fr.md">Français</a> | <a href="docs/readme/README.es.md">Español</a> | <a href="docs/readme/README.zh.md">中文</a> | <a href="docs/readme/README.ar.md">العربية</a>
  5. </p>
  6. <br/>
  7. ### Productionize LangGraph & ADK agents.
  8. Self-hosted. Open source. No vendor lock-in.
  9. <br/>
  10. [![License: GPLv3](https://img.shields.io/badge/License-GPLv3-purple.svg)](https://www.gnu.org/licenses/gpl-3.0.html)
  11. [![CI](https://github.com/Idun-Group/idun-agent-platform/actions/workflows/ci.yml/badge.svg)](https://github.com/Idun-Group/idun-agent-platform/actions/workflows/ci.yml)
  12. [![PyPI](https://img.shields.io/pypi/v/idun-agent-engine?color=purple)](https://pypi.org/project/idun-agent-engine/)
  13. [![Discord](https://img.shields.io/badge/Discord-Join%20Us-purple?logo=discord&logoColor=white)](https://discord.gg/KCZ6nW2jQe)
  14. [![Stars](https://img.shields.io/github/stars/Idun-Group/idun-agent-platform?style=social)](https://github.com/Idun-Group/idun-agent-platform)
  15. [![Commits](https://img.shields.io/github/commit-activity/m/Idun-Group/idun-agent-platform?color=purple)](https://github.com/Idun-Group/idun-agent-platform)
  16. <br/>
  17. [Cloud](https://cloud.idunplatform.com) · [Try the demos](https://idun-group.com/demo) · [Quickstart](https://docs.idun-group.com/quickstart) · [Docs](https://docs.idun-group.com) · [Discord](https://discord.gg/KCZ6nW2jQe) · [Book a demo](https://calendar.app.google/RSzm7EM5VZY8xVnN9)
  18. ⭐ If you find this useful, please star the repo. It helps others discover the project.
  19. </div>
  20. <br/>
  21. <p align="center">Idun Agent Platform is an open-source, self-hosted production wrapper for <b>LangGraph</b> and <b>Google ADK</b> agents. <code>pip install idun-agent-engine</code> and your agent runs as a FastAPI process with built-in chat UI, admin panel, traces, observability, guardrails, memory persistence, MCP tool governance, and prompt management.</p>
  22. <p align="center">
  23. <img src="docs/images/readme/demo.webp" alt="Idun Agent Platform demo" width="100%"/>
  24. </p>
  25. > **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.
  26. ---
  27. ## Quick start
  28. > **Prerequisites**: Python 3.12 or 3.13.
  29. Create a new directory and install the engine:
  30. ```bash
  31. mkdir my-agent && cd my-agent
  32. pip install idun-agent-engine langgraph langchain-google-genai
  33. ```
  34. Save the three files below inside `my-agent/`.
  35. **`my-agent/agent.py`**
  36. ```python
  37. from typing import Annotated, TypedDict
  38. from idun_agent_engine.mcp import get_langchain_tools_sync
  39. from langchain_google_genai import ChatGoogleGenerativeAI
  40. from langgraph.graph import StateGraph, START
  41. from langgraph.graph.message import add_messages
  42. from langgraph.prebuilt import ToolNode, tools_condition
  43. class State(TypedDict):
  44. messages: Annotated[list, add_messages]
  45. tools = get_langchain_tools_sync()
  46. llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash").bind_tools(tools)
  47. def chatbot(state: State):
  48. return {"messages": [llm.invoke(state["messages"])]}
  49. graph = StateGraph(State)
  50. graph.add_node("chatbot", chatbot)
  51. graph.add_node("tools", ToolNode(tools))
  52. graph.add_edge(START, "chatbot")
  53. graph.add_conditional_edges("chatbot", tools_condition)
  54. graph.add_edge("tools", "chatbot")
  55. ```
  56. **`my-agent/config.yaml`**
  57. ```yaml
  58. server:
  59. api:
  60. port: 8000
  61. agent:
  62. type: LANGGRAPH
  63. config:
  64. name: "my-agent"
  65. graph_definition: "./agent.py:graph"
  66. checkpointer:
  67. type: sqlite
  68. db_url: "sqlite:///conversations.db"
  69. mcp_servers:
  70. - name: idun-docs
  71. transport: streamable_http
  72. url: https://docs.idun-group.com/mcp
  73. ```
  74. **`my-agent/.env`** — get a Gemini key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey):
  75. ```
  76. GEMINI_API_KEY=your-key-here
  77. ```
  78. From inside `my-agent/`, run:
  79. ```bash
  80. idun init
  81. ```
  82. > `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.
  83. A browser opens at [http://localhost:8000](http://localhost:8000) for the chat UI. The agent already has tools from the Idun docs MCP wired in. Visit [/admin](http://localhost:8000/admin) to configure more MCP servers, managed prompts, guardrails, observability, messaging integrations, and SSO. Visit [/admin/traces](http://localhost:8000/admin/traces) for the trace store.
  84. <p align="center">
  85. <img src="docs/images/readme/welcome-ui.png" alt="Idun Agent chat UI welcome screen" width="100%"/>
  86. </p>
  87. <p align="center">
  88. <img src="docs/images/readme/chat-mcp.png" alt="Chat answering an MCP-backed question with tool-call reasoning" width="100%"/>
  89. </p>
  90. > **What `pip install idun-agent-engine` delivers**
  91. >
  92. > A single wheel that bundles three Python packages:
  93. >
  94. > - **`idun_agent_engine`** — the engine SDK (FastAPI app factory, MCP registry, observability, guardrails).
  95. > - **`idun_agent_standalone`** — the `idun` CLI, the admin REST API, and the chat / admin / traces UIs.
  96. > - **`idun_agent_schema`** — the Pydantic config schemas.
  97. >
  98. > 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.
  99. >
  100. > See [docs.idun-group.com/architecture](https://docs.idun-group.com/architecture) for the full layering.
  101. ## What's inside
  102. <table>
  103. <tr>
  104. <td width="50%" valign="top">
  105. ### Observability
  106. Langfuse · Arize Phoenix · LangSmith · GCP Trace · GCP Logging
  107. Trace every agent run. Connect multiple providers at the same time through config.
  108. <img src="docs/images/readme/observability.png" alt="Observability" width="100%"/>
  109. </td>
  110. <td width="50%" valign="top">
  111. ### Guardrails
  112. PII detection · Toxic language · Ban lists · Topic restriction · Bias checks · NSFW · 9 more
  113. Apply policies per agent on input, output, or both. Powered by Guardrails AI.
  114. <img src="docs/images/readme/guardrails.png" alt="Guardrails" width="100%"/>
  115. </td>
  116. </tr>
  117. <tr>
  118. <td width="50%" valign="top">
  119. ### MCP tool governance
  120. Register MCP servers and control which tools each agent can access. Supports stdio, SSE, streamable HTTP, and WebSocket.
  121. <img src="docs/images/readme/mcp.png" alt="MCP" width="100%"/>
  122. </td>
  123. <td width="50%" valign="top">
  124. ### Memory and persistence
  125. PostgreSQL · SQLite · In-memory · Vertex AI · ADK Database
  126. Conversations persist across restarts. Pick a backend per agent.
  127. <img src="docs/images/readme/memory.png" alt="Memory" width="100%"/>
  128. </td>
  129. </tr>
  130. <tr>
  131. <td colspan="2" valign="top" align="center">
  132. ### Prompt management
  133. Versioned templates with Jinja2 variables. Assign prompts to agents from the UI or API.
  134. <img src="docs/images/readme/prompts.png" alt="Prompts" width="50%"/>
  135. </td>
  136. </tr>
  137. </table>
  138. > [!NOTE]
  139. > **AG-UI streaming** — Every agent gets a standards-based streaming API, compatible with CopilotKit clients. Built-in chat playground for testing.
  140. <p align="center">
  141. <img src="docs/images/readme/agent-detail.png" alt="Agent detail" width="100%"/>
  142. </p>
  143. ---
  144. ## Architecture
  145. 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.
  146. ```mermaid
  147. flowchart LR
  148. subgraph Idun["idun-agent-standalone (one process)"]
  149. direction TB
  150. UI["Chat UI / Admin / Traces"] --> ENG["Engine SDK"]
  151. ENG --> DB[(Postgres / SQLite)]
  152. end
  153. Users --> UI
  154. Admin --> UI
  155. ENG --> Agent["Your LangGraph / ADK agent"]
  156. Agent --> LLM["LLMs / MCP / tools"]
  157. ```
  158. ---
  159. ## Integrations
  160. <p align="center">
  161. <img src="docs/images/logos/langgraph-color.png" alt="LangGraph" style="height:36px; margin:6px; vertical-align:middle;" />
  162. <img src="docs/images/logos/agent-development-kit.png" alt="ADK" style="height:36px; margin:6px; vertical-align:middle;" />
  163. <img src="docs/images/logos/langfuse-color.png" alt="Langfuse" style="height:36px; margin:6px; vertical-align:middle;" />
  164. <img src="docs/images/logos/mcp.png" alt="MCP" style="height:36px; margin:6px; vertical-align:middle;" />
  165. <img src="docs/images/logos/Postgresql_elephant.png" alt="PostgreSQL" style="height:36px; margin:6px; vertical-align:middle;" />
  166. <img src="docs/images/logos/phoenix.svg" alt="Phoenix" style="height:36px; margin:6px; vertical-align:middle;" />
  167. <img src="docs/images/logos/langsmith-color.png" alt="LangSmith" style="height:36px; margin:6px; vertical-align:middle;" />
  168. <img src="docs/images/logos/google-cloud.png" alt="Google Cloud" style="height:36px; margin:6px; vertical-align:middle;" />
  169. <img src="docs/images/logos/guardrails-ai.png" alt="Guardrails AI" style="height:36px; margin:6px; vertical-align:middle;" />
  170. <img src="docs/images/logos/langchain-color.png" alt="LangChain" style="height:36px; margin:6px; vertical-align:middle;" />
  171. <img src="docs/images/logos/A2A.png" alt="A2A" style="height:36px; margin:6px; vertical-align:middle;" />
  172. <img src="docs/images/logos/ag-ui.png" alt="AG-UI" style="height:36px; margin:6px; vertical-align:middle;" />
  173. </p>
  174. > [!NOTE]
  175. > **Framework support** — LangGraph and Google ADK are first-class today, with full adapters in the engine. LangChain is supported via the LangGraph adapter; broader native LangChain compatibility is on the [roadmap](https://docs.idun-group.com/roadmap).
  176. ---
  177. ## Idun vs alternatives
  178. | | **Idun Engine** | **LangGraph Cloud** | **LangSmith** | **DIY (FastAPI + glue)** |
  179. |---|:---:|:---:|:---:|:---:|
  180. | Self-hosted / on-prem | ✅ | ❌ | ❌ | ✅ |
  181. | Multi-framework (LangGraph + ADK) | ✅ | LangGraph only | ❌ obs only | Manual |
  182. | Guardrails (15+ built-in) | ✅ | ❌ | ❌ | Build yourself |
  183. | MCP tool governance | ✅ per-agent | ❌ | ❌ | Build yourself |
  184. | Observability (multi-provider) | ✅ Langfuse, Phoenix, LangSmith, GCP | ❌ LangSmith only | ✅ LangSmith only | Manual |
  185. | Memory / checkpointing | ✅ Postgres, SQLite, in-memory | ✅ | ❌ | Build yourself |
  186. | AG-UI / CopilotKit streaming | ✅ | ✅ | ❌ | Manual |
  187. | Open source (GPLv3) | ✅ | ❌ | ❌ | — |
  188. > [!NOTE]
  189. > Idun is not a replacement for LangSmith (observability) or LangGraph Cloud (hosting). It is the layer between your agent code and production that handles governance, security, and operations, regardless of which observability or hosting you choose.
  190. ---
  191. ## Configuration
  192. ### Components in this install
  193. After `pip install idun-agent-engine`, your `$PATH` and `site-packages` contain:
  194. | Module | Distributed via | Purpose |
  195. |---|---|---|
  196. | `idun_agent_engine` | declared in `requires_dist` | FastAPI app factory, MCP registry, observability, guardrails wiring |
  197. | `idun_agent_schema` | declared in `requires_dist` | Pydantic config models for `config.yaml` |
  198. | `idun_agent_standalone` | **co-bundled in the engine wheel** | `idun` CLI, admin REST under `/admin/api/v1/`, chat / admin / traces UIs at `/`, `/admin/`, `/admin/traces/` |
  199. | `idun` (console script) | `[project.scripts] idun = "idun_agent_standalone.cli:main"` | Subcommands: `setup`, `serve`, `init`, `hash-password`, `agent serve` |
  200. The bundled-install model means **you do not need to `pip install idun-agent-standalone` separately** — it isn't published. To verify your install carries everything:
  201. ```bash
  202. python -c "import idun_agent_engine, idun_agent_standalone, idun_agent_schema; print('all 3 modules importable')"
  203. idun --help
  204. ```
  205. Both checks are smoke-tested in the release pipeline before any wheel is published.
  206. Heads up: both `pypi.org` and `test.pypi.org` JSON APIs report `entry_points: null` and omit `idun-agent-standalone` from `requires_dist`. This is a Warehouse rendering quirk — the wheel itself still wires the `idun` console script and bundles standalone. The smoke-test commands above are the canonical way to verify a healthy install.
  207. ### YAML reference
  208. Every agent is configured through a single YAML file. Here is a complete example with all features enabled:
  209. ```yaml
  210. server:
  211. api:
  212. port: 8001
  213. agent:
  214. type: "LANGGRAPH"
  215. config:
  216. name: "Support Agent"
  217. graph_definition: "./agent.py:graph"
  218. checkpointer:
  219. type: "sqlite"
  220. db_url: "sqlite:///checkpoints.db"
  221. observability:
  222. - provider: "LANGFUSE"
  223. enabled: true
  224. config:
  225. host: "https://cloud.langfuse.com"
  226. public_key: "${LANGFUSE_PUBLIC_KEY}"
  227. secret_key: "${LANGFUSE_SECRET_KEY}"
  228. guardrails:
  229. input:
  230. - config_id: "DETECT_PII"
  231. on_fail: "reject"
  232. reject_message: "Request contains personal information."
  233. output:
  234. - config_id: "TOXIC_LANGUAGE"
  235. on_fail: "reject"
  236. mcp_servers:
  237. - name: "time"
  238. transport: "stdio"
  239. command: "docker"
  240. args: ["run", "-i", "--rm", "mcp/time"]
  241. prompts:
  242. - prompt_id: "system-prompt"
  243. version: 1
  244. content: "You are a support agent for {{ company_name }}."
  245. tags: ["latest"]
  246. ```
  247. > [!TIP]
  248. > Environment variables like `${LANGFUSE_SECRET_KEY}` are resolved at startup. You can use `.env` files or inject them through Docker/Kubernetes.
  249. Serve the engine directly from a YAML file (no admin UI, just the agent endpoints):
  250. ```bash
  251. idun agent serve --source file --path config.yaml
  252. ```
  253. > [!IMPORTANT]
  254. > Full config reference: [docs.idun-group.com/configuration](https://docs.idun-group.com/configuration)
  255. >
  256. > 9 runnable agent examples: [idun-agent-template](https://github.com/Idun-Group/idun-agent-template)
  257. ---
  258. ## Community
  259. | | |
  260. |---|---|
  261. | **Questions and help** | [Discord](https://discord.gg/KCZ6nW2jQe) |
  262. | **Feature requests** | [GitHub Discussions](https://github.com/Idun-Group/idun-agent-platform/discussions) |
  263. | **Bug reports** | [GitHub Issues](https://github.com/Idun-Group/idun-agent-platform/issues) |
  264. | **Contributing** | [CONTRIBUTING.md](./CONTRIBUTING.md) |
  265. | **Roadmap** | [ROADMAP.md](./ROADMAP.md) |
  266. ## Commercial support
  267. Maintained by [Idun Group](https://idun-group.com). We help with platform architecture, deployment, and IdP/compliance integration. [Book a call](https://calendar.app.google/RSzm7EM5VZY8xVnN9) · contact@idun-group.com
  268. ## Telemetry
  269. Minimal, anonymous usage metrics + masked session replay via PostHog, hosted in the EU (`eu.i.posthog.com`). No message content, no PII beyond email after sign-in (set `IDUN_TELEMETRY_IDENTIFY_USERS=false` to disable). [View source](libs/idun_agent_engine/src/idun_agent_engine/telemetry/telemetry.py). Off: `IDUN_TELEMETRY_ENABLED=false`. Replay-only off: `IDUN_TELEMETRY_SESSION_REPLAY=false`.
  270. ## License
  271. [GPLv3](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.