SDK Reference

General Augment SDKs are backend integration packages. Use them only from trusted server code. Browser and mobile clients should call your backend, and your backend should call General Augment.

Use project-scoped API keys for app traffic such as /v1/responses and memory calls. Admin and setup helpers such as project creation, config deploy, OpenAPI registration, usage, and hosted test calls require a management/admin-capable key and send it as X-Admin-Key.

GA package names:

• TypeScript/Node: @general-augment/sdk
• Python: general-augment-sdk

Version status:

Surface	Status	Notes
TypeScript/Node SDK	GA, current target 0.1.x	Server-side SDK for Responses, memory, admin, identity, usage, and test calls.
Python SDK	GA, current target 0.1.x	Server-side SDK for Responses, memory, admin, identity, usage, and test calls.
Raw HTTP contract	Stable v1 app contract	Fallback for backend services, generated clients, mobile backend adapters, and languages without an official SDK.
Swift, Go, Kotlin SDKs	Not official SDKs today	Use your backend plus raw HTTP or generated clients. Do not put General Augment API keys in mobile apps.

Versioning and upgrades

Current SDK packages target 0.1.x while the v1 HTTP contract remains stable. Use raw HTTP, local mock contract tests, or repo-local package paths when a deployment environment cannot resolve its package index. Operators can use scripts/package-registry-readiness.py and scripts/local-package-publish.py to verify and repair package-index availability without changing the app integration contract.

Registry availability is split as of 2026-05-14: npm packages are visible at 0.1.1 for @general-augment/sdk and @general-augment/local-imessage; PyPI currently exposes 0.1.0 for general-augment-sdk and general-augment-cli while the source packages target 0.1.1. Before relying on registry installs, run uv run python scripts/package-registry-readiness.py and keep the resulting readiness artifact with release evidence. Use repo-local package paths or raw HTTP until PyPI 0.1.1 packages are visible.

pip install --upgrade general-augment-sdk general-augment-cli
npm install @general-augment/sdk@latest
genaug --version

The TypeScript SDK exports VERSION; the Python SDK exports __version__ from genaug. Include those values in backend health checks or support bundles so operators can connect traces to the shipped client. When you run genaug onboarding verify --project <project> --json, keep the artifact with your app release evidence. It should sit next to the SDK package version, CLI genaug --version, API health/build metadata, and app commit SHA so support can separate client-version drift from platform behavior.

If your environment cannot resolve these packages from its package index, use the repository packages, raw HTTP examples, or the local mock server for app contract tests. Operators verify registry visibility with uv run python scripts/package-registry-readiness.py during release checks.

There is no official Swift or Go SDK today. There is also no official Kotlin SDK today. Native apps should call their own backend so General Augment API keys stay server-side.

Local Mock

Run the deterministic local mock and point either SDK at it:

uv run --project packages/cli genaug mock --host 127.0.0.1 --port 8787 --quiet
export GENAUG_API_BASE_URL="http://127.0.0.1:8787"
export GENAUG_API_KEY="local-test"

The mock is for contract tests and fixtures. It does not run the live managed runtime, enforce billing, or validate production provider behavior.

The SDKs include mock-backed examples. Run scripts/package-registry-readiness.py before using registry install commands in a production release.

npm install @general-augment/sdk
node examples/contract-test.mjs

pip install general-augment-sdk
python examples/contract_test.py

Raw HTTP Fallback

Use the raw HTTP contract from your backend when an official SDK is unavailable. Native apps should call your backend, and your backend should call General Augment with the project-scoped key.

curl -sS "${GENAUG_API_BASE_URL:-https://api.generalaugment.com}/v1/responses" \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: support-thread-123-turn-1" \
  -H "X-Request-ID: req_app_123" \
  -d '{
    "model": "balanced",
    "user": "app-user-123",
    "input": "Summarize this support request and suggest the next action.",
    "metadata": { "feature": "support-triage" }
  }'

Go backend:

body, _ := json.Marshal(map[string]any{
  "model": "balanced",
  "user":  userID,
  "input": input,
})

baseURL := os.Getenv("GENAUG_API_BASE_URL")
if baseURL == "" {
  baseURL = "https://api.generalaugment.com"
}

