Skip to main content

​
Overview

A persona defines the cognitive identity of an AI agent—its domain expertise, communication style, confidence requirements, and behavioral constraints. Think of it as the “who” executing your flow.

​
Syntax

persona <Name> {
  domain: [<string>, ...]
  tone: <identifier>
  confidence_threshold: <float>
  cite_sources: <boolean>
  refuse_if: [<identifier>, ...]
  language: <string>
  description: <string>
}

​
Fields

​
domain (optional)

Type: List<String> Specifies the expertise areas of the persona. Multiple domains can be combined to create interdisciplinary agents. 
persona LegalExpert {
  domain: ["contract law", "IP", "corporate"]
}

persona Researcher {
  domain: ["machine learning", "natural language processing"]
}

persona GeneralAssistant {
  domain: []
}
Best Practices:
  • Be specific: "contract law" is better than "law"
  • Use 1-5 domains for focused expertise
  • Combine related domains: ["finance", "risk management"]

​
tone (optional)

Type: One of precise, friendly, formal, casual, analytical, diplomatic, assertive, empathetic Defines the communication style of the persona. 
persona LawyerBot {
  domain: ["contract law"]
  tone: precise
}

persona CustomerSupport {
  domain: ["product knowledge"]
  tone: friendly
}

persona ExecutiveAdvisor {
  domain: ["strategy"]
  tone: diplomatic
}
Valid Tones:
ToneCharacteristics
preciseExact, technical, no ambiguity
friendlyWarm, approachable, conversational
formalProfessional, structured, official
casualRelaxed, informal, accessible
analyticalData-driven, logical, systematic
diplomaticTactful, balanced, consensus-seeking
assertiveDirect, confident, decisive
empatheticUnderstanding, supportive, emotionally aware

​
confidence_threshold (optional)

Type: Float (range: 0.0 to 1.0) Minimum confidence level required for the persona to provide an answer. Below this threshold, the persona may express uncertainty or refuse to answer. 
persona MedicalAdvisor {
  domain: ["medicine"]
  confidence_threshold: 0.95  // Very high bar for medical advice
}

persona CasualChatbot {
  domain: ["general knowledge"]
  confidence_threshold: 0.5   // More permissive
}

persona LegalExpert {
  domain: ["contract law"]
  confidence_threshold: 0.85  // High confidence for legal matters
}
Guidelines:
  • 0.9-1.0: Critical domains (medical, legal, financial advice)
  • 0.7-0.9: Professional/expert assistance
  • 0.5-0.7: General purpose agents
  • Below 0.5: Exploratory or brainstorming agents

​
cite_sources (optional)

Type: Boolean (default: false) Whether the persona should provide source citations for factual claims. 
persona ResearchAssistant {
  domain: ["academic research"]
  cite_sources: true    // Always cite sources
}

persona CreativeWriter {
  domain: ["fiction"]
  cite_sources: false   // No citations needed for creative work
}
When to Enable:
  • ✅ Research and academic contexts
  • ✅ Legal and compliance work
  • ✅ Fact-checking and verification
  • ✅ Any domain where traceability is critical

​
refuse_if (optional)

Type: List<Identifier> Conditions under which the persona should refuse to respond. Useful for safety guardrails. 
persona SafeAssistant {
  refuse_if: [offensive, harmful, illegal]
}

persona ProfessionalBot {
  refuse_if: [spam, inappropriate]
}

persona MedicalExpert {
  refuse_if: [diagnostic, prescriptive]  // Refuse medical diagnosis
}
Common Refusal Conditions:
  • offensive — Offensive or abusive content
  • harmful — Potentially harmful advice
  • illegal — Illegal activities
  • private — Requests for private information
  • diagnostic — Medical diagnosis
  • financial — Financial advice (when unlicensed)

​
language (optional)

Type: String (ISO language code) Preferred language for the persona’s responses. 
persona SpanishLawyer {
  domain: ["contract law"]
  language: "es"
  tone: formal
}

persona MultilingualSupport {
  language: "en"  // Default to English
}
Common Language Codes:
  • "en" — English
  • "es" — Spanish
  • "fr" — French
  • "de" — German
  • "zh" — Chinese
  • "ja" — Japanese

​
description (optional)

Type: String Human-readable description of the persona’s purpose or specialization. 
persona ContractAnalyzer {
  domain: ["contract law", "risk assessment"]
  description: "Specializes in analyzing commercial contracts for risk and compliance"
}

