Совместимый с OpenAI роутер для CrewAI: один ключ для многоагентных рабочих процессов

Настройка совместимого с OpenAI роутера для CrewAI полезна, когда вы хотите, чтобы несколько агентов CrewAI использовали одну границу шлюза вместо того, чтобы разбрасывать ключи провайдеров, базовые URL-адреса и псевдонимы моделей по каждой роли в рабочем процессе.

Текущая документация LLM для CrewAI показывает два важных пути настройки для совместимых с OpenAI конечных точек: переменные окружения, такие как OPENAI_API_BASE, и явные атрибуты LLM(...), такие как model, base_url и api_key. Flatkey вписывается в эту границу. Его публичный сайт направляет совместимые с OpenAI клиенты на https://router.flatkey.ai/v1, с возможностью просмотра использования, затрат, маршрутизации и ошибок в панели управления продуктом.

Это руководство демонстрирует практический шаблон совместимого с OpenAI роутера для CrewAI для многоагентных рабочих процессов. Код является шаблоном: проверьте точные псевдонимы моделей, поведение инструментов и логи с вашим собственным ключом Flatkey перед маршрутизацией агентов в производственной среде.

Краткий ответ для совместимого с OpenAI роутера CrewAI

Используйте один корневой API шлюза и явные имена маршрутов. Не скрывайте маршрутизацию в тексте промпта.

В этом заключается основной шаблон совместимого с OpenAI роутера для CrewAI: оставить CrewAI ответственным за оркестрацию, оставить Flatkey ответственным за границу шлюза, совместимого с OpenAI, и сделать операционные проверки видимыми.

Почему многоагентным рабочим процессам нужна граница шлюза

Рабочие процессы CrewAI часто начинаются с простой структуры: один агент-менеджер, несколько агентов-специалистов и одна финальная задача. Это работает до тех пор, пока рабочий процесс не превращается из демонстрации в сервис, на который полагаются другие команды.

Производственные многоагентные системы обычно требуют больше, чем просто работающий ответ:

Для смежных элементов управления дизайном используйте руководство Flatkey по элементам управления шлюзом для AI-агентов. Совместимый с OpenAI роутер для CrewAI должен конкретизировать эти элементы управления для каждой роли агента.

Шаг 1: Создайте значения маршрутов Flatkey

Создайте один ключ Flatkey для этой рабочей нагрузки и храните значения маршрутов вне системы контроля версий.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_DEFAULT_MODEL=your-default-flatkey-model-alias
FLATKEY_PLANNER_MODEL=your-planner-model-alias
FLATKEY_TOOL_MODEL=your-tool-capable-model-alias
FLATKEY_VERIFIER_MODEL=your-verifier-model-alias

Держите корневой API отдельно от пути конечной точки. Объект LLM CrewAI должен получать базовый URL. Прямые тесты с помощью curl добавляют /chat/completions.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_DEFAULT_MODEL"'",
    "messages": [
      { "role": "user", "content": "Reply with exactly: flatkey route ok" }
    ]
  }'

Если этот прямой запрос не удался, сначала исправьте ключ Flatkey, псевдоним модели, семейство конечных точек или маршрут учетной записи. Совместимый с OpenAI роутер для CrewAI не может компенсировать псевдоним модели, который учетная запись шлюза не может вызвать.

Шаг 2: Настройте объекты LLM CrewAI явным образом

CrewAI поддерживает установку базового URL API для LLM через base_url, и его документация показывает настройку LLM, совместимых с OpenAI, либо через переменные окружения, либо через атрибуты класса LLM. Для производственной работы явные объекты LLM легче проверять, поскольку каждая роль агента указывает на известный маршрут.

import os

from crewai import Agent, Crew, LLM, Process, Task


BASE_URL = os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1")
API_KEY = os.environ["FLATKEY_API_KEY"]


def flatkey_llm(model_env: str, temperature: float = 0.2) -> LLM:
    return LLM(
        model=os.environ[model_env],
        base_url=BASE_URL,
        api_key=API_KEY,
        temperature=temperature,
    )


planner_llm = flatkey_llm("FLATKEY_PLANNER_MODEL", temperature=0.1)
tool_llm = flatkey_llm("FLATKEY_TOOL_MODEL", temperature=0.0)
verifier_llm = flatkey_llm("FLATKEY_VERIFIER_MODEL", temperature=0.0)

