Agent manual

Manage App AI Gateway on a person's behalf with the CLI or an existing MCP connection. This manual is also served as plain markdown at https://docs.appaigateway.com/agents.md. Use the documentation index to find task-specific guides and OpenAPI for exact HTTP schemas. Prefer the connected server's capabilities and the installed CLI's --help when versions differ.

Choose the connection before changing anything

Hosted defaults:

For self-hosting, substitute that deployment's console and API origins; they may be the same. Do not deploy infrastructure unless the person asked for self-hosting. GATEWAY_URL below means the selected API origin, with no /v1 suffix. Use the URLs returned by handoff operations instead of constructing them.

With MCP, start with get_account and read agw://guide; see "MCP" below. For the CLI, install @maxceem/agw on Node.js 22.19 or later, then:

agw deployment status --json --no-input
agw account status --json --no-input

The CLI defaults to hosted only when no connection is saved. Inspect its reported URL, deployment and account; do not assume a previous task left the right connection active. A configured credential is not proof it is valid.

• Existing account: use the saved connection if it matches. Otherwise run agw account login --no-open --json --no-input. To sign in to hosted again, use agw deployment connect --cloud --no-open --json --no-input. Without a supplied management key, this returns a pending browser login just like account login; have the person approve it before continuing.
• Existing self-hosted gateway: use agw deployment connect --url URL --no-open --json --no-input.
• New hosted account, when requested: on a fresh hosted connection, the first provider, provider-gateway or app creation initializes an unclaimed account. Do not use this path to recover a failed login to an existing one. Check account status for its expiry, start agw account claim --no-open --json --no-input, and give the person the URL to keep the account.

Help, status, lists, validation and dry runs never create accounts. Claiming requires the person to create their sign-in in their own browser; do not open or approve the claim yourself. Claiming preserves the agent's access.

CLI task workflow

1. Read agw provider list --json and agw app list --json. Reuse the IDs and slugs returned; inspect a target with agw app show <app-id> --json.
2. Add a missing provider with agw provider add --type openai --browser --no-open --json --no-input. Give the person the returned URL and wait with agw operation wait <id> --json. Never request the secret in chat.
3. Read the command's --help and make the requested change. For iOS, supply the person's Team ID and Bundle ID. Set --attest-environments production for a production-only app: CLI flag-based creation otherwise enables both production and development. For server keys, use --key-output with an unused private path, or retain the CLI's managed private output file.
4. For a new app file, use agw app validate --file app.json --json. For an existing app, use agw app update <app-id> --file app.json --dry-run --json so validation is performed as an update of that app. The file contains only name, config and status from result.app; exclude metadata such as id, revision and timestamps. Keep every existing configuration field.
5. Apply the requested update, then reread the app. File updates replace the whole document. The CLI reads a revision when the update command starts; this protects against a competing write during that command, not edits made since an earlier file export. Refresh and merge an old file first.
6. Run agw app check <app-id> --json and agw app snippet <app-id> --json. Resolve any placeholders named in result.notes. The check reads configuration only: no provider key, physical device, sign-in or entitlement is exercised. Do not send inference unless the person requested it.
7. Report the app ID, provider slugs, API base URL, key file location, checks and remaining work. Report pending handoffs as pending, never completed.

For every unattended command, use --json --no-input; for browser handoffs, add --no-open. --json returns {schemaVersion:1,ok:true,context,result} or {schemaVersion:1,ok:false,error}. Inspect both ok and the result: a successful pending operation still needs the browser step and polling. Exit codes are 0 success, 2 invalid input, 3 remote failure, 4 state/authentication recovery and 5 wait timeout. A timeout does not cancel the operation. Follow error.nextAction, preserving retry state after a lost response.

Use agw usage show --month YYYY-MM --json for retained account totals, including deleted apps. Configuration files transfer neither credentials nor usage history between deployments.

Signing in

