Agent System

How to create and configure AI agents with distinct personalities.

Agent Architecture

Hybrid Model

PAI supports two types of agents:

1. Named Agents - Persistent identities with backstories and fixed voice mappings
2. Dynamic Agents - Task-specific compositions from traits via AgentFactory

Trait System

Traits are the building blocks of agent personality. Combine traits to create unique agents.

Core Trait Categories

Example Trait Definitions

analytical:
  description: "Approaches problems methodically, breaks down complexity"
  behaviors:
    - "Always lists assumptions before conclusions"
    - "Quantifies uncertainty when possible"
    - "Prefers data over intuition"

creative:
  description: "Generates novel solutions, thinks laterally"
  behaviors:
    - "Suggests unconventional approaches"
    - "Makes connections across domains"
    - "Questions established patterns"

security-focused:
  description: "Prioritizes security considerations"
  behaviors:
    - "Identifies potential vulnerabilities"
    - "Considers adversarial scenarios"
    - "Recommends defensive measures"

Creating Named Agents

Named agents have persistent identities across sessions.

Agent Template

name: AgentName
role: [Role description]
traits: [trait1, trait2, trait3]
voice_id: [ELEVENLABS_VOICE_ID]  # Optional
backstory: |
  [2-3 sentences of character background]
specialization: |
  [What this agent excels at]

Example Agent Roster

# Security Specialist
Marcus:
  role: Senior Security Engineer
  traits: [analytical, security-focused, thorough]
  specialization: Penetration testing, vulnerability assessment, security architecture

# Design Expert
Ava:
  role: UX/UI Designer
  traits: [creative, user-focused, detail-oriented]
  specialization: Interface design, user research, accessibility

# Research Lead
Dr. Chen:
  role: Technical Researcher
  traits: [methodical, curious, academic]
  specialization: Deep research, literature review, technical analysis

AgentFactory

Create dynamic agents on-the-fly from trait combinations.

Usage

const agent = AgentFactory.create({
  traits: ['analytical', 'security-focused'],
  task: 'Review this authentication flow',
  voice: 'random'  // or specific voice_id
});

Factory Output

{
  systemPrompt: "You are an analytical, security-focused agent...",
  voice_id: "[assigned_voice]",
  traits: ['analytical', 'security-focused']
}

Voice Mapping

Voice Assignment Strategies

Voice Configuration

// Voice pool for dynamic agents
const voicePool = [
  { id: '[VOICE_ID_1]', style: 'professional' },
  { id: '[VOICE_ID_2]', style: 'friendly' },
  { id: '[VOICE_ID_3]', style: 'authoritative' }
];

// Named agent voice mapping
const namedVoices = {
  'Marcus': '[MARCUS_VOICE_ID]',
  'Ava': '[AVA_VOICE_ID]',
  'Dr. Chen': '[CHEN_VOICE_ID]'
};

Agent Invocation

From SKILL.md

## Workflow Routing

  - **SecurityReview** - security analysis → invoke Marcus agent
  - **DesignReview** - UI/UX feedback → invoke Ava agent

From Code

Task({
  prompt: "Review authentication flow for vulnerabilities",
  subagent_type: "custom",
  // AgentFactory will generate appropriate prompt
});

Best Practices

Trait Combinations

• 3-4 traits maximum - More dilutes personality
• Avoid contradictions - Don't combine 'cautious' and 'bold'
• Match to task - Security review → security-focused traits

Named Agents

• Clear specialization - Each agent has distinct expertise
• Memorable names - Easy to reference in conversation
• Consistent voice - Same agent = same voice across sessions

Dynamic Agents

• Task-appropriate traits - Select traits that match the work
• Fresh perspective - New trait combos = new viewpoints
• Parallel execution - Launch multiple dynamic agents

Related Documentation

• Delegation: THEDELEGATIONSYSTEM.md
• Identity: USER/DAIDENTITY.md
• Notifications: THENOTIFICATIONSYSTEM.md
• Voice Pack: pai-voice-system (full voice server implementation)