Agents, drafts and versions
How an agent is configured, published to an environment as an immutable version, previewed and rolled back.
An agent is one configured assistant. Most projects have one; a large app may have several (support, sales, onboarding) and pick one per screen.
What an agent is made of
| Tab in the builder | Fields | Notes |
|---|---|---|
| Persona | name, description (internal), system prompt, tone chips, greeting, fallback | The system prompt is a template: {{ context.plan }}, {{ context.currency }} and any other key listed under public context keys are filled per turn. Only context.* variables exist; unknown paths render as empty text. |
| Model | provider, model id, temperature, max output tokens, secret name | Provider is openai, anthropic, google, groq or mock. The key is a project secret, referenced by name, never pasted into the agent. |
| Tools | the project tools this agent may call, each with “require confirmation” and “act as user” | Built-in tools (render_ui, notify_app, app_command, handoff) are always available. |
| Knowledge | sources attached to the agent | Indexing is planned; see Roadmap. |
| Workflow | an optional workflow attached to the agent | Built in the visual builder. Running it from a live turn is not wired yet; see Roadmap. |
| UI | allowed component types, URL allowlist | The model may only render types on this list. Custom types appear after Sync from code. |
| Behaviour | max tool rounds, history messages, handoff triggers, handoff destination, public and sensitive context keys | Defaults: 6 rounds, 20 messages. |
| Versions | published versions per environment, notes, rollback |
Draft, publish, version
Edits go to the agent’s draft. Nothing your users see changes until you publish the draft to an environment. Publishing creates a version: an immutable copy of the whole configuration with a number, a note, who published it and when.
- Development and production are published separately. A common flow is publish to development, test with a development key in a debug build, then publish the same draft to production.
- Rollback re-publishes an earlier version. It creates a new version entry, so history is never rewritten.
- The Publish button is disabled while the draft equals the version already live in that environment.
- Sessions pick up the newest version at bootstrap. Conversations already open finish their current turn on the version they started with.
Preview
The builder has a live preview on the right. It runs a real conversation against the runtime with the current draft, on the environment selected in the top bar, so you see exactly what the model and tools do before publishing. Preview conversations are tagged preview:<your email> and show up in Conversations like any other.
Duplicate and archive
Duplicate copies the draft into a new agent (useful for A/B prompts or per-market variants). Archive hides an agent from the list and stops new sessions; existing conversations remain readable.
Practical advice
- Keep the system prompt short and specific about when to call which tool and what to render. Real models ask clarifying questions when the prompt is vague; tell them to call tools with sensible defaults.
- Put per-user facts in context (
plan,currency,locale) rather than in the prompt text. The SDK sends context with the session and the template fills it in. - Publish with a note. Notes appear in the Versions tab and in the Events tail.