DEV Community

Cover image for Building AI Agents with the Kotlin Agent Development Kit (ADK)
Google Developer Experts profile image xbill
xbill for Google Developer Experts

Posted on

Building AI Agents with the Kotlin Agent Development Kit (ADK)

#kotlin #ai #gemini #webdev

This tutorial builds a starter "Hello World" style agent using Kotlin and the native Kotlin version of the Agent Development Kit (ADK).

The full sample project is available on GitHub:

GitHub logo xbill9 / adk-hello-world-kotlin

Kotlin ADK and MCP Hello World

This project is a runnable Kotlin Agent Development Kit (ADK) demo. A Kotlin LlmAgent uses Gemini to decide when to call a greet tool discovered from a local Kotlin Model Context Protocol (MCP) server.

The project has two Gradle modules:

  • agent: the Kotlin ADK agent, Gemini model configuration, MCP toolset, and interactive ReplRunner;
  • server: the Ktor MCP server that exposes greet.

Technology Stack

  • Kotlin: 2.3.0
  • Kotlin ADK SDK: com.google.adk:google-adk-kotlin-core (v0.6.0)
  • MCP Kotlin SDK: io.modelcontextprotocol:kotlin-sdk-jvm (v0.8.1)
  • Ktor Framework: 3.0.0 (Netty, SSE, ContentNegotiation, CORS)
  • JDK: Java 25
  • Build System: Gradle 9.2.1 (Kotlin DSL)

Prerequisites

  • Java 25
  • A Gemini Developer API key

The Gradle wrapper is included.

Configure Gemini

Create the local environment file:

cp .env.example .env
Enter fullscreen mode Exit fullscreen mode

Set GOOGLE_API_KEY in .env, then load it:

source ./set_env.sh
Enter fullscreen mode Exit fullscreen mode

The file is ignored by Git.

Run the Demo

Start the Kotlin MCP server in one…

View on GitHub

What Is Kotlin?

Kotlin is a modern, statically typed programming language created by JetBrains. It runs on the Java Virtual Machine (JVM), works alongside existing Java libraries, and is widely used for Android, backend, and multiplatform development.

Static typing is especially useful when building agents. Agent configuration, tool schemas, and tool results can all be checked by the compiler before a prompt reaches the model.

Installing Java

This sample uses Java 25. If Java is not installed, SDKMAN! is a convenient way to install and switch between JDK versions on Linux and macOS:

Home | SDKMAN! the Software Development Kit Manager

SDKMAN! is a tool for managing parallel versions of multiple Software Development Kits on most Unix based systems.

favicon sdkman.io

After installing SDKMAN!, list the available Java 25 distributions:

sdk list java
Enter fullscreen mode Exit fullscreen mode

Install the Java 25 distribution you prefer, then verify the active version:

java --version
Enter fullscreen mode Exit fullscreen mode

The project includes the Gradle wrapper, so you do not need to install Gradle separately.

What Is the Agent Development Kit?

The Agent Development Kit (ADK) is Google's code-first framework for building and deploying AI agents. It provides the pieces needed to configure models, write agent instructions, connect tools, manage sessions, and run agents locally.

Google provides the Kotlin quickstart and API documentation here:

Kotlin - Agent Development Kit (ADK)Agent Development Kit (ADK)

Build powerful multi-agent systems with Agent Development Kit (ADK)

favicon adk.dev

The complete Kotlin ADK source is also available on GitHub:

GitHub logo google / adk-kotlin

Agent Development Kit (ADK) for Kotlin

License Maven Central r/agentdevelopmentkit Ask DeepWiki

An open-source, code-first Kotlin toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.

Important Links: Docs & Samples & Python ADK & Java ADK.

Agent Development Kit (ADK) is designed for developers seeking fine-grained control and flexibility when building advanced AI agents that are tightly integrated with services in Google Cloud. It allows you to define agent behavior, orchestration, and tool use directly in code, enabling robust debugging, versioning, and deployment anywhere – from your laptop to the cloud.

