Skip to main content

Kotlin SDK

The AG-UI Kotlin SDK is a Kotlin Multiplatform library for building AI agent user interfaces that implement the Agent User Interaction Protocol (AG-UI). It provides real-time streaming communication between Kotlin applications and AI agents across Android, iOS, and JVM platforms. Note: This SDK is community contributed and maintained. Please reach out to mefinsf in the AG-UI Discord with any questions.

Installation

Add the SDK to your Gradle project:
The client module automatically includes both kotlin-core and kotlin-tools as dependencies, giving you access to the complete SDK functionality. For advanced use cases where you only need specific modules:

Architecture

The SDK follows a modular architecture with three main components:

kotlin-client

High-level agent implementations and client infrastructure.
  • AgUiAgent: Stateless client for cases where no ongoing context is needed or the agent manages all state server-side
  • StatefulAgUiAgent: Stateful client that maintains conversation history and sends it with each request
  • HttpAgent: Low-level HTTP transport implementation
  • AbstractAgent: Base class for custom agent implementations
Learn more about the Client module →

kotlin-core

Protocol types, events, and message definitions.
  • Events: All AG-UI protocol event types and serialization
  • Types: Protocol message types and state management
  • Serialization: JSON handling with kotlinx.serialization
Learn more about the Core module →

kotlin-tools

Tool execution framework for extending agent capabilities.
  • ToolExecutor: Interface for implementing custom tools
  • ToolRegistry: Tool registration and management
  • ToolExecutionManager: Tool execution with circuit breaker patterns
Learn more about the Tools module →

Supported Platforms

Quick Start

Basic Agent Interaction

Conversational Agent

Chunked protocol events (TEXT_MESSAGE_CHUNK, TOOL_CALL_CHUNK) are automatically rewritten into their corresponding start/content/end sequences, so Kotlin clients see the same structured events as non-chunked streams. Thinking telemetry (THINKING_* events) is surfaced alongside normal messages, allowing UIs to indicate when an agent is reasoning internally before responding.

Client-Side Tool Integration

Note: Tools registered with the SDK execute on the client device, not on the agent’s server. This enables secure access to local device capabilities (location, camera, file system) while maintaining privacy and reducing server load.

Authentication

The SDK supports multiple authentication methods:

Error Handling

State Management