ADK Agents with Idun¶

This guide shows how to connect an ADK (Agent Development Kit) agent to the Idun Agent Platform and run it as a managed, observable service.

It continues from the Quickstart and assumes that:

The platform is running via docker compose -f docker-compose.dev.yml up --build.
You can access the Manager UI at http://localhost:3000.
You are familiar with the basic ADK Python quickstart.

1. Create an Agent configuration in Idun¶

Open your browser at http://localhost:3000 and press Login (no credentials needed for local dev).
Click "Create an agent".

Create agent

Fill in the basic info:
Name: My first agent
Base URL: http://localhost:8008 (where your ADK agent will be reachable)
Server Port: 8008 (local development port)
Agent framework: select ADK (Agent Development Kit by Google)
Click Next.
Fill in the framework-specific settings:
Name: My first agent
Agent Definition Path: my_agent/agent.py:root_agent (adjust to match your ADK project layout and entrypoint; for an existing project, point to your current root agent function)
App Name: firstagent (required by ADK)
For session service and observability, keep the default values for now. By default, agent memory is set to AdkInMemory.
Click Next.
For now, skip MCP Server and Guardrails; these are covered in their own guides.
Click Create Agent.

Create agent

Congratulations

Your ADK agent configuration is created in the Idun Agent Manager.

Get agent api key

You will use this key to let your ADK agent fetch its configuration from the Idun Agent Manager.

Now that the Idun Agent Platform is ready, you can connect either an existing ADK project or create a new one.

If you already have an ADK agent project: Keep your current project structure. Make sure the Agent Definition Path you configured in Idun points to your existing root agent function. Then follow Step 3 (configure Idun access) and Step 4 (run the agent) below from within your existing project.
If you don’t have an ADK agent yet: Follow Step 1 and Step 2 below to create a new ADK project, then continue with Step 3 and Step 4 to connect it to Idun.

mkdir demo-adk-idun-agent
cd demo-adk-idun-agent

Tip

If you are using Vertex AI models:

Authenticate your gcloud account:
```
gcloud auth application-default login
```
Use gemini-2.5-flash unless you have enabled Gemini 3 preview and are using the correct region:
```
gemini-2.5-flash
```
When running adk web, use a different port than Idun (which uses 8000 internally):
```
adk web --port 8010
```
ADK does not support folder paths that contain spaces.

Install the Idun Agent Engine package in your ADK project (existing or new):

pip install idun-agent-engine

Create an .env file for your agent and add the following variables (adjust host if your Manager is not on localhost):

IDUN_MANAGER_HOST=http://localhost:8000
IDUN_AGENT_API_KEY=<PASTE_THE_AGENT_KEY_FROM_STEP_2>

Make sure you create this .env file inside your ADK project folder and that any helper scripts you use load it from the correct path.

Export the environment variables from your .env file in your terminal:

set -o allexport
source ./my_agent/.env
set +o allexport

Then start the Idun Agent Engine in managed mode so it pulls configuration from the Manager:

idun agent serve --source manager

Congratulations

Your ADK agent is now running behind the Idun Agent Engine and managed by the Idun Agent Platform.

Try a simple question like:

What time is it in Paris ?

Chat with agent

Congratulations

You’ve successfully connected an ADK agent to Idun.

From here you can enrich your ADK agent with more platform capabilities: