Skip to Content
DocsDeploymentThe Kastrax Client

Kastrax Client SDK ✅

The Kastrax Client SDK provides a simple and type-safe interface for interacting with your Kastrax Server from various client environments. The SDK is available for multiple platforms, including JVM (Kotlin/Java), Android, iOS, and JavaScript.

Development Requirements ✅

To ensure smooth development, make sure you have:

For JVM/Kotlin Client

  • JDK 11 or later installed (JDK 17 recommended)
  • Gradle 7.0+ or Maven 3.6+
  • Your Kastrax server running (typically on port 8080)

For Android Client

  • Android Studio Arctic Fox (2020.3.1) or later
  • Android SDK 21+ (Android 5.0 Lollipop or later)
  • Kotlin 1.6+

For JavaScript/TypeScript Client

  • Node.js 18.x or later installed
  • TypeScript 4.7+ (if using TypeScript)
  • A modern browser environment with Fetch API support

Installation ✅

// Add the Kastrax repository
repositories {
    mavenCentral()
    maven { url = uri("https://repo.kastrax.ai/repository/maven-public/") }
}
 
// Add the Kastrax client dependency
dependencies {
    implementation("ai.kastrax:kastrax-client:1.0.0")
}

Initialize Kastrax Client ✅

import ai.kastrax.client.KastraxClient
 
// Create a client with default configuration
val client = KastraxClient("http://localhost:8080")
 
// Or with custom configuration
val clientWithConfig = KastraxClient(
    baseUrl = "http://localhost:8080",
    apiKey = "your-api-key",  // Optional: for authenticated servers
    timeout = 30000,          // Connection timeout in milliseconds
    retries = 3               // Number of retry attempts
)

Configuration Options

The Kastrax Client SDK supports the following configuration options:

OptionDescriptionDefault
baseUrlThe base URL of the Kastrax serverRequired
apiKeyAPI key for authenticationnull
timeoutConnection timeout in milliseconds30000
retriesNumber of retry attempts for failed requests3
retryDelayInitial delay between retries in milliseconds300
maxRetryDelayMaximum delay between retries in milliseconds5000
headersCustom HTTP headers to include in all requests{}

Examples ✅

Once your KastraxClient is initialized, you can start making client calls via the type-safe interface.

import ai.kastrax.client.KastraxClient
import kotlinx.coroutines.runBlocking
 
fun main() = runBlocking {
    // Initialize the client
    val client = KastraxClient("http://localhost:8080")
    
    // Get a reference to your agent
    val agent = client.getAgent("assistant")
    
    // Generate a response
    val response = agent.generate("Hello, I'm testing the Kastrax client!")
    
    // Print the response
    println("Agent response: ${response.text}")
    
    // You can also use the streaming API
    agent.generateStream("Tell me a story about AI").collect { chunk ->
        print(chunk.text)
    }
}

Available Features ✅

The Kastrax Client SDK exposes all resources served by the Kastrax Server:

  • Agents: Create and manage AI agents, generate responses, and handle streaming interactions
  • Memory: Manage conversation threads and message history
  • Tools: Access and execute tools available to agents
  • Workflows: Create and manage automated workflows
  • Vectors: Handle vector operations for semantic search and similarity matching
  • Files: Upload, download, and manage files
  • Monitoring: Access logs, metrics, and traces

Agent Operations

// Get an agent by ID
val agent = client.getAgent("assistant")
 
// List all available agents
val agents = client.listAgents()
 
// Generate a response
val response = agent.generate("What is Kastrax?")
 
// Generate a response with options
val responseWithOptions = agent.generate(
    prompt = "What is Kastrax?",
    options = GenerateOptions(
        temperature = 0.7,
        maxTokens = 500,
        tools = listOf("web-search", "calculator")
    )
)
 
// Stream a response
agent.generateStream("Tell me a story").collect { chunk ->
    print(chunk.text)
}

Best Practices ✅

Error Handling

Implement proper error handling to gracefully handle API errors and network issues:

import ai.kastrax.client.KastraxClient
import ai.kastrax.client.exception.KastraxApiException
import ai.kastrax.client.exception.KastraxNetworkException
import kotlinx.coroutines.runBlocking
 
fun main() = runBlocking {
    val client = KastraxClient("http://localhost:8080")
    
    try {
        val agent = client.getAgent("assistant")
        val response = agent.generate("Test message")
        println("Response: ${response.text}")
    } catch (e: KastraxApiException) {
        // Handle API errors (e.g., invalid request, authentication issues)
        println("API Error: ${e.statusCode} - ${e.message}")
    } catch (e: KastraxNetworkException) {
        // Handle network issues (e.g., connection timeout, server unreachable)
        println("Network Error: ${e.message}")
    } catch (e: Exception) {
        // Handle other unexpected errors
        println("Unexpected Error: ${e.message}")
    }
}

Configuration Management

Use environment variables or configuration files to manage client settings:

import ai.kastrax.client.KastraxClient
 
// Load configuration from environment variables
val baseUrl = System.getenv("KASTRAX_API_URL") ?: "http://localhost:8080"
val apiKey = System.getenv("KASTRAX_API_KEY")
 
// Create client with environment-based configuration
val client = KastraxClient(
    baseUrl = baseUrl,
    apiKey = apiKey
)

Performance Optimization

  1. Reuse Client Instances: Create a single client instance and reuse it throughout your application
  2. Connection Pooling: The client automatically manages connection pooling for optimal performance
  3. Streaming for Large Responses: Use streaming for large responses to reduce memory usage
  4. Batch Operations: Use batch operations when processing multiple items
  5. Caching: Implement caching for frequently accessed data

Security Best Practices

  1. API Key Management: Store API keys securely and never hardcode them in your application
  2. HTTPS: Always use HTTPS in production environments
  3. Request Validation: Validate user input before sending it to the server
  4. Response Validation: Validate server responses before processing them
  5. Rate Limiting: Implement client-side rate limiting to avoid overwhelming the server
Last updated on
Serverless PlatformsDeploying to Kastrax Cloud