• agw account login --no-open --json opens a login and returns state: "pending" with url, userCode and id. Give the person the URL and the pairing code. They open the URL in their own browser, check that the page shows the same code, and approve. Then run agw operation wait <id> --json; the CLI stores its new management key and prints only non-secret fields. Without --no-open the CLI also opens the page in the local browser when one is available (not over SSH, on Linux with no display, or without a terminal), and without --json it waits for the approval itself and prints the pairing code to stderr.
• For your own deployment, agw deployment connect --url URL runs the same login against that URL.
• A declined login fails with operation_denied; an expired one with operation_expired. Start a new login; do not retry the old id.
• In CI, or when the person gives you an existing management key, use the AGW_MANAGEMENT_KEY environment variable. When it is set it is the credential for every command, ahead of any saved login, and the environment key is not saved to disk; agw account login refuses with environment_credential. Alternatively pipe the key once with agw account login --key-stdin (or agw deployment connect --url URL --key-stdin) to save it. Never pass a key as an argument.
• agw account logout --json revokes the saved key and removes it locally. Its result is {loggedOut: true, revoked: true|false}; revoked: false means the key was already refused or the deployment could not be reached.
• Every key a CLI login creates appears on the console's Access page, tagged CLI and labelled with the machine it was issued to, for example CLI on mac-studio. The person can revoke it there at any time.

MCP

If you are connected to the gateway as an MCP server, at the console's address followed by /mcp (https://console.appaigateway.com/mcp when hosted), you can work with the same account through its tools instead of the CLI. A client connects with OAuth by itself: the person approves it on the console's consent page, choosing the account and whether you may read or manage, or continues without an account, which creates an unclaimed account your connection manages. An unclaimed account expires unless a person claims it: when get_account says so, call claim_account and give the person its URL. A management key as a bearer token works too. Use the tools: get_account first, then list_providers, list_apps, get_app, validate_app, check_app, usage and event tools, and the change tools. add_app and add_app_key take two calls: the first reserves and creates nothing, the second, with the same arguments and the answer's handle, creates it once, and repeating it is safe. An answer that names an operation calls it id; that is what get_operation takes. A key is revealed on a page a person opens, never in a tool result: give them reveal_url. If a read contains [redacted] configuration, do not send that marker back in an update or drop those fields from a full replacement; have the person preserve them through the console or another authorized client. A provider key or gateway token is never a tool argument: add_provider and the rotate tools answer a URL where the person enters it, and get_operation reports when they have finished. A refusal is a tool result marked as an error with the gateway's code and the next step to take. The server's agw://guide resource has its full rules, and the MCP server guide at /automation/mcp lists every tool.

The API reference below is useful for integrations that do not use the CLI.

What the gateway is

App AI Gateway is a proxy between a person's applications and AI providers (OpenAI, Anthropic, Gemini, xAI and others). The person adds provider keys once; they are shared by all their apps. They create applications; each app has a permanent ID, an authentication policy, a proxy policy saying which providers, paths and models it may use, optional custom endpoints, and limits on its users. Client apps call {GATEWAY_URL}/v1/apps/{app}/proxy/{provider_slug}/{provider_path} with the provider's own request format. You manage all of this through the admin API.

Authentication

• Use the explicitly selected gateway URL; the hosted API is https://api.appaigateway.com. GET /v1/healthz checks basic availability.
• Direct integrations send a management credential as Authorization: Bearer using their protected credential store. The CLI uses AGW_MANAGEMENT_KEY when it is set, and otherwise the key its active connection saved.
• All admin routes are under /v1/admin/. Request and response bodies are JSON with Content-Type: application/json.
• A management key has the current role of its owning identity. It does not expire. It cannot perform human-only actions such as claiming an account, changing human ownership, or creating, listing and revoking other management keys, which are console-only and answer 403 session_required to a key. A key can revoke only itself, with DELETE /v1/cli/credential; that is what agw account logout sends.

Rules

