> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration best practices

> A production checklist for secure, isolated, reliable, and cost-aware AutoSage integrations.

Use this checklist before taking an AutoSage integration to production. Each section links to the detailed concept or lifecycle behind the recommendation.

<AccordionGroup>
  <Accordion title="Protect API keys" icon="key">
    * 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.

    See [Authentication](/developers/authentication) and [Access & scopes](/developers/concepts/access-scopes).
  </Accordion>

  <Accordion title="Model multi-customer isolation" icon="users">
    * 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](/developers/concepts/tenancy).
  </Accordion>

  <Accordion title="Keep prompt precedence clear" icon="layer-group">
    * 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.

    See [Prompt assembly](/developers/concepts/prompt-assembly) and [Knowledge-base prompts](/knowledge-bases/prompts).
  </Accordion>

  <Accordion title="Prepare agents before deployment" icon="robot">
    * 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.

    See [Agent configuration](/agents/configuring) and [Agent lifecycle](/developers/lifecycles/agent-lifecycle).
  </Accordion>

  <Accordion title="Schedule predictable runs" icon="calendar">
    * 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.

    See [Agent scheduling](/agents/scheduling) and [Running agents](/agents/running).
  </Accordion>

  <Accordion title="Ingest source documents deliberately" icon="file-arrow-up">
    * 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.

    See [Upload documents](/developers/guides/upload-documents) and [RAG lifecycle](/developers/lifecycles/rag).
  </Accordion>

  <Accordion title="Handle streaming as a stateful protocol" icon="wave-square">
    * 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.

    See [Chat & streaming](/developers/guides/chat-and-stream) and [Chat lifecycle](/developers/lifecycles/chat-lifecycle).
  </Accordion>

  <Accordion title="Plan for rate limits and credits" icon="gauge-high">
    * 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.

    See [Rate limits](/developers/rate-limits) and the [Billing API](/developers/api/billing).
  </Accordion>
</AccordionGroup>

## Production readiness summary

| 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 |

<Tip>
  Start production with the smallest practical permissions, corpus, and agent toolset. Expand each deliberately as real workloads require it; this keeps behavior easier to observe and reason about.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/developers/quickstart">
    Verify a complete knowledge-base and chat flow.
  </Card>

  <Card title="API reference" icon="code" href="/developers/api/overview">
    Review endpoint authentication, parameters, and schemas.
  </Card>
</CardGroup>