К основному содержанию
скилл CX Codex

mlkit-agent-api — скилл для Claude Code: установка

Скилл mlkit-agent-api для Claude Code помогает создавать агентные сценарии в Android-приложениях через ML Kit GenAI Agent API. Подключается при работе с многошаговым чатом, вызовом инструментов или обработкой ошибок GenAiException.

Apache-2.0 374 установок ★ 10 691 обновлён 2026-10-23

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add android/skills --skill mlkit-agent-api -a claude-code
Открыть на GitHub

Что делает mlkit-agent-api

Скилл описывает настройку агента и запуск его задач на устройстве через ML Kit GenAI Agent API с Gemini Nano и AICore. Он охватывает создание Agent и AgentRunner, многошаговый чат с AgentSession во ViewModel, вызов Android AppFunctions и запуск одного хода через runSingleTurnAsync.

Отдельные рекомендации касаются хранения истории сессии, освобождения её из памяти и обработки GenAiException. Для AppFunctions используются зависимости Gradle com.google.mlkit:genai-agent:1.0.0-alpha1 и androidx.appfunctions:appfunctions:1.0.0-alpha13. Инструкции рассчитаны на AICore Developer Preview; облачные модели Gemini и Vertex AI не входят в область применения скилла.

Какие задачи решает

  • настроить Agent и AgentRunner для локального агента
  • сохранить историю многошагового чата во ViewModel
  • подключить вызовы Android AppFunctions
  • обработать ошибки GenAiException и закрыть сессию

Примеры запросов агенту

  • Настрой локального агента для Android через ML Kit GenAI Agent API.
  • Добавь многошаговый чат с AgentSession во ViewModel и обработай GenAiException.
  • Покажи, как подключить AppFunctions и запустить один ход через runSingleTurnAsync.

Как установить mlkit-agent-api

1Через Skills CLI (Vercel)

npx skills add android/skills --skill mlkit-agent-api -a claude-code

2Вручную: положить файлы

~/.claude/skills/mlkit-agent-api/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/mlkit-agent-api/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о mlkit-agent-api

Как установить mlkit-agent-api в Claude Code?

Выполни npx skills add android/skills --skill mlkit-agent-api -a claude-code. Файл скилла находится по пути ~/.claude/skills/mlkit-agent-api/SKILL.md.

Что делает mlkit-agent-api?

Скилл помогает создавать локальные агентные сценарии для Android через ML Kit GenAI Agent API: многошаговый чат, вызов AppFunctions и обработку ошибок.

Что нужно для работы mlkit-agent-api?

Нужны AICore Developer Preview и зависимости Gradle com.google.mlkit:genai-agent:1.0.0-alpha1 и androidx.appfunctions:appfunctions:1.0.0-alpha13. Скилл ориентирован на Gemini Nano, а не на облачные модели Gemini или Vertex AI.

Исходный текст

SKILL.md · Apache-2.0
---
name: mlkit-agent-api
description: Builds autonomous on-device agentic workflows in Android apps using the
  ML Kit GenAI Agent API powered by Gemini Nano and AICore. Use this skill when implementing
  conversational agents, multi-turn chat with AgentSession in a ViewModel, autonomous
  tool calling using Android AppFunctions (@AppFunctionDeclaration and AppFunctionAgentTools.discover),
  ephemeral single-turn execution with runner.runSingleTurnAsync, or handling GenAiException
  error resilience. It solves the problem of orchestrating local reasoning loops,
  typed tool dispatch, and session persistence on-device with zero cloud latency and
  privacy preservation. Don't use for cloud-based Gemini models or Vertex AI, single-turn
  text generation without agent loops (suggest Prompt API), or non-Android platforms.
license: Complete terms in LICENSE.txt
metadata:
  author: Google LLC
  last-updated: '2026-11-10'
  keywords:
  - Android
  - ML Kit
  - GenAI
  - Agent API
  - Gemini Nano
  - AICore
  - AppFunctions
  - Tool Calling
  - Function Calling
  - Session Persistence
  - AgentSession
---

