Client Wrappers

Sagewai provides client libraries in 17 programming languages. Every wrapper exposes the same API surface — Harness, Registry, Observatory, and Gateway — with three authentication methods.

Supported Languages

Tier 1 wrappers have full implementations with tests and are published to their respective package registries. Tier 2 wrappers follow the same API surface and are currently in development — install commands will be available once packages are published. Mobile wrappers share the same API as their base language (TypeScript for React Native, Dart for Flutter).

Quick Start by Language

Python

from sagewai_client import SagewaiClient

client = SagewaiClient(
    base_url="http://localhost:8100",
    api_key="sk-harness-...",
)

response = client.chat("gpt-4o", "What is Sagewai?")
print(response.content)

TypeScript / JavaScript

import { SagewaiClient } from "sagewai";

const client = new SagewaiClient({
  baseUrl: "http://localhost:8100",
  apiKey: "sk-harness-...",
});

const response = await client.chat({
  model: "gpt-4o",
  messages: [{ role: "user", content: "What is Sagewai?" }],
});
console.log(response.content);

Go

package main

import (
    "context"
    "fmt"
    sagewai "github.com/sagewai/sagewai-go"
)

func main() {
    client := sagewai.NewClient(
        sagewai.WithBaseURL("http://localhost:8100"),
        sagewai.WithAPIKey("sk-harness-..."),
    )

    ctx := context.Background()
    response, err := client.Chat(ctx, &sagewai.ChatRequest{
        Model:    "gpt-4o",
        Messages: []sagewai.Message{{Role: "user", Content: "What is Sagewai?"}},
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(response.Content)
}

Rust

use sagewai::SagewaiClient;

#[tokio::main]
async fn main() -> Result<(), sagewai::Error> {
    let client = SagewaiClient::builder()
        .base_url("http://localhost:8100")
        .api_key("sk-harness-...")
        .build()?;

    let response = client
        .chat("gpt-4o")
        .message("user", "What is Sagewai?")
        .send()
        .await?;

    println!("{}", response.content);
    Ok(())
}

Java

import com.sagecurator.sagewai.SagewaiClient;

var client = SagewaiClient.builder()
    .baseUrl("http://localhost:8100")
    .apiKey("sk-harness-...")
    .build();

var response = client.chat("gpt-4o", "What is Sagewai?");
System.out.println(response.content());

C# / .NET

using Sagewai;

var client = new SagewaiClient("http://localhost:8100", "sk-harness-...");
var response = await client.ChatAsync("gpt-4o", "What is Sagewai?");
Console.WriteLine(response.Content);

Kotlin

import com.sagecurator.sagewai.SagewaiClient

val client = SagewaiClient(
    baseUrl = "http://localhost:8100",
    apiKey = "sk-harness-..."
)

val response = client.chat("gpt-4o", "What is Sagewai?")
println(response.content)

Ruby

require "sagewai"

client = Sagewai::Client.new(
  base_url: "http://localhost:8100",
  api_key: "sk-harness-..."
)

response = client.chat("gpt-4o", "What is Sagewai?")
puts response.content

Swift

import Sagewai

let client = SagewaiClient(
    baseURL: "http://localhost:8100",
    apiKey: "sk-harness-..."
)

let response = try await client.chat(model: "gpt-4o", message: "What is Sagewai?")
print(response.content)

PHP

use Sagewai\Client;

$client = new Client("http://localhost:8100", "sk-harness-...");
$response = $client->chat("gpt-4o", "What is Sagewai?");
echo $response->content;

Dart / Flutter

import 'package:sagewai/sagewai.dart';

final client = SagewaiClient(
  baseUrl: 'http://localhost:8100',
  apiKey: 'sk-harness-...',
);

final response = await client.chat('gpt-4o', 'What is Sagewai?');
print(response.content);

Elixir

client = Sagewai.Client.new(
  base_url: "http://localhost:8100",
  api_key: "sk-harness-..."
)

{:ok, response} = Sagewai.chat(client, "gpt-4o", "What is Sagewai?")
IO.puts(response.content)

Unified API Surface

Every wrapper exposes the same operations organized by pillar:

Harness (LLM Proxy)

Registry (Agent Governance)

Observatory (Cost Tracking)

Gateway (Token Management)

Health

Authentication

All wrappers support three authentication methods:

API Key (Simplest)

Best for scripts, services, and development.

# Python
client = SagewaiClient(base_url="...", api_key="sk-harness-...")

// TypeScript
const client = new SagewaiClient({ baseUrl: "...", apiKey: "sk-harness-..." });

// Go
client := sagewai.NewClient(sagewai.WithAPIKey("sk-harness-..."))

Sends X-API-Key header with every request.

JWT (Token-based)

Best for authenticated users and service-to-service calls.

# Python
client = SagewaiClient(base_url="...", jwt="eyJhbGciOi...")

// TypeScript
const client = new SagewaiClient({ baseUrl: "...", auth: { type: "jwt", token: "eyJ..." } });

// Go
client := sagewai.NewClient(sagewai.WithJWT("eyJ..."))

Sends Authorization: Bearer header.

OAuth (Enterprise)

Supports automatic token refresh for long-lived applications.

// TypeScript — with auto-refresh
const client = new SagewaiClient({
  baseUrl: "http://localhost:8100",
  auth: {
    type: "oauth",
    accessToken: "ya29...",
    refreshToken: "1//0...",
    refreshUrl: "https://auth.sagewai.ai/token",
  },
});

Response Types

Consistent across all wrappers:

ChatResponse

AgentSummary

SpendSummary

Python SDK vs Client Wrappers

In a typical setup: Python SDK defines and runs your agents on the server, while client wrappers let your TypeScript frontend, Go microservice, or Rust CLI interact with those agents.