Build Resilient Agentic AI Applications

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

android {
    defaultConfig {
        val properties = java.util.Properties()
        val localPropertiesFile = rootProject.file("local.properties")
        if (localPropertiesFile.exists()) {
            properties.load(localPropertiesFile.inputStream())
        }
        buildConfigField("String", "OLLAMA_API_KEY", "\"${properties.getProperty("OLLAMA_API_KEY", "")}\"")
        buildConfigField("String", "GEMINI_API_KEY", "\"${properties.getProperty("GEMINI_API_KEY", "")}\"")
    }
    buildFeatures {
        buildConfig = true
    }
}

val aivo = AivoSdk.create(
    provider = AivoProvider.OLLAMA,
    model    = OllamaModel.GPT_OSS_120B.modelId,
    apiKey   = BuildConfig.OLLAMA_API_KEY
)

// One-shot completion
val response = aivo.chat("Explain coroutines in 2 sentences")
println(response.text)

// Token-by-token streaming Flow
aivo.stream("Explain state machines")
    .collect { event ->
        if (event is AgentEvent.Delta) print(event.text)
    }

val aivo = AivoSdk {
    providers {
        ollama("private-cluster") {
            // Optional: specify custom internal URL
            baseUrl("https://internal-llm.company.com/api/chat")
            apiKey(BuildConfig.CUSTOM_LLM_KEY)
        }
    }
    // Pass custom fine-tuned model name as string
    defaultModel("custom-llama3-fine-tuned:latest")
}

val getWeatherTool = tool("get_weather", "Fetches live weather conditions for a given city") {
    // 1. Declare JSON schema parameter constraints
    parameters {
        string("city", "The city name", required = true, minLength = 2)
        string("unit", "Temperature unit", required = false, enum = listOf("celsius", "fahrenheit"))
        boolean("forecast", "Include 3-day forecast", required = false)
    }

    // 2. Execute business logic with type-safe extractors
    execute { args ->
        val city = args.string("city")
        val unit = args.stringOrNull("unit") ?: "celsius"
        val isForecast = args.booleanOrNull("forecast") ?: false
        
        // Call your real backend or network service
        """{"city": "$city", "temp": 24, "unit": "$unit", "condition": "Sunny"}"""
    }
}

val transferFundsTool = tool("transfer_funds", "Transfers funds between bank accounts") {
    riskLevel = RiskLevel.HIGH
    requireConfirmation = true  // Runtime pauses and emits RequiresConfirmation event

    parameters {
        string("fromAccount", "Debiting account", required = true)
        string("toAccount", "Crediting account", required = true)
        double("amount", "Transfer amount in USD", required = true, minimum = 1.0)
    }

    execute { args ->
        val from = args.string("fromAccount")
        val to = args.string("toAccount")
        val amount = args.double("amount")
        bankApi.transfer(from, to, amount)
        "Successfully transferred $$amount from $from to $to"
    }
}

// When user taps "Approve" in Compose Dialog:
runtime.confirm(toolCallId = event.toolCallId, approved = true)

// Or if user rejects:
runtime.confirm(toolCallId = event.toolCallId, approved = false, reason = "User cancelled transfer")

val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) { apiKey(BuildConfig.OLLAMA_API_KEY) }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)

    // 1. Register available tools
    tools {
        +getWeatherTool
        +transferFundsTool
    }

    // 2. Define the Agent and assign scoped tools
    agents {
        define("concierge") {
            name = "Personal Concierge"
            systemPrompt = """
                You are a helpful mobile concierge.
                Customer Name: {{user_name}}
                Always check weather before suggesting outdoor activities.
            """.trimIndent()
            
            // Give specific tools to this agent
            tools("get_weather")
            
            // Set maximum execution turns to prevent infinite loops
            maxSteps = 10
        }
    }
    entryAgent("concierge")
}

// 3. Execute with dynamic prompt variables
val response = aivo.chat(
    message   = "What should I wear today in Cairo?",
    variables = mapOf("user_name" to "Abdallah")
)
println(response.text)

---
name: Support Specialist
role: assistant
provider: ollama
model: gpt-oss-120b
tools: [order_status, refund_tool]
maxSteps: 8
---
You are a tier-1 customer support agent.
Current customer: {{user_name}}.
Always verify the order ID before processing any refund. Be courteous and concise.

val agentDef = AgentLoader.fromMarkdown(markdownFileContent)
val runtime = AgentRuntime.create(agentDef) {
    apiKey(BuildConfig.OLLAMA_API_KEY)
}