Targeting **AICore Developer Preview**. This skill provides authoritative
execution patterns and failure-prevention rules for on-device agentic workflows
in Android apps.

*** ** * ** ***

## 1. Prerequisites and setup

### Gradle dependencies

```kotlin
// app/build.gradle.kts
dependencies {
    // Core ML Kit GenAI Agent API
    implementation("com.google.mlkit:genai-agent:1.0.0-alpha1")

    // Android AppFunctions dependency for on-device tool declarations
    implementation("androidx.appfunctions:appfunctions:1.0.0-alpha13")
}
```
> \[!IMPORTANT\] Always use official SDK interfaces from
> `com.google.mlkit.genai.agent.*`, `androidx.appfunctions.*`,
> `com.google.mlkit.genai.prompt.*`, and `com.google.mlkit.genai.common.*`.
> Never declare local placeholder interfaces or fallback mocks.

*** ** * ** ***

## 2. Minimal agent and runner initialization

Configure an `Agent` with `Agent.builder` and wrap execution in `AgentRunner`:

```kotlin
import com.google.mlkit.genai.agent.Agent
import com.google.mlkit.genai.agent.AgentRunner

val agent = Agent.builder()
    .setName("OnDeviceAssistant")
    .setInstructions("You are a helpful on-device assistant.")
    .build()

val runner = AgentRunner(agent)
```

- `Agent.builder` defaults to `maxTurns = 10` automatically to prevent infinite tool loops.
- `AgentRunner` defaults to greedy decoding (`temperature = 0.0f`) for deterministic tool selection and schema compliance.
- `AgentRunner(agent)` automatically resolves application context using `MlKitContext` for AppFunction execution in Android apps. An explicit `AgentRunner(context, agent)` overload is available for headless tests or custom context scopes.

*** ** * ** ***

## 3. Multi-turn chat and lifecycle (ViewModel)

`AgentSession` preserves conversational history in memory and is **not
`Parcelable`** . To preserve dialogue history across Android configuration
changes (such as screen rotation), retain `session` inside an AndroidX
`ViewModel`.

When executing single-turn ephemeral queries, managing concurrent
multi-sessions, or requiring explicit RAM cleanup, you must follow the
guidelines in [Session lifecycle](references/session_lifecycle.md).

```kotlin
package com.example.app

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.google.mlkit.genai.agent.Agent
import com.google.mlkit.genai.agent.AgentRunner
import com.google.mlkit.genai.agent.AgentSession
import com.google.mlkit.genai.agent.textTokens
import com.google.mlkit.genai.common.GenAiException
import com.google.mlkit.genai.prompt.Content
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch

class ChatViewModel : ViewModel() {
    private val agent = Agent.builder()
        .setInstructions("You are a helpful on-device assistant.")
        .build()
    private val runner = AgentRunner(agent)
    private val session: AgentSession =
        runner.getOrCreateSession("chat_session")

    private val _uiState = MutableStateFlow<ChatUiState>(ChatUiState.Idle)
    val uiState: StateFlow<ChatUiState> = _uiState.asStateFlow()

    fun sendMessage(prompt: String) {
        viewModelScope.launch {
            _uiState.value = ChatUiState.Loading("")
            try {
                // Content.builder() required; runAsync takes Content
                val content = Content.builder().text(prompt).build()
                var fullResponse = ""
                session.runAsync(content)
                    // Extension function requiring textTokens import
                    .textTokens()
                    .collect { token ->
                        fullResponse += token
                        _uiState.value = ChatUiState.Loading(fullResponse)
                    }
                _uiState.value = ChatUiState.Success(fullResponse)
            } catch (e: GenAiException) {
                // Catch GenAiException to prevent app crashes on AI errors
                val err = e.localizedMessage ?: "AI error (${e.errorCode})"
                _uiState.value = ChatUiState.Error(err)
            }
        }
    }

    override fun onCleared() {
        super.onCleared()
        // Evict conversation session from RAM when ViewModel is destroyed
        session.close()
    }
}
```

### Essential lifecycle and coroutine rules

