Integrate a Runtime Client

A runtime client calls one released Agent Business through its scoped public runtime contract. It does not receive creator-console access or provider credentials.

Get the runtime contract

From the Agent Business Surfaces workspace, record:

• the business slug;
• the active capability and interaction mode;
• the public runtime token with the pk_app_ prefix;
• the input and output schemas;
• the allowed origins when the caller is a browser;
• any quota, authentication, payment, or Turnstile requirement.

Treat the token as public but scoped. It may authorize only the published runtime surface for that Agent Business. It must never authorize creator, billing-administration, provider-secret, or operator endpoints.

Read runtime configuration

Use the managed API origin:

https://api.agentaab.com/api

The runtime configuration route is:

GET /app/{business-slug}/runtime-config

It returns public-safe capability, parameter, endpoint, access, and presentation metadata. Use it to select the supported invocation route instead of assuming that every business uses the same interaction mode.

Authenticate runtime calls

Mutating runtime calls accept the Agent Business public runtime token through either header:

Authorization: Bearer pk_app_your_scoped_token

or:

X-API-Key: pk_app_your_scoped_token

Use Authorization: Bearer unless an existing client convention requires X-API-Key. Never send a creator session token to a public runtime endpoint.

Choose the invocation route

Use the runtime configuration and Runtime API reference to build the request body for the published contract:

• prompt completion: POST /app/{business-slug}/completion-messages;
• conversational capability: POST /app/{business-slug}/chat-messages;
• workflow capability: POST /app/{business-slug}/workflows/run.

Send a stable, app-scoped runtime user identifier when the contract requires quota, authentication, credit, or payment decisions. Do not reuse raw internal user identifiers across unrelated Agent Businesses.

Browser clients and CORS

Browser responses are readable only when the exact HTTPS origin appears in the Agent Business allowed-origin policy. Register the production origin and each intentionally supported preview origin. Do not use a wildcard to work around a missing deployment configuration.

If a preflight request fails, verify the business slug, route, HTTP method, visibility, and allowed origin before changing client code.

Handle runtime decisions

Clients should treat these outcomes distinctly:

• 401: the public runtime token is missing or invalid;
• 402: quota, credit, or payment is required before execution;
• 403: origin, visibility, authorization, or protection policy denied the request;
• 429: rate or usage policy limited the request;
• 5xx: execution or required runtime state was unavailable.

Display or log the public error code and request correlation data when supplied. Do not expose raw request bodies, response bodies, credentials, or provider payloads in analytics.

Verify before production

1. Fetch runtime configuration from the production API origin.
2. Send a representative valid request using the published schema.
3. Exercise invalid input and any quota, auth, or payment boundary.
4. Confirm browser CORS from the final HTTPS origin when applicable.
5. Verify the invocation appears under the expected Agent Business, release, channel, and Offer in Operations.