Реализация AI-агента с доступом к внешним API в мобильном приложении
AI-агент с доступом к внешним API — это не просто Function Calling. Это архитектура, в которой модель самостоятельно решает, какую последовательность запросов к внешним сервисам выполнить, чтобы дать ответ. Пользователь пишет «забронируй мне перелёт в Берлин на следующую пятницу, отель рядом с центром до 100 евро» — агент ищет рейсы, выбирает оптимальный, ищет отели по критериям, сравнивает варианты, и только потом предлагает подтвердить. Несколько API, несколько шагов, минимум вмешательства пользователя.
Orchestration Loop и его реализация на мобильном
Сердце агента — цикл: LLM → tool_calls → execute → LLM → .... На мобильном этот цикл живёт либо на клиенте, либо на сервере (рекомендую второй вариант для сложных агентов). Клиентский цикл уместен для 2–4 инструментов без длинных цепочек зависимостей.
// Android — агентный цикл
suspend fun runAgent(userMessage: String): String {
val messages = mutableListOf(Message(role = "user", content = userMessage))
repeat(MAX_ITERATIONS) {
val response = llmClient.complete(messages, tools = availableTools)
if (response.finishReason == "stop") return response.content ?: ""
if (response.finishReason == "tool_calls") {
messages.add(response.toAssistantMessage())
response.toolCalls.map { call ->
async { toolDispatcher.dispatch(call.name, call.arguments) }
}.awaitAll().forEachIndexed { i, result ->
messages.add(Message(role = "tool", toolCallId = response.toolCalls[i].id, content = result))
}
}
}
return "Агент не смог завершить задачу за $MAX_ITERATIONS шагов"
}
MAX_ITERATIONS — критически важная защита. Без неё агент может зациклиться и выжечь бюджет токенов. Для большинства задач 10 итераций достаточно.
Реальные проблемы при доступе к внешним API
Аутентификация и безопасность токенов. Агент вызывает внешние API от имени пользователя — значит нужны токены (OAuth, API key). Никогда не храните чужие API-ключи в мобильном приложении открытым текстом. Правильная схема: мобильный клиент → ваш бэкенд (с валидацией) → внешний API. Бэкенд хранит токены, проксирует запросы, логирует вызовы. Иначе ключ Google Maps или Booking API утечёт через декомпиляцию APK.
Rate limiting и таймауты. Внешние API ограничивают запросы. Если агент делает 5 запросов к одному сервису за 2 секунды, получает 429 Too Many Requests. Нужен retry с exponential backoff: первый retry через 1с, второй через 2с, третий через 4с. OkHttp Interceptor позволяет реализовать это прозрачно для всех вызовов.
Непредсказуемые ответы API. Внешние API возвращают данные в разных форматах, с разными кодами ошибок, иногда возвращают HTML вместо JSON при ошибках инфраструктуры. Каждый инструмент должен возвращать агенту понятный текст ошибки, а не бросать исключение. Агент умеет работать с ошибками — если ему передать {"error": "Авиакомпания недоступна, попробуй другую"}, он переключится на альтернативу.
Инструменты агента: описание решает всё
Архитектурно каждый внешний API — это один или несколько инструментов с чётким описанием. Пример для API бронирования авиабилетов:
{
"name": "search_flights",
"description": "Ищет доступные рейсы. Используй ТОЛЬКО когда пользователь хочет найти или забронировать перелёт. Не используй для отелей или трансфера.",
"parameters": {
"origin": {"type": "string", "description": "IATA-код аэропорта отправления, например MSQ, SVO"},
"destination": {"type": "string", "description": "IATA-код аэропорта назначения"},
"date": {"type": "string", "description": "Дата в формате YYYY-MM-DD"},
"passengers": {"type": "integer", "default": 1}
}
}
Слово «ТОЛЬКО» в описании важно — без явных ограничений модель может вызвать инструмент в неподходящем контексте.
Серверный агент vs клиентский
Для агентов с доступом к 5+ API, долгими цепочками вызовов или чувствительными данными рекомендуем серверную оркестрацию. Клиент отправляет задачу, получает обновления через WebSocket или long polling, рендерит прогресс. Это позволяет:
- Продолжать работу агента при сворачивании приложения
- Кешировать промежуточные результаты
- Логировать каждый шаг для дебага
- Не раскрывать ключи внешних API на клиенте
На мобильном остаётся только UI: прогресс-индикатор шагов агента, возможность отмены, итоговая карточка с результатом и подтверждением действия.
Этапы работы
Аудит внешних API и их аутентификации → проектирование инструментов и схем → реализация бэкенд-прокси (если нужен) → агентный цикл с защитой от зацикливания → обработка rate limit и таймаутов → UX прогресс агента на клиенте → тестирование сценариев с ошибками API → мониторинг и алерты.
Сроки: агент с 3–5 внешними API, серверная оркестрация — 4–7 недель. Клиентский агент для 2–3 простых API — 2–3 недели.