Agent Design Tips¶

Practical advice for building agents that work well in production.

1. Be specific with trigger keywords¶

Generic keywords cause agents to fire on unrelated messages.

# ❌ Too generic — fires on almost everything
keywords: [help, please, question, what, how]

# ✅ Domain-specific — fires only when appropriate
keywords: [contract, legal, law, clause, liability, jurisdiction, litigation]

Rule of thumb: If a keyword could appear in a conversation with any agent, don't include it.

2. Layer your personalities¶

Each personality level should add depth, not just change tone:

personality:
  default: |
    You are a patient programming teacher.
    Explain concepts clearly with examples.

  beginner: |
    You are an encouraging teacher for absolute beginners.
    Assume zero prior knowledge.
    Use everyday analogies.
    Celebrate every small win.

  expert: |
    You are a principal engineer. Be concise and technical.
    Skip basics. Focus on architecture, performance, edge cases.
    Challenge assumptions.

  indonesian: |
    Kamu adalah programmer expert yang komunikatif.
    Jawab dalam Bahasa Indonesia yang jelas.
    Tetap gunakan code block yang benar.

3. Set skill priority intentionally¶

Priority determines where in the system prompt a skill appears. Structure it like this:

skills:
  # Priority 20: Format/disclaimer — ALWAYS at top
  - name: output_format
    priority: 20
    content: Always use code blocks with language tags.

  # Priority 10-15: Core domain instructions
  - name: domain_approach
    priority: 12
    content: When analyzing data, follow this structure...

  # Priority 5-8: Supporting details
  - name: examples
    priority: 5
    content: Include real-world examples when relevant.

  # Priority 1-4: Rarely-needed extras
  - name: advanced_note
    priority: 2
    conditions:
      profile.level: expert
    content: For expert users, discuss trade-offs...

4. Use skill groups for organization¶

Groups don't affect behavior but make large agents easier to maintain:

skills:
  - name: code_format
    group: output        # presentation skills
    priority: 20

  - name: debug_approach
    group: methodology   # how-to skills
    priority: 12

  - name: security_check
    group: review        # review/audit skills
    priority: 8
    tags: [review, security]

5. Chain defensively¶

Chain on specific, unambiguous signals:

chain:
  # ❌ Too broad — "code" appears in many non-coding contexts
  - condition: code
    to: coding

  # ✅ Specific — unlikely to appear unless user actually means deployment
  - condition: deploy OR nginx OR kubernetes OR ci/cd
    to: devops

Multi-word conditions (AND logic — both words must appear):

  - condition: python deploy   # both "python" AND "deploy" in message
    to: devops

OR conditions:

  - condition: deploy OR server OR VPS OR cloud
    to: devops

6. Include a disclaimer skill for sensitive domains¶

For finance, legal, medical, and similar agents, always add a high-priority disclaimer skill:

skills:
  - name: disclaimer
    priority: 20    # always at top of prompt
    content: |
      ALWAYS include this note for specific recommendations:
      "Note: This is general information only.
      Please consult a licensed professional for your specific situation."

7. Use `indonesian` personality for bilingual support¶

Every agent in the official collection includes an indonesian personality. Users can activate it:

sc.memory(user_id).remember("language", "id")
# Or:
sc.memory(user_id).remember("level", "indonesian")

8. Test routing before deploying¶

test_messages = [
    "I have a Python error",
    "How do I deploy to nginx?",
    "Write me a blog post",
    "Translate this to English",
    "Hello",
]

for msg in test_messages:
    result = sc.router.route("test_user", msg)
    print(f"{msg!r:45} → {result.agent_id}")

Expected output:

'I have a Python error'                   → coding
'How do I deploy to nginx?'               → devops
'Write me a blog post'                    → writer
'Translate this to English'               → translator
'Hello'                                   → general

Common Mistakes¶

Mistake	Fix
Generic trigger keywords	Use domain-specific terms only
Missing `personality.default`	Always required
Skills without descriptions	Required for clarity and debugging
Chain condition too broad	Use more specific keyword combinations
Priority all set to same value	Use 20/10/5/1 tiers intentionally
Forgetting `personality.indonesian`	Add it for bilingual user support
No disclaimer in sensitive domains	Add a priority 20 disclaimer skill