How easy it is to use Idun Engine with any Deep Agent

Deep Agents is LangChain’s framework for agents that plan, write to a virtual filesystem, and spawn subagents. Under the hood, it produces a compiled LangGraph StateGraph — which means the Idun Engine treats it exactly like any other LangGraph agent. No adapter, no glue code: point Idun at the module, get a streaming API, a chat UI, observability, and MCP tools for free. This guide takes the official text-to-SQL Deep Agent example, drops it behind Idun, and walks all the way to a Gemini-powered agent that queries SQLite, traces every step in the built-in dashboard and Langfuse, and emails its results via a Google Workspace MCP server.

What you will build

Discover the agent

Clone the Deep Agents example, run idun init, point the wizard at agent.py.

Chat with it

Ask natural-language questions, watch the planning + SQL tool calls stream live.

Persist conversations

Switch the LangGraph checkpointer to SQLite — full chat history with one click.

See what's happening

Use the built-in dashboard and trace viewer, then plug Langfuse on top.

Plug in a Google Workspace MCP

Connect Gmail / Drive / Calendar through MCP and have the agent email the results.

Prerequisites

Python 3.12+
A Gemini API key — get one
(Step 7) A free Langfuse Cloud account
(Step 8) A Google Cloud project with a Desktop OAuth client and Gmail API enabled

Clone the Deep Agents example

We’ll work from the official text-to-sql-agent example. It ships with the Chinook SQLite database and a few skills (query-writing, schema-exploration):

git clone https://github.com/langchain-ai/deepagents.git
cd deepagents/examples/text-to-sql-agent

# Download the demo database
curl -L -o chinook.db \
  https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite

The interesting bit of agent.py is the very last line:

agent.py

agent = create_sql_deep_agent()

create_deep_agent(...) returns a compiled CompiledStateGraph. Idun’s LangGraph adapter accepts both compiled graphs and raw StateGraph builders, so this Just Works — no rewrite needed.

Set up Idun

Install the engine and the standalone runtime alongside the example’s dependencies:

uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .
uv pip install idun-agent-engine idun-agent-standalone langchain-google-genai

Create .env from the template the repo ships:

cp .env.example .env

.env

# Idun standalone
IDUN_CONFIG_PATH=./config.yaml
IDUN_AGENT_CONFIG_PATH=./config.yaml
IDUN_ALLOW_OPEN_ADMIN=1
IDUN_ADMIN_AUTH_MODE=password
IDUN_ADMIN_PASSWORD_HASH=${IDUN_ADMIN_PASSWORD_HASH}    # paste the output of `idun hash-password`
IDUN_SESSION_SECRET=${IDUN_SESSION_SECRET}              # paste the output of `openssl rand -hex 32`

# LLM
GEMINI_API_KEY=${GEMINI_API_KEY}                        # export your real Gemini API key in your shell

Generate the two secrets:

idun hash-password            # prompts, prints a bcrypt hash → IDUN_ADMIN_PASSWORD_HASH
openssl rand -hex 32          # → IDUN_SESSION_SECRET

