Quickstart

This path gets you to one successful POST /v1/responses call first. Once that works, you can layer in tools, memory, approvals, observability, app-owned scheduled jobs, and channels without changing the core integration shape.

1. Create a project and API key

Sign in at https://app.generalaugment.com, create a project for your app, and generate a project-scoped API key from the onboarding flow or project settings.

Keep the key on your server. Browser and mobile clients should call your backend, not General Augment directly.

export GENAUG_API_KEY="gaadmlive_your_project_scoped_key"
export GENAUG_API_BASE_URL="https://api.generalaugment.com"

Authenticate the CLI from the installed genaug package, or use the repository command prefix when working from a source checkout:

uv run --project packages/cli genaug auth login \
  --api-key "$GENAUG_API_KEY" \
  --base-url "$GENAUG_API_BASE_URL"
uv run --project packages/cli genaug doctor --json
uv run --project packages/cli genaug auth whoami

2. Make your first backend call

Call the Responses-compatible API from your backend with a stable user id from your own product.

curl -sS "$GENAUG_API_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $GENAUG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "balanced",
    "user": "usr_123",
    "input": "Help me summarize this support request and suggest the next action.",
    "metadata": {"source": "quickstart"}
  }'

TypeScript example:

const baseUrl = process.env.GENAUG_API_BASE_URL ?? "https://api.generalaugment.com";

const response = await fetch(`${baseUrl}/v1/responses`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GENAUG_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "balanced",
    user: "usr_123",
    input: "Help me summarize this support request and suggest the next action.",
    metadata: { source: "quickstart" },
  }),
});

if (!response.ok) {
  throw new Error(`Responses call failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Use model: "simple", "balanced", or "complex" as a portable tier selector. Operators can change the provider model behind each project tier without app code changes. Current Responses-style reasoning.effort can override auto-routing: low maps to simple, medium to balanced, and high or xhigh to complex. The legacy top-level reasoning_effort alias remains accepted for existing clients.

3. Confirm the response shape

Look for a successful response with model output in the output array.

{
  "id": "resp_123",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Here is the next action..."
        }
      ]
    }
  ]
}

Store the response id and metadata.general_augment_trace_id for support. The top-level model and metadata.general_augment_model show the actual model used after tier routing, usage.input_tokens, usage.output_tokens, and usage.total_tokens show token counts, and metadata.general_augment_cost_usd includes the per-turn cost when available.

Once this works, you have the core General Augment integration in place. /v1/responses and the documented app-developer v1 surfaces are covered by the API stability policy.

Use an opaque stable app user id such as app:user_123 or your database user id on every production turn. General Augment resolves that value inside the authenticated project, then uses the resolved project user for memory, approvals, traces, usage, and future channel identity links.

4. Test offline

For backend CI and contract tests, run the local HTTP mock and point your client 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 supports /v1/responses, memory store/search/profile/delete routes, health, idempotency replays, trace metadata, and semantic SSE fixtures without live model calls or provider credentials. See Local Testing for the supported routes and limitations.

5. Add tools

When the first turn is working, connect your app APIs as governed tools.

• Use the dashboard or CLI to register built-in tools.
• Import an OpenAPI spec to generate governed tool definitions.
• Keep credentials behind your backend or auth proxy instead of passing them in prompts.

From a source checkout, the CLI path is:

uv run --project packages/cli genaug init my-app-agent --tool web_search

# Or, when your API spec is ready:
uv run --project packages/cli genaug integrate https://api.example.com/openapi.json \
  --name my-app-agent

Use genaug init when you are still shaping the agent before an OpenAPI spec exists. Use genaug integrate when your app API is ready to become governed tools. The scaffold includes CODING_AGENT_PROMPT.md, a paste-ready handoff for Claude Code, Cursor, Codex, or another coding agent to wire the app backend, keep keys server-side, add memory, and run genaug smoke, genaug verify, and genaug onboarding verify.

Then test locally:

uv run --project packages/cli genaug validate ./my-app-agent/genaug-agent.yaml
uv run --project packages/cli genaug dev ./my-app-agent/genaug-agent.yaml --message "What can you do?"

Before production traffic, prove the hosted tenant end to end:

uv run --project packages/cli genaug deploy ./my-app-agent/genaug-agent.yaml
uv run --project packages/cli genaug doctor --json
uv run --project packages/cli genaug smoke \
  --project my-app-agent \
  --message "Reply exactly with: genaug-smoke-ok" \
  --json
uv run --project packages/cli genaug smoke \
  --project my-app-agent \
  --structured \
  --json
uv run --project packages/cli genaug verify --project my-app-agent
uv run --project packages/cli genaug onboarding verify --project my-app-agent --json

Fully working means CLI auth and API readiness pass, /v1/responses answers with the project key, structured output succeeds, generated tools are registered and governed, usage and trace rows are written, and the printed dashboard URLs show the same project across overview, tools, integration setup, and analytics. In genaug verify, project_key_execution=PASS means the configured project-scoped key actually called /v1/responses; project_key_execution=SKIP means you verified the project with broader admin auth and still need a project-key smoke before launch. Keep the JSON from genaug onboarding verify with release evidence because it includes CLI/API version metadata, auth scope, dashboard links, usage limits, memory lifecycle checks, trace readiness, and per-check status without exposing raw keys.

6. Layer in memory, approvals, and channels

After the core backend path is live, expand the same project:

• Memory: keep continuity per user by sending the same stable user id on every turn, and use the same value as user_id for explicit memory API calls from trusted server code. Deterministic launch proof should include explicit store/search/profile checks and per-user memory-context scoping; autonomous memory final-answer behavior should have separate hosted smoke and trace evidence before it is treated as a production guarantee.
• Approvals: require confirmation for sensitive write actions or external side effects.
• Observability: review traces, usage, cost, and tool execution from the project portal.
• Rate and budget protection: handle 429 with Retry-After, handle 402 as a budget gate, and request higher launch ceilings before planned traffic.
• Channels and jobs: bring the same agent to Telegram, WhatsApp, SMS, or app-owned scheduled workflows that call /v1/responses from your backend.

Next, read Connect Your API to add tools or Add chat to your app for the in-product path.