Agent spec

An agent's behaviour is one JSON document. Every call snapshots the spec it ran with, so a transcript always matches the configuration that produced it.

Fields

Field	Description
`company`required{ name, description, website?, knowledge? }	Who the agent speaks for. `knowledge` is free text it may answer from — FAQ, prices, hours.
`persona`required{ name, tone, style? }	The name it introduces itself with, and its tone: warm \| professional \| energetic \| calm.
`voice`required{ engine, voice_id?, language, languages? }	engine: auto \| voxbox \| azure \| gemini \| elevenlabs. `auto` picks the in-region voice for the language.
`goals`required{ id, description }[]	What a successful call achieves; used for the outcome.
`greeting`string	Your opening line. Placeholders: {company}, {persona}, {contact}. The AI disclosure is always spoken first.
`hours`{ timezone, open, after_hours }	Inbound opening hours by weekday (0 = Sunday) in minutes, and what to do outside them: take_message \| voicemail \| transfer.
`tools`required{ builtins[], mcp[] }	Built-in tools and the MCP servers + tool names this agent may use.
`calendar_id`uuid	The native calendar the booking tools use.
`transfer`{ label, number, when }[]	Humans it may transfer to, and when.
`guardrails`required{ max_call_seconds, max_silence_seconds, rec…	recording: off \| on \| by_jurisdiction.
`outbound`{ voicemail, voicemail_message? }	On an answering machine: drop a short message, or hang up.

Example — a receptionist template

AgentSpecjson

{
  "company": {
    "name": "Acme Dental",
    "description": "Family dental practice in Zurich"
  },
  "persona": {
    "name": "Alex",
    "tone": "warm"
  },
  "voice": {
    "engine": "auto",
    "language": "en"
  },
  "goals": [
    {
      "id": "resolve",
      "description": "Answer the caller’s question from the company knowledge."
    },
    {
      "id": "book",
      "description": "Book, move or cancel an appointment when asked."
    },
    {
      "id": "route",
      "description": "Transfer to a human for anything urgent or out of scope."
    }
  ],
  "greeting": "Thanks for calling {company}. How can I help?",
  "hours": {
    "timezone": "Europe/Zurich",
    "open": {
      "1": [
        [
          480,
          1080
        ]
      ],
      "2": [
        [
          480,
          1080
        ]
      ],
      "3": [
        [
          480,
          1080
        ]
      ],
      "4": [
        [
          480,
          1080
        ]
      ],
      "5": [
        [
          480,
          1080
        ]
      ]
    },
    "after_hours": "take_message"
  },
  "tools": {
    "builtins": [
      "end_call",
      "take_message",
      "log_note",
      "set_outcome",
      "opt_out",
      "lookup_knowledge",
      "check_availability",
      "book_appointment",
      "reschedule_appointment",
      "cancel_appointment",
      "transfer",
      "send_sms",
      "update_contact"
    ],
    "mcp": []
  },
  "guardrails": {
    "max_call_seconds": 900,
    "max_silence_seconds": 20,
    "recording": "by_jurisdiction"
  }
}