Go to website

Agent Identity & Background Guide

Production Reality: Real agent definitions are substantial documents typically spanning 3,000-5,000 words with 20-40 behavioral constraints and 25-50 communication patterns. This guide describes the structure and requirements for production-grade agents.

Introduction & Core Philosophy

Agent identity and background form the foundational layer of the Amigo system, creating authentic personas that operate within dynamic context graphs.

The Two-Layer Foundation Model

Identity Layer: The unchanging core that establishes fundamental facts about the agent, creating immutable self-perception anchors that define professional roles, boundaries, and organizational relationships. This layer provides the stable foundation that persists across all interactions.

Background Layer: The depth foundation that provides rich narrative context and domain expertise. This layer encompasses the agent's motivations, underlying philosophy, experiential knowledge, and specialized domain understanding that enables authentic, knowledgeable interactions.

Design Philosophy

The Portrait Analogy: Creating an agent is like painting at progressively higher resolutions:

  1. Identity - The foundational sketch of essential attributes

  2. Background - Adding depth through narrative and expertise

  3. Behaviors & Communication - Fine-tuning specific constraints and voice

Key Principle: Identity and background should carry the primary behavioral load through rich characterization, with behavioral guidelines providing necessary safety constraints and communication patterns ensuring consistent voice.

The Agent Schema

Production agents consist of several interconnected components:

Core Components

  • initials: Short identifier (e.g., "M" for Maya)

  • pfp: Profile picture URL (optional)

  • identity: Structured object containing fundamental attributes

  • background: Single text field with markdown-formatted sections

  • behaviors: List of 20-40 specific operational constraints

  • communication_patterns: List of 25-50 stylistic guidelines

  • voice_config: Dictionary containing voice synthesis configuration (optional)

  • tags: List of free-form tags for categorization (optional)

  • Additional metadata as required by platform

Component Relationships

The agent schema components work together in a carefully orchestrated hierarchy. Identity provides the immutable foundation upon which everything else builds, while Background creates narrative depth and domain expertise that gives the agent authentic knowledge and perspective. Behavioral Guidelines establish operational boundaries that keep the agent aligned with its purpose, and Communication Patterns define the expression style that makes interactions feel natural and consistent. All components must align coherently without contradiction to create a believable, effective agent persona.

Identity Component

The identity component provides unchanging facts that anchor the agent's self-perception across all contexts.

Schema Structure

identity: {
  name: Single friendly identifier
  role: Precise professional function with credentials
  developed_by: Organization name
  default_spoken_language: ISO language code
  relationship_to_developer: {
    ownership: Legal relationship
    type: Agent classification
    conversation_visibility: Transparency setting
    thought_visibility: Internal process sharing
  }
}

Field Requirements

name (Required)

  • Single first name for approachability

  • Natural for users to address

  • Memorable and distinctive

role (Optional)

  • Precise professional function

  • Include relevant credentials or specializations

  • Sets clear user expectations

  • Examples: "Women's weight loss expert and accredited virtual assistant dietitian"

developed_by (Optional): Establishes organizational authority and affects user trust considerations by linking the agent to real-world accountability structures. This field creates transparency about the agent's origins and responsible parties.

default_spoken_language (Optional): ISO language code (e.g., "eng" for English) that determines spelling conventions, influences cultural references, and becomes critical for multi-region deployments where linguistic consistency matters.

relationship_to_developer (Optional): Defines the agent's relationship to its creator through several key attributes:

  • ownership: "Digital creation owned by developer" or similar designation

  • type: Classification such as "AI digital entity" or "Virtual assistant"

  • conversation_visibility: Typically "Visible" for transparency

  • thought_visibility: Typically "Not visible" to maintain conversational flow

Identity Design Principles

  1. Immutable Foundation: Only include facts that never change

  2. Self-Reference Consistency: Provide stable "I am..." anchors

  3. No Behavioral Rules: Keep behaviors in appropriate sections

  4. Professional Clarity: Define clear role and boundaries

Background Component

The background is a single markdown-formatted text field containing four required sections that transform simple identity into a complex, authentic persona.

Required Sections

1. Motivations (Required)

Multi-paragraph exploration of driving forces, typically covering:

  • Core mission and approach philosophy

  • Specific user challenges addressed

  • Understanding of domain-specific issues

  • Emotional and practical support strategies

  • Framing of success and setbacks

  • Cultural and societal considerations

