Integration best practices

Protect API keys

Call AutoSage from your backend, never directly from browser or mobile code.
Grant only the scopes, tenants, and knowledge bases a workload needs.
Keep admin:full for a tightly protected provisioning key that needs wildcard scope coverage. Populated tenant and knowledge-base allowlists still constrain specific resource access; tenant discovery is the exception.
Store keys in a secrets manager, rotate them regularly, and revoke exposed keys immediately.

Model multi-customer isolation

Create one tenant per customer account or isolated project.
Use a small set of workload-specific keys per environment instead of minting a key for every customer.
Pass a stable external_subject_id for every API end user.
Include the same external_subject_id when reading or continuing that user’s chats.

Tenants isolate data, credits, and quotas; external subjects isolate individual chat ownership and memory. See Tenancy.

Keep prompt precedence clear

Prefer Persona for identity and presentation.
Use Instructions for authoritative task and operating rules.
Use a full Custom Prompt only when you need complete white-label control.
Include the entire answering contract in a full Custom Prompt because it supersedes Persona and Instructions for that mode.
Configure the standard Custom Prompt for Quick mode and the Main/Deep Custom Prompt for Deep mode.

Prepare agents before deployment

Authenticate connected apps before enabling them on an agent.
Choose the knowledge base carefully at creation; use Copy to move a configuration to another knowledge base.
Give custom tools the narrowest useful schemas and keep secret headers out of logs.
Validate agent behavior interactively before enabling a schedule.

Schedule predictable runs

Express schedules in UTC and account for daylight-saving changes in the desired local run time.
Keep enough tenant credits available for scheduled work.
Bind an external subject when an API-key-created scheduled agent needs connected apps.
Review run history for skipped, failed, or cancelled runs.

Ingest source documents deliberately

Upload original source files instead of placing very large text blocks in prompts.
Use descriptive filenames and clear headings to improve chunk boundaries and retrieval.
Wait for processed before querying or evaluating answer quality.
Remove failed and abandoned uploads because they count toward document and storage quotas.

Handle streaming as a stateful protocol

Show progress events as they arrive. Support optional partial final_response events, then replace them with the canonical complete content when isComplete is true.
Add source and chart events as they arrive.
Ignore ping keep-alives.
Close the client cleanly on done, and surface or retry appropriately on error.
Remember that one chat has one active stream; coordinate sends per chat.

Plan for rate limits and credits

Add exponential backoff with jitter for rate-limit responses and transient failures.
Retry only operations documented as idempotent. Before replaying a write, check the resource state to avoid creating duplicate work.
Monitor the tenant credit balance and usage through the billing endpoints.
Alert before credits are exhausted so interactive messages and scheduled runs continue without interruption.

Area	Ready when
Security	Keys are backend-only, scoped, stored securely, and rotated
Isolation	Every customer has a tenant and every end user has a stable external subject
Prompts	Persona, Instructions, and mode-specific overrides have explicit ownership
Agents	Apps are connected, schedules are UTC-aware, and scheduled identities are bound
Documents	Uploads reach `processed`, quotas are monitored, and abandoned records are removed
Reliability	Streaming terminal events, backoff, retries, credits, and run failures are handled

Quickstart

Verify a complete knowledge-base and chat flow.

Review endpoint authentication, parameters, and schemas.