Реалізація 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 тижні.