// 1. Define strongly-typed shared keys for inter-agent communication
object TeamKeys {
    val ResearchFindings = StateKey.string("research_findings")
    val DraftSummary = StateKey.string("draft_summary")
}

// 2. Build the Multi-Agent Team
val marketReportTeam = team("MarketAnalysisTeam") {
    
    // Supervisor coordinates the workflow
    supervisor {
        name = "Lead Coordinator"
        systemPrompt = "Analyze the user prompt. First delegate research to 'researcher'. Then delegate reporting to 'writer'."
        model(AivoProvider.OLLAMA, OllamaModel.GPT_OSS_120B.modelId)
    }

    // Specialist 1: Researcher (has web search tool)
    agent("researcher") {
        name = "Market Researcher"
        systemPrompt = "Extract key verified industry statistics and write notes into the blackboard."
        tools("web_search")
        model(AivoProvider.OLLAMA, OllamaModel.GPT_OSS_120B.modelId)
    }

    // Specialist 2: Writer (synthesizes findings)
    agent("writer") {
        name = "Executive Writer"
        systemPrompt = "Read research findings and format a bulleted executive briefing."
        model(AivoProvider.OLLAMA, OllamaModel.GPT_OSS_120B.modelId)
    }
}

// 3. Execute the collaborative workflow
val finalBriefing = marketReportTeam.execute("Analyze renewable energy battery storage growth in 2026")
println(finalBriefing.text)

data class MessageUi(val sender: String, val text: String, val isToolExecuting: Boolean = false)

class ChatViewModel(private val aivo: AivoSdk) : ViewModel() {
    private val _messages = MutableStateFlow>(emptyList())
    val messages: StateFlow> = _messages.asStateFlow()

    // Confirmation gate state for UI Dialog
    var pendingConfirmation by mutableStateOf(null)
        private set

    fun sendMessage(prompt: String) {
        _messages.update { it + MessageUi(sender = "User", text = prompt) }
        _messages.update { it + MessageUi(sender = "Assistant", text = "") }

        viewModelScope.launch {
            aivo.stream(prompt).collect { event ->
                when (event) {
                    is AgentEvent.Delta -> {
                        _messages.update { list ->
                            val last = list.last()
                            list.dropLast(1) + last.copy(text = last.text + event.text)
                        }
                    }
                    is AgentEvent.ToolStarted -> {
                        _messages.update { list ->
                            val last = list.last()
                            list.dropLast(1) + last.copy(isToolExecuting = true)
                        }
                    }
                    is AgentEvent.ToolCompleted -> {
                        _messages.update { list ->
                            val last = list.last()
                            list.dropLast(1) + last.copy(isToolExecuting = false)
                        }
                    }
                    is AgentEvent.RequiresConfirmation -> {
                        pendingConfirmation = event // Triggers Compose alert dialog
                    }
                    is AgentEvent.Completed -> { /* Stream finished */ }
                    is AgentEvent.Error -> { /* Handle error */ }
                    else -> Unit
                }
            }
        }
    }

    fun handleConfirmation(approved: Boolean) {
        val event = pendingConfirmation ?: return
        aivo.confirm(event.toolCallId, approved)
        pendingConfirmation = null
    }
}

@Composable
fun ChatScreen(viewModel: ChatViewModel = viewModel()) {
    val messages by viewModel.messages.collectAsState()
    var input by remember { mutableStateOf("") }

    // Human Confirmation Dialog Gate
    viewModel.pendingConfirmation?.let { conf ->
        AlertDialog(
            onDismissRequest = { viewModel.handleConfirmation(false) },
            title = { Text("Approve Action: ${conf.toolName}") },
            text = { Text("Parameters: ${conf.arguments}") },
            confirmButton = {
                Button(onClick = { viewModel.handleConfirmation(true) }) { Text("Approve") }
            },
            dismissButton = {
                OutlinedButton(onClick = { viewModel.handleConfirmation(false) }) { Text("Reject") }
            }
        )
    }

    Column(modifier = Modifier.fillMaxSize().padding(16.dp)) {
        LazyColumn(modifier = Modifier.weight(1f)) {
            items(messages) { msg ->
                ChatBubble(msg)
            }
        }
        Row(modifier = Modifier.fillMaxWidth()) {
            TextField(
                value = input,
                onValueChange = { input = it },
                modifier = Modifier.weight(1f),
                placeholder = { Text("Ask Aivo...") }
            )
            Button(onClick = { 
                viewModel.sendMessage(input)
                input = "" 
            }) { Text("Send") }
        }
    }
}