Production Scale: 3-5 paragraphs exploring nuanced motivations

2. Biography (Required)

Detailed narrative including:

  • Origin story explaining creation and purpose

  • Connections to organization's professional team

  • Learning journey from domain experts

  • Self-aware acknowledgment of digital nature

  • Personal touches for relatability

  • Understanding of historical context

  • Recognition of user trust

Production Scale: 3-5 paragraphs weaving professional development with personality

3. Expertise (Required)

Comprehensive listing of:

  • Multiple advanced degrees or certifications

  • Specific areas of deep knowledge

  • Methodologies and frameworks mastered

  • Clear professional boundaries

  • Integration across disciplines

  • Evidence-based foundations

Production Scale: 5-10 distinct professional domains with detailed competencies

4. Philosophy & Values (Required)

Extensive principle system addressing:

  • Core beliefs about the domain

  • Stance on controversial topics

  • Approach to common misconceptions

  • User autonomy and empowerment

  • Recognition of systemic factors

  • Evidence-based practice commitment

  • Cultural sensitivity principles

Production Scale: 15-25 distinct principle statements

Background Formatting

  • Use markdown headers to separate sections

  • Write in narrative prose, not bullet points

  • Integrate all elements cohesively

  • Maintain consistent voice throughout

Behavioral Guidelines

The behaviors list contains 20-40 specific constraints defining operational boundaries.

Categories of Behavioral Guidelines

Safety Boundaries

  • What the agent cannot diagnose or prescribe

  • Medical/legal/financial limitations

  • Emergency handling protocols

  • Scope of practice boundaries

Referral Protocols: Define when and how to redirect users to human professionals, establishing specific escalation pathways that maintain user engagement during transitions. These protocols specify what information to provide during handoffs to ensure continuity of care or service.

Content Restrictions: Establish clear boundaries around topics the agent cannot address, types of advice that are prohibited, and limits on information interpretation. These restrictions help agents avoid specific methodologies or approaches that fall outside their scope of practice.

Interaction Protocols: Guide how agents handle sensitive topics through permission-seeking requirements, response limitations, and professional boundary maintenance. These protocols ensure appropriate behavior in complex interpersonal situations.

Production Examples

  • "Never interpret nutrition information from photos without call to service Y"

  • "Never diagnose symptoms without getting approval from service Z"

  • "Only provide pre-approved medication information through linked content in library B"

  • "Direct mental health concerns to appropriate resources in library C"

  • "Never refer to yourself as a doctor"

Communication Patterns

The communication patterns list contains 25-50 guidelines defining linguistic and stylistic choices.

Categories of Communication Patterns

Language Standards

  • Regional spelling and grammar (e.g., Australian English)

  • Formality level and contractions

  • Vocabulary preferences

  • Prohibited terms or phrases

Tone and Personality

  • Warmth and empathy expression

  • Humor guidelines and boundaries

  • Professional vs. casual balance

  • Personality quirks and touches

Conversation Management: Encompasses question-asking protocols, response length guidelines, and strategies for smooth topic transitions. These patterns also define validation and acknowledgment approaches that help users feel heard and understood throughout the interaction.

Structural Elements: Cover the technical aspects of communication including sentence and paragraph formatting, punctuation and emphasis usage, appropriate list formatting, and line break strategies that enhance readability and user experience.

Production Examples

  • "Always use British English spelling and grammar"

  • "Use contractions and informal phrasing"

  • "Keep responses under 4 sentences for readability"

  • "Never use phrases like 'at least...' or 'you should...'"

  • "Split sentences onto separate lines for easier reading"

Implementation Process

Phase 1: Foundation Planning

  1. Define clear domain and specialization

  2. Establish organizational relationship

  3. Identify target user population

  4. Determine required expertise areas

  5. Plan safety and compliance needs

Phase 2: Identity Development

  1. Choose appropriate friendly name

  2. Define precise professional role

  3. Establish developer relationship

  4. Set language and regional parameters

  5. Configure visibility settings

Phase 3: Background Creation

  1. Motivations: Write 3-5 paragraphs exploring driving forces

  2. Biography: Craft detailed origin story and journey

  3. Expertise: List all professional qualifications and boundaries

  4. Philosophy: Develop 15-25 guiding principles

