General Augment TypeScript SDK

General Augment is the easiest way to deploy a governed agent inside an existing authenticated app—with its users, permissions, memory, and tools already wired.

General Augment is the agent backend for your app.

This package is the server-side runtime client for POST /v1/responses. Configure Projects, Agents, identity, memory, capabilities, credentials, releases, and runtime keys with genaug or the General Augment dashboard. The SDK intentionally does not expose management-plane mutations.

Install

npm install @general-augment/[email protected]

Node.js 22–25 is supported. Keep the Project runtime key on your app backend; never ship it to a browser or mobile client.

Create a turn

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

const client = new GeneralAugmentClient({
  apiKey: process.env.GENAUG_API_KEY!,
  projectId: process.env.GENAUG_PROJECT_ID!,
  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));

Approval-gated turns return status: "in_progress" under the same response/run/trace identity. Use the durable response read to update the customer transcript after approval:

const terminal = await client.waitForResponse(response);
console.log(responseOutputText(terminal));

waitForResponse polls GET /v1/responses/{response_id}; it never starts a second Agent turn or tool effect. Use retrieveResponse(response.id) when your backend owns the polling schedule.

The CLI writes the key and its paired GENAUG_PROJECT_ID together. The SDK sends both so a stale or cross-Project key fails before Agent resolution. The user value must be the stable app-user identity declared by the Project’s trusted identity contract. General Augment resolves the exact Live release, Agent policy, capabilities, and per-user memory server-side.

Stream a turn

const messageId = "app-message-456"; // Persist this with the app message.
for await (const event of client.streamResponse(
  {
    agent: "support",
    user: authenticatedUser.id,
    input: "Cancel my last order",
  },
  { idempotencyKey: messageId },
)) {
  // Forward semantic Responses events to your UI.
  console.log(event.id, event.event, event.data);
}

Streams are live with either an automatic or caller-supplied idempotency key. Supply and persist the key when your app may reconnect; after a disconnect, retry the identical request with that key and deduplicate replayed events by event.id. The stream deadline defaults to five minutes and is configurable with streamTimeoutMs; use 0 only when your backend provides its own total deadline.

GeneralAugmentAPIError exposes statusCode, code, reason, requestId, retryAfter, and rate-limit metadata. Transient failures are retried with the same automatically generated idempotency key by default.

Keep previous_response_id state per stable (user, agent) pair. When the app switches Agents, start that Agent's own continuation chain (or reuse its last response ID); do not send another Agent's response ID. Shared user memory crosses Agents only when the release grants both Agents that memory namespace. The SDK raises GeneralAugmentAPIError for both event: error and terminal response.failed frames, so a UI never has to treat an empty failed stream as a response still in progress.

Full reference: https://docs.generalaugment.com/sdk/reference/

Verify and answer app-backend callbacks

For Cloudflare Workers and other Web Crypto runtimes, use verifyAppBackendCallback for the signed Project ownership challenge. For tool requests, use verifyAppBackendRequest, authorize the authenticated Project/user/Agent/capability against your own domain rules, claim or replay the request's idempotency_key, and return createSignedAppBackendResponse(result, { signingSecret }). The helper signs the exact JSON bytes and always supplies the required timestamp and signature headers. Keep the signing secret and runtime key server-side. The ownership verifier additionally requires an atomic claimReplay callback and rejects non-POST or larger-than-64,000-byte requests. See the complete field and error contract at https://docs.generalaugment.com/guides/app-backend-callbacks/.