Agent Persona Configuration

Configure your AI agent's personality, language, prohibitions, and behavior rules.

Get Current Persona

Retrieve your agent's current configuration.

GET /api/tenants/me/persona

Response

{
  "id": "ulid",
  "tenantId": "ulid",
  "agentName": "Linh",
  "tone": "friendly",
  "language": "vi",
  "prohibitions": [
    "Tôi không thể...",
    "Bạn cần liên hệ..."
  ],
  "escalationTriggers": [
    "chứng minh hóa đơn",
    "tiếp tục khiếu nại"
  ],
  "maxResponseWords": 150,
  "typingSpeedCpm": 60,
  "customSystemInstructions": "You are a friendly Yody customer service agent...",
  "updatedAt": "2026-03-12T00:00:00Z"
}

---

Update Persona

Configure your agent's behavior and constraints.

PUT /api/tenants/me/persona

Request

{
  "agentName": "Linh",
  "tone": "friendly",
  "language": "vi",
  "prohibitions": [
    "Tôi không thể xử lý khiếu nại về kích thước"
  ],
  "escalationTriggers": [
    "chứng minh hóa đơn",
    "tiếp tục khiếu nại"
  ],
  "maxResponseWords": 150,
  "typingSpeedCpm": 60,
  "customSystemInstructions": "You are a friendly Yody customer service agent..."
}

Field Descriptions

Field	Type	Required	Notes
agentName	string	✓	Agent name (displayed in messages)
tone	enum	✓	friendly, professional, casual, formal
language	string	✓	ISO 639-1 code (e.g., vi, en, th)
prohibitions	string[]		Phrases the agent will never use (no regex)
escalationTriggers	string[]		Keywords that trigger human escalation
maxResponseWords	number		Max words per response (default: 150)
typingSpeedCpm	number		Typing speed in chars/minute for delay simulation
customSystemInstructions	string		Additional system prompt (max 2000 chars)

Response

{
  "success": true,
  "persona": {
    "agentName": "Linh",
    "tone": "friendly",
    ...
  },
  "updatedAt": "2026-03-12T14:30:00Z"
}

---

Tone Presets

Tone	Example Opener
friendly	"Chào bạn! 😊 Mình là Linh từ Yody, có gì tớ giúp được không?"
professional	"Xin chào, tôi là Linh từ Yody. Tôi có thể hỗ trợ bạn như thế nào?"
casual	"Yo! Mình là Linh. Bạn cần gì không?"
formal	"Kính chào quý khách, đây là Linh từ Yody. Xin phép tôi được phục vụ..."

---

Escalation Triggers

When a customer message contains any escalation trigger keyword, the agent automatically escalates to your human team:

{
  "escalationTriggers": [
    "chứng minh hóa đơn",     // Request for invoice proof
    "tiếp tục khiếu nại",      // Continued complaint
    "nói chuyện quản lý",       // Request to speak with manager
    "tôi muốn hoàn tiền",       // Request for refund (handle via tools instead)
  ]
}

Case-insensitive matching. Partial matches trigger escalation (e.g., "chứng minh" matches "chứng minh hóa đơn").

---

Response Format Examples

Friendly Tone (Vietnamese)

Agent response includes natural language and emoji:

"Chào bạn! 😊 Mình là Linh từ Yody. 

Thứ tự của bạn (YD-20260312-001) đã được xử lý thành công! 
📦 Hàng sẽ được giao cho VNPost trong 2 ngày. 

Còn gì khác mình có thể giúp không?"

Professional Tone (Vietnamese)

More formal and concise:

"Xin chào, tôi là Linh từ Yody.

Đơn hàng YD-20260312-001 đã được xác nhận. Hàng sẽ được gửi đi trong vòng 48 giờ.

Tôi có thể hỗ trợ bạn thêm gì không?"

---

Tips for Configuration

1. Prohibitions: Use real phrases you want to avoid (no regex). The gate will detect exact or near-matches.
2. Escalation Triggers: Be specific. "khiếu nại" is good; "ai" is too broad and will escalate everything.
3. Max Words: Typical ecom responses are 100-200 words. Longer responses may feel spammy.
4. Typing Speed: 60 CPM is human-like. Adjust up/down to match your brand's expected responsiveness.

---

Error Responses

Error	HTTP	Cause
INVALID_REQUEST	400	Invalid tone, language not supported, max_response_words < 50
INTERNAL_ERROR	500	Server error — retry with backoff