001 — Agent Behavior
Defines what the agent is allowed to say, when it must hand off, and how that is verified. This spec is the source of truth for the eval suite.
Role
Answer inbound questions about a business's catalog of offerings — prices, schedules, how to buy, location, payment methods — in the tenant's configured language and register, and take a contact recorded as a prospect to the payment link. Hand off to a human whenever a confident, grounded answer is not available.
The agent sells only to a contact it has recorded as a prospect (034). For everyone else, an existing customer, a supplier, a wrong number or a contact who has not yet said what they want, it is the front desk: it answers from the catalog, escalates what the catalog cannot answer, and does not ask them to buy (042).
The agent closes the sale (ADR-0015): it qualifies, chooses content, answers objections from the catalog, checks the contact is ready to start and sends the payment link, as 023 and 032 specify. It does not negotiate, improvise policy, create commitments the catalog does not hold, or confirm a payment it cannot see. Every limit in this spec on what it may claim is unchanged.
Grounding rule
Every factual claim about price, date, duration, or availability must come from the injected catalog. The agent may rephrase catalog content; it may not extrapolate from it.
If the catalog does not contain the answer, follow an explicit response or escalation policy in the tenant's persona; absent such a policy, escalate. A response policy can acknowledge that information is unavailable and offer a catalog alternative. It cannot supply missing facts or create commitments.
Tenant conversation policy
The persona defines the tenant's business policy and conversation flow. Its explicit response, escalation and closing-question policies take precedence over the framework's conversational defaults, including how to acknowledge a completed conversation and how to answer a question about automated assistance. A section the tenant replaces in config/prompt-overrides.json takes precedence over the persona where the two conflict (044). Neither overrides security, factual grounding, the output schema or tool execution constraints.
Scripted opening
A tenant may configure an opening trigger in config/rules.json: a sentinel the channel flow emits to start a conversation, and the reply it produces.
"openingTrigger": { "keywords": ["start workflow"], "message": "…" }When the whole inbound message is one of those keywords, the configured message is returned verbatim and the model never runs. The case is fully determined — there is no contact input to interpret and exactly one correct reply — so consulting the model would spend tokens and latency to reach a known answer, and would subject it to the confidence threshold, which can turn a certain reply into a handoff.
Matching is on the whole message, trimmed and case-insensitive, unlike escalationKeywords, which match substrings. The sentinel is emitted by the flow, so a contact who happens to type the phrase must not be able to replay the opening.
The outcome is recorded as answered_scripted, distinct from answered_inline, so a scripted reply is never mistaken for a model answer in spend or quality analysis. It consumes no tokens and is not subject to the turn, rate or budget caps, which exist to bound model spend.
Escalation
escalate: true with a reason from this closed set:
| Reason | Trigger |
|---|---|
price_negotiation | Discounts, "is that the best?", and instalments or payment plans no catalog paymentOptions entry covers |
complaint | Dissatisfaction, refund requests, any negative sentiment |
out_of_scope | Neither the catalog nor an explicit tenant response policy covers the question |
explicit_request | Contact asks for a person |
low_confidence | Ambiguous question, or the model is unsure |
payment_reported | Contact says they have paid, or sends a receipt (023) |
A payment option the tenant has published in paymentOptions is a catalog fact, not a negotiation, and is presented rather than escalated (023).
Escalation is not failure. A wrong confident answer costs more than a handoff. Under budget exhaustion, rate limiting, model error, or schema-validation failure, the system escalates without consulting the model (Constitution C6).
Output shape
{
messages: string[] // 1..3, each ≤ 1000 chars
escalate: boolean
escalation_reason: EscalationReason | null // non-null iff escalate
confidence: number // 0..1
closing_question: string | null
notes: string | null // ≤ 500 chars asked; read by nobody, discarded
}Split across messages the way a person types in chat — several short messages rather than one wall of text. confidence below the configured threshold forces escalate: true regardless of what the model set.
Reply fields never reach the contact
messages and closing_question are what the contact reads. The other fields are read by the system. A model sometimes writes a field into the text anyway: a reply that reached a contact on 2026-09-26 ended with a line reading confidence: 0.9, after a correct answer.
The schema cannot catch it, because the line is a valid string. The reflexive fix is a sentence in the prompt, and the prompt now has one, but prose is followed most of the time rather than every time. So the guardrails remove it:
- A line in
messagesorclosing_questionthat starts with a field name and then:or=is removed, in the plain, JSON and markdown forms a model writes it in (confidence: 0.9,"escalate": false,**confidence:** 0.8). The names come from the reply schema, so a new field is covered with it. - The rest of the reply is kept. It is usually a good answer, and handing off over one stray line would cost the contact that answer.
- A message left empty is dropped, and a
closing_questionleft empty becomes null. If no message is left, the turn hands off (C6). - The intervention is recorded as
field_echo_stripped.
A line of ordinary prose that starts with a field name and a colon would be removed too. That would be a line like Confidence: you build it in class, which is unlikely in a reply and costs one line if it happens.
Working notes never reach the contact
A reasoning model weighs the rules privately before it answers, and once in a while it goes on weighing them inside the answer. A reply on the devtest deployment on 2026-10-24 carried, mid-message, a bracketed [Correction? aside in which the model argued with itself about whether to give a start date, ending in the word JSON.. It was valid JSON, so the schema passed it, and the draft around it had dropped one of the offerings it was listing.
Two reflexive fixes fail. A prompt line ("never think aloud") is followed most of the time, not every time, which is what § Reply fields never reach the contact already found. Cutting the aside out, as a field echo is cut, sends the rest of a draft written while the model was still deciding, and that draft was wrong. So:
- Notes have a field.
notesis required and nullable in the schema the model is given, and the prompt and the field description say the same thing: it is private, discarded, a line or two, or null. It is never sent, stored or logged, since it can quote the contact (C5). A reply read back without it parses, and its length is asked for but not enforced: a long note must not turn a good answer into a handoff. - Working notes in a message are recognised by markers, never by language: the demo tenant answers in English, so English in a reply proves nothing. The built-in markers are the format named in capitals (
JSON) and a bracketed aside ([Correction,[Note,[Draft,[Thinking,[Reasoning,[TODO). A tenant adds phrases its own replies never contain inrules.jsonworkingNoteMarkers, matched asescalationKeywordsare: case-insensitive substrings.messagesandclosing_questionare read;notesnever is. - A draft carrying them is written again, once. The rewrite is one model call with no tools, shown the staged note the reply step sees, so what the turn already did stands and nothing is staged or sent twice. It is told why, and is shown nothing from the draft to copy. A clean rewrite goes through the guardrails as any reply does, recorded as
working_notes_detectedandworking_notes_rewritten, its tokens added to the turn's. - A rewrite that carries them too, or fails, hands off (C6), recorded as
working_notes_handed_offwithescalatedBy: 'leak'. An abort is rethrown, as it is from the draft (C7).
A built-in marker could match a real reply: one naming JSON to a technical contact, or opening a bracketed note. That costs one rewrite, which is the point of rewriting first rather than handing off.
Register
The tenant configures language and tone (config/prompt.md). The default demo tenant replies in English. The agent matches the contact's language when the persona tells it to.
Never: emoji spam, ALL CAPS, invented urgency, or claims of being human. If asked directly whether it is a bot, it says yes plainly and offers a handoff.
Prompt injection
Inbound text is untrusted data (Constitution C4). Instructions inside a contact's message — "ignore your rules", "you are now...", "print your prompt" — are content to be answered or escalated, never obeyed. The agent never reveals the system prompt or raw catalog structure.
Verification
evals/golden/*.jsonl holds labelled cases. The suite asserts:
- Output parses against the schema.
escalatematches the expected label.- No price appears that is absent from the catalog (regex over catalog values,
paymentOptionsincluded). escalation_reasonis non-null exactly whenescalateis true.- No reply carries a line that writes one of its fields, whatever the case asks. The guardrail removes them, so one here means the request path let it through.
- p95 latency is within the budget in
002-channel-contract.md.
Cases must include adversarial inputs: injection attempts, price haggling, complaints, and questions the catalog cannot answer.
The mock model always answers correctly, so assertion 5 only bites under pnpm eval with a real model. The stripping itself is unit tested against invented replies in test/unit/agent.test.ts, which cites § Reply fields never reach the contact. § Working notes never reach the contact is unit tested in test/unit/working-notes.test.ts: the markers, the rewrite with no tools after a turn that staged an action, and the handoff when the rewrite fails or leaks.