API агентов

Сам Решу предоставляет drop-in эндпоинт chat/completions. Если вы уже используете OpenAI SDK, поменяйте base URL и ключ, больше ничего.

  • Base URL: https://samreshuuu.ru/v1
  • Авторизация: ключ организации со scope chat:write (см. Аутентификацию)
  • model: хэндл агента, который отвечает, из GET /v1/models

Drop-in пример

Перед запуском любого примера задайте ключ организации в переменной окружения SAMRESHUUU_API_KEY.

python
import os from openai import OpenAI client = OpenAI(api_key=os.environ["SAMRESHUUU_API_KEY"], base_url="https://samreshuuu.ru/v1") reply = client.chat.completions.create( model="samreshu", messages=[{"role": "user", "content": "Привет! Что ты умеешь?"}], ) print(reply.choices[0].message.content)

О поле model и других полях OpenAI

model адресует агента, а не LLM. GET /v1/models перечисляет агентов, с которыми может говорить организация ключа: первым встроенный ассистент (samreshu, owned_by: "system"), затем собственные и общие агенты организации (owned_by это id организации). LLM выбирает настройка модели самого агента, запрос её не переопределяет. Каждый ответ и каждый чанк несут хэндл агента, который ответил. Хэндл, которого нет или до которого создатель ключа не дотягивается, отклоняется с 404 DATA_NOT_FOUND и param: "model", текст: «The model x does not exist or you do not have access to it. List models with GET /v1/models.»; подмены другим агентом нет, поэтому стандартный gpt-4o падает явно. Ведущий @ допускается. Эти поля OpenAI принимаются, чтобы обычные вызовы SDK работали, но не применяются: tools, tool_choice, parallel_tool_calls, temperature, top_p, max_tokens, max_completion_tokens, stop, seed, user, stream_options. Два поля, которые изменили бы форму ответа, отклоняются с 400 DATA_INVALID_PARAMETER: response_format типа json_object или json_schema и n больше 1. response_format: {"type": "text"} и n: 1 проходят.

Поля запроса

FieldTypeDescription
modelrequiredstringХэндл агента, который отвечает, id из GET /v1/models. Ведущий @ допускается.
messagesrequiredarrayСообщения чата; хотя бы одно с ролью user, иначе 400 с param: messages. Последнее сообщение пользователя задаёт текущий ход. Предыдущие сообщения user и assistant становятся историей нового разговора; у существующей сессии своя история, и предыдущие сообщения не читаются. Сообщения system, developer и tool в историю не пишутся: у агента свои инструкции и инструменты. content это строка, массив текстовых частей ({type: text или input_text, text}) или null (сообщение assistant с tool_calls). Часть с картинкой, файлом или аудио отклоняется с 400 и param: messages[i].content. name, tool_calls и tool_call_id принимаются и игнорируются.
streambooleanЕсли true, стримит фреймы OpenAI chat.completion.chunk. По умолчанию false.
session_idstring (UUID)UUID разговора, который вы генерируете сами; передавайте его же, чтобы продолжить. Опустите для нового. Разговор принадлежит агенту, с которым начат, и организации ключа: с другим model или с другого ключа он отвечает 409 DATA_CONFLICT с param: session_id. Это не поле OpenAI: в Python SDK передавайте через extra_body, в Node.js просто в теле запроса.
max_iterationsintegerЛимит цикла агента. Границы и значение по умолчанию ниже. Передаётся так же, как session_id.
tool_eventsbooleanЕсли true (вместе со stream: true), в потоке идут и именованные события инструментов, см. ниже. По умолчанию false. Поле верхнего уровня: в Python SDK передавайте через extra_body.

max_iterations принимает значения от 1 до 50, по умолчанию 25.

Последнее сообщение пользователя не длиннее 200000 символов. Более длинное отклоняется 400 DATA_INVALID_PARAMETER, и message ошибки называет лимит. Большие данные передавайте частями в несколько ходов той же сессии.

Этот ключ действует от имени всего аккаунта

Ключ со scope chat:write управляет вашими агентами так же, как рабочее пространство: агент имеет доступ ко всему реестру инструментов, включая общие подключения организации и исполнение кода. Личные кабинеты и память создателя ключа ему закрыты. Относитесь к ключу как к учётным данным аккаунта: выдавайте отдельный ключ на интеграцию, храните только на сервере и ротируйте при утечке. Режима только-для-чтения у этого эндпоинта нет.

Стриминг

С stream: true ответ приходит чанками OpenAI по Server-Sent Events, с tool_events: true в потоке идут ещё события инструментов. Чанки, события, пинги, ошибка посреди потока и обрыв описаны на странице Стриминг (SSE).

Отличия от OpenAI

  • Эндпоинты: только POST /v1/chat/completions и GET /v1/models. responses, embeddings и completions нет.
  • Длительность: ход агента может длиться долго, до 1800 секунд. Без стрима соединение всё это время молчит: поднимите timeout клиента заметно выше значения по умолчанию в OpenAI SDK или включите stream: true и опирайтесь на ping. Со стримом держите timeout чтения выше интервала ping, а общий timeout запроса выше предела хода: клиент, который сдаётся через две минуты, обрывает долгую сверку на середине, а обрыв соединения останавливает ход.
  • usage: приходит только в ответе без стрима. В стриме чанка с usage нет.
  • finish_reason: stop. Сбой после начала потока приходит чанком error (см. Стриминг), а не значением finish_reason.
  • Обрыв соединения останавливает ход. Если закрыть поток посреди ответа, агент остановится, и ход запишется как остановленный, а не как сбой; продолжайте в той же сессии.
  • Отказ до старта хода это HTTP-ошибка, тело которой тот же объект error, со stream: true тоже до открытия потока. Коды, статусы и лимиты описаны в разделе Ошибки и лимиты API агентов.
  • Склейка чанков может отличаться от сохранённого ответа: агент иногда переписывает текст по ходу. Авторитетный текст отдаёт ответ без стрима.

Многоходовые диалоги

Сгенерируйте UUID и передавайте его как session_id во всех запросах разговора с тем же model. Ответ id сессии не возвращает, поэтому храните его у себя.

Частые вопросы

Что нужно поменять, чтобы использовать OpenAI SDK с Сам Решу?

Только base URL (https://samreshuuu.ru/v1) и ключ агента. Существующий код chat.completions работает без изменений, если model называет агента, а ключу нужен scope chat:write.

Что передавать в параметре model?

Хэндл агента, который должен ответить, из списка GET /v1/models (встроенный ассистент это samreshu). LLM выбирает настройка модели самого агента. Неизвестный или недоступный хэндл отклоняется с 404 DATA_NOT_FOUND, подмены нет. Параметры сэмплинга вроде temperature и max_tokens принимаются для совместимости, но не применяются; response_format json_object или json_schema и n больше 1 отклоняются с 400 DATA_INVALID_PARAMETER.

Как сохранять контекст между запросами?

Сгенерируйте UUID на своей стороне и передавайте его как session_id в каждом вызове. Ответ id сессии не возвращает: без session_id каждый вызов начинает новый разговор.

Что может ключ агента со scope chat:write?

Он управляет агентами вашей организации так же, как рабочее пространство, с доступом ко всему реестру инструментов, включая подключённые кабинеты и исполнение кода. Режима «только чтение» нет: относитесь к ключу как к учётным данным аккаунта, храните на сервере и меняйте при утечке.

Была ли страница полезна?