IDUN_ALLOW_OPEN_ADMIN=1 lets you reach /admin/* without an auth gate while you explore locally. Turn it off (or remove it) before exposing the service.

`idun init` — the discover flow

You don’t need to write config.yaml yourself. idun init boots the standalone server, opens your browser, and — since no agent is configured yet — routes you to the onboarding wizard.

idun init

What happens on first run:

Alembic migrations create the standalone DB.
The server starts on http://localhost:8000.
Your browser opens the discover wizard.

The wizard asks two things:

Framework — pick LangGraph. Deep Agents compile to a StateGraph, so the LangGraph adapter handles them.
Graph definition — point Idun at the compiled graph: agent.py:agent. Format is path/to/file.py:variable.

That’s the entire setup. No FastAPI route, no streaming protocol, no thread-id wiring. Click through and the engine boots with your agent attached.

Verify the wired-up agent

Once the wizard finishes you land in the admin Agent page. The connection probe confirms the engine reports your agent as text2sql_deepagent; the configuration card shows the framework (LangGraph), the agent name, and the agent.py:agent graph reference.

Agent configuration — healthy, LangGraph, agent.py:agent

Scroll down for the Agent graph card. Idun introspects the compiled graph and renders the Deep Agent’s actual node structure — the MemoryMiddleware, SkillsMiddleware, and PatchToolCallsMiddleware before_agent hooks, the model node, the TodoListMiddleware.after_model post-hook, and the tools node. This is the Deep Agents runtime, made visible.

Agent graph — Deep Agent middleware + model + tools

Chat with the Deep Agent

Open http://localhost:8000/ and ask something the agent has to plan for:

Hello, show me the schema for our users and transactions tables and find any customers who haven’t made a purchase in 6 months.

The chat collapses the agent’s planning into a Reasoning card. Expand it and you see exactly what the Deep Agent did: it loaded its skills via read_file, listed the SQL tables, fetched the Customer and Invoice schemas, sanity-checked the date, ran the query through sql_db_query_checker, and finally executed the result.

Below the reasoning card, the agent renders the final answer: a clean schema breakdown and a table of the 10 customers who haven’t bought anything in six months.

Try a few more:

“Top 5 best-selling artists?”
“Which employee generated the most revenue, broken down by country?”
“Plot revenue by genre and write a one-paragraph summary.”

The same POST /agent/run endpoint is exposed at the API level — point CopilotKit, Vercel AI SDK, or any AG-UI client at it.

Persist conversations with SQLite

By default the LangGraph checkpointer is in-memory: restart the server and every conversation is gone. The Memory page in the admin lets you swap the backend without touching code.Pick SQLite, set a file-backed URL (sqlite:///deep.db), Save. Idun reloads the checkpointer in place.

Back in the chat, every previous turn now lives in the History sidebar. New threads, named after their first message, persist across restarts.

Chat — history sidebar with past conversations

For multi-replica production deployments, swap SQLite for PostgreSQL the same way — same UI, same one-click reload.

Built-in observability

Before you wire up an external trace backend, Idun already gives you a built-in dashboard and a trace viewer powered by the same OpenTelemetry stream.The Dashboard summarizes the last 24 hours: request count, p50/p95 latency, error rate, total cost, requests-per-minute and latency time series, and top error spans.

Built-in dashboard — requests, latency, error rate, cost

The Traces page lists every run with model, tokens, cost, and status — filter by model, status, user, or session.

Traces — per-run list with tokens and cost

Click any trace to inspect the span tree. You see the same node structure as the agent graph, plus the ChatGoogleGenerativeAI calls with their token counts, and the sql_db_query tool span.

Switch to Waterfall for the time-ordered view — which span ran in parallel, which blocked, where the latency lives.

This works out of the box. Nothing to configure.

Add Langfuse on top

Already-rich built-in observability is fine for development. For long-term storage, evaluations, prompt management, and team-wide sharing, plug in Langfuse.

Sign up for Langfuse Cloud (free) and create a project. Copy the public + secret keys.
In the Idun admin, open Observability → pick Langfuse, fill in host, public key, secret key, and a run name. Toggle Enabled and Save.

Ask the agent another question. Refresh the Langfuse dashboard.

Every Deep Agent step is captured: the middleware hooks, each ChatGoogleGenerativeAI call with tokens and cost, the tool spans, the full prompt/completion pair. Langfuse also renders the graph topology — same nodes you saw inside Idun, now persisted for evaluation runs and team review.

Langfuse trace of the same Deep Agent run

Idun supports Langfuse, Arize Phoenix, LangSmith, GCP Trace, and GCP Logging side-by-side. They don’t conflict; add more on the same Observability page.

Plug in the Google Workspace MCP

Now the fun part: give the agent the ability to email its findings. We’ll use the open-source Google Workspace MCP server, which exposes Gmail, Calendar, Drive, Docs, Sheets, Slides, and Forms as MCP tools.

9a. Get a Desktop OAuth client

In Google Cloud Console:

Create or pick a project, enable the Gmail API and Google Docs API (and any other Workspace APIs you want).
APIs & Services → Credentials → Create credentials → OAuth client ID → Desktop app.
Copy the client ID and secret into .env:

.env

GOOGLE_OAUTH_CLIENT_ID=...apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-...
USER_GOOGLE_EMAIL=you@yourdomain.com
OAUTHLIB_INSECURE_TRANSPORT=1   # localhost OAuth callback

9b. Start the MCP server

Run the Google Workspace MCP locally over streamable HTTP:

uvx workspace-mcp --transport streamable-http --port 8000

The first time you connect, the server prints an OAuth URL — complete the consent flow once and the token is cached for future runs.

9c. Register the server in Idun

In the admin: MCP → pick Streamable HTTP → fill in the endpoint (http://127.0.0.1:8000/mcp), name it google-workspace, save.

MCP servers — google-workspace registered

Click the wrench (🔧) to probe the server. Idun lists every tool it discovered — send_gmail_message, create_doc, create_calendar, append_table_rows, and 116 others.

Tools — google-workspace, 120 tools discovered

9d. Wire the tools into the Deep Agent

Deep Agents bind tools at construction time, so we expose Idun’s configured MCP tools to create_deep_agent. The engine ships an async helper for this — idun_agent_engine.mcp.get_langchain_tools — that reads the MCP servers from your Idun config and returns ready-to-use LangChain tools.Because agent.py is imported at module load (inside the engine’s lifespan, where an event loop is already running), we wrap the async helper in a one-shot thread so it can be called synchronously:

agent.py

import asyncio
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from typing import Any

from idun_agent_engine.mcp import get_langchain_tools


def get_langchain_tools_sync(config_path: str | Path | None = None) -> list[Any]:
    """Run the async ``get_langchain_tools`` from sync code at module load."""
    with ThreadPoolExecutor(max_workers=1) as ex:
        return ex.submit(asyncio.run, get_langchain_tools(config_path)).result()


idun_tools = get_langchain_tools_sync()

# ... inside create_sql_deep_agent():
return create_deep_agent(
    model=model,
    memory=["./AGENTS.md"],
    skills=["./skills/"],
    tools=sql_tools + idun_tools,
    backend=FilesystemBackend(root_dir=base_dir),
)

Restart the engine (admin → Agent → Restart) and the Deep Agent now sees the 120 MCP tools alongside its SQL toolkit.

9e. Ask the agent to ship the report

Back in chat:

Find the 10 customers who haven’t bought anything in 6 months. Write up a detailed report as a Google Doc and email it to me at you@example.com.

The Deep Agent plans, runs the SQL, edits its working file with the report content, saves your address to memory via write_todos, then calls the MCP tools to create a Google Doc and send the email with the doc linked.

Chat — agent creating the doc and sending the email

Check your inbox: the agent sent a clean message with the Doc link, signed as “Deep Agent”, with the Google Doc auto-attached by Gmail.

Email delivered with Google Doc attachment

And because Langfuse is still attached, the create_doc and send_gmail_message calls show up in the trace alongside the SQL steps — full causal chain in one place.

What this gave you

Starting from an agent.py you didn’t touch, you got:

	Without Idun	With Idun
API serving	Write FastAPI yourself	`idun init`
Streaming protocol	Map `astream_events` by hand	AG-UI out of the box
Chat UI	Build a frontend	Bundled
Conversation memory	Wire up checkpointer + thread IDs	One-click backend swap
Dashboard	Hand-roll Prometheus + Grafana	Built in
Distributed tracing	Instrument OTLP manually	Built in + plug Langfuse on top
MCP tools	Write LangChain adapters	Register, discover, attach

Total engine code written: zero lines.

Next steps

Lock down access

turn off IDUN_ALLOW_OPEN_ADMIN, add SSO/OIDC, generate API keys for /agent/run.

Swap SQLite for PostgreSQL

when you go multi-replica — same Memory page, same one-click reload.

Add input guardrails

(PII, prompt injection) before exposing the chat publicly.

Deploy to Cloud Run

with the provided Dockerfile.

The Deep Agents framework gives you planning, filesystem, and subagents. Idun gives you the production wrapper. Together: an agent you can actually ship.

Get started

Guides

Standalone

Frameworks

Memory

Guardrails

Tools

Observability

Authentication

Integrations

Deploy

Reference

Advanced

Enterprise

Help

How easy it is to use Idun Engine with any Deep Agent

What you will build

Prerequisites

9a. Get a Desktop OAuth client

9b. Start the MCP server

9c. Register the server in Idun

9d. Wire the tools into the Deep Agent

9e. Ask the agent to ship the report

What this gave you

Next steps

Lock down access

Swap SQLite for PostgreSQL

Add input guardrails

Deploy to Cloud Run

​What you will build

​Prerequisites

​9a. Get a Desktop OAuth client

​9b. Start the MCP server

​9c. Register the server in Idun

​9d. Wire the tools into the Deep Agent

​9e. Ask the agent to ship the report

​What this gave you

​Next steps

Lock down access

Swap SQLite for PostgreSQL

Add input guardrails

Deploy to Cloud Run

What you will build

Prerequisites

9a. Get a Desktop OAuth client

9b. Start the MCP server

9c. Register the server in Idun

9d. Wire the tools into the Deep Agent

9e. Ask the agent to ship the report

What this gave you

Next steps