req, _ := http.NewRequestWithContext(ctx, "POST", baseURL+"/v1/responses", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("GENAUG_API_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Idempotency-Key", "support-thread-123-turn-1")

Swift mobile-to-backend:

let url = URL(string: "https://api.yourapp.com/ai/responses")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = try JSONSerialization.data(withJSONObject: [
  "user": "app-user-123",
  "input": "Summarize this support request and suggest the next action."
])
let (_, response) = try await URLSession.shared.data(for: request)

Kotlin mobile-to-backend:

val body = """
  {"user":"app-user-123","input":"Summarize this support request and suggest the next action."}
""".trimIndent().toRequestBody("application/json".toMediaType())

val request = Request.Builder()
  .url("https://api.yourapp.com/ai/responses")
  .post(body)
  .build()

TypeScript

Use the package install for app integrations:

npm install @general-augment/sdk

import { GeneralAugmentClient, responseOutputText } from "@general-augment/sdk";

const client = new GeneralAugmentClient({
  apiKey: process.env.GENAUG_API_KEY!,
  baseUrl: process.env.GENAUG_API_BASE_URL ?? "https://api.generalaugment.com",
  timeoutMs: 60_000,
});

const response = await client.createResponse(
  {
    model: "balanced",
    user: "app-user-123",
    input: "Summarize this support request and suggest the next action.",
    metadata: { feature: "support-triage" },
  },
  {
    idempotencyKey: "support-thread-123-turn-1",
    requestId: "req_app_123",
  },
);

const text = responseOutputText(response);

The TypeScript client defaults to a 60-second request timeout and reports stalled calls as a typed request_timeout API error. Set timeoutMs: 0 only when your app backend already applies its own fetch timeout policy.

Structured output:

const structured = await client.createResponse({
  model: "balanced",
  user: "app-user-123",
  input: "Extract: window seat.",
  text: {
    format: {
      type: "json_schema",
      name: "travel_preference",
      strict: true,
      schema: {
        type: "object",
        required: ["seat"],
        properties: { seat: { type: "string" } },
        additionalProperties: false,
      },
    },
  },
});

Streaming:

for await (const event of client.streamResponse({
  model: "balanced",
  user: "app-user-123",
  input: "Draft a two sentence welcome message.",
})) {
  if (event.event === "response.output_text.delta") {
    process.stdout.write(String((event.data as any).delta ?? ""));
  }
}

Python

Use the package install for app integrations:

pip install general-augment-sdk

import os

from genaug import GeneralAugmentClient, response_output_text

client = GeneralAugmentClient(
    api_key=os.environ["GENAUG_API_KEY"],
    base_url=os.getenv("GENAUG_API_BASE_URL", "https://api.generalaugment.com"),
)

response = client.create_response(
    {
        "model": "balanced",
        "user": "app-user-123",
        "input": "Summarize this support request and suggest the next action.",
        "metadata": {"feature": "support-triage"},
    },
    idempotency_key="support-thread-123-turn-1",
    request_id="req_app_123",
)

text = response_output_text(response)

Structured output:

structured = client.create_response(
    {
        "model": "balanced",
        "user": "app-user-123",
        "input": "Extract: window seat.",
        "text": {
            "format": {
                "type": "json_schema",
                "name": "travel_preference",
                "strict": True,
                "schema": {
                    "type": "object",
                    "required": ["seat"],
                    "properties": {"seat": {"type": "string"}},
                    "additionalProperties": False,
                },
            }
        },
    }
)

Streaming:

for event in client.stream_response(
    {
        "model": "balanced",
        "user": "app-user-123",
        "input": "Draft a two sentence welcome message.",
    }
):
    if event["event"] == "response.output_text.delta":
        print(event["data"].get("delta", ""), end="")

Memory Helpers

Use explicit memory writes for durable facts, then send the same user value to /v1/responses so future turns resolve the right project user.

await client.storeMemory({
  user_id: "app-user-123",
  fact: "User prefers window seats",
  fact_type: "preference",
  importance_score: 0.9,
  source: "booking",
  idempotency_key: "memory-window-seat-1",
});

Usage And Admin Helpers

const usage = await client.usage("project_123", {
  startDate: "2026-04-01",
  endDate: "2026-04-24",
});

usage = client.usage("project_123", start_date="2026-04-01", end_date="2026-04-24")

The TypeScript and Python SDKs also include admin/integration helpers for project config, OpenAPI tools, identity linking, usage, hosted test calls, and scheduled-job lifecycle. Use a management/admin-capable key for these helpers.

Scheduled Jobs

const job = await client.createScheduledJob("project_123", {
  target_app_user_id: "app-user-123",
  prompt: "Review this account and summarize the next action.",
  schedule: { type: "interval", every_seconds: 3600 },
});

await client.listScheduledJobs("project_123", { status: "active" });
await client.listScheduledJobRuns("project_123", job.id, { limit: 20 });
await client.dispatchScheduledJob("project_123", job.id, {
  dispatchKey: "operator-smoke-1",
  execute: false,
});
await client.pauseScheduledJob("project_123", job.id);
await client.resumeScheduledJob("project_123", job.id);
await client.deleteScheduledJob("project_123", job.id);

job = client.create_scheduled_job(
    "project_123",
    {
        "target_app_user_id": "app-user-123",
        "prompt": "Review this account and summarize the next action.",
        "schedule": {"type": "interval", "every_seconds": 3600},
    },
)

client.list_scheduled_jobs("project_123", status="active")
client.list_scheduled_job_runs("project_123", job["id"], limit=20)
client.dispatch_scheduled_job(
    "project_123",
    job["id"],
    dispatch_key="operator-smoke-1",
    execute=False,
)
client.pause_scheduled_job("project_123", job["id"])
client.resume_scheduled_job("project_123", job["id"])
client.delete_scheduled_job("project_123", job["id"])

Scheduled job responses include next/last run timestamps, retry history, terminal reason, target user/channel, latest trace ID, and linked durable run IDs.

Error Handling

SDK API errors preserve HTTP status, stable reason/code values when present, Retry-After, rate-limit headers, request IDs, and rate-limit metadata. The Python SDK also exposes trace IDs and the decoded response body when the API returns them. Switch on reason for retry and limit behavior instead of parsing human-readable messages.

Related: Quickstart, Local Testing, and API Reference.