Agents

Behavior

The blocks an agent's prompt is built from.

An agent's behavior is made of blocks. Each block covers one aspect, such as role, tone or when to hand over to a human. The platform builds the prompt the agent receives in the conversation from these blocks. So you do not write a long prompt, you fill in fields.

Structure

{
  "blocks": [
    {
      "key": "role",
      "type": "role"
    },
    {
      "key": "tone",
      "type": "tone"
    },
    {
      "key": "custom-1",
      "type": "custom"
    }
  ],
  "values": {
    "role": {
      "text": "You are the reception of Dr. Müller's dental practice."
    },
    "tone": {
      "closeness": "formal",
      "style": "brief",
      "length": "two_three_sentences"
    },
    "custom-1": {
      "title": "Emergencies",
      "text": "Offer a same-day appointment for patients in pain."
    }
  },
  "rendered_prompt": "…"
}

blocks: which blocks exist, in this order.
values: the content per block, keyed by key.
rendered_prompt: the prompt built from them. Read-only.

When updating, sending values with the blocks that change is enough. The others stay.

Blocks

Type	Fields
`role`	`text`: who the agent is. Required and non-empty.
`company`	`name`, `industry`, `hours`, `exceptions`, `address`, `directions`, `phone`, `web`
`tone`	`closeness`: `formal` or `personal` · `style`: `balanced`, `brief` or `detailed` · `length`: `two_three_sentences`, `one_sentence` or `as_needed`
`personality`	`preset`: `friendly_professional`, `relaxed`, `formal_precise` or `calm_patient` · `text`
`task`	`text`: what the agent should achieve.
`flow`	`text`: the steps of the conversation, numbered.
`limits`	`text`: what the agent does not do.
`ambiguity`	`behavior`: `ask_once`, `ask_twice` or `hand_over` · `then`: `human`, `callback` or `end`
`examples`	`text`: sample questions and answers.
`escalation`	`when`: `on_request`, `complaints` or `out_of_scope` · `target`: where to hand over
`custom`	`title`, `text`. Repeatable, key `custom-<name>`.

The API rejects unknown types or values with 422 and the field's path, for example behavior.values.tone.closeness.

Custom blocks

Use custom blocks for rules that have no type of their own. The key starts with custom-, followed by a name of your choice:

{
  "behavior": {
    "values": {
      "custom-shop-notes": {
        "title": "Shop notes",
        "text": "Free shipping from 50 euros."
      }
    }
  }
}

What belongs in blocks and what does not

Facts such as prices, catalogs or long rule sets belong in the knowledge base, not in blocks. The prompt costs processing on every conversation turn, a document only when it is needed. company is the exception: short and asked about so often that it belongs in the prompt.