1. Never print, log or echo any secret: management keys, provider keys, application API keys. When a call returns a key, store it in a private file where the person asked, then report its location.
2. Never send id when creating an application. The gateway assigns the ID from the name and returns it as app.id. IDs cannot be changed.
3. Validate an application body before writing it: a new application with POST /v1/admin/app-drafts/validate, an existing one with POST /v1/admin/apps/{app}/validate.
4. PUT /v1/admin/apps/{app} replaces the whole application. Always GET first, modify the returned app.name, app.config and app.status, and send all three back together with the app.revision from that read. A missing revision returns 400; a stale revision returns 409. Reread and merge.
5. Read before you write. List providers and apps before changing anything, so you use slugs and IDs that exist.
6. App and provider changes take up to one minute to apply to live traffic. Blocking an authenticated user refuses new token exchanges immediately; existing gateway tokens stop working within ten seconds. Header-based users must be blocked in the backend.
7. Prefer reversible actions. Disable an app or provider rather than deleting it unless deletion was asked for. Deleting a provider also deletes its custom prices; deleting an app removes its users and keys.
8. Do not test the setup by sending provider requests unless asked, because each one costs the person money at the provider.

Errors

Every refusal is JSON:

{ "error": { "code": "slug_taken", "message": "…", "data": { } } }

Workflow for setting up an app

1. GET /v1/admin/providers. Note which provider types exist and their slug values.
2. If a provider is missing, use a CLI or MCP browser handoff so the person can enter the key privately.
3. Compose the application body from the reference below.
4. POST /v1/admin/app-drafts/validate with the body. Fix every error.
5. Create through the retry-safe operation, using kind: "app.add" and that body as payload. Read result.app.id and store result.api_key.key privately for a server app. A plain POST /v1/admin/apps instead returns app and api_key at the top level, but cannot safely be retried after a lost response.
6. Report the app ID, the base URL {GATEWAY_URL}/v1/apps/{app.id}/proxy/{provider_slug}/{provider_path}, and where the key went. Do not include the key.

Providers

A provider row is one key for one provider type, or a reference to a gateway that holds the key. Its slug is the URL segment clients use. The first provider of each type defaults to the type name as its slug (openai, anthropic, gemini, xai, perplexity, deepseek, groq, mistral, together, fireworks, cerebras, moonshot, huggingface, baseten, bytedance, openrouter). A second provider of the same type must be given a slug, or the create answers 409 slug_taken.

pricing is per model, in USD per million tokens:

{ "my-model": { "input": 0.5, "output": 1.5, "cached_input": 0.05 } }

input and output are required. Any other per-token rate the catalog uses is optional under the same name: cached_input, cache_write, cache_write_1h, image_input, audio_input, video_input, image_output, and the long_* rates, which also need long_context_threshold. A custom price replaces the catalog's rates for that model and inherits none of them: a rate left out bills as on a catalog entry without it, so a cache rate falls back to input.

A model that is in neither the built-in catalog (GET /v1/admin/prices) nor the provider's pricing cannot be used by any app: requests answer 400 pricing_not_configured, and an app configuration that names it in allowed_models, model_rewrites targets or endpoints is rejected on validation. OpenRouter reports its own cost and needs no price, and so does xAI on Chat Completions, Responses and image generation, directly or through Cloudflare; its Messages API, v1/stt and the Vercel route still need one. The catalog prices OpenAI's gpt-image-* and Gemini's image models per token, with separate image rates, and BytePlus Seedream 5.0 flash, 5.0 lite, 4.5 and 4.0 per generated image. Other image models billed per image or per megapixel, such as Together AI's and Seedream 5.0 pro, are not supported, and per-token pricing cannot express them.

Custom baseUrl points an openai-type provider at an OpenAI-compatible server. It requires https, a public hostname, the default port and no query. The client path is appended literally: use https://my-vllm.example.com/ with v1/chat/completions, or Azure's https://RESOURCE.openai.azure.com/openai/ with that same path. Do not duplicate v1/. See Custom base URLs.

Gateways

A gateway row is a connection to a Cloudflare AI Gateway or Vercel AI Gateway whose token is stored once and shared by providers routed through it.

Provider and gateway updates use the revision returned by their list route. A missing or invalid revision returns 400. If another edit wins first, the write returns 409 conflict; read the row again and merge before retrying.

