# SDK Reference

Source: https://docs.generalaugment.com/sdk/reference/
Description: TypeScript and Python helpers for server-side General Augment integrations.

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.

```bash
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:

```bash
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.

```bash
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.

```bash
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:

```go
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:

```swift
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:

```kotlin
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:

```bash
npm install @general-augment/sdk
```

```ts

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:

```ts
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:

```ts
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:

```bash
pip install general-augment-sdk
```

```python

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:

```python
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:

```python
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.

```ts
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

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

```python
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

```ts
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);
```

```python
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](/getting-started/quickstart/), [Local Testing](/guides/local-testing/),
and [API Reference](/api/).