# Quickstart

Source: https://docs.generalaugment.com/getting-started/quickstart/
Description: Add your first General Augment agent call to your app backend.

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.

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

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

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

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

```json
{
  "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](/guides/api-stability/).

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:

```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 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](/guides/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:

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

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

```bash
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](/guides/connect-your-api/) to add tools or
[Add chat to your app](/guides/add-chat-to-your-app/) for the in-product path.