API инструментов AI-агента: serverless-эндпоинты с авторизацией для LLM
Дайте каждому инструменту LLM свой HTTP-эндпоинт с авторизацией за шлюзом: API-ключ проверяется до запуска обработчика, секреты подставляются из воркспейса, изолированный контейнер на инструмент и тёплые пулы для стабильного трафика модели. Одна функция на инструмент — небольшая, тестируемая, наблюдаемая.
Обновлено: 2026-06-28
Кратко
Суть ответа
API инструментов AI-агента: serverless-эндпоинты с авторизацией для LLM. Деплойте каждый инструмент отдельной serverless-функцией за API-шлюзом. Шлюз проверяет API-ключ до запуска кода обработчика — без шаблонной авторизации в каждой функции. Секреты ограничены воркспейсом и подставляются в рантайме как переменные окружения.
Когда подходит
- Продакшен-агенты с несколькими инструментами, которым нужны авторизация, изолированные секреты и наблюдаемость по инструментам
- Разноязычные бэкенды инструментов: Python для ML, Node.js для вызовов API
На что обратить внимание
- Один сервер со всеми инструментами означает, что один сбой зависимости (например, конфликт версий numpy) кладёт все инструменты сразу. Один деплой затрагивает каждую возможность.
- Общие API-ключи на все инструменты означают, что ротация одной учётки задевает посторонние инструменты. Один слой авторизации на всё не позволяет ограничить права на уровне инструмента.
Нагрузка и где ломается
Что нужно бэкенду инструментов LLM
- HTTP-эндпоинты с авторизацией — модель не вызывает открытые маршруты
- Секреты вне пути модели — API-ключи никогда не попадают в промпты и контекст
- Изолированное выполнение — сбой одного инструмента не заражает другой
- Низкая задержка на тёплом пути — плотным циклам инструментов нужен ответ быстрее 100 мс
- Наблюдаемость — видно, какой инструмент упал и почему, на каждый вызов модели
В большинстве демо агентов вся логика инструментов лежит в одном сервере или одной Lambda. В проде каждый инструмент нужно изолировать, каждый секрет — ограничить областью, каждый сбой — трассировать независимо.
Компромиссы
Почему монолитные бэкенды инструментов ломаются в проде
Один сервер со всеми инструментами означает, что один сбой зависимости (например, конфликт версий numpy) кладёт все инструменты сразу. Один деплой затрагивает каждую возможность.
Общие API-ключи на все инструменты означают, что ротация одной учётки задевает посторонние инструменты. Один слой авторизации на всё не позволяет ограничить права на уровне инструмента.
Как помогает Inquir
Одна функция на инструмент, один шлюз на всех
Деплойте каждый инструмент отдельной serverless-функцией за API-шлюзом. Шлюз проверяет API-ключ до запуска кода обработчика — без шаблонной авторизации в каждой функции. Секреты ограничены воркспейсом и подставляются в рантайме как переменные окружения.
Тёплые контейнеры держат эндпоинты инструментов отзывчивыми при стабильном трафике агента — хотя первый деплой или вытесненный по простою контейнер всё ещё может быть холодным, поэтому задавайте таймауты с учётом самых важных инструментов. Разные инструменты используют разные рантаймы: Node.js для вызовов API, Python для ML-инференса, Go для быстрых lookup-запросов. Общая архитектура агента — на странице /serverless-for-ai-agents.
Что вы получаете
Возможности API инструментов AI-агента
Авторизация по API-ключу на шлюзе
Авторизация на маршруте (none, X-Api-Key или bearer) выполняется до кода функции. Ключи — 32 байта base64url, хранятся как SHA-256, показываются один раз; маршрут можно ограничить конкретными ID ключей и ротировать без правок обработчика.
Секреты на инструмент
Привязывайте секреты воркспейса к функции. Ключ OpenAI у суммаризатора никогда не попадёт в инструмент-коннектор к базе.
Изолированные контейнеры
Каждый инструмент работает в своём контейнере. Сломанная зависимость в одном не задевает остальные.
Тёплые пулы для циклов инструментов
Включайте тёплые контейнеры для инструментов, которые модель вызывает раз за разом. Прежде чем настраивать размер пула, измерьте p95 задержки под реалистичным трафиком агента.
Что дальше
Как собрать API инструментов AI-агента на Inquir
Описать контракты инструментов
Задокументируйте схему входа, схему выхода и формы ошибок для каждого инструмента. Держите контракты стабильными между версиями модели.
Задеплоить одну функцию на инструмент
Node.js, Python или Go — выбирайте под инструмент по нужным библиотекам. Секреты привязывайте на уровне воркспейса.
Подключить маршруты шлюза с API-ключом
Создайте маршрут на каждый эндпоинт инструмента. Включите авторизацию по API-ключу на уровне маршрута. Передайте ключ оркестратору через секреты.
Пример кода
Многоязычный API инструментов: lookup (Node.js) + classify (Python)
Один шлюз, разные рантаймы. Модель вызывает оба с одним API-ключом; секреты ограничены каждой функцией.
export async function handler(event) { // API key verified at gateway — handler assumes authenticated caller const { customerId } = JSON.parse(event.body || '{}'); if (!customerId) return { statusCode: 400, body: JSON.stringify({ error: 'customerId required' }) }; const record = await db.customers.findById(customerId); // DB_URL from workspace secrets if (!record) return { statusCode: 404, body: JSON.stringify({ error: 'not found' }) }; return { statusCode: 200, body: JSON.stringify({ customer: record }) }; }
import json, os from openai import OpenAI client = OpenAI(api_key=os.environ["OPENAI_API_KEY"]) # scoped to this tool only def handler(event, context): body = json.loads(event.get("body") or "{}") text = body.get("text") if not text: return {"statusCode": 400, "body": json.dumps({"error": "text required"})} r = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": f"Classify intent: {text}"}]) return {"statusCode": 200, "body": json.dumps({"intent": r.choices[0].message.content})}
Когда подходит
Кому подходит API инструментов AI-агента
Когда это уместно
- Продакшен-агенты с несколькими инструментами, которым нужны авторизация, изолированные секреты и наблюдаемость по инструментам
- Разноязычные бэкенды инструментов: Python для ML, Node.js для вызовов API
Когда лучше выбрать другое
- Демо с одним инструментом, которому не нужны авторизация и изоляция секретов
Частые вопросы
Частые вопросы
Может ли модель находить маршруты инструментов автоматически?
Отдавайте OpenAPI-спецификацию или манифест инструментов с эндпоинта обнаружения. Как только маршруты подключены, шлюз сам направляет вызовы модели к отдельным функциям инструментов.
Как версионировать инструменты?
Используйте префиксы пути (/tools/v1/lookup, /tools/v2/lookup) и направляйте их на разные версии функций. Переключайтесь вперёд, когда модель перепроверена на новом контракте.