Обзор SDK
Выберите клиентский SDK OpenAI, Anthropic или Gemini по протоколу и выполните проверки перед подключением.
AGTCloud предоставляет совместимые интерфейсы OpenAI, Anthropic и Gemini. В серверных проектах, уже использующих SDK поставщика, обычно можно сохранить основные вызовы, заменив адрес API, ключ API и ID модели настройками AGTCloud.
SDK формирует запросы только по своему протоколу. Перед выбором проверьте протоколы целевой модели и не определяйте совместимость исключительно по её названию.
Выбор клиентского SDK
| SDK | Протокол | Аутентификация | Сценарии использования |
|---|---|---|---|
| OpenAI SDK | Chat Completions, Responses | Bearer API Key | Существующий проект на OpenAI SDK или диалог, Typed Items, потоковые ответы и вызовы инструментов |
| Anthropic SDK | Anthropic Messages | x-api-key и заголовок версии | Существующий проект на Anthropic Messages или Content Blocks и структура инструментов Anthropic |
| Gemini SDK | Gemini Generate Content | Bearer API Key | Существующий проект на Gemini SDK или contents, parts и нативная структура содержимого Gemini |
SDK не преобразует протоколы автоматически
OpenAI messages или input, Anthropic Content Blocks и Gemini contents и parts — разные структуры данных. Используйте руководство для протокола, соответствующего текущему коду; перед межпротокольным рефакторингом прочитайте Миграция SDK поставщиков.
Основные различия трёх протоколов
| Критерий | OpenAI SDK | Anthropic SDK | Gemini SDK |
|---|---|---|---|
| Основные интерфейсы | Chat Completions, Responses | Messages | Generate Content |
| Вход диалога | messages или input | messages и Content Blocks | contents и parts |
| Обычный текстовый ответ | Chat Message или Responses Output Items | Блоки содержимого content | candidates[].content.parts |
| Потоковая структура | Chat Delta или события response.* | События Messages SSE | Stream Generate Content |
| Структура инструментов | Function Tools и встроенные инструменты Responses | tool_use, tool_result | functionCall, functionResponse |
Полные поля, перечисления и структуры ответов описаны в соответствующем Справочнике API. Руководства по SDK посвящены установке, инициализации и чтению результатов и не повторяют все Schema.
Подготовка к подключению
Создание ключа API
Создайте ключ API AGTCloud на странице API Keys и храните его в серверной переменной окружения или сервисе управления секретами.
Не записывайте настоящий ключ API в браузерный код, мобильные установщики, открытые репозитории, снимки экрана или журналы.
Проверка модели и протокола
Скопируйте полный ID модели из каталога моделей и подтвердите поддержку выбранного протокола и возможностей.
В этом разделе MODEL_ID обозначает заполнитель модели. Перед реальным вызовом замените его ID модели, видимой текущему ключу API.
Выбор серверной среды
SDK Python и TypeScript должны выполняться в доверенной серверной среде. Установите текущую стабильную версию SDK и зафиксируйте используемую версию в файле блокировки зависимостей проекта.
Рекомендуемый порядок проверки
- Установите SDK и убедитесь, что приложение читает ключ API.
- Укажите Base URL из руководства, без полного пути бизнес-эндпоинта.
- Отправьте один непотоковый запрос с обычным текстом и минимальным набором полей.
- Проверьте текст, состояние завершения и использование токенов.
- Затем проверьте Streaming, инструменты, мультимодальность или структурированный вывод по потребностям приложения.
- Добавьте журналы и контролируемые повторы при тайм-аутах, ограничении частоты и серверных ошибках.
Наличие протокола не означает поддержку всех возможностей моделью
Модели одного протокола могут отличаться по входным модальностям, инструментам, структурированному выводу и потоковой передаче. При неподдерживаемом поле или недоступной модели сначала проверьте информацию о модели и соответствующий Справочник API.
Следующие шаги
- Вызывайте Chat Completions или Responses через OpenAI SDK.
- Вызывайте Messages через Anthropic SDK.
- Вызывайте Generate Content через Gemini SDK.
- Для существующего проекта на SDK поставщика проверьте пункты миграции SDK поставщиков.
- При ошибках запросов прочитайте Ошибки и устранение неполадок.