val aivo = AivoSdk {
    // ...
    memory {
        // Option A: In-memory sliding window
        slidingWindow(maxMessages = 20)
        
        // Option B: Token budget with character heuristic
        tokenBudget(maxTokens = 8_000, estimator = CharCountEstimator)
    }
}

@Test
fun testViewModelStreamsDeltas() = runTest {
    // Mock provider with deterministic streaming chunks
    val fakeLlm = FakeLlmProvider().apply {
        enqueueStreaming("Hello", " from", " Aivo!")
    }

    val viewModel = ChatViewModel(aivo = AivoSdk.createWithProvider(fakeLlm))
    viewModel.sendMessage("Hi")

    assertEquals("Hello from Aivo!", viewModel.messages.value.last().text)
}

// Type-safe roles and blackboard keys
val analyst = AgentRole.ANALYST
val ReviewNotesKey = StateKey.string("review_notes")

// Sequential pipeline loop: Research -> Review -> Finalize
val pipeline = SequenceLoop(
    agents = listOf(researcherAgent, reviewerAgent, writerAgent),
    state = BlackboardState()
)

val pipelineResult = pipeline.run("Analyze Q3 Financials")
println(pipelineResult.finalOutput)

package com.example.aivo

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.aivo.sdk.AivoSdk
import com.aivo.sdk.AivoProvider
import com.aivo.sdk.core.model.*
import com.aivo.sdk.provider.ollama.OllamaModel
import com.aivo.sdk.runtime.tool.tool
import com.aivo.sdk.runtime.agent.team
import kotlinx.coroutines.flow.*
import kotlinx.coroutines.launch

// 1. Define High-Risk Mutation Tool with Confirmation Gate
val bookFlightTool = tool("book_flight", "Books a verified airline ticket") {
    riskLevel = RiskLevel.HIGH
    requireConfirmation = true

    parameters {
        string("destination", "3-letter airport code", required = true)
        string("date", "Departure date YYYY-MM-DD", required = true)
        double("maxPrice", "Maximum ticket price in USD", required = true)
    }

    execute { args ->
        val dest = args.string("destination")
        val date = args.string("date")
        val price = args.double("maxPrice")
        """{"status": "CONFIRMED", "ticket": "TK-9821", "dest": "$dest", "cost": $$price}"""
    }
}

// 2. Define Multi-Agent Travel Team
val travelTeam = team("TravelTeam") {
    supervisor {
        name = "Travel Concierge"
        systemPrompt = "Deconstruct travel requests. Delegate flight booking to 'booking_agent'."
        model(AivoProvider.OLLAMA, OllamaModel.GPT_OSS_120B.modelId)
    }

    agent("booking_agent") {
        name = "Flight Booking Specialist"
        systemPrompt = "Find flight availability and book tickets using 'book_flight'."
        tools("book_flight")
        model(AivoProvider.OLLAMA, OllamaModel.GPT_OSS_120B.modelId)
        maxSteps = 6
    }
}

// 3. Configure Aivo SDK with Cloud Provider and Sliding Window Memory
val aivo = AivoSdk {
    providers {
        ollama(AivoProvider.OLLAMA.id) {
            apiKey(BuildConfig.OLLAMA_API_KEY)
        }
    }
    defaultModel(OllamaModel.GPT_OSS_120B)
    
    tools {
        +bookFlightTool
    }

    memory {
        slidingWindow(maxMessages = 20)
    }
}

// 4. Reactive Jetpack Compose ViewModel
class TravelViewModel : ViewModel() {
    private val _messages = MutableStateFlow<List<String>>(emptyList())
    val messages: StateFlow<List<String>> = _messages.asStateFlow()

    private val _pendingGate = MutableStateFlow<AgentEvent.RequiresConfirmation?>(null)
    val pendingGate: StateFlow<AgentEvent.RequiresConfirmation?> = _pendingGate.asStateFlow()

    fun bookTrip(prompt: String) {
        viewModelScope.launch {
            aivo.stream(prompt).collect { event ->
                when (event) {
                    is AgentEvent.Delta -> {
                        _messages.update { it + event.text }
                    }
                    is AgentEvent.RequiresConfirmation -> {
                        // Triggers Biometric / Dialog Confirmation in Compose UI
                        _pendingGate.value = event
                    }
                    is AgentEvent.Completed -> {
                        println("Workflow finished! Usage: \${event.usage.totalTokens} tokens")
                    }
                    is AgentEvent.Error -> {
                        println("Workflow error: \${event.error.message}")
                    }
                    else -> Unit
                }
            }
        }
    }

    fun approveAction(approved: Boolean) {
        val event = _pendingGate.value ?: return
        aivo.confirm(event.toolCallId, approved)
        _pendingGate.value = null
    }
}

# 1. Clone the official KMP demo repository
git clone https://github.com/Abdallah-Elsobky/Test-Aivo-SDK.git
cd Test-Aivo-SDK

# 2. Run Android App
./gradlew :composeApp:installDebug

# 3. Run Desktop App
./gradlew :composeApp:run

# Install official Aivo SDK skills into your project
npx skills-cli add abdallah-elsobky/aivo-sdk

You are an expert Android AI engineer specializing in the Aivo SDK (io.github.abdallah-elsobky:aivo-sdk:1.0.1).
Aivo SDK is a provider-agnostic, Kotlin Multiplatform AI agent framework supporting Ollama, Google Gemini, OpenRouter, and any OpenAI-compatible endpoint.
Key architectural principles:
1. Strict Hexagonal Architecture: ViewModel and UseCases interact with domain interfaces and AivoSdk. Never leak provider-specific or network types into UI layers.
2. Security: Never hardcode API keys. Use local.properties -> BuildConfig -> SecretString.
3. Streaming: Responses stream via Kotlin Flow<AgentEvent> (TextDelta, ReasoningDelta, ToolCallStarted, ToolCallExecuted, StepStarted, StepCompleted, RunCompleted, RunFailed).
4. Tool Calling: Tools are defined via tool("name", "desc") { ... } DSL with typed params, risk levels (LOW, MEDIUM, HIGH), and optional ConfirmationHandler for human-in-the-loop approval.
5. Multi-Agent: Supports supervisor delegation, SingleTurnLoop, ToolCallingLoop (ReAct), SequenceLoop, RouterLoop, and ParallelLoop.
6. Memory: In-memory or custom MemoryStore (e.g. Room Database), with keepAll(), slidingWindow(N), or tokenBudget(tokens).
7. Resilience & Errors: Built-in exponential backoff retry with jitter, timeouts, and exhaustive SdkException hierarchy.
8. Testing: Use FakeLlmProvider.scripted(...) and InMemoryTelemetry from sdk-testing (1.0.1) for offline deterministic tests.
Write clean, idiomatic Kotlin using Jetpack Compose, StateFlow, Coroutines, and MVVM/Clean Architecture.

You are an expert Kotlin Multiplatform (KMP) AI architect specializing in the Aivo SDK (io.github.abdallah-elsobky:aivo-sdk:1.0.1).
Aivo SDK is a unified, provider-agnostic, Kotlin Multiplatform AI agent framework supporting Ollama, Google Gemini, OpenRouter, and any OpenAI-compatible endpoint across Android, JVM, and iOS from a single codebase.
Core Multiplatform Invariants:
1. Version Catalog Bundle: Define the 'aivo-sdk' bundle in 'gradle/libs.versions.toml' and declare 'implementation(libs.bundles.aivo.sdk)' in commonMain. This ensures complete klib symbol resolution across Android, iOS, and JVM.
2. Hexagonal Clean Architecture: All LLM orchestration, agent definitions, memory strategies, and repository interfaces live in commonMain. Never leak provider or network types into UI layers.
3. Platform Security: Never hardcode API keys. Inject them via expect/actual or DI (Android BuildConfig, iOS Info.plist/ProcessInfo, JVM System.getenv) and wrap in SecretString.
4. Compose Multiplatform (CMP): Write chat UI once in commonMain using Material 3, observing StateFlow<ChatUiState> and collecting Flow<AgentEvent>.
5. iOS Swift Interoperability: For native SwiftUI apps, use the built-in iOS interop shim (AivoSdkKt.create, FlowAdapter, CancellableJob) to bridge Kotlin Flow to Swift closures.
6. Custom Tools: Implement multiplatform tools in commonMain, delegating platform-specific actions via expect/actual or interface injection.
7. Memory & Resilience: Use KeepAllMemoryStore, SlidingWindowMemoryStore, TokenBudgetMemoryStore, or custom SQLDelight/Room KMP MemoryStore. Configure exponential backoff with jitter.
8. Testing: Run fast, deterministic unit tests in commonTest using FakeLlmProvider.scripted(...) and InMemoryTelemetry from 'io.github.abdallah-elsobky:sdk-testing:1.0.1'.
Write clean, idiomatic Kotlin Multiplatform code with Coroutines, Flow, and MVI/MVVM architecture.