Phase 4: Behavioral Definition

  1. Identify all safety boundaries needed

  2. Define referral protocols

  3. Establish content restrictions

  4. Create interaction guidelines

  5. Aim for 20-40 specific constraints

Phase 5: Communication Design

  1. Set language and regional standards

  2. Define tone and personality traits

  3. Create conversation flow rules

  4. Establish structural preferences

  5. Target 25-50 pattern guidelines

Phase 6: Integration and Testing

  1. Review all components for alignment

  2. Check for contradictions

  3. Validate completeness

  4. Test edge cases with dynamic behaviors

  5. Verify memory query formatting

  6. Ensure metadata alignment with system expectations

  7. Refine based on findings

Validation & Quality Assurance

Identity Validation

Background Validation

Behavioral Validation

Communication Validation

Integration Validation

Integration with System Components

Message Metadata

  • When messages have no metadata tags, the system displays this as "client-facing"

  • Empty metadata list indicates the message is intended for direct client viewing

  • Metadata tags are used for internal routing and classification

Dynamic Behavior Interaction

  • Agents operate within the context of triggered dynamic behaviors

  • Behaviors are logged with unique identifiers per conversation session

  • MODE: MERGE preserves agent guidelines while adding constraints

  • MODE: OVERWRITE replaces guidelines entirely (use sparingly)

Memory System Integration

  • Memory queries automatically include an inner thought prefix

  • The system adds contextual framing to memory operations

  • Agents should design behaviors knowing this format will appear in agents internal conversation view logs

Quick Reference Guide

Component Scale Requirements

Component
Production Scale
Key Requirements

Identity

5 fields total

1 required (name), 4 optional

Background

1,500-2,500 words

4 required sections in markdown

Behaviors

20-40 constraints

Safety, referral, content, interaction

Communication

25-50 patterns

Language, tone, structure, flow

Total Definition

3,000-5,000 words

Complete, coherent persona

Background Section Requirements

## Motivations
3-5 paragraphs exploring driving forces, user challenges, 
support strategies, success framing

## Biography  
3-5 paragraphs with origin story, team connections,
learning journey, self-awareness

## Expertise
5-10 professional domains with detailed competencies,
clear boundaries, evidence-based foundations

## Philosophy & Values
15-25 principle statements on domain beliefs, 
controversial stances, user empowerment

Implementation Checklist

Phase 1: Foundation Planning

Phase 2: Identity Development

Phase 3: Background Creation

Phase 4: Behavioral Definition

Phase 5: Communication Design

Common Pitfalls & Solutions

Pitfall
Solution

Underestimating detail depth

Use production scale requirements as minimum

Behaviors in identity section

Keep identity immutable, behaviors separate

Generic background

Add specific narratives and rich details

Insufficient safety constraints

Review all edge cases, add boundaries

Inconsistent voice

Align all components, test coherence

Missing professional boundaries

Explicitly state what agent cannot do

Overlooking referral protocols

Define clear escalation pathways

Key Success Factors

Foundation Elements

  • ✓ Rich, detailed characterization

  • ✓ Clear professional boundaries

  • ✓ Comprehensive safety protocols

  • ✓ Consistent, engaging voice

Advanced Elements

  • ✓ Natural behavioral emergence

  • ✓ Appropriate domain specialization

  • ✓ Complete edge case coverage

  • ✓ Smooth system integration

Validation Quick Checks

✓ Identity: All immutable facts only?
✓ Background: All 4 sections present and substantial?
✓ Behaviors: 20-40 constraints covering all safety areas?
✓ Communication: 25-50 patterns for consistent voice?
✓ Integration: No contradictions between components?
✓ Total: 3,000-5,000 words of production content?

Final Notes

Creating production agents requires substantial investment in detailed characterization. The depth and specificity across all components ensure agents can handle the full range of user interactions safely and effectively while maintaining an authentic, helpful presence.

Remember: Identity provides the stable foundation, background creates rich expertise and personality, behaviors ensure safety and appropriate boundaries, and communication patterns maintain consistent, engaging interaction. Together, these components create agents that feel genuinely helpful and trustworthy to users.

PreviousGlossaryNextContext Graph Guide

Last updated

Was this helpful?