La construcción de agentes de IA está evolucionando rápidamente, y ahora Kotlin —el lenguaje moderno y tipado de JetBrains— tiene un lugar destacado en este ecosistema gracias al Agent Development Kit (ADK) de Google en su versión nativa para Kotlin.

En este tutorial construiremos un agente “Hello World” usando Kotlin y el ADK, con integración al Protocolo de Contexto de Modelo (MCP), conexión a Gemini y despliegue en Cloud Run. El proyecto completo está disponible en GitHub.

¿Qué es Kotlin y por qué usarlo para agentes de IA?

Kotlin es un lenguaje de programación moderno, tipado estáticamente, creado por JetBrains. Corre sobre la Máquina Virtual de Java (JVM), funciona junto a librerías Java existentes y se usa ampliamente para desarrollo Android, backend y multiplataforma.

El tipado estático es especialmente útil al construir agentes. La configuración del agente, los esquemas de herramientas y los resultados de las herramientas pueden ser verificados por el compilador antes de que cualquier prompt llegue al modelo. Esto reduce drásticamente los errores en producción.

Instalando Java

Este ejemplo usa Java 25. Si no tienes Java instalado, SDKMAN! es la forma más conveniente de instalar y cambiar entre versiones de JDK en Linux y macOS:

sdk list java

Instala la distribución de Java 25 que prefieras y verifica la versión activa:

java --version

El proyecto incluye el wrapper de Gradle, así que no necesitas instalar Gradle por separado.

¿Qué es el Agent Development Kit?

El Agent Development Kit (ADK) es el framework code-first de Google para construir y desplegar agentes de IA. Proporciona todo lo necesario para configurar modelos, escribir instrucciones para el agente, conectar herramientas, gestionar sesiones y ejecutar agentes localmente.

Google ofrece la guía de inicio rápido para Kotlin y la documentación de la API en adk.dev/get-started/kotlin/. El código fuente completo del ADK Kotlin también está disponible en GitHub.

El SDK de Kotlin se publica como com.google.adk:google-adk-kotlin-core. Este tutorial usa Kotlin ADK 0.6.0.

Obteniendo la API Key de Gemini

Necesitas una clave de API de Gemini Developer para ejecutar el agente interactivo. Puedes crear una en Google AI Studio. El servidor MCP y las pruebas de descubrimiento de herramientas no necesitan API key.

Verificando el entorno de desarrollo

Clona el repositorio de ejemplo y ejecuta el script de inicialización:

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

Esto construye el proyecto y crea un archivo .env local a partir de la plantilla incluida. Edita .env y coloca tu API key:

GOOGLE_API_KEY=tu-api-key

Cárgala en el shell actual:

source set_env.sh

Nota: Nunca subas .env al repositorio. Ya está incluido en .gitignore.

El agente Kotlin ADK

El ejemplo tiene dos módulos Gradle:

  • agent — contiene el agente ADK Kotlin y el runner interactivo de línea de comandos.
  • server — contiene un servidor MCP Ktor que expone la herramienta greet.

El agente principal se define en GreetingAgent.kt. Configura Gemini, le da la instrucción al agente y conecta un conjunto de herramientas MCP:

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),
)

LlmAgent reúne el modelo, las instrucciones y las herramientas disponibles. El modelo por defecto es gemini-3.1-flash-lite, pero puedes seleccionar otro con la variable de entorno GEMINI_MODEL.

Conectando el agente a MCP

A diferencia del ejemplo meteorológico en TypeScript, este proyecto mantiene la herramienta en un proceso separado. El agente descubre e invoca la herramienta a través del Model Context Protocol.

GreetingAgent.kt crea un McpToolset conectado al servidor local:

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

La conexión es perezosa (lazy). Cuando el agente necesita sus herramientas, el ADK abre una sesión MCP, solicita la lista de herramientas y pone el esquema de greet a disposición de Gemini.

El servidor registra la herramienta en Tools.kt. El agente y el servidor se comunican por HTTP usando Server-Sent Events (SSE). Por defecto, el servidor escucha en http://localhost:8080, con /sse para el stream y /messages para los mensajes del cliente.

Pruebas y estilo de código

Un solo comando construye ambos módulos, ejecuta las pruebas unitarias y verifica el formato Kotlin:

make check

Las pruebas verifican que el agente ADK contenga su conjunto de herramientas MCP y que la lógica de saludo devuelva el texto esperado. Como el formateador de saludo es una función Kotlin simple, se puede probar sin llamar a Gemini:

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

Ejecutando el ADK desde la terminal

El servidor de herramientas y el agente se ejecutan como aplicaciones separadas. Inicia el servidor MCP en una terminal:

./server.sh

En una segunda terminal, carga el entorno e inicia el agente:

source set_env.sh
./run.sh

Pídele al agente que salude a alguien:

Greet Kotlin Developer

Gemini selecciona la herramienta greet descubierta y pasa el parámetro. El servidor MCP responde con Hello, Kotlin Developer!. Escribe exit para cerrar el agente.

Probando MCP sin llamar a Gemini

Puedes verificar la conexión MCP independientemente del modelo. Con el servidor corriendo:

./gradlew :agent:smokeMcp

Esto se conecta a través de McpToolset y confirma que el agente puede descubrir greet. No requiere GOOGLE_API_KEY.

El repositorio también incluye un cliente Python JSON-RPC directo:

python3 test_mcp.py

Desplegando el servidor MCP en Cloud Run

Este proyecto despliega el servidor MCP Ktor como un contenedor. El agente ADK sigue siendo un cliente y se conecta al servicio desplegado a través de MCP_SERVER_URL.

gcloud auth login
gcloud config set project TU_PROYECTO_ID
./cloudrun.sh

El script construye la imagen Docker, la sube a Container Registry y despliega el servicio en Cloud Run.

Precaución: El ejemplo almacena sesiones SSE activas en memoria, por lo que la configuración de Cloud Run limita el servicio a una instancia. Agrega autenticación, autorización, reglas CORS más estrictas y almacenamiento de sesiones compartido antes de usar este diseño en producción.

Resumen

El Kotlin Agent Development Kit lleva el desarrollo de agentes a la JVM con las herramientas familiares de Kotlin y Gradle:

  1. Configuración tipada del agente: Configura LlmAgent, Gemini e instrucciones en Kotlin.
  2. Integración MCP: Descubre e invoca herramientas alojadas en un servicio Ktor separado.
  3. Pruebas deterministas: Prueba el comportamiento de las herramientas sin hacer solicitudes al modelo.
  4. Desarrollo local: Ejecuta el servidor y el agente interactivo directamente desde Gradle.
  5. Despliegue en la nube: Empaqueta el servidor MCP en un contenedor y despliégalo en Cloud Run.

Si trabajas con el ecosistema JVM y quieres construir agentes de IA modulares, probables y desplegables, el ADK Kotlin es una opción sólida que merece tu atención.

Sigue explorando estos temas en el blog de DojoFullStack.