Cloudflare routes openai, anthropic, xai, gemini, perplexity. Vercel routes those plus deepseek and moonshot, and accepts only the paths v1/responses, v1/chat/completions and v1/messages.

Applications

status is active or disabled. A disabled app refuses every request with 403 app_disabled and keeps everything.

An app's warnings describe behaviour that will stop on the stated date: each has a code, a message, and usually until and docs_url. Tell the person about every warning and help them act before its date. Warnings are read-only: leave warnings, id, created_at and updated_at out of the body you write back, or the write is refused, and keep the revision from the read, which an update requires.

Application configuration reference

config is one JSON object with four top-level keys. Unknown keys are rejected.

{
  "authentication": { … },
  "routing": { … },
  "limits": { … },
  "endpoints": { … }
}

authentication

Discriminated on type.

iOS application (apple_app_attest):

Server application (api_key):

The issuer object (signed-in users):

Preset values for common identity providers:

A RevenueCat entitlement check is { "path": "revenueCatEntitlements", "contains": "<entitlement id>" } with "entitlement": "revenuecat".

routing

Policy object for one provider:

limits

Optional. Omit for no limits. Every field is null (unlimited) or a number. Non-null per_user limits require an app that identifies users; an all-null block is accepted without user identity. Request limits must be positive; a spend budget may be 0 to stop all spend.

On an iOS app, per_user request limits count per install (one copy of the app on one device), and so does the budget unless per_user.spending.scope is "user", which needs end_user.source issuer. scope defaults to "install" on iOS apps and "user" on server apps, where "install" is refused. The gateway writes the default in.

"limits": {
  "per_user": { "requests": { "per_minute": 10, "per_day": 300 }, "spending": { "monthly_usd": null } },
  "per_app":  { "requests": { "per_minute": null, "per_day": null }, "spending": { "monthly_usd": 100 } }
}

endpoints

Optional. Keyed by slug (^[a-z0-9-]{1,64}$). Each endpoint:

listModelPrices gives every catalog model's kind: text, image, speech, transcription, embedding or realtime. Pick an endpoint's models by it; a realtime model serves no endpoint.

Complete examples

A server app for a backend that names its users, restricted to one OpenAI model:

{
  "name": "Search service",
  "config": {
    "authentication": {
      "type": "api_key",
      "end_user": { "source": "header", "header": "x-end-user-id" }
    },
    "routing": {
      "providers": {
        "mode": "selected",
        "selected": {
          "openai": { "allowed_paths": ["v1/responses"], "allowed_models": ["gpt-5.6-sol"], "max_output_tokens": 4096 }
        }
      },
      "model_rewrites": {}
    },
    "limits": {
      "per_user": { "requests": { "per_minute": 30, "per_day": 1000 }, "spending": { "monthly_usd": 10 } },
      "per_app": { "requests": { "per_minute": 300, "per_day": 10000 }, "spending": { "monthly_usd": 100 } }
    }
  }
}

An iOS app with Firebase sign-in, a RevenueCat entitlement, and a named endpoint:

{
  "name": "Calorie Tracker",
  "config": {
    "authentication": {
      "type": "apple_app_attest",
      "app_attest": { "team_id": "ABCDE12345", "bundle_id": "com.example.calorietracker" },
      "end_user": {
        "source": "issuer",
        "issuer": {
          "jwks_url": "https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com",
          "issuer": "https://securetoken.google.com/calorie-1a2b3",
          "audience": "calorie-1a2b3",
          "user_id_claim": "sub",
          "required_claims": [{ "path": "revenueCatEntitlements", "contains": "pro" }],
          "max_token_lifetime_seconds": 86400,
          "provider": "firebase",
          "entitlement": "revenuecat"
        }
      }
    },
    "routing": { "providers": { "mode": "all" }, "model_rewrites": {} },
    "limits": {
      "per_user": { "requests": { "per_minute": 20, "per_day": 500 }, "spending": { "monthly_usd": 5 } },
      "per_app": { "requests": { "per_minute": null, "per_day": null }, "spending": { "monthly_usd": 500 } }
    },
    "endpoints": {
      "chat": {
        "api_style": "responses",
        "provider": "openai",
        "model": "gpt-5.6-luna",
        "params": { "reasoning": { "effort": "low" } },
        "fallback": [{ "provider": "xai", "model": "grok-4.5" }]
      }
    }
  }
}

