This project demonstrates the use of Koog to create an AI agent with access to external tools. It's built on top of Ktor and provides an SSE endpoint for interacting with the agent.
The agent can access:
- Weather data via the Open-Meteo API
- Google Maps functionality via MCP Gateway
This project uses the following technologies:
| Name | Description |
|---|---|
| Koog | Kotlin framework for building AI agents with tool use capabilities |
| Ktor | Kotlin web framework for building asynchronous servers and clients |
| OpenAI API | Used for the LLM that powers the agent (GPT-4o Mini) |
| Ollama | Alternative LLM provider for local model execution |
| Open-Meteo API | Free weather API used by the weather tool |
| MCP (Model Context Protocol) | Protocol for tool integration, used for Google Maps tools |
| TestContainers | Used to run Docker containers for the MCP Gateway |
Before running the application, you need:
- Set up environment variables in .env or in the terminal (see .env.template)
- Install docker (for the MCP Gateway container)
- Run
docker-compose upto start the database, mcp server, langfuse - Open langfuse in http://localhost:3000/ and sign up, then create a new project and add credentials to .env
To build or run the project, use one of the following tasks:
| Task | Description |
|---|---|
./gradlew test |
Run the tests |
./gradlew build |
Build everything |
./gradlew run |
Run the server |
./gradlew buildFatJar |
Build an executable JAR of the server with all dependencies included |
If the server starts successfully, you'll see output similar to:
INFO Application - Application started in 0.303 seconds.
INFO Application - Responding at http://0.0.0.0:8080
Once the server is running, you can interact with the AI agent by sending a GET request to:
http://localhost:8080/plan?question=YOUR_QUESTION_HERE
Or by using IntelliJ's http client ask-agent-a-question-request.http.
The response will be sent as Server-Sent Events (SSE) that include:
- Tool calls made by the agent
- Results from those tool calls
- The final answer from the agent
The main components of the project are:
| File | Description |
|---|---|
Application.kt |
Main application entry point that sets up the Ktor server, configures the LLM clients, and registers the tools |
Agent.kt |
Defines the AI agent configuration and event handling |
WeatherTool.kt |
Implements the weather tool that fetches data from the Open-Meteo API |
McpUtils.kt |
Utility functions for working with the MCP Gateway for Google Maps tools |