templates

Goals and extraction

A goal is something the agent is trying to accomplish in the conversation. Most often that's capturing a piece of structured data (the user's name, their goal for using your product, a free-form note). It can also be confirming something, proposing a next step, or running a walkthrough.

Goals live inside phases. Each phase has an ordered list of goals; the agent pursues them in order, with flexibility to backtrack when the conversation flows that way.

Goal types

The type field tells the agent (and the extraction layer) what shape of data to capture.

Type	Use for
`open`	Free-form text or a few related fields, no strict shape. "Tell me about your team."
`quantitative`	A number with units. "How many engineers?"
`qualitative`	Free-form text with a defined thematic anchor. "What's your biggest pain with X?"
`structured`	A specific JSON shape (define a `schema`). Best for anything you'll feed to a downstream system.
`context_dump`	Pull context from the user without strict structure — broad backstory.
`walkthrough`	Coordinate a guided experience (instead of capture). Use with screen-share.

When in doubt: if a downstream system needs the data, use structured with a schema. The extraction layer is strongest there.

Anatomy of a goal

{
  "id": "use_case",
  "type": "qualitative",
  "prompt": "Find out what they plan to use the product for.",
  "schema": {
    "type": "object",
    "properties": {
      "primary_use_case": { "type": "string" },
      "secondary_use_cases": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["primary_use_case"]
  },
  "commit_policy": "auto",
  "invariants": [],
  "extraction_mode": "auto",
  "probing_areas": ["industry", "team size", "current tooling"],
  "entry_points": ["What brings you to us?"],
  "follow_up_depth": "medium"
}

Field	Description
`id`	Stable identifier. Use it in output templates (`{{data.use_case}}`).
`type`	One of the types above.
`prompt`	What you want the agent to do for this goal. Speak in directives ("Find out X"), not questions ("What's X?").
`schema`	Optional JSON Schema. Drives extraction shape and validates committed data.
`commit_policy`	When the goal commits — `auto` (agent decides) or `require_resolved` (must satisfy invariants).
`invariants`	Optional rules the data must satisfy before commit (e.g. `email must be valid`).
`extraction_mode`	`auto` (extract from conversation) or `manual` (the agent calls a tool to commit).
`probing_areas`	Hints to the agent about what aspects to explore.
`entry_points`	Suggested opening lines for this goal.
`follow_up_depth`	How hard to push for completeness — `low`, `medium`, `high`.

When a goal commits

A goal commits when the agent decides the data captured is enough. On commit:

The data is recorded in the conversation's findings.
All outputs configured for the goal fire (webhooks, frontend callbacks, chained APIs).
The conversation moves to the next goal (or the next phase, or wrap-up).

You influence commit timing through:

follow_up_depth — low commits faster, high pushes for more detail before committing.
invariants — hard rules; the agent can't commit without satisfying them.
commit_policy: "require_resolved" — combined with invariants, this guarantees the data shape your downstream system needs before anything fires.

Schemas and the commit-author tool

When you set a schema, two things happen:

The agent sees the schema when deciding what to commit. It will refuse to commit data that doesn't match, and will ask the user follow-up questions to fill in missing fields.
The committed data is validated against the schema before outputs fire. Validation failure is caught and surfaced as a learning (Retries and idempotency § learnings).

This is the strongest path for "I need exactly this shape" — structured goals with schemas + require_resolved commit policy.

Free-form notes

Not everything needs a schema. For unstructured observations the agent captures along the way (e.g. "user mentioned they're using a competitor"), use extraction_mode: "auto" with no schema; the data lands as free-form text on the goal.

The frontend understanding event fires for both structured and free-form extractions; check whether event.data or event.text is present. See Embed events § extraction-and-goal-events.

Live document view

If your template enables the live document view (a form or table the user can see during the call), the document is bound to one or more goals' schemas. Field updates flow as the agent extracts, and the user can manually edit them — those edits become part of the captured data.

This is the path for "fill out a form while talking" — the user sees the form, the agent fills it, both can adjust.

Conversation context

Goals can reference the session's context — what you passed when creating the session. Use this when:

The agent should know who the user is (e.g. "Greet them by name: {{context.name}}").
A goal should pull from your data (e.g. "Reference their plan: {{context.plan}}").
Outputs should include identifiers from your system.

Context is read-only from the agent's side. To change it mid-conversation (e.g. after a lookup), use a chained API or a data source.

Patterns

Schema-strict capture for downstream systems

For data that feeds your CRM or analytics:

type: "structured"
Define a JSON Schema matching what the downstream system expects.
commit_policy: "require_resolved"
follow_up_depth: "high"

Result: nothing commits until the data is right; webhooks fire with clean, validated payloads.

Lightweight discovery

For early-stage research where you want a feel, not a contract:

type: "qualitative" or open
No schema
follow_up_depth: "medium"
commit_policy: "auto"

Result: the agent has flexibility to probe interestingly; you get text data + a summary at the end.

Multi-goal sequence

Order matters. The agent generally pursues goals in order. To gate one on the other ("don't ask about pricing until you've understood the use case"), put them in the right order in the array. The agent backtracks when natural.