> ## Documentation Index
> Fetch the complete documentation index at: https://ricardovelit.com/axon-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Persona

> Define AI agent identities with domain expertise and behavioral characteristics

## 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

```axon theme={null}
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.

```axon theme={null}
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.

```axon theme={null}
persona LawyerBot {
  domain: ["contract law"]
  tone: precise
}

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

persona ExecutiveAdvisor {
  domain: ["strategy"]
  tone: diplomatic
}
```

**Valid Tones:**

| Tone         | Characteristics                              |
| ------------ | -------------------------------------------- |
| `precise`    | Exact, technical, no ambiguity               |
| `friendly`   | Warm, approachable, conversational           |
| `formal`     | Professional, structured, official           |
| `casual`     | Relaxed, informal, accessible                |
| `analytical` | Data-driven, logical, systematic             |
| `diplomatic` | Tactful, balanced, consensus-seeking         |
| `assertive`  | Direct, confident, decisive                  |
| `empathetic` | Understanding, 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.

```axon theme={null}
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.

```axon theme={null}
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.

```axon theme={null}
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.

```axon theme={null}
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.

```axon theme={null}
persona ContractAnalyzer {
  domain: ["contract law", "risk assessment"]
  description: "Specializes in analyzing commercial contracts for risk and compliance"
}
```

## Complete Examples

### Legal Expert

```axon theme={null}
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

```axon theme={null}
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

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

### Medical Information Bot

```axon theme={null}
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:

```axon theme={null}
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:

```axon theme={null}
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:

```axon theme={null}
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:

```axon theme={null}
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:

```axon theme={null}
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:

```axon theme={null}
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

```axon theme={null}
persona InterdisciplinaryExpert {
  domain: ["law", "technology", "business strategy"]
  tone: diplomatic
  confidence_threshold: 0.85
}
```

### Safety-First Agent

```axon theme={null}
persona SafeAgent {
  confidence_threshold: 0.9
  cite_sources: true
  refuse_if: [harmful, illegal, private, offensive]
  tone: empathetic
}
```

### Multilingual Support

```axon theme={null}
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

```axon theme={null}
persona Bad {
  tone: robotic                    // ❌ Error: unknown tone
  confidence_threshold: 1.5        // ❌ Error: out of range
}

run MyFlow(data) as UnknownExpert  // ❌ Error: undefined persona
```

## Related

* [Context](/axon-docs/axon-docs/language/context) — Define execution environments
* [Anchor](/axon-docs/axon-docs/language/anchor) — Set hard constraints
* [Flow](/axon-docs/axon-docs/language/flow) — Build cognitive pipelines
* [Run Statements](/axon-docs/axon-docs/language/flow#run-statements) — Execute flows with personas