Zum Inhalt springen
Olivares AI docs

Die Client-SDKs verwenden (Go, Java, Python, TypeScript)

Die control plane liefert vier hauseigene Client-SDKs für ihren veröffentlichten REST-Vertrag (/v1), generiert aus demselben OpenAPI-Dokument, das die Engine ausliefert und das die API-Referenz rendert:

SDKPaketLaufzeitanforderungen
Gogithub.com/olivaresai/olivares/clients/go (package olivares)nur stdlib
Javaai.olivares:olivares-client (package ai.olivares.client)Java ≥ 17, nur java.net.http des JDK
Pythonolivares-client (import olivares_client)Python ≥ 3.10, nur stdlib
TypeScript@olivaresai/clientglobales fetch (Node ≥ 20, Deno, Browser)

Alle vier teilen ein Design. Ein handgeschriebener Kern implementiert das vertragliche Verhalten — opake Bearer-Tokens (olvs_ Session / olvk_ API-Schlüssel), der X-Olivares-Tenant-Header, die einheitliche Fehler-Hülle der API, Cursor-Pagination (items/cursor/has_more), Retries, die Retry-After bei ratenbegrenzten Aufrufen beachten (429 immer; 503 nur für idempotente GETs), und die Deprecation-Header der Stabilitätsrichtlinie, die einmal pro Endpunkt herausgereicht werden. Darüber sitzt eine generierte Methode pro veröffentlichter Operation, benannt nach der Route (GET /v1/agents → GetV1Agents / get_v1_agents / getV1Agents), mit Request-/Response-Bodies als generisches JSON — der veröffentlichte Vertrag hält die Bodies bewusst opak.

Go

Abschnitt betitelt „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"])
}

Fehler sind *olivares.APIError (mit errors.As abgleichen); Code trägt die stabilen Fehlercodes des Vertrags (not_found, forbidden, rate_limited, …). Deprecation-Signale treffen einmal pro Endpunkt als slog-Warnung ein, oder über Ihren eigenen WithDeprecationHandler-Callback.

Java

Abschnitt betitelt „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"));
}

Fehler werfen OlivaresApiException mit getStatus(), getCode(), getApiMessage() und getRequestId(). Deprecation-Signale treffen einmal pro Endpunkt über den onDeprecation-Callback ein. Der Kern ist abhängigkeitsfrei — nur das java.net.http des JDK und ein handgeschriebener JSON-Codec.

Python

Abschnitt betitelt „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"])

Fehler lösen APIError aus, mit .status, .code, .message, .request_id. Veraltete Endpunkte geben eine DeprecationWarning pro Endpunkt aus (oder Ihren on_deprecation=-Callback). Für das standardmäßig selbstsignierte TLS der Engine geben Sie im Labor verify=False an — pinnen Sie in der Produktion eine echte CA.

TypeScript

Abschnitt betitelt „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);
}

Fehler sind APIError-Instanzen; Deprecation-Signale treffen einmal pro Endpunkt über console.warn oder Ihren onDeprecation-Callback ein.

Versionierung und Neugenerierung

Abschnitt betitelt „Versionierung und Neugenerierung“

Jedes SDK exportiert API_VERSION (die Major-Version des API-Vertrags, aus der es generiert wurde) und SPEC_HASH (das SHA-256 des exakten OpenAPI-Snapshots) — APIVersion und SpecHash in Go. Die Operationsschichten werden durch task sdk:generate neu generiert und durch task sdk:check auf Drift geprüft, was im Pre-Push-Gate und in CI läuft — eine Vertragsänderung kann nicht stillschweigend von den ausgelieferten Clients abweichen. Die Kompatibilitätszusage für alles, was die SDKs berühren, ist die API-Stabilitätsrichtlinie.

Verwandt

Abschnitt betitelt „Verwandt“