Skip to content

Commit 08dffbb

Browse files
contextablemarkcontextablemark
committed
Updated README.md
1 parent 8940ad2 commit 08dffbb

1 file changed

Lines changed: 154 additions & 137 deletions

File tree

‎README.md‎

Lines changed: 154 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,191 +1,208 @@
1-
# ag-ui-4k - AG-UI Protocol Client for Kotlin Multiplatform
2-
3-
A Kotlin Multiplatform (KMP) client library for connecting to AI agents that implement the Agent User Interaction Protocol (AG-UI).
1+
AG-UI-4K_README.md
2+
# AG-UI-4K - Agent User Interaction Protocol Client for Kotlin
43

54
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
65
[![Kotlin](https://img.shields.io/badge/kotlin-2.1.21-blue.svg?logo=kotlin)](http://kotlinlang.org)
6+
[![Platform](https://img.shields.io/badge/platform-Android%20%7C%20iOS%20%7C%20JVM-lightgrey)](https://kotlinlang.org/docs/multiplatform.html)
7+
[![API](https://img.shields.io/badge/API-26%2B-brightgreen.svg?style=flat)](https://android-arsenal.com/api?level=26)
78

8-
## Overview
9+
A production-ready Kotlin Multiplatform client library for connecting applications to AI agents that implement the [Agent User Interaction Protocol (AG-UI)](https://docs.ag-ui.com/).
910

10-
ag-ui-4k is a multiplatform **client library** that enables applications to connect to and communicate with AI agents using the AG-UI protocol. This library provides a type-safe, coroutine-based API for real-time, event-driven interactions with AI services.
11+
## 🎯 Why AG-UI-4K?
1112

12-
**Important**: ag-ui-4k is a client-side library for connecting TO agents, not for implementing agents themselves. See [OVERVIEW.md](OVERVIEW.md) for more details.
13+
AG-UI-4K enables seamless integration with AI agents across all major platforms through a unified, type-safe API.
1314

14-
Built with the latest Kotlin technology stack including the K2 compiler, Ktor 3, and kotlinx.serialization 1.8, ag-ui-4k delivers exceptional performance and developer experience across all supported platforms.
15+
- **True Multiplatform**: Write once, run everywhere with platform-specific optimizations
16+
- **Modern Kotlin**: Leveraging coroutines, flows, and the latest K2 compiler for exceptional performance
1517

16-
### Features
18+
## ✨ Features
1719

18-
- 🚀 **Multiplatform Support**: Connect to AG-UI agents from Android, iOS, JVM, and more
19-
- 🔄 **Real-time Streaming**: Event-driven architecture with Kotlin Flows for receiving agent responses
20-
- 🛡️ **Type Safety**: Fully typed events and messages from the AG-UI protocol
21-
- ⚡ **Coroutine-based**: Built on Kotlin Coroutines for efficient async operations
22-
- 🔧 **Extensible**: Easy to create custom client implementations
23-
- 📦 **Lightweight**: Minimal dependencies, powered by Ktor
24-
- 🎯 **K2 Compiler**: Optimized with Kotlin 2.1.21's K2 compiler for better performance
25-
- 🆕 **Latest Stack**: Built with Ktor 3.1.3 and kotlinx.serialization 1.8.1
20+
### Core Capabilities
21+
- 🔄 **Real-time Streaming**: Event-driven architecture with Kotlin Flows for live agent responses
22+
- 🛡️ **Type Safety**: Fully typed protocol implementation with compile-time guarantees
23+
- ⚡ **High Performance**: Optimized with K2 compiler and efficient state management
24+
- 🔧 **Extensible Tools**: Comprehensive framework for extending agent capabilities
25+
- 📊 **State Management**: Automatic synchronization with JSON Patch support
26+
- 🔒 **Secure**: Built-in authentication options (Bearer, API Key, Basic Auth)
2627

27-
## Requirements
28+
### Technical Excellence
29+
- 📦 **Modular Architecture**: Clean separation between core, client, tools, and SDK layers
30+
- 🎯 **Latest Tech Stack**: Kotlin 2.1.21, Ktor 3.x, kotlinx.serialization 1.8.x
31+
- 🧪 **Well Tested**: Unit tests and Android-specific platform tests
32+
- 📝 **Fully Documented**: Extensive KDocs, example Chat App
2833

29-
- Kotlin 2.1.21 or higher
30-
- Java 11 or higher
31-
- Gradle 8.5 or higher
32-
- Android API 21+ (for Android targets)
33-
- iOS 13+ (for iOS targets)
34+
## 🚀 Quick Start
3435

35-
## Installation
36+
### Installation
3637

37-
### Gradle (Kotlin DSL)
38+
Add the SDK to your project:
3839

3940
```kotlin
41+
// For high-level agent interactions
4042
dependencies {
41-
implementation("com.contextable:ag-ui-4k:0.1.0")
43+
implementation("com.contextable:agui4k-agent-sdk:0.2.1")
4244
}
43-
```
44-
45-
### Maven
4645

47-
```xml
48-
<dependency>
49-
<groupId>com.contextable</groupId>
50-
<artifactId>ag-ui-4k</artifactId>
51-
<version>0.1.0</version>
52-
</dependency>
46+
// For direct protocol access (advanced users)
47+
dependencies {
48+
implementation("com.contextable:agui4k-client:0.2.1")
49+
implementation("com.contextable:agui4k-core:0.2.1")
50+
}
5351
```
5452

55-
## Quick Start
53+
### Basic Usage
5654

5755
```kotlin
58-
import com.contextable.agui4k.client.HttpAgent
59-
import com.contextable.agui4k.core.types.*
56+
import com.contextable.agui4k.sdk.*
6057
import kotlinx.coroutines.flow.collect
61-
import kotlinx.coroutines.launch
62-
63-
// Create an HTTP client to connect to an AG-UI agent
64-
val client = HttpAgent {
65-
url = "https://your-agent-endpoint.com/agent"
66-
headers = mapOf(
67-
"Authorization" to "Bearer your-api-key"
68-
)
58+
59+
// Create a stateless agent
60+
val agent = AgUi4KAgent("https://your-agent-api.com/agent") {
61+
bearerToken = "your-api-token"
62+
systemPrompt = "You are a helpful AI assistant"
6963
}
7064

71-
// Send a message to the agent
72-
client.addMessage(
73-
UserMessage(
74-
id = "1",
75-
content = "Hello, how can you help me today?"
76-
)
77-
)
78-
79-
// Connect to the agent and handle responses
80-
scope.launch {
81-
client.runAgent {
82-
tools = listOf(
83-
Tool(
84-
name = "confirmAction",
85-
description = "Ask user to confirm an action",
86-
parameters = mapOf(
87-
"type" to "object",
88-
"properties" to mapOf(
89-
"action" to mapOf(
90-
"type" to "string",
91-
"description" to "The action to confirm"
92-
)
93-
),
94-
"required" to listOf("action")
95-
)
96-
)
97-
)
98-
}.collect { event ->
99-
when (event) {
100-
is TextMessageContentEvent -> {
101-
// Handle streaming text from the agent
102-
println("Agent: ${event.delta}")
103-
}
104-
is ToolCallStartEvent -> {
105-
// Agent is requesting to use a tool
106-
println("Tool call: ${event.toolCallName}")
107-
}
108-
is StateSnapshotEvent -> {
109-
// Agent state has been updated
110-
println("State updated: ${event.snapshot}")
111-
}
112-
// Handle other events...
113-
}
65+
// Send a message and receive streaming responses
66+
agent.sendMessage("What's the weather like?").collect { state ->
67+
println("State updated: $state")
68+
}
69+
```
70+
71+
### Conversational Agent
72+
73+
```kotlin
74+
// Create a stateful agent that maintains conversation history
75+
val chatAgent = StatefulAgUi4KAgent("https://your-agent-api.com/agent") {
76+
bearerToken = "your-api-token"
77+
systemPrompt = "You are a friendly conversational AI"
78+
initialState = buildJsonObject {
79+
put("userName", "Alice")
80+
put("preferences", buildJsonObject {
81+
put("language", "en")
82+
})
11483
}
11584
}
85+
86+
// Have a conversation
87+
chatAgent.chat("Hello!").collect { /* ... */ }
88+
chatAgent.chat("What's my name?").collect { state ->
89+
// Agent remembers the conversation context
90+
}
11691
```
11792

118-
## Project Structure
93+
### Tool Integration
11994

120-
The project is organized with the main library code and build infrastructure in the `library` directory:
95+
```kotlin
96+
// Create an agent with tools
97+
val agent = agentWithTools(
98+
url = "https://your-agent-api.com/agent",
99+
toolRegistry = toolRegistry {
100+
addTool(WeatherToolExecutor())
101+
addTool(CalculatorToolExecutor())
102+
addTool(ConfirmationToolExecutor(uiHandler))
103+
}
104+
) {
105+
bearerToken = "your-api-token"
106+
}
121107

122-
- `/library` - Main library module with all source code and build files
123-
- `/docs` - Documentation and guides
124-
- `/examples` - Example applications (coming soon)
125-
- `/.github` - GitHub Actions CI/CD configuration
108+
// Agent can now use tools during conversation
109+
agent.sendMessage("What's 15% tip on $85.50?").collect { state ->
110+
// Agent will use calculator tool automatically
111+
}
112+
```
126113

127-
All development work happens in the `library` directory. See the [library README](library/README.md) for detailed build instructions.
114+
## 📐 Architecture
128115

129-
## Architecture
116+
AG-UI-4K follows a clean, modular architecture:
130117

131-
The library follows a clean architecture with clear separation of concerns:
118+
```
119+
┌─────────────────────────────────────────────────────────────┐
120+
│ Your Application │
121+
├─────────────────────────────────────────────────────────────┤
122+
│ agui4k-agent-sdk │
123+
│ ┌─────────────┐ ┌───────────────────┐ ┌──────────────┐ │
124+
│ │ AgUi4KAgent │ │StatefulAgUi4KAgent│ │ Builders │ │
125+
│ └─────────────┘ └───────────────────┘ └──────────────┘ │
126+
├─────────────────────────────────────────────────────────────┤
127+
│ agui4k-client │ agui4k-tools │
128+
│ ┌────────────┐ ┌─────────────┐ │ ┌──────────────────────┐ │
129+
│ │ HttpAgent │ │AbstractAgent│ │ │ ToolRegistry │ │
130+
│ ├────────────┤ ├─────────────┤ │ ├──────────────────────┤ │
131+
│ │EventVerifier│ │DefaultApply │ │ │ ToolExecutor │ │
132+
│ │ SseParser │ │ Events │ │ │ToolExecutionManager │ │
133+
│ └────────────┘ └─────────────┘ │ └──────────────────────┘ │
134+
├─────────────────────────────────────────────────────────────┤
135+
│ agui4k-core │
136+
│ Protocol Types & Event Definitions │
137+
└─────────────────────────────────────────────────────────────┘
138+
```
132139

133-
- **Core Module**: Protocol definitions, event types, and base client abstractions
134-
- **Client Module**: Concrete client implementations (HttpAgent) for connecting to agents
135-
- **Platform Modules**: Platform-specific optimizations and integrations
140+
### Module Overview
136141

137-
### Key Components
142+
- **agui4k-core**: Protocol definitions, event types, and message structures
143+
- **agui4k-client**: Low-level client infrastructure and transport implementations
144+
- **agui4k-tools**: Tool execution framework and built-in tool executors
145+
- **agui4k-agent-sdk**: High-level APIs for common agent interaction patterns
138146

139-
1. **AbstractAgent**: Base class for client implementations
140-
2. **HttpAgent**: HTTP-based client using Server-Sent Events (SSE) to connect to AG-UI agents
141-
3. **Event System**: Strongly typed events for receiving agent responses
142-
4. **State Management**: Efficient state synchronization with snapshots and deltas from the agent
147+
## 🎯 Supported Platforms
143148

144-
## Supported Platforms
149+
| Platform | Status | Minimum Version | Notes |
150+
|----------|--------|-----------------|-------|
151+
| Android | ✅ Stable | API 26+ | Full feature support |
152+
| iOS | ✅ Stable | iOS 13+ | Native performance (not tested beyond unit tests) |
153+
| JVM | ✅ Stable | Java 11+ | Desktop |
145154

146-
- ✅ Android (API 21+)
147-
- ✅ iOS (iOS 13+)
148-
- ✅ JVM (Java 11+)
149-
- 🚧 JS (Browser) - Coming soon
150-
- 🚧 Native (Linux, macOS, Windows) - Coming soon
155+
## 📚 Documentation
151156

152-
## Documentation
157+
### Essential Guides
153158

154-
For detailed documentation, please visit our [Wiki](https://github.com/contextable/agui4k/wiki).
159+
- [API Reference](https://contextable.github.io/ag-ui-4k/) - Complete API documentation
155160

156-
### Important Documents
161+
### Example Applications
162+
- [Chat Application](examples/chatapp) - Basic chat client
163+
- [Tool Examples](examples/tools) - Custom tool implementations
157164

158-
- [OVERVIEW](OVERVIEW.md) - Understanding what AGUI4K is (and isn't)
159-
- [CHANGELOG](CHANGELOG.md) - Version history and release notes
160-
- [CONTRIBUTING](CONTRIBUTING.md) - How to contribute to the project
161-
- [PERFORMANCE](PERFORMANCE.md) - Performance optimization guide
165+
### Development Setup
162166

163-
### Examples
167+
1. **Clone the repository**
168+
```bash
169+
git clone https://github.com/contextable/ag-ui-4k.git
170+
cd ag-ui-4k
171+
```
164172

165-
Check out the [examples](examples/) directory for:
166-
- Android sample app
167-
- iOS sample app
168-
- Multiplatform chat application
173+
2. **Build the project**
174+
```bash
175+
cd library
176+
./gradlew build
177+
```
169178

170-
## Contributing
179+
3. **Run tests**
180+
```bash
181+
./gradlew test
182+
```
171183

172-
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
184+
4. **Generate documentation**
185+
```bash
186+
./gradlew dokkaHtml
187+
```
173188

174-
### Development Setup
189+
## 🔄 Version Compatibility
175190

176-
1. Clone the repository
177-
2. Open in IntelliJ IDEA or Android Studio (open the `library` directory as the project)
178-
3. Build using one of these methods:
179-
- **From library directory**: `cd library && ./gradlew build`
180-
- **Using helper script**: `./build.sh build` (Unix) or `build.bat build` (Windows)
181-
4. Run tests: `./build.sh test` or `cd library && ./gradlew test`
191+
| AG-UI-4K | Kotlin | Ktor | AG-UI Protocol |
192+
|----------|--------|------|----------------|
193+
| 0.2.x | 2.1.21+ | 3.1.x | 1.0 |
182194

183-
## License
195+
## 📄 License
184196

185197
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
186198

187-
## Acknowledgments
199+
## 🙏 Acknowledgments
200+
201+
- Built on the [AG-UI Protocol](https://github.com/ag-ui-protocol/ag-ui) specification
202+
- Powered by [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html)
203+
- Networking by [Ktor](https://ktor.io/)
204+
- Serialization with [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization)
205+
206+
## 📬 Support
188207

189-
- Inspired by the [AG-UI Protocol](https://github.com/ag-ui/protocol)
190-
- Built with [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html)
191-
- Powered by [Ktor](https://ktor.io/) for networking
208+
- **Issues**: [GitHub Issues](https://github.com/contextable/ag-ui-4k/issues)

0 commit comments

Comments
 (0)