Перейти к содержимому
Olivares AI docs

Использование клиентских SDK (Go, Java, Python, TypeScript)

Control plane поставляется с четырьмя официальными клиентскими SDK для своего опубликованного REST-контракта (/v1), сгенерированными из того же документа OpenAPI, который движок отдаёт, а справочник API отображает:

SDKПакетТребования рантайма
Gogithub.com/olivaresai/olivares/clients/go (пакет olivares)только stdlib
Javaai.olivares:olivares-client (пакет ai.olivares.client)Java ≥ 17, только java.net.http из JDK
Pythonolivares-client (импорт olivares_client)Python ≥ 3.10, только stdlib
TypeScript@olivaresai/clientглобальный fetch (Node ≥ 20, Deno, браузеры)

Все четыре используют один дизайн. Написанное вручную ядро реализует контрактное поведение — непрозрачные bearer-токены (сессия olvs_ / API-ключ olvk_), заголовок X-Olivares-Tenant, единый конверт ошибок API, курсорную пагинацию (items/cursor/has_more), повторы, которые учитывают Retry-After для вызовов с ограничением частоты (429 всегда; 503 только для идемпотентных GET), и заголовки устаревания из политики стабильности, выводимые один раз на конечную точку. Поверх этого расположен сгенерированный метод на каждую опубликованную операцию, названный по маршруту (GET /v1/agents → GetV1Agents / get_v1_agents / getV1Agents), с телами запроса/ответа в виде обобщённого JSON — опубликованный контракт намеренно держит тела непрозрачными.

Go

Заголовок раздела «Go»
import olivares "github.com/olivaresai/olivares/clients/go"


c, err := olivares.New("https://olivares.example:8443", os.Getenv("OLIVARES_API_TOKEN"),
    olivares.WithTenant("9be0…"))
if err != nil { … }


info, err := c.GetV1ServerInfo(ctx)


for agent, err := range c.ListPages(ctx, "/v1/agents", olivares.Query("limit", "100")) {
    if err != nil { … }
    fmt.Println(agent["id"])
}

Ошибки представляют собой *olivares.APIError (сопоставляйте через errors.As); Code несёт стабильные коды ошибок контракта (not_found, forbidden, rate_limited, …). Сигналы устаревания приходят один раз на конечную точку как предупреждение slog или ваш собственный коллбэк WithDeprecationHandler.

Java

Заголовок раздела «Java»
import ai.olivares.client.Client;
import ai.olivares.client.ClientOptions;
import ai.olivares.client.OlivaresApiException;
import ai.olivares.client.RequestOptions;


Client c = new Client(ClientOptions.builder()
    .endpoint("https://olivares.example:8443")
    .token(System.getenv("OLIVARES_API_TOKEN"))
    .tenant("9be0…")
    .build());


var info = c.getV1ServerInfo();


for (var agent : c.paginate("/v1/agents",
        RequestOptions.builder().query("limit", "100").build())) {
    System.out.println(agent.get("id"));
}

Ошибки выбрасывают OlivaresApiException с getStatus(), getCode(), getApiMessage() и getRequestId(). Сигналы устаревания приходят один раз на конечную точку через коллбэк onDeprecation. Ядро без зависимостей — только java.net.http из JDK и написанный вручную JSON-кодек.

Python

Заголовок раздела «Python»
from olivares_client import Client, APIError


c = Client("https://olivares.example:8443", token="olvk_…", tenant="9be0…")


info = c.get_v1_server_info()
for agent in c.paginate("/v1/agents", limit="100"):
    print(agent["id"])

Ошибки порождают APIError с .status, .code, .message, .request_id. Устаревшие конечные точки выдают одно DeprecationWarning на конечную точку (или ваш коллбэк on_deprecation=). Для готового самоподписанного TLS движка передавайте verify=False в лабораторных условиях — в продакшене закрепляйте реальный CA.

TypeScript

Заголовок раздела «TypeScript»
import { Client, APIError } from "@olivaresai/client";


const c = new Client({ endpoint: "https://olivares.example:8443", token: "olvk_…" });


const info = await c.getV1ServerInfo();
for await (const agent of c.paginate("/v1/agents", { query: { limit: "100" } })) {
  console.log(agent.id);
}

Ошибки — это экземпляры APIError; сигналы устаревания приходят один раз на конечную точку через console.warn или ваш коллбэк onDeprecation.

Версионирование и перегенерация

Заголовок раздела «Версионирование и перегенерация»

Каждый SDK экспортирует API_VERSION (мажорная версия контракта API, из которой он был сгенерирован) и SPEC_HASH (SHA-256 точного снимка OpenAPI) — APIVersion и SpecHash в Go. Слои операций перегенерируются через task sdk:generate и проверяются на расхождение через task sdk:check, который запускается в пре-пуш гейте и в CI — изменение контракта не может молча разойтись с поставляемыми клиентами. Обязательство по совместимости для всего, чего касаются SDK, — это политика стабильности API.

Связанное

Заголовок раздела «Связанное»