✨ Key Features

  • Rich Tool Ecosystem: Utilize pre-built tools, custom functions, OpenAPI specs, or integrate existing tools to give agents diverse capabilities, all for tight integration with the Google ecosystem.

  • Code-First Development: Define agent logic, tools, and orchestration directly in Kotlin for ultimate flexibility, testability, and versioning.

  • Modular Multi-Agent Systems: Design scalable applications by composing multiple specialized…

View on GitHub

The Kotlin SDK is published as com.google.adk:google-adk-kotlin-core. This tutorial uses Kotlin ADK 0.6.0.

Gemini API Key

You need a Gemini Developer API key to run the interactive agent. Create one in Google AI Studio:

https://aistudio.google.com/apikey

The MCP server and tool-discovery smoke test do not need an API key.

Checking the Developer Environment

Clone the sample repository and run the initialization script. It builds the project and creates a local .env file from the included template:

git clone https://github.com/xbill9/adk-hello-world-kotlin
cd adk-hello-world-kotlin
source init.sh
Enter fullscreen mode Exit fullscreen mode

Output:

Created .env from .env.example. Add your credentials before running the agent.
Setup complete. Start ./server.sh, then run ./run.sh in another terminal.
Enter fullscreen mode Exit fullscreen mode

Edit .env and set your API key:

GOOGLE_API_KEY=your-api-key
Enter fullscreen mode Exit fullscreen mode

Load it into the current shell:

source set_env.sh
Enter fullscreen mode Exit fullscreen mode

Note: Never commit .env. It is already listed in .gitignore.

The Kotlin ADK Agent

The sample has two Gradle modules:

  • agent contains the Kotlin ADK agent and interactive command-line runner.
  • server contains a Ktor MCP server that exposes the greet tool.

The core agent is defined in GreetingAgent.kt. It configures Gemini, gives the agent its instruction, and connects an MCP toolset:

return LlmAgent(
    name = "kotlin_greeting_agent",
    description = "A Kotlin ADK agent that greets people through an MCP tool.",
    model =
        Gemini(
            name = modelName,
            apiKey = apiKey,
        ),
    instruction =
        Instruction(
            """
            You are a concise greeting assistant.
            When the user asks you to greet someone, always call the greet tool with that
            person's name. Return the greeting produced by the tool.
            """.trimIndent(),
        ),
    toolsets = listOf(mcpToolset),
)
Enter fullscreen mode Exit fullscreen mode

LlmAgent brings together the model, instructions, and available tools. The model defaults to gemini-3.1-flash-lite, but you can select another model with the GEMINI_MODEL environment variable.

Connecting the Agent to MCP

Unlike the TypeScript weather sample, this project keeps the tool in a separate process. The agent discovers and invokes it through the Model Context Protocol.

GreetingAgent.kt creates an McpToolset connected to the local server:

val mcpToolset =
    McpToolset.McpToolsetConfig(
        sseConnectionParams =
            McpConnectionParameters.Sse(
                url = mcpServerUrl,
                sseEndpoint = "sse",
            ),
        toolFilter = listOf("greet"),
    ).toToolset()
Enter fullscreen mode Exit fullscreen mode

The connection is lazy. When the agent needs its tools, ADK opens an MCP session, requests the tool list, and makes the greet schema available to Gemini. The tool filter limits this agent to that single tool.

The server registers the tool in Tools.kt:

server.addTool(
    name = Config.Tools.GREET,
    description = "Get a greeting from a local HTTP server.",
    inputSchema =
        ToolSchema(
            properties =
                buildJsonObject {
                    put(
                        Config.Tools.GREET_PARAM,
                        buildJsonObject {
                            put("type", "string")
                            put("description", "The name to greet")
                        },
                    )
                },
            required = listOf(Config.Tools.GREET_PARAM),
        ),
) { request ->
    // Read the name and return: Hello, <name>!
}
Enter fullscreen mode Exit fullscreen mode

