templates

Templates overview

A template is the design of a conversation. You author it once; Roxels runs it any number of times. Every conversation has exactly one template behind it.

What a template describes

A template tells the agent:

Who it is. Tone, voice, language, greeting style.
What it's trying to do. The goals — what to learn, propose, or confirm.
What tools it has. Skills (functional capabilities) and data sources (live lookups).
What to do with results. Outputs — webhooks, frontend callbacks, chained API calls.
How long, in what posture. Maximum session duration, whether to allow screen-share, whether to use the persistent launcher.

The mental model: phases, goals, outputs

Template
├── Phases (a conversation can have 1 or more)
│   └── Phase
│       ├── body_instructions (what the agent does in this phase)
│       ├── Goals (what to capture)
│       │   └── Goal { id, type, prompt, schema, commit_policy, outputs }
│       ├── Data sources (live lookups available in this phase)
│       └── Outputs (per-phase webhooks/callbacks)
└── Settings
    ├── greeting, language, tone, voice
    ├── max_session_duration_minutes
    ├── allow_screen_share
    ├── system_instructions (template-specific prompt addition)
    ├── speaker_skills / advisors (agent capabilities + observers)
    ├── outputs (template-level webhooks/callbacks)
    ├── embedded (launcher config, persistence, FAB anchor)
    └── integration_shape (declared delivery contract)

Most templates have one phase. Multi-phase templates let you script handoffs — e.g., phase 1 captures basic info, phase 2 does a deeper dive on a specific topic. Each phase has its own goals and can fire its own outputs at the end.

Key concepts

Goals

A goal is one thing the agent is trying to accomplish — capture a piece of data, propose a recommendation, or get a user confirmation. Goals have a type (open, quantitative, qualitative, structured, context_dump, walkthrough) and optionally a JSON Schema. See Goals and extraction.

Skills

A skill is a discrete capability the agent can invoke — sending an email, looking up a database, running a screen-share walkthrough. Skills are composable: attach the ones you need; the agent decides when to call them. See Skills and advisors.

Advisors

An advisor is an observer agent that watches the conversation and feeds the speaker agent with suggestions. Advisors don't talk; they whisper. Use them to push extraction quality (e.g. notice when a numeric value was implied but not captured). See Skills and advisors.

Data sources

A data source is a live API the agent can query during the conversation — e.g. "look up this customer by name" or "find a matching SKU." Data sources are declared in the template; the agent uses them to resolve ambiguity or pull live context. See Data sources.

Outputs

An output delivers structured data when a goal commits. Three flavors: webhook, frontend callback, chained API call. See Webhooks overview.

Archetype

A template archetype is a category that opts into shared instructions. Example archetypes: "guided walkthrough," "intake form," "consultative discovery." Each archetype contributes a prompt section so all templates of that kind behave consistently — without you having to copy-paste guidance into every template.

Most templates don't need to set an archetype; the default is fine. When the template's posture is distinctive (e.g. "this is a walkthrough, not an interrogation"), the right archetype sets the tone for free.

Settings

Template-level configuration that doesn't fit cleanly into a phase: greeting, voice, language, max duration, screen-share permission, persistent launcher, integration shape, template-level webhooks.

Where to author a template

The dashboard. The default surface — UI, immediate iteration, version history.
The REST API. Programmatic creation, useful in CI/CD or migration scripts.
The MCP package. Natural-language authoring from Claude Code, Cursor, or any MCP-compatible agent. Highly recommended for first-time setup — the assistant pulls in best practices and points out what you're missing.

Versioning

Templates are versioned. Each save creates a new version. The dashboard shows version history; you can compare versions, restore an older one, or fork to experiment. Sessions are bound to a specific version, so editing a template never breaks in-flight conversations.