Users

Usage and events

Usage event status values: ok, provider_error. Refusal sample reason values: blocked_app_rate, blocked_app_budget, blocked_user, blocked_billing, blocked_replay (a replayed App Attest proof). scope is install, user, app or account. Samples are limited to one per identity per minute, so sample counts are not exact request totals. Event cost_source values: computed, reported, unresolved.

What clients send

You do not normally call these, but you may need to explain them or write client code.

• Proxy: {METHOD} /v1/apps/{app}/proxy/{provider_slug}/{provider_path} with the provider's own body. Credential: Authorization: Bearer <gateway token> plus X-App-Version for iOS and signed-in-user apps, or Authorization: Bearer agw_… for a server app without user identity. When an iOS app's verify_on is every_request, every request also carries X-AppAttest-Proof, an App Attest assertion over that request; without it the gateway answers 401 assertion_required. With token_exchange the token alone is enough.
• Custom endpoint: POST /v1/apps/{app}/endpoints/{slug}.
• Token exchange for a server app with signed-in users: POST /v1/apps/{app}/auth/token with { "api_key", "issuer_token" }, returning { "access_token", "expires_in": 3600 }.
• iOS apps use the AppAIGateway Swift package 1.4 or later, which handles App Attest, the token exchange and, when the token exchange answers verify_on: "every_request", the per-request proof. Send requests with withAuthorizedRequest (1.4.1 or later): it builds the request, hands it to the app's own send closure, and on a 401 discards the token and sends a rebuilt request once. Pass the request body to it, never set it afterwards. authorizedRequest builds the request alone, for an app that handles the retry itself. See the human documentation under Integrate your app.

For Auth0's API-identifier preset, issuer_token must be a JWT access token for that API. Firebase uses its ID token. In every case the configured issuer and audience must match; see User authentication.

Contacting human support

Where the deployment offers human support, you can write to it on the person's behalf: agw support send with the CLI, contact_support over MCP, or POST /v1/admin/support with a management key. Support replies to the person's own email address, never to you.

1. Only when the person asked you to contact support. Show them the exact message first, and send it only once they agree. Without a terminal, agw support send refuses to send unless you pass --yes, which says you have done this.
2. Choose the type: bug for something broken, support for a question or a request for help, feedback for an idea or a missing feature.
3. Write what happened, what they expected and what was tried. Put ids and codes in context so support can act without asking back: --context app_id=my-app --context request_id=… --context error_code=….
4. Never include a key, token or password. A message or context value that looks like one is refused with invalid_request, and nothing is sent.
5. Tell the person the answer's reference, such as SUP-7F3K2Q. The same message sent again within ten minutes sends nothing new: the answer has duplicate: true and the first reference, so do not resend to make sure.
6. If the gateway refuses because the account cannot use human support, tell the person what the message says instead of retrying.

agw support send --type bug --message "Streaming responses from my-app stop after about 30 seconds since Monday." \
  --context app_id=my-app --context error_code=provider_timeout --yes --json --no-input

Reporting back

When you finish a task, report: what you created or changed, by ID and slug; the client base URL for any app; where each secret was stored; and anything you could not do, such as a provider whose key was not available. Do not include secret values.

Retrying creation safely

A plain POST to create an app, application key, provider or provider gateway is not safe to repeat: a response lost in transit leaves you not knowing whether it landed. Send the creation as an operation instead: POST /v1/cli/operations with { kind, payload, token }, where kind is app.add, app.key.add, provider.add or provider-gateway.add, payload is the body the plain endpoint takes (plus app for app.key.add), and token is a random URL-safe string of 32–256 characters you persist before sending. Repeat the same kind, payload and token to recover the original result; a different payload under the same token is 409. A new application key is returned in result.api_key.key for 15 minutes after creation; past that the result still names the resource and the key's id, and no second key is minted. Records are kept for 90 days.