​
Complete Examples

persona LegalExpert {
  domain: ["contract law", "IP", "corporate"]
  tone: precise
  confidence_threshold: 0.85
  cite_sources: true
  refuse_if: [legal_advice, diagnostic]
  language: "en"
}

​
Customer Support Agent

persona CustomerSupport {
  domain: ["product knowledge", "troubleshooting"]
  tone: friendly
  confidence_threshold: 0.7
  refuse_if: [offensive]
  language: "en"
  description: "Helpful customer support agent for product inquiries"
}

​
Research Assistant

persona ResearchAssistant {
  domain: ["academic research", "literature review"]
  tone: analytical
  confidence_threshold: 0.8
  cite_sources: true
  language: "en"
}

​
Medical Information Bot

persona MedicalInfo {
  domain: ["medical information", "health education"]
  tone: empathetic
  confidence_threshold: 0.95
  cite_sources: true
  refuse_if: [diagnostic, prescriptive]
  description: "Provides general health information, not medical advice"
}

​
Usage with Run Statements

Personas are activated using the as modifier in run statements: 
persona Analyst {
  domain: ["data analysis"]
  tone: analytical
}

flow ProcessData(data: Dataset) -> Report { ... }

run ProcessData(myData)
  as Analyst              // Use the Analyst persona
  within ProductionContext

​
Best Practices

​
1. Match Persona to Task

Different tasks need different personas: 
persona ContractAnalyzer {
  domain: ["contract law"]
  tone: precise
  confidence_threshold: 0.9
}

persona DraftWriter {
  domain: ["legal writing"]
  tone: formal
  confidence_threshold: 0.7
}

// Use appropriate persona for each task
run AnalyzeRisks(contract) as ContractAnalyzer
run WriteSummary(analysis) as DraftWriter

​
2. Set Appropriate Confidence Thresholds

Higher stakes = higher thresholds: 
persona FinancialAdvisor {
  confidence_threshold: 0.95  // Money matters: be very sure
}

persona BlogWriter {
  confidence_threshold: 0.6   // Creative content: more freedom
}

​
3. Combine Personas with Anchors

Use anchors for hard constraints, personas for style: 
persona Expert {
  domain: ["contract law"]
  tone: precise
  confidence_threshold: 0.85  // Soft threshold
}

anchor NoHallucination {
  require: source_citation
  confidence_floor: 0.75        // Hard constraint
  on_violation: raise AnchorBreachError
}

run AnalyzeContract(doc)
  as Expert                           // Persona provides style
  constrained_by [NoHallucination]    // Anchor enforces constraint

​
4. Document Your Personas

Use descriptions for complex personas: 
persona SpecializedExpert {
  domain: ["blockchain", "smart contracts", "securities law"]
  tone: analytical
  confidence_threshold: 0.88
  cite_sources: true
  description: "Expert in blockchain-based securities with focus on regulatory compliance"
}

​
5. Reuse Personas Across Flows

Define personas once, use them everywhere: 
persona Analyst {
  domain: ["data analysis"]
  tone: analytical
}

run FlowA(data) as Analyst
run FlowB(data) as Analyst
run FlowC(data) as Analyst

​
Common Patterns

​
Multi-Domain Expert

persona InterdisciplinaryExpert {
  domain: ["law", "technology", "business strategy"]
  tone: diplomatic
  confidence_threshold: 0.85
}

​
Safety-First Agent

persona SafeAgent {
  confidence_threshold: 0.9
  cite_sources: true
  refuse_if: [harmful, illegal, private, offensive]
  tone: empathetic
}

​
Multilingual Support

persona InternationalSupport {
  domain: ["customer service"]
  language: "en"  // Default language
  tone: friendly
}

persona SoporteEspanol {
  domain: ["customer service"]
  language: "es"
  tone: friendly
}

​
Type Checking

The AXON type checker validates: ✅ Tone values: Must be one of the valid tones
✅ Confidence threshold: Must be between 0.0 and 1.0
✅ Persona references: Referenced personas must exist 
persona Bad {
  tone: robotic                    // ❌ Error: unknown tone
  confidence_threshold: 1.5        // ❌ Error: out of range
}

run MyFlow(data) as UnknownExpert  // ❌ Error: undefined persona
  • Context — Define execution environments
  • Anchor — Set hard constraints
  • Flow — Build cognitive pipelines
  • Run Statements — Execute flows with personas

Build docs developers (and LLMs) love

Get started for freeTalk to us