1. **`Content` object** : `session.runAsync` and `runner.runSingleTurnAsync` require a `Content` object. Always build it using `Content.builder().text(userPrompt).build()`.
2. **`textTokens` extension** : `textTokens` is a Kotlin extension function on `Flow<AgentEvent>`. Always include `import
   com.google.mlkit.genai.agent.textTokens`.
3. **Session cleanup** : Always invoke `session.close` in `ViewModel.onCleared` to evict conversational RAM and cancel pending tasks.
4. **`AgentEvent` stream** : When collecting `Flow<AgentEvent>` directly instead of `textTokens`, always include `import
   com.google.mlkit.genai.agent.AgentEvent`. Match against `AgentEvent.TextMessage(text, isPartial)`, `AgentEvent.FunctionCall(name, args)`, and `AgentEvent.FunctionResponse(name, response)`, and always include an `else
   -> {}` branch in `when (event)` expressions (`AgentEvent` is non-exhaustive for forward compatibility):

```kotlin
import com.google.mlkit.genai.agent.AgentEvent

session.runAsync(content).collect { event ->
    when (event) {
        is AgentEvent.FunctionCall -> {
            _uiState.update {
                it.copy(activeToolStatus = "Tool started: ${event.name}")
            }
        }
        is AgentEvent.FunctionResponse -> {
            _uiState.update {
                it.copy(activeToolStatus = "Tool completed: ${event.name}")
            }
        }
        is AgentEvent.TextMessage -> {
            _uiState.update {
                it.copy(responseText = it.responseText + event.text)
            }
        }
        else -> {} // Required: AgentEvent is non-exhaustive for forward compat
    }
}
```

*** ** * ** ***

## 4. Tool calling recipe

All tools used with `Agent` originate from Android AppFunctions
(`@AppFunctionDeclaration`), registered using the declarative path
(`enableAppFunctions(true)` or `addAppFunctionIds(...)`) or advanced discovery
(`AppFunctionAgentTools.discover(...)`).

When you need to restrict caller access levels for private in-app tools or wrap
discovered AppFunctions with human-in-the-loop (HITL) confirmation decorators,
you must consult [Tools and functions](references/tools_and_functions.md).

### Option A: Declarative AppFunctions path

Define tools declaratively in your app using AndroidX AppFunctions:

```kotlin
package com.example.app.tools

import androidx.appfunctions.AppFunctionDeclaration
import androidx.appfunctions.AppFunctionSerializable

@AppFunctionSerializable
data class CalendarEvents(val date: String, val events: List<String>)

class CalendarTools {
    /**
     * Fetches scheduled calendar appointments for a specific date in
     * YYYY-MM-DD format.
     *
     * @param date Date string in YYYY-MM-DD format
     */
    @AppFunctionDeclaration(isDescribedByKDoc = true)
    fun fetch_calendar(
        date: String
    ): CalendarEvents {
        return CalendarEvents(
            date = date,
            events = listOf(
                "Team Standup at 10:00 AM",
                "Product Review at 2:00 PM"
            )
        )
    }
}
```

Enable AppFunctions on `Agent.Builder` and initialize `AgentRunner`:

```kotlin
import com.google.mlkit.genai.agent.Agent
import com.google.mlkit.genai.agent.AgentRunner

val agent = Agent.builder()
    .setName("CalendarAssistant")
    .setInstructions("You assist with calendar queries.")
    // Automatically discovers AppFunctions in your app package
    .enableAppFunctions(true)
    // Optional: scope to specific function IDs or method names
    .addAppFunctionIds("fetch_calendar")
    .build()

val runner = AgentRunner(agent)
```