Это самое важное решение при настройке миграции на совместимый с OpenAI роутер для CrewAI. Псевдоним модели может меняться в зависимости от окружения, но код CrewAI сохраняет один корневой API, совместимый с OpenAI, и одного владельца ключа шлюза.

Шаг 3: Назначьте маршруты в соответствии с обязанностями агента

Назначьте каждому агенту CrewAI маршрут LLM, соответствующий его профилю риска. Начните с небольшого набора маршрутов. Вы всегда сможете разделить роли позже, после того как логи подтвердят работоспособность первой политики.

planner = Agent(
    role="Планировщик рабочего процесса",
    goal="Разбить запрос на короткий план выполнения.",
    backstory="Вы следите за тем, чтобы команда не выходила за рамки задачи, и избегаете ненужных вызовов модели.",
    llm=planner_llm,
)

researcher = Agent(
    role="Исследователь",
    goal="Собирать только факты, необходимые для выполнения задачи.",
    backstory="Вы предпочитаете заметки, подкрепленные источниками, а не широкие домыслы.",
    llm=planner_llm,
)

tool_user = Agent(
    role="Оператор инструментов",
    goal="Использовать утвержденные инструменты только тогда, когда этого требует задача.",
    backstory="Вы проверяете входные данные инструментов перед вызовом внешних систем.",
    llm=tool_llm,
)

verifier = Agent(
    role="Верификатор",
    goal="Проверить окончательный ответ на соответствие требованиям и доказательствам.",
    backstory="Вы ищете недостающие доказательства, ошибки инструментов и риски отката.",
    llm=verifier_llm,
)

При первом развертывании совместимого с OpenAI роутера для CrewAI избегайте назначения уникальной модели каждому агенту. Обычно достаточно двух или трех типов маршрутов: планирование, выполнение с использованием инструментов и верификация.

Шаг 4: Создайте небольшую команду и сохраняйте поля с доказательствами

Команда может оставаться обычной. А вот доказательства маршрутизации — нет. Добавьте простые поля в описание задачи, выходные данные или в логи вашего приложения, чтобы запрос можно было сопоставить с логами Flatkey.