The agent and server communicate over HTTP using Server-Sent Events (SSE). By default, the server listens at http://localhost:8080, with /sse for the stream and /messages for client messages.

Build, Tests, and Code Style

A single command builds both modules, runs the unit tests, and checks Kotlin formatting:

make check
Enter fullscreen mode Exit fullscreen mode

You can call the Gradle tasks directly:

./gradlew build ktlintCheck test
Enter fullscreen mode Exit fullscreen mode

The tests check that the ADK agent contains its MCP toolset and that the greeting logic returns the expected text. Because the greeting formatter is a plain Kotlin function, it can be tested without calling Gemini:

@Test
fun testFormatGreeting() {
    val result = Tools.formatGreeting("Kotlin Developer")
    assertEquals("Hello, Kotlin Developer!", result)
}
Enter fullscreen mode Exit fullscreen mode

Run make format if ktlintCheck reports a style issue.

Running the ADK from the CLI

The tool server and agent run as separate applications. Start the MCP server in one terminal:

./server.sh
Enter fullscreen mode Exit fullscreen mode

In a second terminal, load the environment and start the agent:

source set_env.sh
./run.sh
Enter fullscreen mode Exit fullscreen mode

The Gradle commands provide the same entry points:

./gradlew :server:run
./gradlew :agent:run
Enter fullscreen mode Exit fullscreen mode

Ask the agent to greet someone:

Greet Kotlin Developer
Enter fullscreen mode Exit fullscreen mode

Gemini selects the discovered greet tool and supplies:

{"param":"Kotlin Developer"}
Enter fullscreen mode Exit fullscreen mode

The MCP server returns:

Hello, Kotlin Developer!
Enter fullscreen mode Exit fullscreen mode

Type exit to close the agent.

Testing MCP Without Calling Gemini

You can verify the MCP connection independently of the model. With the server running, use the Kotlin ADK smoke test:

./gradlew :agent:smokeMcp
Enter fullscreen mode Exit fullscreen mode

This connects through McpToolset and confirms that the agent can discover greet. It does not require GOOGLE_API_KEY.

The repository also includes a direct Python JSON-RPC client:

python3 test_mcp.py
Enter fullscreen mode Exit fullscreen mode

It initializes an MCP session, lists the available tools, calls greet with Galaxy, and verifies the response Hello, Galaxy!.

Deploying the MCP Server to Cloud Run

This project deploys the Ktor MCP server as a container. The ADK agent remains a client and connects to the deployed service through MCP_SERVER_URL.

Set your Google Cloud project, then run the deployment script:

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
./cloudrun.sh
Enter fullscreen mode Exit fullscreen mode

The script submits cloudbuild.yaml, which builds the Docker image, pushes it to Container Registry, and deploys the service to Cloud Run.

The sample stores active SSE sessions in memory, so the supplied Cloud Run configuration limits the service to one instance. It also allows unauthenticated access for demonstration purposes. Add authentication, authorization, stricter CORS rules, and shared session storage before using this design in production.

Check Google Cloud Console

After deployment, retrieve the service URL:

gcloud run services describe adk-hello-world-kotlin \
  --region us-central1 --format 'value(status.url)'
Enter fullscreen mode Exit fullscreen mode

Point the local agent at that URL:

export MCP_SERVER_URL="https://your-service-url"
./run.sh
Enter fullscreen mode Exit fullscreen mode

Summary

The Kotlin Agent Development Kit brings agent development to the JVM with familiar Kotlin and Gradle tooling:

  1. Typed Agent Configuration: Configure LlmAgent, Gemini, and instructions in Kotlin.
  2. MCP Tool Integration: Discover and invoke tools hosted by a separate Ktor service.
  3. Deterministic Testing: Test tool behavior without making model requests.
  4. Local Development: Run the server and interactive agent directly from Gradle.
  5. Cloud Deployment: Package the MCP server in a container and deploy it to Cloud Run.

Top comments (0)