Agents
Agent Configuration (YAML)
Define instructions, opening hours, and transfers in a portable YAML file.
Agent Configuration (YAML)
Agent YAML files live wherever you prefer—many teams store them under packages/agent/samples. The sample onenine-agent.yaml in this repository shows every supported field and maps directly to what the API stores in Postgres (agents.raw_config plus mapped columns).
phone: "+14507004061"
openingHours: |
Monday to Friday: 9:00 AM - 6:00 PM Eastern
Saturday & Sunday: Closed
description: |
Meet OneNine’s Onenine AI guide...
supportedLanguages: ["ENGLISH", "FRENCH"]
defaultLanguage: "FRENCH"
instructions: |
You are John, OneNine Innovations’ official AI assistant.
faqs: |
Q: What are your opening hours? ...
transfers:
- department: "Technical Support"
instructions: "Transfer when a caller needs human support..."
phone_number: "+15147548195"Field reference
| Field | Used by | Notes |
|---|---|---|
phone | API + operator runbooks | Stored inside rawConfig so you can document the public DID. Provisioning writes the authoritative number to agents.twilio_phone_number. |
openingHours | Agent instructions | Merged into the prompt via company_instructions_parts. |
description | API + agent prompt | Saved in agents.description and appended to the runtime instructions. |
instructions | Agent prompt | Free-form markdown. Keep it concise; the runtime prepends shared receptionist behaviors from prompts.get_default_instructions. |
supportedLanguages | API + runtime | Must use AgentLanguage enum values (FRENCH, ENGLISH). Drives multilingual enforcement in language_utility.py. |
defaultLanguage | Runtime | The Assistant class greets callers in this language and uses it as a fallback when detection is uncertain. |
faqs | Agent prompt | Added verbatim; keep question/answer formatting consistent. |
transfers | Agent prompt + transfer_call tool | Each object needs department, instructions, and phone_number. When the LLM invokes transfer_call, it looks up the matching department case-insensitively and triggers a SIP cold transfer. |
Upload workflow
- Store the YAML file in your repo and keep it under version control so rollbacks are trivial.
- Create or update the agent using the
/api/agents/.../from-yamlendpoints. - The raw YAML is persisted as JSON (
raw_config) so the LiveKit worker can access all keys, even ones the API doesn’t care about yet (e.g., marketing blurbs or experiment flags).
Validation rules
- Only
.yamland.ymlfiles are accepted; others are rejected by Multer before processing. - Files larger than 1 MB are rejected to keep uploads snappy.
js-yamlmust return an object; arrays or scalars result inInvalid YAML format.- Language fields must adhere to the enum in
packages/server/src/types/agents.type.ts.
Keep YAML files short and declarative, then use git history to track what changed between deployments.