diff --git a/docs/runtime/api-server.md b/docs/runtime/api-server.md index 2bc7ca57a4..cb42c54792 100644 --- a/docs/runtime/api-server.md +++ b/docs/runtime/api-server.md @@ -1,7 +1,7 @@ # Use the API Server
- Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0 + Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0Kotlin v0.1.0
Before you deploy your agent, you should test it to ensure that it is working as @@ -94,6 +94,46 @@ Use the following command to run your agent in an ADK API server: In Java, both the Dev UI and the API server are bundled together. +=== "Kotlin" + + In Kotlin there is no standalone `adk` CLI. Construct an `AdkApiServer` in + your own `main`: + + ```kotlin title="ApiMain.kt" + import com.google.adk.kt.webserver.AdkApiServer + import com.google.adk.kt.webserver.AdkServerConfig + + fun main() = + AdkApiServer(AdkServerConfig.inMemory(rootAgent)).start(wait = true) + ``` + + `AdkServerConfig.inMemory()` supplies a single-agent loader with in-memory + session and artifact services; build `AdkServerConfig` directly to serve + several agents or to persist state. + + Then run that class like any other JVM entry point. With the Gradle + `application` plugin, point `mainClass` at it — a top-level `main` in + `ApiMain.kt` compiles to `ApiMainKt`, not `ApiMain`: + + ```kotlin title="build.gradle.kts" + application { + mainClass.set("com.example.agent.ApiMainKt") + } + ``` + + ```console + gradle run + ``` + + See the [Kotlin quickstart](../get-started/kotlin.md) for full project + setup, including how to select between several entry points. + + !!! note "Kotlin defaults to port 8080 and loopback" + + Adjust the `curl` examples below accordingly, or set `port` on + `AdkServerConfig`. The server binds `127.0.0.1`, so a container must + set `host` too, or nothing outside it can connect. + This command will launch a local web server, where you can run cURL commands or send API requests to test your agent. By default, the server runs on `http://localhost:8000`. @@ -179,6 +219,20 @@ The output should appear similar to: 2025-05-13T23:32:08.981-06:00 INFO 37864 --- [ebServer.main()] com.google.adk.web.AdkWebServer : AdkWebServer application started successfully. ``` +=== "Kotlin" + + ```shell + 12:07:20.157 [main] INFO com.google.adk.kt.webserver.AdkApiServer -- AdkApiServer starting on 127.0.0.1:8080 + 12:07:20.343 [main] INFO ktor.application -- Application started in 0.257 seconds. + 12:07:20.596 [DefaultDispatcher-worker-1] INFO ktor.application -- Responding at http://127.0.0.1:8080 + ``` + + !!! note "Kotlin: default port" + + The Kotlin API server defaults to port **8080** (not 8000), so adjust + the example `curl` commands below. Unlike Go it adds no path prefix, so + the paths themselves are unchanged: `http://localhost:8080/list-apps`. + Your server is now running locally. Ensure you use the correct **_port number_** in all the subsequent commands. **Create a new session** diff --git a/docs/runtime/command-line.md b/docs/runtime/command-line.md index 06fea48136..53744fb890 100644 --- a/docs/runtime/command-line.md +++ b/docs/runtime/command-line.md @@ -1,7 +1,7 @@ # Use the Command Line
- Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0 + Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0Kotlin v0.1.0
ADK provides an interactive terminal interface for testing your agents. This is @@ -63,6 +63,26 @@ Use the following command to run your agent in the ADK command line interface: mvn compile exec:java -Dexec.mainClass="com.example.agent.AgentCliRunner" ``` +=== "Kotlin" + + In Kotlin there is no standalone `adk` CLI. `ReplRunner` provides the + interactive loop; call it from your own `main`: + + ```kotlin title="Main.kt" + import com.google.adk.kt.runners.ReplRunner + + fun main() = ReplRunner(rootAgent).start() + ``` + + Then run that class with the Gradle `application` plugin, pointing + `mainClass` at it — a top-level `main` in `Main.kt` compiles to `MainKt`: + + ```console + gradle run + ``` + + See the [Kotlin quickstart](../get-started/kotlin.md) for full project setup. + This starts an interactive session where you can type queries and see agent responses directly in your terminal. @@ -105,6 +125,21 @@ responses directly in your terminal. [user]: exit ``` +=== "Kotlin" + + ```shell + Agent my_agent is ready. Type 'exit' to quit. + + You > What's the weather in New York? + + my_agent > The weather in New York is sunny with a temperature of 25°C. + + You > exit + Exiting agent. + ``` + + `quit` also exits, as does an empty line. + ## Session options !!! note "Python only" diff --git a/docs/runtime/web-interface/index.md b/docs/runtime/web-interface/index.md index 35052b32a8..112d17060d 100644 --- a/docs/runtime/web-interface/index.md +++ b/docs/runtime/web-interface/index.md @@ -1,7 +1,7 @@ # Use the Web Interface
- Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0 + Supported in ADKPython v0.1.0TypeScript v0.2.0Go v0.1.0Java v0.1.0Kotlin v0.1.0
The ADK web interface lets you test your agents directly in the browser. This @@ -112,6 +112,29 @@ Use the following command to start the ADK web interface: In Java, the web interface and the API server are bundled together. +=== "Kotlin" + + In Kotlin there is no standalone `adk` CLI. Construct an `AdkDevServer` in + your own `main` — it serves the web interface plus the REST API behind it: + + ```kotlin title="WebMain.kt" + import com.google.adk.kt.webserver.AdkServerConfig + import com.google.adk.kt.webserver.dev.AdkDevServer + + fun main() = + AdkDevServer(AdkServerConfig.inMemory(rootAgent)).start(wait = true) + ``` + + Then run that class with the Gradle `application` plugin, pointing + `mainClass` at it — a top-level `main` in `WebMain.kt` compiles to + `WebMainKt`: + + ```console + gradle run + ``` + + Use `AdkApiServer` instead to serve the REST API without the web interface. + Once started, the server prints the access URL to the console. Open it in your browser to use the web interface: @@ -153,6 +176,20 @@ browser to use the web interface: | For local testing, access at http://localhost:8000. | +-----------------------------------------------------------------------------+ ``` + +=== "Kotlin" + + ```shell + [main] INFO com.google.adk.kt.webserver.AdkApiServer - AdkDevServer starting on 127.0.0.1:8080 + [main] INFO ktor.application - Autoreload is disabled because the development mode is off. + [main] INFO com.google.adk.kt.webserver.routes.StaticRoutesKt - Serving embedded static browser assets as fallback. + [main] INFO ktor.application - Application started in 0.191 seconds. + [DefaultDispatcher-worker-1] INFO ktor.application - Responding at http://127.0.0.1:8080 + ``` + + The interface is served at `/dev-ui`, and `/` redirects there. Note the + default port is **8080**, not 8000. + ## Common options === "Python" @@ -241,6 +278,38 @@ browser to use the web interface: go run agent.go web -port 9090 api -path_prefix /myapi webui -api_server_address http://localhost:9090/myapi ``` +=== "Kotlin" + + There is no CLI, so these are properties on `AdkServerConfig` rather than + flags. It is a data class, so `copy()` overrides one without restating the + rest. + + | Property | Description | Default | + |----------|-------------|---------| + | `port` | Port to run the server on | `8080` | + | `host` | Host binding address | `127.0.0.1` | + | `sessionService` | Session storage | required | + | `artifactService` | Artifact storage | required | + | `agentLoader` | Which agents to serve | required | + | `webUiEnabled` | Mount the web interface | server default | + | `captureMessageContent` | Record prompts and responses into trace spans | `false` | + + ```kotlin + AdkDevServer( + AdkServerConfig.inMemory(rootAgent).copy(port = 9090, host = "0.0.0.0"), + ).start(wait = true) + ``` + + `AdkServerConfig.inMemory()` fills the three required properties with a + single-agent loader and in-memory services. `webUiEnabled` defaults to on + for `AdkDevServer` and off for `AdkApiServer`; the `adk.web.ui.enabled` + system property overrides it either way. + + !!! warning "captureMessageContent records prompt and response text" + + It exists so the trace view can display message content, which means + potential PII in your spans. Leave it off outside local development. + ## Usage telemetry The ADK Web UI collects anonymous usage telemetry to understand feature adoption, discover usability issues, and improve your overall developer experience. Data collection is OFF by default until you explicitly choose to enable it.