Skip to main content

​
Provisioning Concepts

The mental model behind the Agent Provisioning API: how a build progresses, what “preview” means, how repeat submits are deduplicated, and how long a preview agent lives.

​
The build lifecycle (FSM)

A build is a finite state machine. The worker emits one ProvisioningEvent on each transition (and on coarse progress ticks in slow phases). The same shape is delivered over SSE, the poll snapshot, and the webhook — you render against one contract.
ready is emitted only when the agent is published and its index run is complete (or a phase timeout elapsed) — so the visitor’s first chat is grounded in the creator’s content, not answering blind. Thin / partial content still publishes and reaches ready with a warning rather than failing.
progress is phase-weighted so the bar stays honest across uneven phases. stepLabel, detail, and channelTitle are written for end-user display, so the client never has to invent copy.

​
Timeouts & partial success

  • Each phase has a timeout. On breach, the worker emits failed with the matching ProvisioningErrorCode instead of hanging the stream.
  • Partial success: a channel with thin public content still publishes an agent and reaches ready with a warning (e.g. “Limited public content found”) — the client sets expectations rather than treating it as an error.

​
Bounded preview vs. full ingestion

The build’s mode flag controls how much content is ingested: Preview is bounded ingestion — a small, recent slice indexed fast so the demo is interactive immediately. For the landing-page / try-it-now use case, use preview; use full for a production agent. Both run through the same provisioning service, selected by the mode flag.

​
Dedup & idempotency

Two independent mechanisms keep repeat submits cheap and safe:

Handle dedup

A fresh existing published agent for the same normalized handle is reused — from-url returns status: "ready" with the existing agentSlug instantly, no new build, no new cost.

Idempotency-Key

Sending an Idempotency-Key makes a double-submit return the same build rather than spawning a second one.
Together they guarantee a double submit never spawns two builds, and resubmitting a recently-built channel is instant and free. See Auth & rate limits.

​
Preview agent TTL (7 days)

Preview agents and their knowledge bases are ephemeral. A TTL cleanup job soft-deletes stale provisioned agents/KBs (proposed 7 days) to bound storage and vector cost. If a visitor returns after the TTL, simply provision again — a fresh build runs.
“Claiming” a preview agent into a real org on signup (to make it permanent) is a future / optional flow — out of scope for v1.

​
Where this fits

The provisioning chain runs the URL→agent pipeline (light-scrape → creator analysis → KB + sources → bot + prompt config → publish), orchestrated server-side by a single AgentProvisioningService shared by both this API and the in-app Creator Wizard. It uses the YouTube / Instagram connectors and the anonymous chat surface.