- **AppFunction Contract** : Tool methods take domain parameters directly (no framework context parameter required). Returns must be primitives or `@AppFunctionSerializable` data classes (`Map<String, Any?>` isn't supported for AppFunctions).
- **Restricting Callers with `ACCESS_LEVEL_SELF`** : AppFunctions don't have to be public to external callers. To restrict execution strictly to your app's internal agent (blocking external system assistants and IPC callers), annotate with `@OptIn(ExperimentalAppFunctionsApi::class)` and `@AppFunctionAccessLevel(level = AppFunctionMetadata.ACCESS_LEVEL_SELF,
  isCompatEnforcementEnabled = true)`.

### Option B: Advanced discovery and decorator pattern

For inspecting, filtering, or decorating discovered AppFunctions (such as
Human-in-the-Loop confirmation wrappers using `AgentTool(delegate)`) before
registering with the agent:

```kotlin
import com.google.mlkit.genai.agent.Agent
import com.google.mlkit.genai.agent.AgentRunner
import com.google.mlkit.genai.agent.AgentTool
import com.google.mlkit.genai.agent.AppFunctionAgentTools

// Discover tools (optionally scoped to function IDs)
val discoveredTools = AppFunctionAgentTools.discover(
    enabledAppFunctionIds = listOf("fetch_calendar")
)

// Optional: Wrap sensitive tools using AgentTool(delegate) decorator
class HitlConfirmationTool(
    delegate: AgentTool,
    private val onConfirm: suspend (
        toolName: String,
        args: Map<String, Any>
    ) -> Boolean
) : AgentTool(delegate) {
    override suspend fun execute(args: Map<String, Any>): Map<String, Any?> {
        if (!onConfirm(name, args)) {
            return mapOf("status" to "CANCELLED_BY_USER")
        }
        return checkNotNull(delegate).execute(args)
    }
}

val agent = Agent.builder()
    .setName("CalendarAssistant")
    .setInstructions("You assist with calendar queries.")
    .addTools(discoveredTools)
    .build()

val runner = AgentRunner(agent)
```
> \[!WARNING\] **Mutual exclusivity** : Configure AppFunctions using either the
> declarative path (`enableAppFunctions(true)` on `Agent.Builder`) or the
> advanced path (`AppFunctionAgentTools.discover` passed to `addTools`), but
> not both. Using both simultaneously triggers a warning and registers
> duplicate tool schemas.

### Deprecated annotations (@Tool and @Param)

The legacy `@Tool` and `@Param` annotations in
`com.google.mlkit.genai.schema.annotations.*`, along with
`AgentTool.fromAnnotatedObject`, `Agent.Builder.addTools(annotatedObject:
Any)`, and standalone `FunctionTool`, have been deprecated or removed. All tools
added to `Agent` must originate from
`@androidx.appfunctions.AppFunctionDeclaration` using
`Agent.Builder.enableAppFunctions(true)` or `AppFunctionAgentTools.discover`.

*** ** * ** ***

## 5. Ephemeral single-turn execution

For one-off tasks where conversation history isn't needed (such as summarizing
text, formatting data, or answering standalone questions), invoke
`runner.runSingleTurnAsync(content)` directly:

```kotlin
import com.google.mlkit.genai.agent.AgentRunner
import com.google.mlkit.genai.agent.textTokens
import com.google.mlkit.genai.prompt.Content
import kotlinx.coroutines.flow.Flow

// Executes a single-turn query ephemerally without session persistence:
fun askQuickQuestion(runner: AgentRunner, question: String): Flow<String> {
    val content = Content.builder().text(question).build()
    return runner.runSingleTurnAsync(content).textTokens()
}
```

- `runner.runSingleTurnAsync(content)` automatically creates and evicts an ephemeral session upon Flow completion.
- **Cleanup reference** :
  - `session.close`: Releases session resources and cancels coroutines (call in `ViewModel.onCleared`).
  - `session.delete` or `runner.deleteSession(sessionId)`: Permanently deletes the session from the runner.

*** ** * ** ***

## 6. Error handling and GenAiException reference

Runtime failures during on-device execution (such as model unavailability or
exceeding maximum turn limits) are emitted or thrown as `GenAiException`:

```kotlin
import com.google.mlkit.genai.common.GenAiException
```

### Key error codes

