From 9f08fb2cca5cf961b100151b6ae2dcc652754eb2 Mon Sep 17 00:00:00 2001 From: Mike Grabowski Date: Sat, 24 Oct 2026 22:49:01 +0400 Subject: [PATCH 1/4] docs(adk): align readme and guides with apple and ai sdk 7 - trim the readme to the apple shape and link to the docs site - fix the ml kit feature status table (1 is downloadable, 3 is available) - state that cloud gemini needs an explicit modelName - use ai sdk 7 apis: sync streamText, flat usage fields, Output.json, stopWhen - explain that tools only run when registered via availableTools - drop duplicated examples and the untyped updateTools section Co-Authored-By: Claude Opus 5.5 --- packages/adk/README.md | 202 +++++------------------------------------ 1 file changed, 21 insertions(+), 181 deletions(-) diff --git a/packages/adk/README.md b/packages/adk/README.md index ac720cbd4..6653ed9a1 100644 --- a/packages/adk/README.md +++ b/packages/adk/README.md @@ -1,206 +1,46 @@ # ADK Provider for Vercel AI SDK -A Vercel AI SDK provider for [Google's Agent Development Kit (ADK)](https://developer.android.com/ai/adk) on Android. Use on-device Gemini Nano or cloud Gemini with tool calling and multi-turn sessions. +A Vercel AI SDK provider for [Google's Agent Development Kit (ADK)](https://developer.android.com/ai/adk), enabling on-device Gemini Nano and cloud Gemini in React Native applications on Android. **Requirements:** -- Android `minSdkVersion` 26 or greater (required by ML Kit GenAI / Gemini Nano; set in your app, not only in this package) -- React Native New Architecture +- Android only, with `minSdkVersion` 26+ set in your app +- A device that supports Gemini Nano through AICore for on-device inference (see [ML Kit GenAI device support](https://developers.google.com/ml-kit/genai#feature-device)) +- A Google AI API key for cloud Gemini - Vercel AI SDK v7 -- If using on-device models: a device capable of running Gemini Nano (Android 14+ with AICore); you can consult the [ML Kit GenAI documentation](https://developers.google.com/ml-kit/genai#feature-device) for more details. - -Consuming apps must set `minSdkVersion` to at least 26. ADK pulls in Google GenAI libraries that duplicate `META-INF/INDEX.LIST`; exclude it in your app packaging. For Expo: - -```json -[ - "expo-build-properties", - { - "android": { - "minSdkVersion": 26, - "packagingOptions": { - "exclude": ["META-INF/INDEX.LIST", "META-INF/DEPENDENCIES"] - } - } - } -] -``` - -For bare React Native, add to `android/app/build.gradle`: - -```gradle -android { - packagingOptions { - excludes += ["META-INF/INDEX.LIST", "META-INF/DEPENDENCIES"] - } -} -``` +- React Native New Architecture -Then run `npx expo prebuild --clean` so the native Android project picks up the change. +Your app also has to exclude duplicate `META-INF` files from Android packaging. See [Getting Started](https://react-native-ai.com/docs/adk/getting-started) for the Expo and bare React Native setup. ```ts import { adk } from '@react-native-ai/adk' import { generateText } from 'ai' -const { text } = await generateText({ - model: adk(), - prompt: 'What time is it in New York?', -}) -``` - -## Features - -- Cloud Gemini model via ADK `LlmAgent` and `InMemoryRunner` -- On-device Gemini Nano via ML Kit GenAI (`genai-nano` model type) -- Tool calling bridged to JavaScript executors -- Streaming responses with tool-call stream parts -- Post-generation token usage via ADK `UsageMetadata` -- Multimodal user prompts (text + inline images) -- Structured JSON output via `responseMimeType` (schema constraints not yet supported) -- Vercel AI SDK v7 `LanguageModelV4` provider - -## Usage metadata - -ADK returns token usage in response events (`promptTokenCount`, `candidatesTokenCount`, `totalTokenCount`). The provider maps this into AI SDK `usage` on both `generateText` and streaming `finish` events. - -## Multimodal input - -Pass file parts in user messages using the standard AI SDK prompt format: - -```ts -import { generateText } from 'ai' - -const { text } = await generateText({ - model: adk(), - messages: [ - { - role: 'user', - content: [ - { type: 'text', text: 'What is in this image?' }, - { - type: 'file', - mediaType: 'image/jpeg', - data: base64Image, - }, - ], - }, - ], -}) -``` - -## Structured output - -Streaming structured JSON is not supported by ADK yet. - -## Cloud Gemini - -```ts -import { createAdkProvider } from '@react-native-ai/adk' -import { generateText } from 'ai' - -const adk = createAdkProvider({ - apiKey: process.env.GOOGLE_API_KEY, - modelType: 'gemini', - modelName: 'gemini-2.5-flash', - instruction: 'You are a helpful assistant.', -}) - const { text } = await generateText({ model: adk(), prompt: 'Summarize on-device AI in one sentence.', }) ``` -> Do not embed API keys in production client apps. Prefer a backend proxy or secure runtime configuration. - -## On-device Gemini Nano - -Gemini Nano has two separate availability checks: - -| API | Label | Question | -| ------------------------------- | --------------------- | ------------------------------------------ | -| `adk.isNanoSupported()` | **Device capability** | Can this device ever run Nano? | -| `adk.isAvailable('genai-nano')` | **Runtime readiness** | Can I call `prepareNano()` / generate now? | - -If `isNanoSupported()` is `false`, `isAvailable('genai-nano')` is also `false`. - -### ML Kit status codes - -Both checks use ML Kit `Generation.getClient().checkStatus()`: - -| Status | `isNanoSupported()` | `isAvailable('genai-nano')` | Suggested UX | -| -------------- | ------------------- | --------------------------- | ---------------------------------------- | -| `0` | `false` | `false` | Hide or disable — not supported | -| `1` | `true` | `true` | Ready — call `prepareNano()` | -| `3` | `true` | `true` | Ready to download — call `prepareNano()` | -| Other non-zero | `true` | `false` | Show disabled — not ready yet | - -See [ML Kit GenAI Prompt API](https://developers.google.com/ml-kit/genai) for details. - -### Recommended flow - -```ts -import { createAdkProvider } from '@react-native-ai/adk' - -const adk = createAdkProvider({ - modelType: 'genai-nano', - modelName: 'gemini-nano', -}) - -const supported = await adk.isNanoSupported() -if (!supported) { - // Device lacks Gemini Nano / AICore support — hide from model picker - return -} - -const ready = await adk.isAvailable('genai-nano') -if (!ready) { - // Device supports Nano but ML Kit is not ready yet (e.g. downloading) - // Show disabled — do not mark as "Ready" - return -} - -await adk.prepareNano() -const model = adk() -``` - -Both checks are cheap native calls (no model download). Safe to cache at app startup and re-check after resume. - -> **Note:** `model.prepare()`, `generateText()`, and `streamText()` auto-call `prepareNano()` for `genai-nano` models, but only gate on `isNanoSupported()`. For UI gating, always use `isAvailable('genai-nano')` and handle prepare/generation errors in your chat flow. - -## Tool calling - -```ts -import { createAdkProvider } from '@react-native-ai/adk' -import { generateText, tool } from 'ai' -import { z } from 'zod' - -const getCurrentTime = tool({ - description: 'Get the current time for a city', - inputSchema: z.object({ - city: z.string(), - }), - execute: async ({ city }) => ({ - city, - time: new Date().toLocaleTimeString(), - }), -}) - -const adk = createAdkProvider({ - apiKey: process.env.GOOGLE_API_KEY, - availableTools: { getCurrentTime }, -}) +## Features -const { text } = await generateText({ - model: adk(), - tools: { getCurrentTime }, - prompt: 'What time is it in Warsaw?', -}) -``` +- ✅ On-device Gemini Nano through ML Kit GenAI +- ✅ Cloud Gemini through ADK `LlmAgent` +- ✅ Device capability and readiness checks for Gemini Nano +- ✅ Streaming +- ✅ Tool calling, with the agent loop run natively by ADK +- ✅ Image prompts +- ✅ JSON output (without schema constraints) +- ✅ Token usage -During streaming, the provider emits AI SDK `tool-input-*` and `tool-call` stream parts when ADK surfaces function calls from the model. +## Documentation -Pass tools through the AI SDK `tools` option as usual; the provider bridges execution to JavaScript while ADK orchestrates the agent loop natively. +For complete installation instructions and API documentation, visit our [documentation site](https://react-native-ai.com/docs/adk). ## License MIT + +--- + +Made with ❤️ and [create-react-native-library](https://github.com/callstack/react-native-builder-bob) From e3593cae7ed90d17b3f8e52ecb202423bd891e87 Mon Sep 17 00:00:00 2001 From: Mike Grabowski Date: Sun, 25 Oct 2026 02:55:59 +0400 Subject: [PATCH 2/4] chore(adk): upgrade adk kotlin to 1.4.0 and ml kit genai-prompt to beta4 - depend on google-adk-kotlin-core 1.4.0 and the new google-adk-kotlin-mlkit-android module - import GenaiPrompt and GenerativeModelHelpers from com.google.adk.kt.mlkit - match the nullable FunctionTool.execute args - pin genai-prompt beta4 for gemini nano v4 status and streaming fixes - default compile and target sdk to 36 Co-Authored-By: Claude Opus 5.5 --- packages/adk/android/build.gradle | 7 ++++--- packages/adk/android/gradle.properties | 4 ++-- .../src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt | 4 ++-- .../java/com/callstack/ai/adk/NanoFunctionCallingModel.kt | 2 +- .../java/com/callstack/ai/adk/ReactNativeFunctionTool.kt | 2 +- 5 files changed, 10 insertions(+), 9 deletions(-) diff --git a/packages/adk/android/build.gradle b/packages/adk/android/build.gradle index 458bb0e57..0f5c53f72 100644 --- a/packages/adk/android/build.gradle +++ b/packages/adk/android/build.gradle @@ -92,9 +92,10 @@ def kotlin_version = getExtOrDefault("kotlinVersion") dependencies { implementation "com.facebook.react:react-native:+" implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version" - implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2" - implementation "com.google.adk:google-adk-kotlin-core-android:0.2.0" - implementation "com.google.mlkit:genai-prompt:1.0.0-beta2" + implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.11.0" + implementation "com.google.adk:google-adk-kotlin-core:1.4.0" + implementation "com.google.adk:google-adk-kotlin-mlkit-android:1.4.0-beta" + implementation "com.google.mlkit:genai-prompt:1.0.0-beta4" } react { diff --git a/packages/adk/android/gradle.properties b/packages/adk/android/gradle.properties index cc84bcaa4..96ed9f69a 100644 --- a/packages/adk/android/gradle.properties +++ b/packages/adk/android/gradle.properties @@ -1,4 +1,4 @@ ADK_kotlinVersion=2.1.20 ADK_minSdkVersion=26 -ADK_targetSdkVersion=34 -ADK_compileSdkVersion=34 +ADK_targetSdkVersion=36 +ADK_compileSdkVersion=36 diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt index a82bb2bdf..30cb78f99 100644 --- a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt @@ -8,7 +8,7 @@ import com.google.adk.kt.agents.LlmAgent import com.google.adk.kt.events.Event import com.google.adk.kt.models.Gemini import com.google.adk.kt.models.Model -import com.google.adk.kt.models.mlkit.GenaiPrompt +import com.google.adk.kt.mlkit.GenaiPrompt import com.google.adk.kt.runners.InMemoryRunner import com.google.adk.kt.sessions.InMemorySessionService import com.google.adk.kt.sessions.SessionKey @@ -19,7 +19,7 @@ import com.google.adk.kt.types.GenerateContentConfig import com.google.adk.kt.types.Part import com.google.adk.kt.types.Role import com.google.adk.kt.types.UsageMetadata -import com.google.adk.kt.utils.mlkit.GenerativeModelHelpers +import com.google.adk.kt.mlkit.GenerativeModelHelpers import com.google.mlkit.genai.prompt.Generation import com.google.mlkit.genai.prompt.GenerativeModel import kotlinx.coroutines.flow.Flow diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/NanoFunctionCallingModel.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/NanoFunctionCallingModel.kt index 97e838b2b..7ae69bf2f 100644 --- a/packages/adk/android/src/main/java/com/callstack/ai/adk/NanoFunctionCallingModel.kt +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/NanoFunctionCallingModel.kt @@ -3,7 +3,7 @@ package com.callstack.ai.adk import com.google.adk.kt.models.LlmRequest import com.google.adk.kt.models.LlmResponse import com.google.adk.kt.models.Model -import com.google.adk.kt.models.mlkit.GenaiPrompt +import com.google.adk.kt.mlkit.GenaiPrompt import com.google.adk.kt.types.Content import com.google.adk.kt.types.FunctionCall import com.google.adk.kt.types.Part diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/ReactNativeFunctionTool.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/ReactNativeFunctionTool.kt index e9ab8367c..734c968f9 100644 --- a/packages/adk/android/src/main/java/com/callstack/ai/adk/ReactNativeFunctionTool.kt +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/ReactNativeFunctionTool.kt @@ -85,7 +85,7 @@ class ReactNativeFunctionTool( ) } - override suspend fun execute(context: ToolContext, args: Map): Any { + override suspend fun execute(context: ToolContext, args: Map): Any { val toolCallId = UUID.randomUUID().toString() val argumentsJson = AdkJson.encode(args) onToolCall(toolCallId, toolId, argumentsJson, toolCallScope) From 03407ff265227ac7757ecc20752248dc1d3566b3 Mon Sep 17 00:00:00 2001 From: Mike Grabowski Date: Sun, 25 Oct 2026 03:25:40 +0400 Subject: [PATCH 3/4] feat(adk): align provider with apple and support ai sdk 7 features - take per-model options in adk() and export AdkLanguageModel - add getModelInfo, Gemini Nano download progress, model selection and countTokens - add AdkErrorCodes mapped from ML Kit and Gemini API errors - send no tools for toolChoice none and only the chosen tool for a specific one - warn and return an error when a tool has no registered executor - default cloud Gemini to gemini-2.5-flash and infer it from the model name - support schemas for structured output, including streaming - map reasoning to Gemini thinking and return reasoning parts - return provider-executed tool calls and results, and stream tool results - pass seed, stop sequences and penalties, and warn when Nano ignores them - cancel native runs on abort and read file:// and content:// images - report reasoning and cached tokens and map content filter finish reasons Co-Authored-By: Claude Opus 5.5 --- .../com/callstack/ai/adk/AdkAgentRunner.kt | 315 ++++-- .../java/com/callstack/ai/adk/AdkErrors.kt | 57 ++ .../java/com/callstack/ai/adk/AdkSchema.kt | 57 +- .../callstack/ai/adk/AdkStreamToolCalls.kt | 16 + .../java/com/callstack/ai/adk/AdkUsage.kt | 2 + .../callstack/ai/adk/NativeAdkEngineModule.kt | 203 +++- packages/adk/src/NativeAdkEngine.ts | 77 +- packages/adk/src/__tests__/ai-sdk.test.ts | 541 +++++++++- packages/adk/src/ai-sdk.ts | 941 +++++++++++++----- packages/adk/src/errors.ts | 49 + packages/adk/src/index.ts | 20 +- 11 files changed, 1873 insertions(+), 405 deletions(-) create mode 100644 packages/adk/android/src/main/java/com/callstack/ai/adk/AdkErrors.kt create mode 100644 packages/adk/src/errors.ts diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt index 30cb78f99..75d4ec2dc 100644 --- a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkAgentRunner.kt @@ -1,14 +1,18 @@ package com.callstack.ai.adk +import android.content.Context +import android.net.Uri import android.util.Base64 import com.facebook.react.bridge.ReadableArray import com.facebook.react.bridge.ReadableMap import com.google.adk.kt.agents.Instruction import com.google.adk.kt.agents.LlmAgent +import com.google.adk.kt.agents.RunConfig +import com.google.adk.kt.agents.StreamingMode import com.google.adk.kt.events.Event +import com.google.adk.kt.mlkit.GenaiPrompt import com.google.adk.kt.models.Gemini import com.google.adk.kt.models.Model -import com.google.adk.kt.mlkit.GenaiPrompt import com.google.adk.kt.runners.InMemoryRunner import com.google.adk.kt.sessions.InMemorySessionService import com.google.adk.kt.sessions.SessionKey @@ -18,85 +22,204 @@ import com.google.adk.kt.types.Content import com.google.adk.kt.types.GenerateContentConfig import com.google.adk.kt.types.Part import com.google.adk.kt.types.Role +import com.google.adk.kt.types.ThinkingConfig import com.google.adk.kt.types.UsageMetadata -import com.google.adk.kt.mlkit.GenerativeModelHelpers +import com.google.mlkit.genai.common.DownloadStatus +import com.google.mlkit.genai.common.FeatureStatus +import com.google.mlkit.genai.common.GenAiException import com.google.mlkit.genai.prompt.Generation import com.google.mlkit.genai.prompt.GenerativeModel +import com.google.mlkit.genai.prompt.ModelPreference +import com.google.mlkit.genai.prompt.ModelReleaseStage +import com.google.mlkit.genai.prompt.TextPart +import com.google.mlkit.genai.prompt.generateContentRequest +import com.google.mlkit.genai.prompt.generationConfig +import com.google.mlkit.genai.prompt.modelConfig import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.toList import kotlinx.coroutines.sync.Mutex import kotlinx.coroutines.sync.withLock import java.util.UUID +import java.util.concurrent.ConcurrentHashMap + +data class AdkToolCallRecord(val toolCallId: String, val toolName: String, val input: String) + +data class AdkToolResultRecord(val toolCallId: String, val toolName: String, val output: String) data class AdkRunResult( val content: String, + val reasoning: String?, + val toolCalls: List, + val toolResults: List, val finishReason: String?, val usage: UsageMetadata?, ) +data class AdkModelInfo( + val availability: String, + val baseModelName: String? = null, + val contextSize: Int? = null, +) + +/** Gemini Nano model selection, see ML Kit `ModelConfig`. */ +data class NanoConfig( + val releaseStage: String? = null, + val preference: String? = null, +) { + companion object { + fun from(map: ReadableMap?): NanoConfig = + NanoConfig( + releaseStage = map?.getString("releaseStage"), + preference = map?.getString("preference"), + ) + } +} + +fun Part.isThought(): Boolean = thought == true + +fun Event.textParts(thoughts: Boolean): String = + content?.parts?.filter { it.isThought() == thoughts }?.mapNotNull { it.text }?.joinToString("") + ?: "" + class AdkAgentRunner( + private val context: Context, private val onToolCall: ( toolCallId: String, toolId: String, arguments: String, scope: ToolCallScope?, ) -> Unit, + private val onDownloadProgress: ( + phase: String, + bytesDownloaded: Long?, + bytesToDownload: Long?, + ) -> Unit, ) { - private var generativeModel: GenerativeModel? = null + private val nanoModels = ConcurrentHashMap() private val nanoPrepareMutex = Mutex() - suspend fun prepareNano() { - if (!isNanoSupported()) { - throw IllegalStateException( - "Gemini Nano is not supported on this device or device hasn't fetched the latest configuration to support it", - ) - } - nanoPrepareMutex.withLock { - generativeModel = GenerativeModelHelpers.initGenerativeModel() + private fun nanoClient(config: NanoConfig): GenerativeModel { + if (config.releaseStage == null && config.preference == null) { + return Generation.getClient() } + + return Generation.getClient( + generationConfig { + modelConfig = modelConfig { + config.releaseStage?.let { + releaseStage = + if (it == "preview") ModelReleaseStage.PREVIEW else ModelReleaseStage.STABLE + } + config.preference?.let { + preference = if (it == "fast") ModelPreference.FAST else ModelPreference.FULL + } + } + }, + ) } - private suspend fun ensureNanoPrepared() { - if (generativeModel != null) { - return + private suspend fun nanoStatus(config: NanoConfig): Int = + try { + nanoClient(config).checkStatus() + } catch (_: Exception) { + FeatureStatus.UNAVAILABLE + } + + /** Downloads Gemini Nano when needed, reporting progress, then warms it up. */ + suspend fun prepareNano(config: NanoConfig) { + nanoPrepareMutex.withLock { + if (nanoModels.containsKey(config)) return + + val model = nanoClient(config) + when (val status = model.checkStatus()) { + FeatureStatus.UNAVAILABLE -> + throw AdkErrors.AdkException( + AdkErrors.MODEL_UNAVAILABLE, + "Gemini Nano is not supported on this device or the device has not fetched the latest configuration to support it", + ) + FeatureStatus.DOWNLOADABLE, FeatureStatus.DOWNLOADING -> download(model, status) + } + model.warmup() + nanoModels[config] = model } - prepareNano() } - /** - * Whether this device supports on-device Gemini Nano at all (ML Kit checkStatus != 0). - * Does not download models or run full initialization. - */ - suspend fun isNanoSupported(): Boolean { - return try { - when (Generation.getClient().checkStatus()) { - 0 -> false - else -> true + private suspend fun download(model: GenerativeModel, status: Int) { + try { + model.download().collect { downloadStatus -> + when (downloadStatus) { + is DownloadStatus.DownloadStarted -> + onDownloadProgress("started", 0, downloadStatus.bytesToDownload) + is DownloadStatus.DownloadProgress -> + onDownloadProgress("progress", downloadStatus.totalBytesDownloaded, null) + is DownloadStatus.DownloadCompleted -> onDownloadProgress("completed", null, null) + is DownloadStatus.DownloadFailed -> + throw AdkErrors.AdkException( + AdkErrors.DOWNLOAD_FAILED, + "Gemini Nano download failed: ${downloadStatus.e.message}", + downloadStatus.e, + ) + } } - } catch (_: Exception) { - false + } catch (error: GenAiException) { + if (status == FeatureStatus.DOWNLOADING) { + throw AdkErrors.AdkException( + AdkErrors.MODEL_DOWNLOADING, + "Gemini Nano is still downloading", + error, + ) + } + throw error } } - /** - * Whether Gemini Nano is ready to use now (downloaded or ready to download). - * Returns false when [isNanoSupported] is false. - */ - suspend fun isNanoAvailable(): Boolean { - if (!isNanoSupported()) { - return false + private suspend fun preparedNano(config: NanoConfig): GenerativeModel { + nanoModels[config]?.let { return it } + prepareNano(config) + return nanoModels.getValue(config) + } + + /** Whether this device supports Gemini Nano at all. Does not download the model. */ + suspend fun isNanoSupported(config: NanoConfig): Boolean = + nanoStatus(config) != FeatureStatus.UNAVAILABLE + + /** Whether Gemini Nano is downloaded or can be downloaded now. */ + suspend fun isNanoAvailable(config: NanoConfig): Boolean = + when (nanoStatus(config)) { + FeatureStatus.DOWNLOADABLE, FeatureStatus.AVAILABLE -> true + else -> false + } + + suspend fun getModelInfo(modelType: String, config: NanoConfig): AdkModelInfo { + if (modelType != "genai-nano") { + return AdkModelInfo(availability = "available") } - return try { - when (Generation.getClient().checkStatus()) { - 1, 3 -> true - else -> false + val model = nanoClient(config) + val status = + try { + model.checkStatus() + } catch (_: Exception) { + return AdkModelInfo(availability = "unknown") } - } catch (_: Exception) { - false + + return when (status) { + FeatureStatus.UNAVAILABLE -> AdkModelInfo(availability = "unavailable") + FeatureStatus.DOWNLOADABLE -> AdkModelInfo(availability = "downloadable") + FeatureStatus.DOWNLOADING -> AdkModelInfo(availability = "downloading") + FeatureStatus.AVAILABLE -> + AdkModelInfo( + availability = "available", + baseModelName = runCatching { model.getBaseModelName() }.getOrNull(), + contextSize = runCatching { model.getTokenLimit() }.getOrNull(), + ) + else -> AdkModelInfo(availability = "unknown") } } + suspend fun countTokens(text: String, config: NanoConfig): Int = + preparedNano(config).countTokens(generateContentRequest(TextPart(text)) {}).totalTokens + suspend fun generateText( messages: ReadableArray, config: ReadableMap, @@ -105,21 +228,49 @@ class AdkAgentRunner( runId: String, ): AdkRunResult { val events = runAgent(messages, config, options, tools, stream = false, runId = runId).toList() + val completeEvents = events.filterNot { it.partial } val text = - events - .lastOrNull { it.isFinalResponse && !it.partial } - ?.content - ?.parts - ?.mapNotNull { it.text } - ?.joinToString("") + completeEvents + .lastOrNull { it.isFinalResponse } + ?.textParts(thoughts = false) ?.takeIf { it.isNotEmpty() } - ?: events - .flatMap { event -> event.content?.parts?.mapNotNull { it.text } ?: emptyList() } - .joinToString("") + ?: completeEvents.joinToString("") { it.textParts(thoughts = false) } + val reasoning = + completeEvents + .map { it.textParts(thoughts = true) } + .filter { it.isNotEmpty() } + .joinToString("\n\n") + .ifEmpty { null } + + val toolCalls = + completeEvents.flatMap { event -> + event.functionCalls().map { call -> + AdkToolCallRecord( + toolCallId = call.id ?: UUID.randomUUID().toString(), + toolName = call.name, + input = AdkJson.encode(call.args), + ) + } + } + val toolResults = + completeEvents.flatMap { event -> + event.functionResponses().map { response -> + AdkToolResultRecord( + toolCallId = response.id ?: "", + toolName = response.name, + output = AdkJson.encode(response.response), + ) + } + } - val finishReason = events.lastOrNull()?.finishReason?.name - val usage = AdkUsage.latestFromEvents(events) - return AdkRunResult(content = text, finishReason = finishReason, usage = usage) + return AdkRunResult( + content = text, + reasoning = reasoning, + toolCalls = toolCalls, + toolResults = toolResults, + finishReason = events.lastOrNull()?.finishReason?.name, + usage = AdkUsage.latestFromEvents(events), + ) } suspend fun streamText( @@ -198,22 +349,14 @@ class AdkAgentRunner( userId = userId, sessionId = sessionId, newMessage = lastMessage.content, - runConfig = com.google.adk.kt.agents.RunConfig(streamingMode = if (stream) { - com.google.adk.kt.agents.StreamingMode.SSE - } else { - com.google.adk.kt.agents.StreamingMode.NONE - }), + runConfig = RunConfig(streamingMode = if (stream) StreamingMode.SSE else StreamingMode.NONE), ) } private suspend fun createModel(config: AgentConfig): Model { return when (config.modelType) { - "genai-nano" -> { - ensureNanoPrepared() - val model = generativeModel - ?: throw IllegalStateException("Failed to initialize Gemini Nano") - NanoFunctionCallingModel(GenaiPrompt.create(model, config.modelName)) - } + "genai-nano" -> + NanoFunctionCallingModel(GenaiPrompt.create(preparedNano(config.nano), config.modelName)) else -> Gemini(name = config.modelName, apiKey = config.apiKey) } } @@ -225,23 +368,50 @@ class AdkAgentRunner( if (options == null) return null val responseFormat = options.getMap("responseFormat") - if (responseFormat?.hasKey("schema") == true) { - throw IllegalArgumentException( - "ADK GenerateContentConfig does not support responseFormat.schema yet", - ) - } + val responseSchema = + responseFormat?.getMap("schema")?.let { schema -> + try { + AdkSchema.fromReadableMap(schema) + } catch (error: Exception) { + throw AdkErrors.AdkException( + AdkErrors.INVALID_SCHEMA, + "Unsupported response schema: ${error.message}", + error, + ) + } + } val responseMimeType = when { responseFormat?.hasKey("mimeType") == true -> responseFormat.getString("mimeType") responseFormat?.getString("type") == "json" -> "application/json" else -> null } + + val thinkingConfig = + options.getMap("thinking")?.let { thinking -> + ThinkingConfig( + includeThoughts = thinking.hasKey("includeThoughts") && thinking.getBoolean("includeThoughts"), + thinkingBudget = thinking.takeIf { it.hasKey("budget") }?.getDouble("budget")?.toInt(), + ) + } + return GenerateContentConfig( temperature = options.takeIf { it.hasKey("temperature") }?.getDouble("temperature")?.toFloat(), maxOutputTokens = options.takeIf { it.hasKey("maxTokens") }?.getInt("maxTokens"), topP = options.takeIf { it.hasKey("topP") }?.getDouble("topP")?.toFloat(), topK = options.takeIf { it.hasKey("topK") }?.getDouble("topK")?.toFloat()?.toInt(), + seed = options.takeIf { it.hasKey("seed") }?.getDouble("seed")?.toInt(), + stopSequences = + options.getArray("stopSequences")?.let { array -> + (0 until array.size()).mapNotNull { index -> array.getString(index) } + }, + presencePenalty = + options.takeIf { it.hasKey("presencePenalty") }?.getDouble("presencePenalty")?.toFloat(), + frequencyPenalty = + options.takeIf { it.hasKey("frequencyPenalty") }?.getDouble("frequencyPenalty")?.toFloat(), responseMimeType = responseMimeType, + responseSchema = responseSchema, + thinkingConfig = thinkingConfig, ) } @@ -281,9 +451,10 @@ class AdkAgentRunner( when (part.getString("type")) { "text" -> part.getString("text")?.let { parts.add(Part(text = it)) } "file" -> { - val data = part.getString("data") ?: continue val mimeType = part.getString("mimeType") ?: "application/octet-stream" - val bytes = Base64.decode(data, Base64.DEFAULT) + val bytes = part.getString("data")?.let { Base64.decode(it, Base64.DEFAULT) } + ?: part.getString("uri")?.let { readUri(it) } + ?: continue parts.add(Part(inlineData = Blob(mimeType = mimeType, data = bytes))) } } @@ -296,6 +467,10 @@ class AdkAgentRunner( return Content(role = role, parts = parts) } + private fun readUri(uri: String): ByteArray = + context.contentResolver.openInputStream(Uri.parse(uri))?.use { it.readBytes() } + ?: throw IllegalArgumentException("Cannot read file: $uri") + private fun parseTools( tools: ReadableArray?, toolCallScope: ToolCallScope?, @@ -396,6 +571,7 @@ class AdkAgentRunner( modelType = model.getString("type") ?: "genai-nano", modelName = model.getString("name") ?: "gemini-nano", apiKey = model.getString("apiKey"), + nano = NanoConfig.from(model.getMap("nano")), ) } } @@ -408,6 +584,7 @@ data class AgentConfig( val modelType: String, val modelName: String, val apiKey: String?, + val nano: NanoConfig, ) /** ADK content role — one of [Role.USER], [Role.MODEL], or [Role.SYSTEM]. */ diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkErrors.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkErrors.kt new file mode 100644 index 000000000..107478c33 --- /dev/null +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkErrors.kt @@ -0,0 +1,57 @@ +package com.callstack.ai.adk + +import com.google.mlkit.genai.common.GenAiException +import com.google.mlkit.genai.common.GenAiException.ErrorCode + +/** Error codes shared with `AdkErrorCodes` in `src/errors.ts`. */ +object AdkErrors { + const val MODEL_UNAVAILABLE = "MODEL_UNAVAILABLE" + const val MODEL_DOWNLOADING = "MODEL_DOWNLOADING" + const val DOWNLOAD_FAILED = "DOWNLOAD_FAILED" + const val GENERATION_ERROR = "GENERATION_ERROR" + const val INVALID_MESSAGE = "INVALID_MESSAGE" + const val INVALID_SCHEMA = "INVALID_SCHEMA" + const val CONTEXT_WINDOW_EXCEEDED = "CONTEXT_WINDOW_EXCEEDED" + const val RATE_LIMITED = "RATE_LIMITED" + const val BACKGROUND_USE_BLOCKED = "BACKGROUND_USE_BLOCKED" + + /** Exception that already knows its error code. */ + class AdkException(val code: String, message: String, cause: Throwable? = null) : + Exception(message, cause) + + fun codeFor(error: Throwable): String { + var current: Throwable? = error + while (current != null) { + when (current) { + is AdkException -> return current.code + is GenAiException -> return codeFor(current) + is IllegalArgumentException -> return INVALID_MESSAGE + } + current = current.cause + } + + // Cloud Gemini surfaces HTTP status codes in the message + val message = error.message.orEmpty() + return when { + message.contains("RESOURCE_EXHAUSTED") || message.contains("429") -> RATE_LIMITED + message.contains("exceeds the maximum number of tokens") -> CONTEXT_WINDOW_EXCEEDED + else -> GENERATION_ERROR + } + } + + private fun codeFor(error: GenAiException): String = + when (error.errorCode) { + ErrorCode.NOT_AVAILABLE, + ErrorCode.NOT_SUPPORTED, + ErrorCode.AICORE_INCOMPATIBLE, + ErrorCode.NEEDS_SYSTEM_UPDATE, + ErrorCode.NOT_ENOUGH_DISK_SPACE -> MODEL_UNAVAILABLE + ErrorCode.BUSY, + ErrorCode.PER_APP_BATTERY_USE_QUOTA_EXCEEDED -> RATE_LIMITED + ErrorCode.BACKGROUND_USE_BLOCKED -> BACKGROUND_USE_BLOCKED + ErrorCode.REQUEST_TOO_LARGE -> CONTEXT_WINDOW_EXCEEDED + ErrorCode.INVALID_INPUT_IMAGE, + ErrorCode.REQUEST_TOO_SMALL -> INVALID_MESSAGE + else -> GENERATION_ERROR + } +} diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkSchema.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkSchema.kt index 00c935126..a0c45b10e 100644 --- a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkSchema.kt +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkSchema.kt @@ -6,6 +6,10 @@ import com.facebook.react.bridge.ReadableType import com.google.adk.kt.types.Schema import com.google.adk.kt.types.Type +/** + * Converts a JSON Schema from the AI SDK to an ADK [Schema]. Keywords that Gemini does not + * support, such as `$ref` or `additionalProperties`, are dropped. + */ object AdkSchema { fun fromReadableMap(map: ReadableMap): Schema { val properties = map.getMap("properties")?.let { props -> @@ -33,20 +37,69 @@ object AdkSchema { } } + // `type: ["string", "null"]` and `anyOf: [..., { type: "null" }]` both mean nullable + val typeNames = readTypeNames(map) + var nullable = typeNames.contains("null") || map.getBooleanOrNull("nullable") == true + val type = typeNames.firstOrNull { it != "null" }?.let { parseType(it) } + + val anyOf = (map.getArray("anyOf") ?: map.getArray("oneOf"))?.let { array -> + val schemas = (0 until array.size()).mapNotNull { index -> array.getMap(index) } + val nonNull = schemas.filterNot { readTypeNames(it) == listOf("null") } + if (nonNull.size < schemas.size) nullable = true + nonNull.map { fromReadableMap(it) } + } + + // A nullable value with a single option is that option, marked nullable + if (type == null && anyOf?.size == 1) { + return anyOf.first().copy(nullable = if (nullable) true else anyOf.first().nullable) + } + return Schema( - type = parseType(map.getString("type")), + type = type, properties = properties, items = map.getMap("items")?.let { fromReadableMap(it) }, required = required, description = map.getString("description"), enum = enumValues, + format = map.getString("format"), + nullable = if (nullable) true else null, + anyOf = anyOf?.takeIf { it.isNotEmpty() }, + title = map.getString("title"), + pattern = map.getString("pattern"), + minimum = map.getDoubleOrNull("minimum"), + maximum = map.getDoubleOrNull("maximum"), + minLength = map.getDoubleOrNull("minLength")?.toLong(), + maxLength = map.getDoubleOrNull("maxLength")?.toLong(), + minItems = map.getDoubleOrNull("minItems")?.toLong(), + maxItems = map.getDoubleOrNull("maxItems")?.toLong(), + minProperties = map.getDoubleOrNull("minProperties")?.toLong(), + maxProperties = map.getDoubleOrNull("maxProperties")?.toLong(), ) } + private fun readTypeNames(map: ReadableMap): List { + if (!map.hasKey("type")) return emptyList() + return when (map.getType("type")) { + ReadableType.String -> listOfNotNull(map.getString("type")) + ReadableType.Array -> map.getArray("type")?.strings() ?: emptyList() + else -> emptyList() + } + } + + private fun ReadableArray.strings(): List = + (0 until size()).mapNotNull { index -> getString(index) } + + private fun ReadableMap.getDoubleOrNull(key: String): Double? = + if (hasKey(key) && getType(key) == ReadableType.Number) getDouble(key) else null + + private fun ReadableMap.getBooleanOrNull(key: String): Boolean? = + if (hasKey(key) && getType(key) == ReadableType.Boolean) getBoolean(key) else null + private fun parseType(type: String?): Type? { return when (type) { "string" -> Type.STRING - "number", "integer" -> Type.NUMBER + "number" -> Type.NUMBER + "integer" -> Type.INTEGER "boolean" -> Type.BOOLEAN "array" -> Type.ARRAY "object" -> Type.OBJECT diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkStreamToolCalls.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkStreamToolCalls.kt index 928907bc4..705ad4543 100644 --- a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkStreamToolCalls.kt +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkStreamToolCalls.kt @@ -83,6 +83,22 @@ class AdkStreamToolCallEmitter( } } + /** Emits the result of each tool call that ADK ran in this event. */ + fun handleResults(event: Event) { + for (functionResponse in event.functionResponses()) { + val toolCallId = functionResponse.id ?: continue + emit( + Arguments.createMap().apply { + putString("streamId", streamId) + putString("phase", "result") + putString("toolCallId", toolCallId) + putString("toolName", functionResponse.name) + putString("output", AdkJson.encode(functionResponse.response)) + }, + ) + } + } + private fun emitEnd(toolCallId: String, toolName: String, input: String) { emit( Arguments.createMap().apply { diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkUsage.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkUsage.kt index 76b926a98..480319291 100644 --- a/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkUsage.kt +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/AdkUsage.kt @@ -13,6 +13,8 @@ object AdkUsage { usage.promptTokenCount?.let { putInt("promptTokenCount", it) } usage.candidatesTokenCount?.let { putInt("candidatesTokenCount", it) } usage.totalTokenCount?.let { putInt("totalTokenCount", it) } + usage.thoughtsTokenCount?.let { putInt("thoughtsTokenCount", it) } + usage.cachedContentTokenCount?.let { putInt("cachedContentTokenCount", it) } } } diff --git a/packages/adk/android/src/main/java/com/callstack/ai/adk/NativeAdkEngineModule.kt b/packages/adk/android/src/main/java/com/callstack/ai/adk/NativeAdkEngineModule.kt index 372a2349c..416c031f3 100644 --- a/packages/adk/android/src/main/java/com/callstack/ai/adk/NativeAdkEngineModule.kt +++ b/packages/adk/android/src/main/java/com/callstack/ai/adk/NativeAdkEngineModule.kt @@ -5,6 +5,7 @@ import com.facebook.react.bridge.Promise import com.facebook.react.bridge.ReactApplicationContext import com.facebook.react.bridge.ReadableArray import com.facebook.react.bridge.ReadableMap +import com.google.adk.kt.events.Event import com.google.adk.kt.types.UsageMetadata import kotlinx.coroutines.CoroutineScope import kotlinx.coroutines.Dispatchers @@ -22,51 +23,96 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : override fun getName(): String = NAME private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO) - private val runner = AdkAgentRunner { toolCallId, toolId, arguments, toolCallScope -> - toolCallScope?.streamId?.let { AdkToolBridge.registerToolCall(it, toolCallId) } - toolCallScope?.runId?.let { AdkToolBridge.registerToolCall(it, toolCallId) } - val args = Arguments.createMap().apply { - putString("toolCallId", toolCallId) - putString("toolId", toolId) - putString("arguments", arguments) - toolCallScope?.streamId?.let { putString("streamId", it) } - toolCallScope?.runId?.let { putString("runId", it) } - } - emitOnToolCall(args) + private val runner = AdkAgentRunner( + context = reactContext, + onToolCall = { toolCallId, toolId, arguments, toolCallScope -> + toolCallScope?.streamId?.let { AdkToolBridge.registerToolCall(it, toolCallId) } + toolCallScope?.runId?.let { AdkToolBridge.registerToolCall(it, toolCallId) } + val args = Arguments.createMap().apply { + putString("toolCallId", toolCallId) + putString("toolId", toolId) + putString("arguments", arguments) + toolCallScope?.streamId?.let { putString("streamId", it) } + toolCallScope?.runId?.let { putString("runId", it) } + } + emitOnToolCall(args) + }, + onDownloadProgress = { phase, bytesDownloaded, bytesToDownload -> + emitOnNanoDownloadProgress( + Arguments.createMap().apply { + putString("phase", phase) + bytesDownloaded?.let { putDouble("bytesDownloaded", it.toDouble()) } + bytesToDownload?.let { putDouble("bytesToDownload", it.toDouble()) } + }, + ) + }, + ) + + // Streams and generateText runs, by id, so both can be cancelled + private val activeRuns = ConcurrentHashMap() + + private fun Promise.rejectWithCode(error: Exception) { + reject(AdkErrors.codeFor(error), error.message ?: "Unknown ADK error", error) } - private val activeStreams = ConcurrentHashMap() - override fun isAvailable(modelType: String, promise: Promise) { + override fun isAvailable(modelType: String, nano: ReadableMap?, promise: Promise) { scope.launch { try { val available = when (modelType) { - "genai-nano" -> runner.isNanoAvailable() + "genai-nano" -> runner.isNanoAvailable(NanoConfig.from(nano)) else -> true } promise.resolve(available) - } catch (error: Exception) { + } catch (_: Exception) { promise.resolve(false) } } } - override fun isNanoSupported(promise: Promise) { + override fun isNanoSupported(nano: ReadableMap?, promise: Promise) { scope.launch { try { - promise.resolve(runner.isNanoSupported()) + promise.resolve(runner.isNanoSupported(NanoConfig.from(nano))) } catch (_: Exception) { promise.resolve(false) } } } - override fun prepareNano(promise: Promise) { + override fun getModelInfo(modelType: String, nano: ReadableMap?, promise: Promise) { scope.launch { try { - runner.prepareNano() + val info = runner.getModelInfo(modelType, NanoConfig.from(nano)) + promise.resolve( + Arguments.createMap().apply { + putString("availability", info.availability) + info.baseModelName?.let { putString("baseModelName", it) } + info.contextSize?.let { putInt("contextSize", it) } + }, + ) + } catch (error: Exception) { + promise.rejectWithCode(error) + } + } + } + + override fun prepareNano(nano: ReadableMap?, promise: Promise) { + scope.launch { + try { + runner.prepareNano(NanoConfig.from(nano)) promise.resolve(null) } catch (error: Exception) { - promise.reject("ADK_PREPARE_ERROR", error.message, error) + promise.rejectWithCode(error) + } + } + } + + override fun countTokens(text: String, nano: ReadableMap?, promise: Promise) { + scope.launch { + try { + promise.resolve(runner.countTokens(text, NanoConfig.from(nano)).toDouble()) + } catch (error: Exception) { + promise.rejectWithCode(error) } } } @@ -79,22 +125,53 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : tools: ReadableArray?, promise: Promise, ) { - scope.launch { + val job = scope.launch { try { val result = runner.generateText(messages, config, options, tools, runId) val response = Arguments.createMap().apply { putString("role", "assistant") putString("content", result.content) + result.reasoning?.let { putString("reasoning", it) } + putArray( + "toolCalls", + Arguments.createArray().apply { + result.toolCalls.forEach { call -> + pushMap( + Arguments.createMap().apply { + putString("toolCallId", call.toolCallId) + putString("toolName", call.toolName) + putString("input", call.input) + }, + ) + } + }, + ) + putArray( + "toolResults", + Arguments.createArray().apply { + result.toolResults.forEach { toolResult -> + pushMap( + Arguments.createMap().apply { + putString("toolCallId", toolResult.toolCallId) + putString("toolName", toolResult.toolName) + putString("output", toolResult.output) + }, + ) + } + }, + ) result.finishReason?.let { putString("finishReason", it) } AdkUsage.toWritableMap(result.usage)?.let { putMap("usage", it) } } promise.resolve(response) } catch (error: Exception) { - promise.reject("ADK_GENERATION_ERROR", error.message, error) + promise.rejectWithCode(error) } finally { + activeRuns.remove(runId) AdkToolBridge.cancelForStream(runId) } } + activeRuns[runId] = job } override fun streamText( @@ -105,8 +182,8 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : tools: ReadableArray?, promise: Promise, ) { - if (activeStreams.containsKey(streamId)) { - promise.reject("ADK_STREAM_ERROR", "Stream ID already in use: $streamId") + if (activeRuns.containsKey(streamId)) { + promise.reject(AdkErrors.GENERATION_ERROR, "Stream ID already in use: $streamId") return } @@ -124,9 +201,12 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : // currentTurnText: full reconstructed text of the current agent turn // emittedText: the prefix of currentTurnText already sent to JS // suppressCurrentTurn: true once we confirm this turn is a tool-code turn + // currentTurnReasoning / emittedReasoning: the same for thought parts var currentTurnText = "" var emittedText = "" var suppressCurrentTurn = false + var currentTurnReasoning = "" + var emittedReasoning = "" val toolCallEmitter = AdkStreamToolCallEmitter(streamId) { args -> emitOnStreamToolCall(args) } @@ -136,8 +216,22 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : event.usageMetadata?.let { latestUsage = it } toolCallEmitter.handleEvent(event) + toolCallEmitter.handleResults(event) - val text = event.content?.parts?.mapNotNull { it.text }?.joinToString("") ?: "" + val reasoning = event.textParts(thoughts = true) + if (reasoning.isNotEmpty()) { + currentTurnReasoning = + if (reasoning.startsWith(currentTurnReasoning)) reasoning + else currentTurnReasoning + reasoning + if (currentTurnReasoning.length > emittedReasoning.length && + currentTurnReasoning.startsWith(emittedReasoning) + ) { + emitDelta(streamId, currentTurnReasoning.substring(emittedReasoning.length), "reasoning") + emittedReasoning = currentTurnReasoning + } + } + + val text = event.textParts(thoughts = false) if (text.isNotEmpty()) { // Reconstruct the full turn text. If the event repeats what we already have @@ -158,6 +252,8 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : currentTurnText = "" emittedText = "" suppressCurrentTurn = false + currentTurnReasoning = "" + emittedReasoning = "" } if (!suppressCurrentTurn && !(event.isFinalResponse && !event.partial)) { @@ -165,14 +261,8 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : // so we never emit a partial "```", "```tool", etc. that later completes. val safeEnd = currentTurnText.length - pendingMarkerPrefixLength(currentTurnText) if (safeEnd > emittedText.length) { - val delta = currentTurnText.substring(emittedText.length, safeEnd) + emitDelta(streamId, currentTurnText.substring(emittedText.length, safeEnd), "text") emittedText = currentTurnText.substring(0, safeEnd) - - val updateArgs = Arguments.createMap().apply { - putString("streamId", streamId) - putString("delta", delta) - } - emitOnStreamUpdate(updateArgs) } } @@ -180,42 +270,53 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : // Flush any held-back text for a normal turn (e.g. a response legitimately // ending in backticks that turned out not to be a tool-code marker). if (!suppressCurrentTurn && currentTurnText.length > emittedText.length) { - val delta = currentTurnText.substring(emittedText.length) + emitDelta(streamId, currentTurnText.substring(emittedText.length), "text") emittedText = currentTurnText - val updateArgs = Arguments.createMap().apply { - putString("streamId", streamId) - putString("delta", delta) - } - emitOnStreamUpdate(updateArgs) } - val completeArgs = Arguments.createMap().apply { - putString("streamId", streamId) - putString("finishReason", event.finishReason?.name) - AdkUsage.toWritableMap(latestUsage ?: event.usageMetadata)?.let { - putMap("usage", it) - } - } - emitOnStreamComplete(completeArgs) + emitComplete(streamId, event, latestUsage) } } } catch (error: Exception) { val errorArgs = Arguments.createMap().apply { putString("streamId", streamId) putString("error", error.message ?: "Unknown ADK stream error") + putString("code", AdkErrors.codeFor(error)) } emitOnStreamError(errorArgs) } finally { - activeStreams.remove(streamId) + activeRuns.remove(streamId) } } - activeStreams[streamId] = job + activeRuns[streamId] = job promise.resolve(null) } + private fun emitDelta(streamId: String, delta: String, kind: String) { + emitOnStreamUpdate( + Arguments.createMap().apply { + putString("streamId", streamId) + putString("delta", delta) + putString("kind", kind) + }, + ) + } + + private fun emitComplete(streamId: String, event: Event, latestUsage: UsageMetadata?) { + emitOnStreamComplete( + Arguments.createMap().apply { + putString("streamId", streamId) + event.finishReason?.name?.let { putString("finishReason", it) } + AdkUsage.toWritableMap(latestUsage ?: event.usageMetadata)?.let { + putMap("usage", it) + } + }, + ) + } + override fun cancelStream(streamId: String, promise: Promise) { - activeStreams.remove(streamId)?.cancel() + activeRuns.remove(streamId)?.cancel() AdkToolBridge.cancelForStream(streamId) promise.resolve(null) } @@ -225,8 +326,8 @@ class NativeAdkEngineModule(reactContext: ReactApplicationContext) : } override fun invalidate() { - activeStreams.values.forEach { it.cancel() } - activeStreams.clear() + activeRuns.values.forEach { it.cancel() } + activeRuns.clear() AdkToolBridge.cancelAll() scope.cancel() super.invalidate() diff --git a/packages/adk/src/NativeAdkEngine.ts b/packages/adk/src/NativeAdkEngine.ts index 4862243cc..9c5fffc5a 100644 --- a/packages/adk/src/NativeAdkEngine.ts +++ b/packages/adk/src/NativeAdkEngine.ts @@ -5,7 +5,7 @@ export type AdkMessageRole = 'assistant' | 'system' | 'user' export type AdkMessagePart = | { type: 'text'; text: string } - | { type: 'file'; mimeType: string; data: string } + | { type: 'file'; mimeType: string; data?: string; uri?: string } export interface AdkMessage { role: AdkMessageRole @@ -15,6 +15,13 @@ export interface AdkMessage { export type AdkModelType = 'gemini' | 'genai-nano' +export interface AdkNanoModelConfig { + /** `stable` (default) or `preview`, which needs the AICore developer preview */ + releaseStage?: 'stable' | 'preview' + /** `fast` favors latency, `full` favors quality */ + preference?: 'fast' | 'full' +} + export interface AdkAgentConfig { name: string description?: string @@ -23,6 +30,7 @@ export interface AdkAgentConfig { type: AdkModelType name: string apiKey?: string + nano?: AdkNanoModelConfig } } @@ -52,25 +60,59 @@ export interface AdkGenerationOptions { maxTokens?: number topP?: number topK?: number + seed?: number + stopSequences?: string[] + presencePenalty?: number + frequencyPenalty?: number responseFormat?: AdkResponseFormat + /** Thinking on/off with an optional budget. Gemini Nano only supports on/off */ + thinking?: { + includeThoughts: boolean + budget?: number + } } export interface AdkUsageMetadata { promptTokenCount?: number candidatesTokenCount?: number totalTokenCount?: number + thoughtsTokenCount?: number + cachedContentTokenCount?: number +} + +export interface AdkToolCallRecord { + toolCallId: string + toolName: string + input: string +} + +export interface AdkToolResultRecord { + toolCallId: string + toolName: string + output: string } export interface AdkGeneratedMessage { role: AdkMessageRole content: string + reasoning?: string + toolCalls?: AdkToolCallRecord[] + toolResults?: AdkToolResultRecord[] finishReason?: string usage?: AdkUsageMetadata } +export interface AdkNativeModelInfo { + availability: string + baseModelName?: string + contextSize?: number +} + export interface StreamUpdateEvent { streamId: string delta: string + /** `text` (default) or `reasoning` */ + kind?: string } export interface StreamCompleteEvent { @@ -82,15 +124,17 @@ export interface StreamCompleteEvent { export interface StreamErrorEvent { streamId: string error: string + code?: string } export interface StreamToolCallEvent { streamId: string - phase: 'start' | 'delta' | 'end' + phase: 'start' | 'delta' | 'end' | 'result' toolCallId: string toolName?: string inputDelta?: string input?: string + output?: string } export interface ToolCallEvent { @@ -101,10 +145,25 @@ export interface ToolCallEvent { runId?: string } +export interface NanoDownloadProgressEvent { + /** `started`, `progress` or `completed` */ + phase: string + bytesDownloaded?: number + bytesToDownload?: number +} + export interface Spec extends TurboModule { - isAvailable(modelType: AdkModelType): Promise - isNanoSupported(): Promise - prepareNano(): Promise + isAvailable( + modelType: AdkModelType, + nano?: AdkNanoModelConfig + ): Promise + isNanoSupported(nano?: AdkNanoModelConfig): Promise + getModelInfo( + modelType: AdkModelType, + nano?: AdkNanoModelConfig + ): Promise + prepareNano(nano?: AdkNanoModelConfig): Promise + countTokens(text: string, nano?: AdkNanoModelConfig): Promise generateText( runId: string, @@ -122,6 +181,7 @@ export interface Spec extends TurboModule { tools?: AdkTool[] ): Promise + /** Cancels a stream or a `generateText` run by its id */ cancelStream(streamId: string): Promise submitToolResult(toolCallId: string, result: string): void @@ -130,6 +190,7 @@ export interface Spec extends TurboModule { onStreamError: CodegenTypes.EventEmitter onStreamToolCall: CodegenTypes.EventEmitter onToolCall: CodegenTypes.EventEmitter + onNanoDownloadProgress: CodegenTypes.EventEmitter } declare global { @@ -148,9 +209,11 @@ export default NativeAdkEngine export function getNativeAdkEngine(): Spec { if (!NativeAdkEngine) { - throw new Error( + const error = new Error( '@react-native-ai/adk is only available on Android. See https://developer.android.com/ai/adk' - ) + ) as Error & { code: string } + error.code = 'UNSUPPORTED_PLATFORM' + throw error } return NativeAdkEngine } diff --git a/packages/adk/src/__tests__/ai-sdk.test.ts b/packages/adk/src/__tests__/ai-sdk.test.ts index 17490adc3..654eb6a6a 100644 --- a/packages/adk/src/__tests__/ai-sdk.test.ts +++ b/packages/adk/src/__tests__/ai-sdk.test.ts @@ -4,6 +4,31 @@ import type { } from '@ai-sdk/provider' import { beforeEach, describe, expect, mock, test } from 'bun:test' +type Listener = (event: any) => void + +function createEmitter() { + const listeners = new Set() + const subscribe = (listener: Listener) => { + listeners.add(listener) + return { remove: () => listeners.delete(listener) } + } + subscribe.emit = (event: unknown) => { + for (const listener of listeners) listener(event) + } + return subscribe +} + +const onStreamUpdate = createEmitter() +const onStreamComplete = createEmitter() +const onStreamError = createEmitter() +const onStreamToolCall = createEmitter() +const onNanoDownloadProgress = createEmitter() + +let generateTextResult: Record = { + content: 'ok', + finishReason: 'STOP', +} + const generateText = mock( async ( _runId: string, @@ -11,27 +36,48 @@ const generateText = mock( _config: unknown, _options: unknown, _tools: unknown - ) => ({ content: 'ok', finishReason: 'STOP' }) + ): Promise> => generateTextResult ) +const streamText = mock( + async ( + _streamId: string, + _messages: unknown[], + _config: unknown, + _options: unknown, + _tools: unknown + ) => {} +) +const prepareNano = mock(async (_nano?: unknown) => {}) +const cancelStream = mock(async (_id: string) => {}) +const getModelInfo = mock(async (_modelType: string, _nano?: unknown) => ({ + availability: 'downloadable', +})) mock.module('react-native', () => ({ Platform: { OS: 'android' }, TurboModuleRegistry: { getEnforcing: () => ({ generateText, - streamText: async () => {}, + streamText, + prepareNano, + cancelStream, + getModelInfo, + isNanoSupported: async () => true, + isAvailable: async () => true, onToolCall: () => ({ remove: () => {} }), - onStreamUpdate: () => ({ remove: () => {} }), - onStreamToolCall: () => ({ remove: () => {} }), - onStreamComplete: () => ({ remove: () => {} }), - onStreamError: () => ({ remove: () => {} }), + onStreamUpdate, + onStreamToolCall, + onStreamComplete, + onStreamError, + onNanoDownloadProgress, }), }, })) const { createAdkProvider } = await import('../ai-sdk') -const model = createAdkProvider({ modelType: 'gemini' })() +const gemini = createAdkProvider({ modelType: 'gemini' })() +const nano = createAdkProvider()() // PNG signature followed by padding bytes const pngBytes = new Uint8Array([ @@ -47,13 +93,79 @@ function createCallOptions( } } +const lastGenerateCall = () => generateText.mock.calls.at(-1)! + +async function readAll(stream: ReadableStream) { + const parts: LanguageModelV4StreamPart[] = [] + const reader = stream.getReader() + while (true) { + const { done, value } = await reader.read() + if (done) return parts + parts.push(value) + } +} + +// Starts a stream, then plays native events once the native call is made +async function runStream( + options: LanguageModelV4CallOptions, + play: (streamId: string) => void, + model = gemini +) { + streamText.mockImplementationOnce(async (streamId: string) => { + queueMicrotask(() => play(streamId)) + }) + const { stream } = await model.doStream(options) + return readAll(stream) +} + beforeEach(() => { generateText.mockClear() + streamText.mockClear() + prepareNano.mockClear() + cancelStream.mockClear() + generateTextResult = { content: 'ok', finishReason: 'STOP' } }) -describe('adk prompt conversion', () => { +describe('model resolution', () => { + test('defaults to on-device Gemini Nano', () => { + expect(nano.modelId).toBe('gemini-nano') + }) + + test('defaults cloud Gemini to gemini-2.5-flash', () => { + expect(gemini.modelId).toBe('gemini-2.5-flash') + }) + + test('infers cloud Gemini from a model name', async () => { + const model = createAdkProvider()('gemini-2.5-pro') + await model.doGenerate(createCallOptions()) + + expect(lastGenerateCall()[2]).toMatchObject({ + model: { type: 'gemini', name: 'gemini-2.5-pro' }, + }) + }) + + test('per-model options override provider defaults', () => { + const provider = createAdkProvider({ instruction: 'Be brief.' }) + expect(provider({ modelName: 'gemini-2.5-pro' }).modelId).toBe( + 'gemini-2.5-pro' + ) + expect(provider.languageModel().modelId).toBe('gemini-nano') + }) + + test('reports model availability', async () => { + expect(await createAdkProvider().getModelInfo()).toEqual({ + modelType: 'genai-nano', + modelName: 'gemini-nano', + availability: 'downloadable', + baseModelName: undefined, + contextSize: undefined, + }) + }) +}) + +describe('prompt conversion', () => { test('resolves top-level file media types to a full mime type', async () => { - await model.doGenerate( + await gemini.doGenerate( createCallOptions({ prompt: [ { @@ -71,7 +183,7 @@ describe('adk prompt conversion', () => { }) ) - expect(generateText.mock.calls.at(-1)![1]).toEqual([ + expect(lastGenerateCall()[1]).toEqual([ { role: 'user', parts: [ @@ -85,70 +197,405 @@ describe('adk prompt conversion', () => { }, ]) }) + + test('passes local image URLs to native code', async () => { + await gemini.doGenerate( + createCallOptions({ + prompt: [ + { + role: 'user', + content: [ + { + type: 'file', + mediaType: 'image/jpeg', + data: { type: 'url', url: new URL('file:///tmp/cat.jpg') }, + }, + ], + }, + ], + }) + ) + + expect(lastGenerateCall()[1]).toEqual([ + { + role: 'user', + parts: [ + { type: 'file', mimeType: 'image/jpeg', uri: 'file:///tmp/cat.jpg' }, + ], + }, + ]) + }) + + test('replays earlier tool steps as assistant text', async () => { + await gemini.doGenerate( + createCallOptions({ + prompt: [ + { role: 'user', content: [{ type: 'text', text: 'time?' }] }, + { + role: 'assistant', + content: [ + { + type: 'tool-call', + toolCallId: '1', + toolName: 'getTime', + input: { city: 'Warsaw' }, + }, + { + type: 'tool-result', + toolCallId: '1', + toolName: 'getTime', + output: { type: 'json', value: { time: '10:00' } }, + }, + { type: 'text', text: 'It is 10:00.' }, + ], + }, + { role: 'user', content: [{ type: 'text', text: 'thanks' }] }, + ], + }) + ) + + expect(lastGenerateCall()[1][1]).toEqual({ + role: 'assistant', + content: + '[Tool call: getTime({"city":"Warsaw"})]\n[Tool result for getTime: {"time":"10:00"}]\nIt is 10:00.', + }) + }) }) -const reasoningWarning = { - type: 'unsupported', - feature: 'reasoning', - details: 'ADK models do not support configuring reasoning.', +const weatherTool = { + type: 'function' as const, + name: 'getWeather', + inputSchema: { + type: 'object' as const, + properties: { city: { type: 'string' } }, + required: ['city'], + }, } -async function readFirstPart( - stream: ReadableStream -) { - const { value } = await stream.getReader().read() - return value -} +describe('tool choice', () => { + test('sends no tools for toolChoice none', async () => { + await gemini.doGenerate( + createCallOptions({ tools: [weatherTool], toolChoice: { type: 'none' } }) + ) + + expect(lastGenerateCall()[4]).toEqual([]) + }) -describe('adk language model warnings', () => { - test('warns that reasoning is unsupported in doGenerate', async () => { - const result = await model.doGenerate( - createCallOptions({ reasoning: 'high' }) + test('warns that required tool choice is unsupported', async () => { + const result = await gemini.doGenerate( + createCallOptions({ toolChoice: { type: 'required' } }) ) - expect(result.warnings).toEqual([reasoningWarning]) + expect(result.warnings).toEqual([ + { + type: 'unsupported', + feature: 'toolChoice', + details: + 'ADK runs tools natively and cannot be required to call a tool.', + }, + ]) + }) + + test('limits tools to the chosen tool', async () => { + await gemini.doGenerate( + createCallOptions({ + tools: [weatherTool, { ...weatherTool, name: 'getTime' }], + toolChoice: { type: 'tool', toolName: 'getTime' }, + }) + ) + + expect( + (lastGenerateCall()[4] as { name: string }[]).map((tool) => tool.name) + ).toEqual(['getTime']) }) - test('warns that reasoning is unsupported in doStream', async () => { - const { stream } = await model.doStream( - createCallOptions({ reasoning: 'high' }) + test('warns when a tool has no registered executor', async () => { + const result = await gemini.doGenerate( + createCallOptions({ tools: [weatherTool] }) ) - expect(await readFirstPart(stream)).toEqual({ - type: 'stream-start', - warnings: [reasoningWarning], + expect(result.warnings).toContainEqual({ + type: 'other', + message: + 'Tool "getWeather" has no executor. Pass it to createAdkProvider via availableTools so ADK can run it.', + }) + }) +}) + +describe('generation options', () => { + test('maps reasoning levels to a thinking budget', async () => { + await gemini.doGenerate(createCallOptions({ reasoning: 'high' })) + + expect(lastGenerateCall()[3]).toMatchObject({ + thinking: { includeThoughts: true, budget: 24576 }, }) }) - test('does not warn for provider-default reasoning', async () => { - const result = await model.doGenerate( - createCallOptions({ reasoning: 'provider-default' }) + test('disables thinking for reasoning none', async () => { + await gemini.doGenerate(createCallOptions({ reasoning: 'none' })) + + expect(lastGenerateCall()[3]).toMatchObject({ + thinking: { includeThoughts: false, budget: 0 }, + }) + }) + + test('leaves thinking to the model by default', async () => { + await gemini.doGenerate(createCallOptions()) + + expect((lastGenerateCall()[3] as { thinking?: unknown }).thinking).toBe( + undefined ) + }) - expect(result.warnings).toEqual([]) + test('passes a response schema to cloud Gemini', async () => { + const schema = { type: 'object', properties: { name: { type: 'string' } } } + await gemini.doGenerate( + createCallOptions({ responseFormat: { type: 'json', schema } }) + ) + + expect(lastGenerateCall()[3]).toMatchObject({ + responseFormat: { type: 'json', schema }, + }) + }) + + test('puts the response schema in the Gemini Nano instruction', async () => { + const schema = { type: 'object', properties: { name: { type: 'string' } } } + await nano.doGenerate( + createCallOptions({ responseFormat: { type: 'json', schema } }) + ) + + const [, , config, options] = lastGenerateCall() as [ + string, + unknown, + { instruction: string }, + { responseFormat: { schema?: unknown } }, + ] + expect(config.instruction).toContain(JSON.stringify(schema)) + expect(options.responseFormat.schema).toBe(undefined) + }) + + test('warns about settings Gemini Nano ignores', async () => { + const result = await nano.doGenerate( + createCallOptions({ topP: 0.5, stopSequences: ['END'] }) + ) + + expect( + result.warnings.map((warning) => 'feature' in warning && warning.feature) + ).toEqual(['topP', 'stopSequences']) }) }) -describe('reasoning none and tool choice warnings', () => { - test('does not warn for reasoning none', async () => { - const result = await model.doGenerate( - createCallOptions({ reasoning: 'none' }) +describe('doGenerate results', () => { + test('returns reasoning, provider-executed tool steps and text', async () => { + generateTextResult = { + content: 'It is sunny.', + reasoning: 'Check the weather.', + toolCalls: [ + { toolCallId: '1', toolName: 'getWeather', input: '{"city":"Oslo"}' }, + ], + toolResults: [ + { toolCallId: '1', toolName: 'getWeather', output: '{"sky":"clear"}' }, + ], + finishReason: 'STOP', + usage: { + promptTokenCount: 10, + candidatesTokenCount: 5, + thoughtsTokenCount: 3, + cachedContentTokenCount: 4, + }, + } + + const result = await gemini.doGenerate(createCallOptions()) + + expect(result.content).toEqual([ + { type: 'reasoning', text: 'Check the weather.' }, + { + type: 'tool-call', + toolCallId: '1', + toolName: 'getWeather', + input: '{"city":"Oslo"}', + providerExecuted: true, + }, + { + type: 'tool-result', + toolCallId: '1', + toolName: 'getWeather', + result: { sky: 'clear' }, + }, + { type: 'text', text: 'It is sunny.' }, + ]) + expect(result.usage.inputTokens).toEqual({ + total: 10, + noCache: 6, + cacheRead: 4, + cacheWrite: undefined, + }) + expect(result.usage.outputTokens).toEqual({ + total: 8, + text: 5, + reasoning: 3, + }) + }) + + test('strips Markdown fences from JSON output', async () => { + generateTextResult = { content: '```json\n{"a":1}\n```' } + + const result = await nano.doGenerate( + createCallOptions({ responseFormat: { type: 'json' } }) ) - expect(result.warnings).toEqual([]) + expect(result.content).toEqual([{ type: 'text', text: '{"a":1}' }]) }) - test('warns that required tool choice is unsupported', async () => { - const result = await model.doGenerate( - createCallOptions({ toolChoice: { type: 'required' } }) + test('maps safety finish reasons to content-filter', async () => { + generateTextResult = { content: '', finishReason: 'SAFETY' } + + const result = await gemini.doGenerate(createCallOptions()) + + expect(result.finishReason).toEqual({ + unified: 'content-filter', + raw: 'SAFETY', + }) + }) + + test('attaches error codes to native rejections', async () => { + generateText.mockImplementationOnce(async () => { + throw Object.assign(new Error('busy'), { code: 'RATE_LIMITED' }) + }) + + expect(gemini.doGenerate(createCallOptions())).rejects.toMatchObject({ + message: 'busy', + code: 'RATE_LIMITED', + }) + }) + + test('cancels the native run when aborted', async () => { + const controller = new AbortController() + generateText.mockImplementationOnce(async () => { + controller.abort() + throw new Error('cancelled') + }) + + const error = await gemini + .doGenerate(createCallOptions({ abortSignal: controller.signal })) + .catch((caught: unknown) => caught) + + expect(error).toBe(controller.signal.reason) + expect(cancelStream).toHaveBeenCalledTimes(1) + }) +}) + +describe('doStream', () => { + test('streams reasoning, tool steps and text', async () => { + const parts = await runStream(createCallOptions(), (streamId) => { + onStreamUpdate.emit({ streamId, delta: 'Thinking', kind: 'reasoning' }) + onStreamToolCall.emit({ + streamId, + phase: 'start', + toolCallId: '1', + toolName: 'getWeather', + }) + onStreamToolCall.emit({ + streamId, + phase: 'end', + toolCallId: '1', + toolName: 'getWeather', + input: '{}', + }) + onStreamToolCall.emit({ + streamId, + phase: 'result', + toolCallId: '1', + toolName: 'getWeather', + output: '{"sky":"clear"}', + }) + onStreamUpdate.emit({ streamId, delta: 'Sunny', kind: 'text' }) + onStreamComplete.emit({ streamId, finishReason: 'STOP' }) + }) + + expect(parts.map((part) => part.type)).toEqual([ + 'stream-start', + 'reasoning-start', + 'reasoning-delta', + 'reasoning-end', + 'tool-input-start', + 'tool-input-end', + 'tool-call', + 'tool-result', + 'text-start', + 'text-delta', + 'text-end', + 'finish', + ]) + expect(parts).toContainEqual({ + type: 'tool-result', + toolCallId: '1', + toolName: 'getWeather', + result: { sky: 'clear' }, + }) + }) + + test('streams JSON without Markdown fences', async () => { + const parts = await runStream( + createCallOptions({ responseFormat: { type: 'json' } }), + (streamId) => { + for (const delta of ['``', '`json\n{"a"', ':1}', '\n`', '``']) { + onStreamUpdate.emit({ streamId, delta }) + } + onStreamComplete.emit({ streamId }) + }, + nano ) - expect(result.warnings).toEqual([ + const text = parts + .flatMap((part) => (part.type === 'text-delta' ? [part.delta] : [])) + .join('') + expect(text).toBe('{"a":1}') + }) + + test('surfaces native stream errors with their code', async () => { + const parts = await runStream(createCallOptions(), (streamId) => { + onStreamError.emit({ + streamId, + error: 'Too long', + code: 'CONTEXT_WINDOW_EXCEEDED', + }) + }) + + expect(parts.at(-1)).toMatchObject({ + type: 'error', + error: { message: 'Too long', code: 'CONTEXT_WINDOW_EXCEEDED' }, + }) + }) +}) + +describe('Gemini Nano preparation', () => { + test('reports download progress', async () => { + const provider = createAdkProvider() + const progress: unknown[] = [] + prepareNano.mockImplementationOnce(async () => { + onNanoDownloadProgress.emit({ phase: 'started', bytesToDownload: 100 }) + onNanoDownloadProgress.emit({ phase: 'completed' }) + }) + + await provider.prepareNano({ onProgress: (event) => progress.push(event) }) + + expect(progress).toEqual([ + { phase: 'started', bytesDownloaded: undefined, bytesToDownload: 100 }, { - type: 'unsupported', - feature: 'toolChoice', - details: 'ADK models only support auto and none tool choices.', + phase: 'completed', + bytesDownloaded: undefined, + bytesToDownload: undefined, }, ]) }) + + test('passes the model selection to native code', async () => { + const provider = createAdkProvider({ nano: { releaseStage: 'preview' } }) + await provider().prepare() + + expect(prepareNano.mock.calls.at(-1)![0]).toEqual({ + releaseStage: 'preview', + }) + }) }) diff --git a/packages/adk/src/ai-sdk.ts b/packages/adk/src/ai-sdk.ts index 079e1505c..e0ea49dc1 100644 --- a/packages/adk/src/ai-sdk.ts +++ b/packages/adk/src/ai-sdk.ts @@ -1,6 +1,8 @@ import type { + JSONValue, LanguageModelV4, LanguageModelV4CallOptions, + LanguageModelV4Content, LanguageModelV4FilePart, LanguageModelV4FinishReason, LanguageModelV4FunctionTool, @@ -12,7 +14,6 @@ import type { } from '@ai-sdk/provider' import { generateId, - isCustomReasoning, jsonSchema, parseJSON, resolveFullMediaType, @@ -21,133 +22,362 @@ import { } from '@ai-sdk/provider-utils' import { Platform } from 'react-native' +import { AdkErrorCodes, createAdkError, toAdkError } from './errors' import { type AdkAgentConfig, type AdkGenerationOptions, type AdkMessage, type AdkMessagePart, type AdkModelType, + type AdkNanoModelConfig, type AdkTool, type AdkToolParameter, type AdkUsageMetadata, getNativeAdkEngine, + type NanoDownloadProgressEvent, type StreamToolCallEvent, type ToolCallEvent, } from './NativeAdkEngine' -export interface AdkProviderOptions { +const DEFAULT_NANO_MODEL = 'gemini-nano' +const DEFAULT_GEMINI_MODEL = 'gemini-2.5-flash' + +export type AdkToolDefinitionSet = Record + +/** `gemini-nano` runs on device, any other name is a cloud Gemini model */ +export type AdkLanguageModelId = 'gemini-nano' | (string & {}) + +export interface AdkLanguageModelOptions { + /** Defaults to `genai-nano`, or `gemini` when `modelName` names a cloud model */ + modelType?: AdkModelType + /** Defaults to `gemini-nano` on device and `gemini-2.5-flash` in the cloud */ + modelName?: AdkLanguageModelId + /** ADK agent name */ name?: string + /** ADK agent description */ description?: string + /** System instruction for the agent */ instruction?: string - modelType?: AdkModelType - modelName?: string + /** Gemini API key, required for `gemini` */ apiKey?: string - availableTools?: Record + /** Tools whose `execute` handlers ADK can call */ + availableTools?: AdkToolDefinitionSet + /** Gemini Nano model selection */ + nano?: AdkNanoModelConfig } -/** - * Whether the device can support on-device Gemini Nano at all - * (ML Kit `checkStatus !== 0`). Does not download models. - */ -async function checkNanoSupported(): Promise { - if (Platform.OS !== 'android') { - return false - } +/** Per-call options passed as `providerOptions.adk` */ +export interface AdkProviderOptions { + /** Thinking token budget for cloud Gemini. `0` disables thinking */ + thinkingBudget?: number + /** Whether the model's thoughts come back as reasoning parts */ + includeThoughts?: boolean +} + +export type AdkModelAvailability = + | 'available' + | 'downloadable' + | 'downloading' + | 'unavailable' + | 'unknown' + +export interface AdkModelInfo { + modelType: AdkModelType + modelName: string + availability: AdkModelAvailability + /** Name of the Gemini Nano base model, when ML Kit reports it */ + baseModelName?: string + /** Gemini Nano input token limit, when ML Kit reports it */ + contextSize?: number +} - return getNativeAdkEngine().isNanoSupported() +export interface AdkDownloadProgress { + phase: 'started' | 'progress' | 'completed' + bytesDownloaded?: number + bytesToDownload?: number +} + +export interface AdkPrepareOptions { + onProgress?: (progress: AdkDownloadProgress) => void +} + +export interface AdkLanguageModel extends LanguageModelV4 { + /** Downloads and initializes Gemini Nano. No-op for cloud models */ + prepare: () => Promise + updateTools: (tools: AdkToolDefinitionSet) => void + /** Counts tokens with the Gemini Nano tokenizer. Not available for cloud models */ + countTokens: (text: string) => Promise } export interface AdkProvider { - (): LanguageModelV4 + (options?: AdkLanguageModelId | AdkLanguageModelOptions): AdkLanguageModel readonly specificationVersion: 'v4' - languageModel: () => LanguageModelV4 - /** Device capability check (ML Kit `checkStatus !== 0`). Returns `false` on non-Android. */ + languageModel: ( + options?: AdkLanguageModelId | AdkLanguageModelOptions + ) => AdkLanguageModel + /** Whether the device can run Gemini Nano at all. Returns `false` on non-Android */ isNanoSupported: () => Promise /** - * Whether `modelType` can be used now. For `genai-nano`, checks ML Kit readiness - * (status 1 or 3). Returns `false` when {@link isNanoSupported} is `false`. - * Cloud `gemini` always resolves to `true` on Android. + * Whether `modelType` can be used now. For `genai-nano`, Gemini Nano must be + * available or downloadable. Cloud `gemini` resolves to `true` on Android */ isAvailable: (modelType?: AdkModelType) => Promise - /** Downloads and initializes on-device Gemini Nano. No-op for cloud models. */ - prepareNano: () => Promise + /** Availability details for a model type */ + getModelInfo: (options?: { + modelType?: AdkModelType + nano?: AdkNanoModelConfig + }) => Promise + /** Downloads and initializes Gemini Nano, reporting download progress */ + prepareNano: (options?: AdkPrepareOptions) => Promise +} + +type ResolvedModelOptions = Omit< + AdkLanguageModelOptions, + 'modelType' | 'modelName' +> & { + modelType: AdkModelType + modelName: string +} + +function resolveModelOptions( + defaults: AdkLanguageModelOptions, + options: AdkLanguageModelId | AdkLanguageModelOptions = {} +): ResolvedModelOptions { + const overrides = + typeof options === 'string' ? { modelName: options } : options + const merged = { ...defaults, ...overrides } + const modelType = + merged.modelType ?? + (merged.modelName && merged.modelName !== DEFAULT_NANO_MODEL + ? 'gemini' + : 'genai-nano') + const modelName = + merged.modelName ?? + (modelType === 'gemini' ? DEFAULT_GEMINI_MODEL : DEFAULT_NANO_MODEL) + + return { ...merged, modelType, modelName } +} + +const toModelAvailability = (value: string): AdkModelAvailability => { + switch (value) { + case 'available': + case 'downloadable': + case 'downloading': + case 'unavailable': + return value + default: + return 'unknown' + } +} + +async function prepareNano( + nano: AdkNanoModelConfig | undefined, + options: AdkPrepareOptions = {} +) { + const native = getNativeAdkEngine() + const listener = options.onProgress + ? native.onNanoDownloadProgress((event: NanoDownloadProgressEvent) => { + options.onProgress?.({ + phase: event.phase as AdkDownloadProgress['phase'], + bytesDownloaded: event.bytesDownloaded, + bytesToDownload: event.bytesToDownload, + }) + }) + : null + + try { + await native.prepareNano(nano) + } catch (error) { + throw toAdkError(error) + } finally { + listener?.remove() + } } export function createAdkProvider( - options: AdkProviderOptions = {} + defaults: AdkLanguageModelOptions = {} ): AdkProvider { - const createLanguageModel = () => new AdkChatLanguageModel(options) - const provider = function () { - return createLanguageModel() + const createLanguageModel = ( + options?: AdkLanguageModelId | AdkLanguageModelOptions + ): AdkLanguageModel => + new AdkChatLanguageModel(resolveModelOptions(defaults, options)) + + const provider = function ( + options?: AdkLanguageModelId | AdkLanguageModelOptions + ) { + return createLanguageModel(options) } provider.specificationVersion = 'v4' as const provider.languageModel = createLanguageModel - provider.isNanoSupported = () => checkNanoSupported() + provider.isNanoSupported = async () => { + if (Platform.OS !== 'android') { + return false + } + return getNativeAdkEngine().isNanoSupported(defaults.nano) + } provider.isAvailable = async (modelType: AdkModelType = 'genai-nano') => { - if (modelType === 'genai-nano' && !(await checkNanoSupported())) { + if (Platform.OS !== 'android') { return false } - return getNativeAdkEngine().isAvailable(modelType).then(Boolean) + return getNativeAdkEngine() + .isAvailable(modelType, defaults.nano) + .then(Boolean) + } + provider.getModelInfo = async ( + options: { modelType?: AdkModelType; nano?: AdkNanoModelConfig } = {} + ): Promise => { + const resolved = resolveModelOptions(defaults) + const { modelType, modelName } = + options.modelType && options.modelType !== resolved.modelType + ? resolveModelOptions({ modelType: options.modelType }) + : resolved + const nano = options.nano ?? defaults.nano + + if (Platform.OS !== 'android') { + return { modelType, modelName, availability: 'unavailable' } + } + + const info = await getNativeAdkEngine() + .getModelInfo(modelType, nano) + .catch((error: unknown) => { + throw toAdkError(error) + }) + return { + modelType, + modelName, + availability: toModelAvailability(info.availability), + baseModelName: info.baseModelName, + contextSize: info.contextSize, + } } - provider.prepareNano = () => getNativeAdkEngine().prepareNano() + provider.prepareNano = (options?: AdkPrepareOptions) => + prepareNano(defaults.nano, options) return provider } export const adk = createAdkProvider() type Tool = LanguageModelV4FunctionTool | LanguageModelV4ProviderTool -type ToolDefinitionSet = Record - -const createEmptyUsage = (): LanguageModelV4Usage => ({ - inputTokens: { - total: undefined, - noCache: undefined, - cacheRead: undefined, - cacheWrite: undefined, - }, - outputTokens: { - total: undefined, - text: undefined, - reasoning: undefined, - }, -}) -const mapUsage = (usage?: AdkUsageMetadata): LanguageModelV4Usage => { - if (!usage) { - return createEmptyUsage() +const toolChoiceWarning: SharedV4Warning = { + type: 'unsupported', + feature: 'toolChoice', + details: 'ADK runs tools natively and cannot be required to call a tool.', +} + +function prepareToolChoice( + tools: Tool[] = [], + toolChoice: LanguageModelV4CallOptions['toolChoice'] +): { tools: Tool[]; warnings: SharedV4Warning[] } { + switch (toolChoice?.type) { + case 'none': + return { tools: [], warnings: [] } + case 'required': + return { tools, warnings: [toolChoiceWarning] } + case 'tool': + return { + tools: tools.filter((tool) => tool.name === toolChoice.toolName), + warnings: [toolChoiceWarning], + } + default: + return { tools, warnings: [] } + } +} + +// Gemini thinking budgets for the AI SDK reasoning levels +const thinkingBudgets = { + minimal: 512, + low: 2048, + medium: 8192, + high: 24576, + xhigh: 24576, + max: 24576, +} as const + +function prepareThinking( + reasoning: LanguageModelV4CallOptions['reasoning'], + adkOptions: AdkProviderOptions +): AdkGenerationOptions['thinking'] { + if (adkOptions.thinkingBudget !== undefined) { + return { + includeThoughts: + adkOptions.includeThoughts ?? adkOptions.thinkingBudget !== 0, + budget: adkOptions.thinkingBudget, + } + } + + switch (reasoning) { + case undefined: + case 'provider-default': + return adkOptions.includeThoughts === undefined + ? undefined + : { includeThoughts: adkOptions.includeThoughts } + case 'none': + return { includeThoughts: false, budget: 0 } + default: + return { + includeThoughts: adkOptions.includeThoughts ?? true, + budget: thinkingBudgets[reasoning], + } } +} + +const mapUsage = (usage?: AdkUsageMetadata): LanguageModelV4Usage => { + const promptTokens = usage?.promptTokenCount + const cachedTokens = usage?.cachedContentTokenCount + const textTokens = usage?.candidatesTokenCount + const reasoningTokens = usage?.thoughtsTokenCount return { inputTokens: { - total: usage.promptTokenCount, - noCache: undefined, - cacheRead: undefined, + total: promptTokens, + noCache: + promptTokens !== undefined && cachedTokens !== undefined + ? promptTokens - cachedTokens + : undefined, + cacheRead: cachedTokens, cacheWrite: undefined, }, outputTokens: { - total: usage.candidatesTokenCount, - text: undefined, - reasoning: undefined, - }, - raw: { - promptTokenCount: usage.promptTokenCount, - candidatesTokenCount: usage.candidatesTokenCount, - totalTokenCount: usage.totalTokenCount, + // Gemini counts thoughts separately from candidates + total: + textTokens === undefined && reasoningTokens === undefined + ? undefined + : (textTokens ?? 0) + (reasoningTokens ?? 0), + text: textTokens, + reasoning: reasoningTokens, }, + raw: usage ? { ...usage } : undefined, } } +const contentFilterReasons = new Set([ + 'SAFETY', + 'RECITATION', + 'BLOCKLIST', + 'PROHIBITED_CONTENT', + 'SPII', + 'IMAGE_SAFETY', + 'IMAGE_PROHIBITED_CONTENT', + 'IMAGE_RECITATION', +]) + const convertFinishReason = ( finishReason?: string ): LanguageModelV4FinishReason => { let unified: LanguageModelV4FinishReason['unified'] = 'other' - if (finishReason === 'STOP' || finishReason === 'stop') { + if (finishReason === undefined || finishReason === 'STOP') { unified = 'stop' - } else if (finishReason === 'MAX_TOKENS' || finishReason === 'length') { + } else if (finishReason === 'MAX_TOKENS') { unified = 'length' - } else if (finishReason === 'tool_calls' || finishReason === 'TOOL_CALLS') { - unified = 'tool-calls' + } else if (contentFilterReasons.has(finishReason)) { + unified = 'content-filter' + } else if ( + finishReason === 'MALFORMED_FUNCTION_CALL' || + finishReason === 'UNEXPECTED_TOOL_CALL' + ) { + unified = 'error' } return { @@ -174,34 +404,6 @@ const schemaPropertyToAdkParameter = ( } } -const getCallWarnings = ( - options: LanguageModelV4CallOptions -): SharedV4Warning[] => { - const warnings: SharedV4Warning[] = [] - - // `none` is already what a model without reasoning control does - if (isCustomReasoning(options.reasoning) && options.reasoning !== 'none') { - warnings.push({ - type: 'unsupported', - feature: 'reasoning', - details: 'ADK models do not support configuring reasoning.', - }) - } - - if ( - options.toolChoice?.type === 'required' || - options.toolChoice?.type === 'tool' - ) { - warnings.push({ - type: 'unsupported', - feature: 'toolChoice', - details: 'ADK models only support auto and none tool choices.', - }) - } - - return warnings -} - const uint8ArrayToBase64 = (bytes: Uint8Array): string => { let binary = '' for (let index = 0; index < bytes.length; index++) { @@ -210,97 +412,151 @@ const uint8ArrayToBase64 = (bytes: Uint8Array): string => { return btoa(binary) } -const normalizeFilePart = ( - part: LanguageModelV4FilePart -): { data: string; mediaType: string } => { - if (part.data.type !== 'data') { - throw new Error( - 'ADK wrapper does not support file URLs or references yet. Pass base64 or Uint8Array data.' - ) +const localUrlProtocols = new Set(['file:', 'content:']) + +const toFileMessagePart = (part: LanguageModelV4FilePart): AdkMessagePart => { + // v4 allows top-level media types such as `image`, which Gemini rejects + const mimeType = resolveFullMediaType({ part }) + + switch (part.data.type) { + case 'data': + return { + type: 'file', + mimeType, + data: + typeof part.data.data === 'string' + ? part.data.data.replace(/^data:[^;]+;base64,/, '') + : uint8ArrayToBase64(part.data.data), + } + case 'url': + // The AI SDK downloads other URLs because they are not in `supportedUrls` + if (!localUrlProtocols.has(part.data.url.protocol)) { + throw createAdkError( + `ADK only reads file:// and content:// URLs. Got ${part.data.url.protocol}`, + AdkErrorCodes.InvalidMessage + ) + } + return { type: 'file', mimeType, uri: part.data.url.toString() } + case 'text': + return { type: 'text', text: part.data.text } + default: + throw createAdkError( + 'ADK does not support provider file references.', + AdkErrorCodes.InvalidMessage + ) } +} - const data = - typeof part.data.data === 'string' - ? part.data.data.replace(/^data:[^;]+;base64,/, '') - : uint8ArrayToBase64(part.data.data) +const getAbortReason = (signal: AbortSignal) => { + if (signal.reason !== undefined) { + return signal.reason + } + const error = new Error('The operation was aborted.') + error.name = 'AbortError' + return error +} - return { - data, - // v4 allows top-level media types such as `image`, which Gemini rejects - mediaType: resolveFullMediaType({ part }), +const stringifyToolOutput = (value: unknown) => + typeof value === 'string' ? value : JSON.stringify(value ?? null) + +// Gemini Nano often wraps JSON in a Markdown code fence +const jsonFencePrefix = /^\s*```(?:json)?\s*\n?/ +const stripJsonFences = (text: string) => + text.replace(jsonFencePrefix, '').replace(/\s*```\s*$/, '') + +const parseToolResult = (output: string): NonNullable => { + try { + return (JSON.parse(output) as JSONValue) ?? {} + } catch { + return output } } -class AdkChatLanguageModel implements LanguageModelV4 { +const createNanoJsonInstruction = (schema: unknown) => + schema + ? `Respond only with JSON that matches this JSON schema, without Markdown or other text:\n${JSON.stringify(schema)}` + : 'Respond only with valid JSON, without Markdown or other text.' + +class AdkChatLanguageModel implements AdkLanguageModel { readonly specificationVersion = 'v4' - readonly supportedUrls = {} + readonly supportedUrls = { + 'image/*': [/^file:\/\//, /^content:\/\//], + } readonly provider = 'adk' readonly modelId: string private readonly agentConfig: AdkAgentConfig - private tools: ToolDefinitionSet = {} + private tools: AdkToolDefinitionSet = {} private nanoPreparePromise: Promise | null = null - constructor(options: AdkProviderOptions) { - const modelType = options.modelType ?? 'genai-nano' - this.modelId = options.modelName ?? 'gemini-nano' + constructor(options: ResolvedModelOptions) { + this.modelId = options.modelName this.agentConfig = { name: options.name ?? 'react_native_adk_agent', description: options.description ?? 'React Native ADK agent', instruction: options.instruction, model: { - type: modelType, - name: this.modelId, + type: options.modelType, + name: options.modelName, apiKey: options.apiKey, + nano: options.nano, }, } this.updateTools(options.availableTools ?? {}) } - updateTools(tools: ToolDefinitionSet) { - this.tools = tools + private get isNano() { + return this.agentConfig.model.type === 'genai-nano' } - public isAvailable() { - return getNativeAdkEngine() - .isAvailable(this.agentConfig.model.type) - .then(Boolean) - } - - public prepareNano() { - return getNativeAdkEngine().prepareNano() + updateTools(tools: AdkToolDefinitionSet) { + this.tools = tools } async prepare(): Promise { await this.ensureNanoPrepared() } + async countTokens(text: string): Promise { + if (!this.isNano) { + throw createAdkError( + 'Token counting is only available for Gemini Nano.', + AdkErrorCodes.ModelUnavailable + ) + } + + try { + return await getNativeAdkEngine().countTokens( + text, + this.agentConfig.model.nano + ) + } catch (error) { + throw toAdkError(error) + } + } + private ensureNanoPrepared(): Promise { - if (this.agentConfig.model.type !== 'genai-nano') { + if (!this.isNano) { return Promise.resolve() } if (!this.nanoPreparePromise) { - this.nanoPreparePromise = checkNanoSupported() - .then((supported) => { - if (!supported) { - throw new Error( - 'Gemini Nano is not supported on this device or device has not fetched the latest configuration to support it' - ) - } - return getNativeAdkEngine().prepareNano() - }) - .catch((error) => { + this.nanoPreparePromise = prepareNano(this.agentConfig.model.nano).catch( + (error) => { this.nanoPreparePromise = null throw error - }) + } + ) } return this.nanoPreparePromise } - private prepareMessages(messages: LanguageModelV4Prompt): AdkMessage[] { + private prepareMessages( + messages: LanguageModelV4Prompt, + warnings: SharedV4Warning[] + ): AdkMessage[] { return messages.map((message): AdkMessage => { if (message.role === 'system') { return { @@ -310,19 +566,12 @@ class AdkChatLanguageModel implements LanguageModelV4 { } if (message.role === 'user') { - const parts = message.content - .map((part): AdkMessagePart | null => { - if (part.type === 'text') { - return { type: 'text', text: part.text } - } - if (part.type === 'file') { - const { data, mediaType } = normalizeFilePart(part) - return { type: 'file', mimeType: mediaType, data } - } - console.warn('Unsupported user message content type:', part) - return null - }) - .filter((part): part is AdkMessagePart => part !== null) + const parts = message.content.map((part): AdkMessagePart => { + if (part.type === 'text') { + return { type: 'text', text: part.text } + } + return toFileMessagePart(part) + }) if (parts.length === 1 && parts[0]?.type === 'text') { return { @@ -338,13 +587,34 @@ class AdkChatLanguageModel implements LanguageModelV4 { } if (message.role === 'assistant') { - const content = message.content.reduce((acc, part) => { - if (part.type === 'text') { - return acc + part.text - } - console.warn('Unsupported assistant message content type:', part) - return acc - }, '') + // ADK replays history as text, so earlier tool steps become text too + const content = message.content + .flatMap((part) => { + switch (part.type) { + case 'text': + return [part.text] + case 'tool-call': + return [ + `[Tool call: ${part.toolName}(${stringifyToolOutput(part.input)})]`, + ] + case 'tool-result': + return [ + `[Tool result for ${part.toolName}: ${stringifyToolOutput( + 'value' in part.output ? part.output.value : part.output + )}]`, + ] + case 'reasoning': + return [] + default: + warnings.push({ + type: 'unsupported', + feature: `assistant ${part.type} parts`, + details: 'ADK replays assistant messages as text only.', + }) + return [] + } + }) + .join('\n') return { role: 'assistant', @@ -359,9 +629,7 @@ class AdkChatLanguageModel implements LanguageModelV4 { if (part.output.type === 'execution-denied') { return part.output.reason ?? 'Execution denied' } - return typeof part.output.value === 'string' - ? part.output.value - : JSON.stringify(part.output.value) + return stringifyToolOutput(part.output.value) }) .join('\n') @@ -371,20 +639,54 @@ class AdkChatLanguageModel implements LanguageModelV4 { } } - throw new Error(`Unsupported message role for ADK provider`) + throw createAdkError( + 'Unsupported message role for ADK provider', + AdkErrorCodes.InvalidMessage + ) }) } - private prepareGenerationOptions( + private prepareAgentConfig( options: LanguageModelV4CallOptions + ): AdkAgentConfig { + // Gemini Nano has no response schema, so the schema goes in the instruction + if (!this.isNano || options.responseFormat?.type !== 'json') { + return this.agentConfig + } + + const instruction = [ + this.agentConfig.instruction, + createNanoJsonInstruction(options.responseFormat.schema), + ] + .filter(Boolean) + .join('\n\n') + + return { ...this.agentConfig, instruction } + } + + private prepareGenerationOptions( + options: LanguageModelV4CallOptions, + warnings: SharedV4Warning[] ): AdkGenerationOptions { - if ( - options.responseFormat?.type === 'json' && - options.responseFormat.schema - ) { - throw new Error( - 'ADK does not support responseFormat.schema yet. Use JSON mode without a schema or omit responseFormat.' - ) + const adkOptions = (options.providerOptions?.adk ?? + {}) as AdkProviderOptions + + if (this.isNano) { + const unsupported = { + topP: options.topP, + stopSequences: options.stopSequences, + presencePenalty: options.presencePenalty, + frequencyPenalty: options.frequencyPenalty, + } + for (const [feature, value] of Object.entries(unsupported)) { + if (value !== undefined) { + warnings.push({ + type: 'unsupported', + feature, + details: 'Gemini Nano does not support this setting.', + }) + } + } } return { @@ -392,19 +694,34 @@ class AdkChatLanguageModel implements LanguageModelV4 { maxTokens: options.maxOutputTokens, topP: options.topP, topK: options.topK, + seed: options.seed, + stopSequences: options.stopSequences, + presencePenalty: options.presencePenalty, + frequencyPenalty: options.frequencyPenalty, responseFormat: options.responseFormat?.type === 'json' ? { type: 'json', mimeType: 'application/json', + schema: this.isNano ? undefined : options.responseFormat.schema, } : undefined, + thinking: prepareThinking(options.reasoning, adkOptions), } } - private prepareTools(tools: Tool[] = []) { + private prepareTools(tools: Tool[], warnings: SharedV4Warning[]) { return tools - .filter((tool) => tool.type === 'function') + .filter((tool): tool is LanguageModelV4FunctionTool => { + if (tool.type === 'function') { + return true + } + warnings.push({ + type: 'unsupported', + feature: `provider-defined tool ${tool.name}`, + }) + return false + }) .map((tool) => { const required = Array.isArray(tool.inputSchema.required) ? tool.inputSchema.required @@ -417,6 +734,13 @@ class AdkChatLanguageModel implements LanguageModelV4 { const schema = jsonSchema(tool.inputSchema) + if (!this.tools[tool.name]?.execute) { + warnings.push({ + type: 'other', + message: `Tool "${tool.name}" has no executor. Pass it to createAdkProvider via availableTools so ADK can run it.`, + }) + } + return { native: { id: generateId(), @@ -426,6 +750,13 @@ class AdkChatLanguageModel implements LanguageModelV4 { parameters, } satisfies AdkTool, execute: async (modelInput: unknown) => { + const execute = this.tools[tool.name]?.execute + if (!execute) { + return { + error: `Tool "${tool.name}" is not available in this app.`, + } + } + const text = typeof modelInput === 'string' ? modelInput @@ -439,12 +770,32 @@ class AdkChatLanguageModel implements LanguageModelV4 { messages: [], context: undefined, } - return this.tools[tool.name]?.execute?.(toolCallArguments, opts) + return execute(toolCallArguments, opts) }, } }) } + private prepareCall(options: LanguageModelV4CallOptions) { + const { tools, warnings } = prepareToolChoice( + options.tools, + options.toolChoice + ) + const messages = this.prepareMessages(options.prompt, warnings) + const generationOptions = this.prepareGenerationOptions(options, warnings) + const preparedTools = this.prepareTools(tools, warnings) + + return { + messages, + generationOptions, + preparedTools, + nativeTools: preparedTools.map((tool) => tool.native), + ownedToolIds: new Set(preparedTools.map((tool) => tool.native.id)), + agentConfig: this.prepareAgentConfig(options), + warnings, + } + } + private registerTools( preparedTools: ReturnType ) { @@ -508,52 +859,105 @@ class AdkChatLanguageModel implements LanguageModelV4 { } async doGenerate(options: LanguageModelV4CallOptions) { - const messages = this.prepareMessages(options.prompt) - const generationOptions = this.prepareGenerationOptions(options) - const preparedTools = this.prepareTools(options.tools) - const nativeTools = preparedTools.map((tool) => tool.native) - const ownedToolIds = new Set(preparedTools.map((tool) => tool.native.id)) + const { + messages, + generationOptions, + preparedTools, + nativeTools, + ownedToolIds, + agentConfig, + warnings, + } = this.prepareCall(options) const runId = generateId() + const native = getNativeAdkEngine() + const abortSignal = options.abortSignal + + if (abortSignal?.aborted) { + throw getAbortReason(abortSignal) + } + + const onAbort = () => { + void native + .cancelStream(runId) + .catch((error) => console.warn('[adk] cancel failed:', error)) + } this.registerTools(preparedTools) const toolListener = this.createToolCallListener({ runId, ownedToolIds }) + abortSignal?.addEventListener('abort', onAbort, { once: true }) try { await this.ensureNanoPrepared() - const response = await getNativeAdkEngine().generateText( + const response = await native.generateText( runId, messages, - this.agentConfig, + agentConfig, generationOptions, nativeTools ) + const content: LanguageModelV4Content[] = [] + if (response.reasoning) { + content.push({ type: 'reasoning', text: response.reasoning }) + } + for (const toolCall of response.toolCalls ?? []) { + content.push({ + type: 'tool-call', + toolCallId: toolCall.toolCallId, + toolName: toolCall.toolName, + input: toolCall.input, + providerExecuted: true, + }) + } + for (const toolResult of response.toolResults ?? []) { + content.push({ + type: 'tool-result', + toolCallId: toolResult.toolCallId, + toolName: toolResult.toolName, + result: parseToolResult(toolResult.output), + }) + } + content.push({ + type: 'text', + text: + options.responseFormat?.type === 'json' + ? stripJsonFences(response.content) + : response.content, + }) + return { - content: [{ type: 'text' as const, text: response.content }], + content, finishReason: convertFinishReason(response.finishReason), usage: mapUsage(response.usage), - warnings: getCallWarnings(options), + warnings, + } + } catch (error) { + if (abortSignal?.aborted) { + throw getAbortReason(abortSignal) } + throw toAdkError(error) } finally { + abortSignal?.removeEventListener('abort', onAbort) toolListener.remove() this.unregisterTools(preparedTools) } } async doStream(options: LanguageModelV4CallOptions) { - const messages = this.prepareMessages(options.prompt) - const generationOptions = this.prepareGenerationOptions(options) - const preparedTools = this.prepareTools(options.tools) - const nativeTools = preparedTools.map((tool) => tool.native) - const agentConfig = this.agentConfig + const { + messages, + generationOptions, + preparedTools, + nativeTools, + ownedToolIds, + agentConfig, + warnings, + } = this.prepareCall(options) const streamId = generateId() - const ownedToolIds = new Set(preparedTools.map((tool) => tool.native.id)) - const warnings = getCallWarnings(options) - - if (options.responseFormat?.type === 'json') { - throw new Error('Streaming JSON responses is not yet supported by ADK.') - } + const native = getNativeAdkEngine() + const abortSignal = options.abortSignal + const isJson = options.responseFormat?.type === 'json' if (typeof ReadableStream === 'undefined') { throw new Error( @@ -561,11 +965,18 @@ class AdkChatLanguageModel implements LanguageModelV4 { ) } + if (abortSignal?.aborted) { + throw getAbortReason(abortSignal) + } + this.registerTools(preparedTools) let listeners: { remove(): void }[] = [] let cleanedUp = false const toolListener = this.createToolCallListener({ streamId, ownedToolIds }) + const toolNames = new Map() + + let onAbort = () => {} const cleanup = () => { if (cleanedUp) { @@ -576,37 +987,112 @@ class AdkChatLanguageModel implements LanguageModelV4 { listener.remove() }) listeners = [] + abortSignal?.removeEventListener('abort', onAbort) toolListener.remove() this.unregisterTools(preparedTools) } + const cancelNative = () => { + void native + .cancelStream(streamId) + .catch((error) => console.warn('[adk] cancelStream failed:', error)) + } + const stream = new ReadableStream({ start: async (controller) => { - controller.enqueue({ type: 'stream-start', warnings }) + const textId = `${streamId}-text` + let textOpen = false + let reasoningId: string | undefined + let reasoningCount = 0 + // JSON mode keeps the full text so code fences can be stripped + let rawText = '' + let emittedText = '' const addListener = (listener: { remove(): void }) => { listeners.push(listener) } + const closeReasoning = () => { + if (reasoningId) { + controller.enqueue({ type: 'reasoning-end', id: reasoningId }) + reasoningId = undefined + } + } + + const emitText = (delta: string) => { + if (!delta) { + return + } + closeReasoning() + if (!textOpen) { + controller.enqueue({ type: 'text-start', id: textId }) + textOpen = true + } + controller.enqueue({ type: 'text-delta', id: textId, delta }) + } + + const emitJsonText = (final: boolean) => { + const stripped = final + ? stripJsonFences(rawText) + : // Hold back trailing backticks that could start a closing fence + rawText.replace(jsonFencePrefix, '').replace(/\s*`{1,3}$/, '') + // Only emit once the opening fence can no longer change the prefix + if (!final && /^\s*`{0,3}(j(s(o(n)?)?)?)?$/.test(rawText)) { + return + } + if (stripped.startsWith(emittedText)) { + emitText(stripped.slice(emittedText.length)) + emittedText = stripped + } + } + + controller.enqueue({ type: 'stream-start', warnings }) + + onAbort = () => { + cleanup() + cancelNative() + controller.error(abortSignal && getAbortReason(abortSignal)) + } + abortSignal?.addEventListener('abort', onAbort, { once: true }) + addListener( - getNativeAdkEngine().onStreamUpdate((data) => { - if (data.streamId === streamId && data.delta) { + native.onStreamUpdate((data) => { + if (data.streamId !== streamId || !data.delta) { + return + } + + if (data.kind === 'reasoning') { + if (!reasoningId) { + reasoningId = `${streamId}-reasoning-${reasoningCount++}` + controller.enqueue({ type: 'reasoning-start', id: reasoningId }) + } controller.enqueue({ - type: 'text-delta', + type: 'reasoning-delta', + id: reasoningId, delta: data.delta, - id: streamId, }) + return } + + if (isJson) { + rawText += data.delta + emitJsonText(false) + return + } + + emitText(data.delta) }) ) addListener( - getNativeAdkEngine().onStreamToolCall((data: StreamToolCallEvent) => { + native.onStreamToolCall((data: StreamToolCallEvent) => { if (data.streamId !== streamId) { return } if (data.phase === 'start' && data.toolName) { + closeReasoning() + toolNames.set(data.toolCallId, data.toolName) controller.enqueue({ type: 'tool-input-start', id: data.toolCallId, @@ -637,34 +1123,49 @@ class AdkChatLanguageModel implements LanguageModelV4 { input: data.input, providerExecuted: true, }) + return + } + + if (data.phase === 'result' && data.output !== undefined) { + controller.enqueue({ + type: 'tool-result', + toolCallId: data.toolCallId, + toolName: + data.toolName ?? toolNames.get(data.toolCallId) ?? 'unknown', + result: parseToolResult(data.output), + }) } }) ) addListener( - getNativeAdkEngine().onStreamComplete((data) => { - if (data.streamId === streamId) { - controller.enqueue({ - type: 'text-end', - id: streamId, - }) - controller.enqueue({ - type: 'finish', - finishReason: convertFinishReason(data.finishReason), - usage: mapUsage(data.usage), - }) - cleanup() - controller.close() + native.onStreamComplete((data) => { + if (data.streamId !== streamId) { + return + } + if (isJson) { + emitJsonText(true) + } + closeReasoning() + if (textOpen) { + controller.enqueue({ type: 'text-end', id: textId }) } + controller.enqueue({ + type: 'finish', + finishReason: convertFinishReason(data.finishReason), + usage: mapUsage(data.usage), + }) + cleanup() + controller.close() }) ) addListener( - getNativeAdkEngine().onStreamError((data) => { + native.onStreamError((data) => { if (data.streamId === streamId) { controller.enqueue({ type: 'error', - error: new Error(data.error), + error: toAdkError(data.error, data.code), }) cleanup() controller.close() @@ -675,12 +1176,7 @@ class AdkChatLanguageModel implements LanguageModelV4 { try { await this.ensureNanoPrepared() - controller.enqueue({ - type: 'text-start', - id: streamId, - }) - - await getNativeAdkEngine().streamText( + await native.streamText( streamId, messages, agentConfig, @@ -689,15 +1185,12 @@ class AdkChatLanguageModel implements LanguageModelV4 { ) } catch (error) { cleanup() - const message = error instanceof Error ? error.message : String(error) - controller.error(new Error(`ADK stream failed: ${message}`)) + controller.error(toAdkError(error)) } }, cancel: () => { cleanup() - void getNativeAdkEngine() - .cancelStream(streamId) - .catch((error) => console.warn('[adk] cancelStream failed:', error)) + cancelNative() }, }) diff --git a/packages/adk/src/errors.ts b/packages/adk/src/errors.ts new file mode 100644 index 000000000..7b76f30d7 --- /dev/null +++ b/packages/adk/src/errors.ts @@ -0,0 +1,49 @@ +export type AdkError = Error & { + code: AdkErrorCode +} + +export const AdkErrorCodes = { + UnsupportedPlatform: 'UNSUPPORTED_PLATFORM', + ModelUnavailable: 'MODEL_UNAVAILABLE', + ModelDownloading: 'MODEL_DOWNLOADING', + DownloadFailed: 'DOWNLOAD_FAILED', + GenerationError: 'GENERATION_ERROR', + InvalidMessage: 'INVALID_MESSAGE', + InvalidSchema: 'INVALID_SCHEMA', + ToolCallError: 'TOOL_CALL_ERROR', + ContextWindowExceeded: 'CONTEXT_WINDOW_EXCEEDED', + RateLimited: 'RATE_LIMITED', + BackgroundUseBlocked: 'BACKGROUND_USE_BLOCKED', +} as const + +export type AdkErrorCode = (typeof AdkErrorCodes)[keyof typeof AdkErrorCodes] + +const adkErrorCodes = new Set(Object.values(AdkErrorCodes)) + +export function isAdkErrorCode(value: unknown): value is AdkErrorCode { + return typeof value === 'string' && adkErrorCodes.has(value) +} + +export function createAdkError(message: string, code: AdkErrorCode): AdkError { + const error = new Error(message) as AdkError + error.code = code + return error +} + +/** + * Wraps a native rejection or stream error so it carries an `AdkErrorCode`. + * Errors without a known code become `GENERATION_ERROR`. + */ +export function toAdkError(error: unknown, code?: string): AdkError { + const nativeCode = + code ?? + (typeof error === 'object' && error !== null && 'code' in error + ? String((error as { code: unknown }).code) + : undefined) + const message = error instanceof Error ? error.message : String(error) + + return createAdkError( + message, + isAdkErrorCode(nativeCode) ? nativeCode : AdkErrorCodes.GenerationError + ) +} diff --git a/packages/adk/src/index.ts b/packages/adk/src/index.ts index 405983830..64353ce0b 100644 --- a/packages/adk/src/index.ts +++ b/packages/adk/src/index.ts @@ -1,14 +1,24 @@ -export { - adk, - type AdkProvider, - type AdkProviderOptions, - createAdkProvider, +export type { + AdkDownloadProgress, + AdkLanguageModel, + AdkLanguageModelId, + AdkLanguageModelOptions, + AdkModelAvailability, + AdkModelInfo, + AdkPrepareOptions, + AdkProvider, + AdkProviderOptions, + AdkToolDefinitionSet, } from './ai-sdk' +export { adk, createAdkProvider } from './ai-sdk' +export type { AdkError, AdkErrorCode } from './errors' +export { AdkErrorCodes } from './errors' export { type AdkAgentConfig, default as AdkEngine, type AdkMessage, type AdkModelType, + type AdkNanoModelConfig, type AdkTool, getNativeAdkEngine, } from './NativeAdkEngine' From c337e93ae0d374bc326bce5ff4185b1654ed6916 Mon Sep 17 00:00:00 2001 From: Mike Grabowski Date: Sun, 25 Oct 2026 03:25:54 +0400 Subject: [PATCH 4/4] docs(adk): document model info, errors, reasoning and structured output Co-Authored-By: Claude Opus 5.5 --- packages/adk/README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/adk/README.md b/packages/adk/README.md index 6653ed9a1..2ad9b3fd3 100644 --- a/packages/adk/README.md +++ b/packages/adk/README.md @@ -24,14 +24,16 @@ const { text } = await generateText({ ## Features -- ✅ On-device Gemini Nano through ML Kit GenAI +- ✅ On-device Gemini Nano through ML Kit GenAI, with model selection - ✅ Cloud Gemini through ADK `LlmAgent` -- ✅ Device capability and readiness checks for Gemini Nano +- ✅ Availability, download progress and token counting for Gemini Nano - ✅ Streaming - ✅ Tool calling, with the agent loop run natively by ADK +- ✅ Structured outputs +- ✅ Reasoning - ✅ Image prompts -- ✅ JSON output (without schema constraints) - ✅ Token usage +- ✅ Error codes ## Documentation