analysis_task = Task(
    description=(
        "Проанализируйте заявку в службу поддержки и составьте краткий план ее решения. "
        "Не вызывайте инструменты, если не требуется поиск учетной записи. "
        "Поля с доказательствами, которые нужно хранить вне этого промпта: workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="Краткий план с указанием рисков, потребностей в инструментах и следующего действия.",
    agent=planner,
)

verification_task = Task(
    description=(
        "Проверьте, ссылается ли план на факты из заявки, избегает ли он необоснованных утверждений, "
        "и указывает ли на вызовы инструментов, которые все еще требуют утверждения."
    ),
    expected_output="Заметки о прохождении/непрохождении проверки с требуемыми исправлениями.",
    agent=verifier,
    context=[analysis_task],
)

crew = Crew(
    agents=[planner, researcher, tool_user, verifier],
    tasks=[analysis_task, verification_task],
    process=Process.sequential,
)

result = crew.kickoff(
    inputs={
        "ticket_id": "TICKET-123",
        "request_id": "support-triage-2026-07-08-001",
    }
)
print(result)

request_id в этом шаблоне сам по себе не является функцией маршрутизации CrewAI. Это полезная привычка для обеспечения наблюдаемости. Ваше приложение должно логировать идентификатор запроса, политику маршрутизации, псевдоним модели, временную метку и метку ключа, чтобы путь совместимого с OpenAI роутера для CrewAI можно было проверить в Flatkey.

Шаг 5: Проверьте вызовы инструментов перед широким развертыванием

Использование инструментов — это та область, где совместимая с OpenAI маршрутизация становится рискованной. Обычный маршрут для чата может работать, в то время как маршрут с интенсивным использованием инструментов может не пройти проверку схемы, передавать аргументы инструментов по-другому или генерировать аргументы, которые ваш исполнитель отклонит.

Проведите узконаправленный тест инструментов, прежде чем доверять маршруту инструментов CrewAI. Для более полного понимания поведения провайдеров используйте это руководство вместе со статьей Flatkey о совместимости вызовов инструментов с OpenAI.

Не относитесь к этому как к необязательному шагу. Совместимый с OpenAI роутер для CrewAI готов к работе в производственной среде только тогда, когда маршрут инструментов протестирован как отдельный контракт.

Шаг 6: Добавьте правила бюджета, повторных попыток и отката вне промптов

Не просите агентов запоминать все операционные правила на естественном языке. Храните правила бюджета и отката в коде или конфигурации, которые могут проверить рецензенты.

Когда резервный вариант утвержден, указывайте резервный псевдоним явно. Полезный вопрос не в том, «завершила ли команда работу?», а в том, «какой маршрут завершился, почему произошло переключение и какова была стоимость?». В этом и заключается операционная ценность совместимого с OpenAI роутера для CrewAI.

Шаг 7: Сохраните пакет верификации

Прежде чем сделать Flatkey шлюзом по умолчанию для рабочего процесса CrewAI, сохраните компактный пакет верификации.

1. Прямой запрос curl к https://router.flatkey.ai/v1/chat/completions успешно выполняется с выбранным псевдонимом модели.
2. Каждый объект LLM в CrewAI выполняет один небольшой промпт вне полной команды.
3. Полная команда выполняет один простой рабочий процесс и один процесс с интенсивным использованием инструментов.
4. Принудительный путь сбоя чисто останавливается, а не пытается повторяться вечно.
5. Логи Flatkey показывают ожидаемый ключ, псевдоним модели, временную метку и владельца запроса.
6. Поля токенов или использования достаточно видны для проверки владельцем бюджета.
7. Откат — это изменение одной среды или конфигурации, а не рефакторинг CrewAI.

Используйте руководство по панели использования токенов Flatkey, чтобы решить, какие поля ваша операционная команда должна проверять после первого дымового теста. Для ознакомления с ценами и проверки учетной записи начните с действующей страницы цен Flatkey, а затем проверьте фактический маршрут в своей учетной записи.

Устранение неполадок совместимого с OpenAI роутера для CrewAI

Если первый запрос не удался, сохраняйте область отладки небольшой: один ключ, один базовый URL, один псевдоним модели, один LLM в CrewAI, один прямой запрос и один просмотр лога в Flatkey.

Часто задаваемые вопросы

Является ли совместимый с OpenAI роутер для CrewAI тем же самым, что и резервная модель?

Нет. Совместимый с OpenAI роутер для CrewAI — это шлюз и граница конфигурации, которые CrewAI использует для доступа к маршрутам моделей. Резервный вариант — это одна из политик, которая может быть запущена при сбое выбранного маршрута. Тестируйте маршрутизацию и резервные варианты отдельно.

Должен ли каждый агент CrewAI получать свою модель?

Нет. Начните с маршрута по умолчанию и одного специального маршрута для работы с большим количеством инструментов или для верификации, если это необходимо. Слишком много псевдонимов усложняют логирование, анализ затрат и откат.

Может ли CrewAI использовать переменные среды вместо явных объектов LLM?

Да. Документация CrewAI показывает настройку, совместимую с OpenAI, через переменные среды, такие как OPENAI_API_BASE. Явные объекты LLM часто проще для проверки в производственной среде, потому что для каждой роли агента model, base_url и api_key отображаются в одном месте.

Могу ли я использовать один и тот же ключ Flatkey для каждого рабочего процесса CrewAI?

Можете, но ключи для конкретных рабочих нагрузок легче аудировать. Используйте отдельные ключи или метки, когда разные команды, среды, бюджеты или уровни риска требуют отдельной проверки.

Итоговый чек-лист

Ваша настройка совместимого с OpenAI роутера для CrewAI готова к выходу за рамки шаблона, когда:

1. Объекты LLM в CrewAI используют корневой API Flatkey в качестве base_url.
2. Псевдонимы моделей находятся в среде или конфигурации, а не разбросаны по промптам.
3. Для каждой роли агента есть осознанное решение о маршрутизации.
4. Маршруты с интенсивным использованием инструментов проходят тесты схемы, аргументов, ограничений и сбоев.
5. Ограничения бюджета, повторных попыток и резервных вариантов выполняются вне прозы агента.
6. Логи использования или запросов Flatkey подтверждают ожидаемый ключ и псевдоним модели.
7. Откат — это изменение одной конфигурации.

Когда вы будете готовы маршрутизировать трафик CrewAI через один шлюз, получите ключ Flatkey, протестируйте одну команду с низким уровнем риска и расширяйте только после того, как логи подтвердят, что политика работает.