- `GenAiException.ErrorCode.MAX_TURNS_EXCEEDED` (`-112`): The agent exceeded `maxTurns` (default 10) without completing the reasoning loop.
- `GenAiException.ErrorCode.NOT_AVAILABLE` (`8`): The Gemini Nano model or AICore service isn't available on this device.
- `GenAiException.ErrorCode.BUSY` (`9`): System or AICore is busy, or battery or thermal quota has been reached.

© Google LLC · Apache-2.0 · android/skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
rc-revenuecat-api-quick-reference RevenueCat Скилл rc-revenuecat-api-quick-reference для Claude Code — справочник по Android SDK 10.x и REST API RevenueCat. Помогает быстро вспомнить сигнатуру вызова или структуру объекта без документации. CX Codex +1 747установок testing-mobile-api-authentication mahipal Скилл testing-mobile-api-authentication для Claude Code проверяет аутентификацию и авторизацию мобильных API: JWT, OAuth, токены, сессии и IDOR. Помогает проводить разрешённые API-аудиты. CX Codex +1 276установок sauce-api-mcp saucelabs MCP-сервер sauce-api-mcp связывает ассистента с платформой Sauce Labs для проверки мобильных устройств и виртуальных машин. Пригодится при анализе упавших автотестов и мониторинге туннелей. CX Codex +1 ★ 10звёзд репо open-autoglm-phone-agent reason-machines Скилл open-autoglm-phone-agent для Claude Code, Codex, Cursor и других IDE обучает агента разворачивать Open-AutoGLM — фреймворк голосового управления Android, HarmonyOS NEXT и iOS через модель AutoGLM. CX Codex +1 1 400установок firebase-ai-logic-basics Google LLC Скилл firebase-ai-logic-basics подключает Firebase AI Logic к мобильным и веб-приложениям, позволяя вызывать модели Gemini напрямую из клиентского кода без своего бэкенда. CX Codex +1 146 900установок limrun-expo-development limrun-inc Скилл limrun-expo-development готовит и запускает Expo и React Native приложения на Limrun: dev-client сборка, туннель Metro, правки JS и TS без повторных нативных пересборок. CX Codex +1 45 300установок

Из того же набора36

Весь набор →
litert-runtime Скилл litert-runtime настраивает и пишет Kotlin-код для запуска моделей .tflite на Android через CompiledModel API. Включается в любой задаче с LiteRT: от Gradle-зависимостей до препроцессинга Bitmap и миграции со старого Interpreter. CX Codex +1 558установок wear-widgets Скилл wear-widgets для создания виджетов Wear OS через Glance Wear и Remote Compose. Помогает с нуля поднять виджет, мигрировать старый тайл или проверить существующую реализацию в Android-проекте. CX Codex +1 544установок android-for-cars-parked-apps Скилл android-for-cars-parked-apps для Claude Code помогает адаптировать приложения с видео, играми и браузерами под Android Auto и Android Automotive OS для работы на парковке. CX Codex +1 537установок litert-lm Помогает добавить в Android-приложение запуск текстовой языковой модели на устройстве. Описывает чат, суммаризацию и извлечение данных через LiteRT-LM. CX Codex +1 451установок projected-hardware Скилл projected-hardware для Claude Code помогает подключать железо умных очков Android XR к приложению. Он охватывает камеру, микрофон, разрешения и жизненный цикл соединения. CX Codex +1 444установок glance-appwidget-updates-and-memory Скилл glance-appwidget-updates-and-memory для Claude Code помогает обновлять Android-виджеты на Jetpack Glance и укладывать их изображения в лимит памяти. Подключается при настройке AppWidget, синхронизации состояния или разборе сбоев. CX Codex +1 400установок ink-app-builder Скилл ink-app-builder для Claude Code добавляет в Android-приложение рисование стилусом или касанием через Jetpack Ink и Compose. Подключается к задачам с отрисовкой штрихов, ластиком, историей отмены и сохранением. CX Codex +1 387установок ink-custom-brush-builder Скилл ink-custom-brush-builder для Claude Code и Cursor создаёт определения кистей для Android-приложений с помощью Jetpack Ink. Помогает настраивать геометрию наконечника и динамические реакции на стилус. CX Codex +1 382установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой