SDK Reference

The official SDKs connect a trusted app backend to the stable General Augment runtime. They intentionally expose one job: invoke a deployed Agent through POST /v1/responses.

Project configuration is a separate governed control plane. Use genaug or the dashboard to create Agents, grant capabilities and memory, bind users and connections, test Candidates, inspect runs, and promote releases. SDK calls cannot mutate Project desired state or bypass release review.

Never put a General Augment runtime key in browser or mobile code.

Packages

Language	Package	Supported runtime
TypeScript	@general-augment/sdk	Node.js 22–25
Python	general-augment-sdk	Python 3.10+

There is no official Swift or Go SDK today. Mobile apps call their own authenticated backend, which calls General Augment.

The v3 source manifests target general-augment-sdk==0.5.0 and @general-augment/sdk@0.5.0. Confirm those exact versions are public before relying on a registry install:

uv run python scripts/package-registry-readiness.py

After the readiness artifact confirms the expected release:

npm install @general-augment/sdk@0.5.0
pip install general-augment-sdk==0.5.0 general-augment-cli==0.5.0

TypeScript

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

const client = new GeneralAugmentClient({
  apiKey: process.env.GENAUG_API_KEY!,
  streamTimeoutMs: 300_000,
});

const response = await client.createResponse(
  {
    agent: "support",
    user: authenticatedUser.id,
    input: "Where is my order?",
  },
  { idempotencyKey: `support:${authenticatedUser.id}:${message.id}` },
);

console.log(responseOutputText(response));

const messageId = "app-message-456";
for await (const event of client.streamResponse(
  {
    agent: "support",
    user: authenticatedUser.id,
    input: "Cancel my latest order",
  },
  { idempotencyKey: messageId },
)) {
  console.log(event.id, event.event, event.data);
}

Python

import os

from genaug import GeneralAugmentClient, response_output_text

with GeneralAugmentClient(
    api_key=os.environ["GENAUG_API_KEY"],
    stream_timeout=300,
) as client:
    response = client.create_response(
        {
            "agent": "support",
            "user": authenticated_user.id,
            "input": "Where is my order?",
        },
        idempotency_key=f"support:{authenticated_user.id}:{message.id}",
    )

print(response_output_text(response))

with GeneralAugmentClient(api_key=os.environ["GENAUG_API_KEY"]) as client:
    message_id = "app-message-456"
    for event in client.stream_response(
        {
            "agent": "support",
            "user": authenticated_user.id,
            "input": "Cancel my latest order",
        },
        idempotency_key=message_id,
    ):
        print(event.get("id"), event["event"], event["data"])

Runtime Contract

• Authentication is Authorization: Bearer <project-runtime-key>.
• agent identifies an Agent in the exact Live release.
• user is the stable authenticated app-user claim declared by the Project identity contract.
• General Augment supplies that Agent’s exact capabilities, connections, policy, skills, and permitted memory namespaces server-side.
• Billable turns receive an idempotency key automatically unless the caller supplies one.
• Apps that reconnect must supply and persist a stable key because a newly generated key starts a new turn.
• Idempotent streams remain live; the key is reserved before HTTP 200 rather than forcing the Agent turn to buffer.
• TypeScript uses a configurable streamTimeoutMs and Python uses stream_timeout; both default to a five-minute total stream deadline while ordinary request timeouts remain shorter.
• Stream events expose the server SSE id. After a disconnect, retry the identical request with the same key and deduplicate any replay from sequence zero by id.
• GeneralAugmentAPIError preserves stable error code, reason, request ID, retry timing, and rate-limit metadata.

The SDK test harness is runtime-only. Hosted Candidate acceptance comes from genaug agent test, immutable run evidence, and the Releases review surface—not from a local evidence file or public mock-management command.

For signed app-backend verification and direct-tool callbacks, use the canonical callback contract. @general-augment/sdk exports the edge-compatible verifyAppBackendCallback helper; the Python SDK does not yet ship parity.