Add Koog Framework Examples (#379)

# Add Koog Framework Examples to Samples

This PR introduces comprehensive examples demonstrating A2A protocol
implementation using [Koog](https://koog.ai/), JetBrains' open-source
agentic framework for building enterprise-ready AI agents, targeting JVM
backend, Android, iOS, JS, and WasmJS.

## What's Added

Two progressive examples showing different A2A communication patterns:

### 1. Simple Joke Agent (`simplejoke`)
- Basic message-based A2A communication
- Direct request-response pattern using `sendMessage()`
- Demonstrates minimal A2A server setup with AgentCard and message
storage

### 2. Advanced Joke Agent (`advancedjoke`)
- Full task-based A2A workflow implementation
- Graph-based agent architecture using Koog's `GraphAIAgent`
- Complete task lifecycle: Submitted → Working → InputRequired →
Completed
- Interactive clarifications via InputRequired state
- Streaming task events and artifact delivery
- Structured LLM outputs with type-safe parsing

## Key Features Demonstrated

- **A2A Protocol Integration**: Both simple message-based and advanced
task-based workflows
- **Graph-based Agent Design**: Maintainable, visual agent logic using
nodes and edges
- **Koog's Prompt DSL**: Type-safe prompt building with automatic
context management

## Why Koog?

Adds diversity to A2A samples by showcasing:
- JVM/Kotlin ecosystem representation
- Type-safe agent development with compile-time guarantees
- Multi-platform deployment options beyond Node.js/Python

Each example includes detailed inline documentation and runnable Gradle
tasks for immediate testing.

Author: EugeneTheDev

.editorconfig

@@ -0,0 +1,36 @@
+root = true
+
+[*.{kt,kts}]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+max_line_length = 120
+
+ij_kotlin_code_style_defaults = KOTLIN_OFFICIAL
+
+#  Disable wildcard imports entirely
+ij_kotlin_name_count_to_use_star_import = 2147483647
+ij_kotlin_name_count_to_use_star_import_for_members = 2147483647
+ij_kotlin_packages_to_use_import_on_demand = unset
+
+ktlint_code_style = ktlint_official
+ktlint_standard_annotation = disabled
+ktlint_standard_class-naming = disabled
+ktlint_standard_class-signature = disabled
+ktlint_standard_filename = disabled
+ktlint_standard_function-expression-body = disabled
+ktlint_standard_function-signature = disabled
+ktlint_standard_if-else-bracing = enabled
+ktlint_standard_if-else-wrapping = enabled
+ktlint_standard_no-consecutive-comments = disabled
+ktlint_standard_no-single-line-block-comment = disabled
+ktlint_standard_property-naming = disabled
+ktlint_standard_trailing-comma-on-call-site = disabled
+ktlint_standard_trailing-comma-on-declaration-site = disabled
+ktlint_standard_try-catch-finally-spacing = enabled
+ktlint_standard_backing-property-naming = disabled
+
+[**/build/**/*]
+ktlint = disabled

samples/java/koog/.gitignore

@@ -0,0 +1,3 @@
+/.gradle
+/build
+/.kotlin

samples/java/koog/README.md

@@ -0,0 +1,114 @@
+# Agent-to-Agent (A2A) with Koog Framework Examples
+
+This project demonstrates how to build A2A-enabled agents using [Koog](https://github.com/JetBrains/koog), the official JetBrains' framework for building predictable,
+fault-tolerant, and enterprise-ready AI agents, targeting JVM backend, Android, iOS, JS, and WasmJS.
+
+## What is Koog?
+
+Koog is JetBrains' open-source agentic framework that empowers developers to build AI agents using Kotlin. It provides:
+
+- **Graph-based agent architecture**: Define agent behavior as a graph of nodes and edges with type-safe inputs and outputs,
+  making complex workflows easier to understand and maintain
+- **Multi-platform support**: Deploy agents across JVM, Android, native iOS, JS, and WasmJS using Kotlin Multiplatform
+- **Fault tolerance**: Built-in retry mechanisms and agent state persistence for reliable execution, allowing to recover
+  crashed agents even on another machine.
+- **Prompt DSL**: Clean, type-safe DSL for building LLM prompts and automatically managing conversation context
+- **Enterprise integrations**: Works seamlessly with Spring Boot, Ktor, and other JVM frameworks
+- **Advanced Observability**: Built-in integrations with enterprise observability tools like Langfuse and W&B Weave via OpenTelemetry
+- **A2A protocol support**: Built-in support for Agent-to-Agent communication via the A2A protocol
+
+Learn more at [koog.ai](https://koog.ai/)
+
+## Prerequisites
+
+- JDK 17 or higher
+- Set `GOOGLE_API_KEY` environment variable (or configure other LLM providers in the code)
+
+## Examples
+
+### Simple Joke Agent: [simplejoke](./src/main/kotlin/ai/koog/example/simplejoke)
+
+A basic example demonstrating message-based A2A communication without task workflows.
+
+**What it demonstrates:**
+- Creating an `AgentExecutor` that wraps LLM calls using Koog's prompt DSL
+- Setting up an A2A server with an `AgentCard` that describes agent capabilities
+- Managing conversation context with message storage
+- Simple request-response pattern using `sendMessage()`
+
+**Run:**
+```bash
+# Terminal 1: Start server (port 9998)
+./gradlew runExampleSimpleJokeServer
+
+# Terminal 2: Run client
+./gradlew runExampleSimpleJokeClient
+```
+
+### Advanced Joke Agent: [advancedjoke](./src/main/kotlin/ai/koog/example/advancedjoke)
+
+A sophisticated example showcasing task-based A2A workflows using Koog's graph-based agent architecture.
+
+**What it demonstrates:**
+- **Graph-based agent design**: Uses Koog's `GraphAIAgent` with nodes and edges to create a maintainable workflow
+- **Task lifecycle management**: Full A2A task states (Submitted → Working → InputRequired → Completed)
+- **Interactive clarification**: Agent can request additional information using the InputRequired state
+- **Structured LLM outputs**: Uses sealed interfaces with `nodeLLMRequestStructured` for type-safe agent decisions
+- **Artifact delivery**: Returns final results as A2A artifacts
+- **Streaming events**: Sends real-time task updates via `sendTaskEvent()`
+
+**Run:**
+```bash
+# Terminal 1: Start server (port 9999)
+./gradlew runExampleAdvancedJokeServer
+
+# Terminal 2: Run client
+./gradlew runExampleAdvancedJokeClient
+```
+
+## Key Patterns & Koog Concepts
+
+### A2A Communication Patterns
+
+**Simple Agent:** `sendMessage()` → single response
+**Advanced Agent:** `sendMessageStreaming()` → Flow of events (Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent)
+
+**Task States:** Submitted → Working → InputRequired (optional) → Completed
+
+### Koog Framework Concepts Used
+
+**AgentExecutor**: The entry point for A2A requests. Receives the request context and event processor for sending responses.
+
+**GraphAIAgent**: Koog's graph-based agent implementation. Define your agent logic as nodes (processing steps) connected by edges (transitions).
+
+**Prompt DSL**: Type-safe Kotlin DSL for building prompts:
+```kotlin
+prompt("joke-generation") {
+    system { +"You are a helpful assistant" }
+    user { +"Tell me a joke" }
+}
+```
+
+**MultiLLMPromptExecutor**: Unified interface for executing prompts across different LLM providers (OpenAI, Anthropic, Google, etc.).
+
+**nodeLLMRequestStructured**: Creates a graph node that calls the LLM and parses the response into a structured Kotlin data class using the `@LLMDescription` annotation.
+
+**A2AAgentServer plugin**: Koog plugin that integrates A2A functionality into your GraphAIAgent, providing access to message storage, task storage, and event processors.
+
+### Getting Started with Koog
+
+To build your own A2A agent with Koog:
+
+1. **Add Koog dependencies** (see [build.gradle.kts](./build.gradle.kts))
+2. **Create an AgentExecutor** to handle incoming A2A requests
+3. **Define an AgentCard** describing your agent's capabilities
+4. **Set up the A2A server** with HTTP transport
+5. **For simple agents**: Use prompt executor directly with message storage
+6. **For complex agents**: Use GraphAIAgent with the A2AAgentServer plugin
+
+See the code comments in `JokeWriterAgentExecutor.kt` for detailed implementation guidance.
+
+## Learn More
+
+- [Koog GitHub Repository](https://github.com/JetBrains/koog)
+- [Koog Documentation](https://koog.ai/)

samples/java/koog/build.gradle.kts

@@ -0,0 +1,43 @@
+plugins {
+    alias(libs.plugins.kotlin.jvm)
+    alias(libs.plugins.kotlin.serialization)
+    alias(libs.plugins.ktlint)
+}
+
+dependencies {
+    implementation(platform(libs.kotlin.bom))
+    implementation(platform(libs.kotlinx.coroutines.bom))
+
+    implementation(libs.koog.agents)
+    implementation(libs.koog.agents.features.a2a.server)
+    implementation(libs.koog.agents.features.a2a.client)
+    implementation(libs.koog.a2a.transport.server.jsonrpc.http)
+    implementation(libs.koog.a2a.transport.client.jsonrpc.http)
+
+    implementation(libs.kotlinx.datetime)
+    implementation(libs.kotlinx.coroutines.core)
+
+    implementation(libs.ktor.server.cio)
+
+    runtimeOnly(libs.logback.classic)
+}
+
+fun registerRunExampleTask(
+    name: String,
+    mainClassName: String,
+) = tasks.register<JavaExec>(name) {
+    doFirst {
+        standardInput = System.`in`
+        standardOutput = System.out
+    }
+
+    mainClass.set(mainClassName)
+    classpath = sourceSets["main"].runtimeClasspath
+}
+// Simple joke generation
+registerRunExampleTask("runExampleSimpleJokeServer", "ai.koog.example.simplejoke.ServerKt")
+registerRunExampleTask("runExampleSimpleJokeClient", "ai.koog.example.simplejoke.ClientKt")
+
+// Advanced joke generation
+registerRunExampleTask("runExampleAdvancedJokeServer", "ai.koog.example.advancedjoke.ServerKt")
+registerRunExampleTask("runExampleAdvancedJokeClient", "ai.koog.example.advancedjoke.ClientKt")

samples/java/koog/gradle.properties

@@ -0,0 +1,7 @@
+#Kotlin
+kotlin.code.style=official
+
+#Gradle
+org.gradle.jvmargs=-Dfile.encoding=UTF-8
+org.gradle.parallel=true
+org.gradle.caching=true

samples/java/koog/gradle/libs.versions.toml

@@ -0,0 +1,29 @@
+[versions]
+kotlin = "2.2.20"
+kotlinx-coroutines = "1.10.2"
+kotlinx-datetime = "0.6.2"
+kotlinx-serialization = "1.8.1"
+ktor3 = "3.2.2"
+koog = "0.5.0"
+logback = "1.5.13"
+oshai-logging = "7.0.7"
+ktlint = "13.1.0"
+
+[libraries]
+kotlin-bom = { module = "org.jetbrains.kotlin:kotlin-bom", version.ref = "kotlin" }
+kotlinx-coroutines-bom = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-bom" }
+kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core" }
+kotlinx-datetime = { module = "org.jetbrains.kotlinx:kotlinx-datetime", version.ref = "kotlinx-datetime" }
+ktor-server-cio = { module = "io.ktor:ktor-server-cio", version.ref = "ktor3" }
+koog-agents = { module = "ai.koog:koog-agents", version.ref = "koog" }
+koog-agents-features-a2a-server = { module = "ai.koog:agents-features-a2a-server", version.ref = "koog" }
+koog-agents-features-a2a-client = { module = "ai.koog:agents-features-a2a-client", version.ref = "koog" }
+koog-a2a-transport-server-jsonrpc-http = { module = "ai.koog:a2a-transport-server-jsonrpc-http", version.ref = "koog" }
+koog-a2a-transport-client-jsonrpc-http = { module = "ai.koog:a2a-transport-client-jsonrpc-http", version.ref = "koog" }
+logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
+oshai-kotlin-logging = { module = "io.github.oshai:kotlin-logging", version.ref = "oshai-logging" }
+
+[plugins]
+kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+ktlint = { id = "org.jlleitschuh.gradle.ktlint", version.ref = "ktlint" }

samples/java/koog/gradle/wrapper/gradle-wrapper.jar

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists