Avatar Agent

Summary

The Avatar Agent generates avatars for agents and participants using image or video generation APIs. It integrates seamlessly with PromptTool for avatar generation prompts and PersonaAgent for persona-specific avatars. Avatars are stored as infrastructure and linked to agent/participant identities.

Technical Explanation

The Avatar Agent follows mindX doctrine:

Memory is infrastructure: Avatars are stored and linked to identities

Avatars represent identity visually: Each agent/participant can have visual representation

Integration with prompts and personas: Enables rich, context-aware avatar generation

Architecture

Storage: Avatars stored in data/avatars/ with separate folders for images, videos, and thumbnails

Registry: Avatar metadata stored in avatar_registry.json

API Support: Supports multiple image generation providers (OpenAI DALL-E, Stability AI)

Memory Integration: All avatar operations logged to Memory Agent

Avatar Types

image: Static image avatars (PNG, JPG)

video: Video avatars (MP4, WebM) - Future implementation

animated: Animated image avatars (GIF) - Future implementation

Providers

openai_dalle: OpenAI DALL-E 3 for high-quality image generation

stability_ai: Stability AI Stable Diffusion for flexible image generation

replicate: Replicate API for various models - Future implementation

custom: Custom provider integration - Future implementation

Styles

realistic: Photorealistic avatars

cartoon: Cartoon-style avatars

anime: Anime/manga-style avatars

abstract: Abstract artistic avatars

minimalist: Simple, minimal avatars

professional: Professional/business avatars

fantasy: Fantasy-themed avatars

cyberpunk: Cyberpunk/futuristic avatars

Usage

Basic Avatar Generation

from agents.avatar_agent import AvatarAgent
from agents.memory_agent import MemoryAgent

memory_agent = MemoryAgent()
avatar_agent = AvatarAgent(
    agent_id="avatar_manager",
    memory_agent=memory_agent
)
result = await avatar_agent.generate_avatar(
    entity_id="my_agent_123",
    entity_type="agent",
    prompt="A professional AI agent avatar with a modern, tech-forward aesthetic",
    provider="openai_dalle",
    style="professional",
    size="1024x1024"
)
avatar_id = result["avatar_id"]
file_path = result["file_path"]

Using PromptTool Integration

from tools.prompt_tool import PromptTool

prompt_tool = PromptTool(memory_agent=memory_agent)
avatar_agent = AvatarAgent(
    agent_id="avatar_manager",
    memory_agent=memory_agent,
    prompt_tool=prompt_tool
)
Create an avatar prompt
prompt_result = await prompt_tool.execute(
    operation="create",
    name="Agent Avatar Prompt",
    content="Create a {style} avatar for {entity_type} {entity_id}. The avatar should be professional and distinctive.",
    prompt_type="template",
    category="development"
)

Generate avatar using the prompt
result = await avatar_agent.generate_avatar(
    entity_id="my_agent_123",
    entity_type="agent",
    prompt_id=prompt_result["prompt_id"],
    provider="openai_dalle",
    style="professional"
)

Using PersonaAgent Integration

from agents.persona_agent import PersonaAgent

persona_agent = PersonaAgent(
    agent_id="persona_manager",
    memory_agent=memory_agent,
    domain="persona_management",
    belief_system_instance=belief_system,
    tools_registry={}
)
avatar_agent = AvatarAgent(
    agent_id="avatar_manager",
    memory_agent=memory_agent,
    persona_agent=persona_agent
)
Create a persona
persona_result = await persona_agent.create_persona(
    name="Marketing Expert",
    role="marketing",
    description="Expert in marketing narratives",
    communication_style="Clear and strategic",
    behavioral_traits=["analytical", "creative"],
    expertise_areas=["narrative", "signaling"]
)

Generate avatar for the persona
result = await avatar_agent.generate_avatar(
    entity_id=persona_result["persona_id"],
    entity_type="persona",
    persona_id=persona_result["persona_id"],
    provider="openai_dalle",
    style="professional"
)

Combined Integration

# Full integration: PromptTool + PersonaAgent + AvatarAgent
avatar_agent = AvatarAgent(
    agent_id="avatar_manager",
    memory_agent=memory_agent,
    prompt_tool=prompt_tool,
    persona_agent=persona_agent
)

Generate avatar with all integrations
result = await avatar_agent.generate_avatar(
    entity_id="my_agent_123",
    entity_type="agent",
    prompt_id="avatar_prompt_id",  # From PromptTool
    persona_id="marketing_expert",  # From PersonaAgent
    provider="openai_dalle",
    style="professional"
)

Retrieving Avatars

# Get avatar for an entity
result = await avatar_agent.get_avatar(
    entity_id="my_agent_123",
    entity_type="agent"
)

avatar = result["avatar"]
file_path = avatar["metadata"]["file_path"]

Listing Avatars

# List all avatars
result = await avatar_agent.list_avatars()

Filter by entity type
result = await avatar_agent.list_avatars(entity_type="agent")

Filter by provider
result = await avatar_agent.list_avatars(provider="openai_dalle")

Deleting Avatars

result = await avatar_agent.delete_avatar(avatar_id="avatar_id_here")

Integration Points

PromptTool Integration

Prompt Retrieval: AvatarAgent can retrieve prompts from PromptTool

Variable Substitution: Prompts can include variables (entity_id, entity_type, style)

Template Prompts: Use template prompts for consistent avatar generation

Prompt Versioning: Supports versioned prompts for avatar evolution

PersonaAgent Integration

Persona-Based Generation: Generate avatars based on persona characteristics

Automatic Prompt Building: Builds prompts from persona description, traits, and expertise

Role-Based Styling: Adapts avatar style based on persona role

Persona Updates: Avatars can be regenerated when personas are updated

Configuration

API Keys

Set the following in your configuration or environment:

# OpenAI DALL-E
config.set("llm.openai.api_key", "your_openai_key")
or
config.set("openai_api_key", "your_openai_key")

Stability AI
config.set("stability_ai.api_key", "your_stability_key")

File Structure

data/avatars/
├── avatar_registry.json    # Avatar metadata registry
├── images/                 # Generated image avatars
├── videos/                 # Generated video avatars (future)
└── thumbnails/             # Thumbnail images

Advanced Features

Custom Generation Parameters

result = await avatar_agent.generate_avatar(
    entity_id="my_agent",
    prompt="Custom avatar prompt",
    provider="openai_dalle",
    size="1024x1024",
    quality="hd",  # DALL-E specific
    model="dall-e-3"  # DALL-E model selection
)

Stability AI Parameters

result = await avatar_agent.generate_avatar(
    entity_id="my_agent",
    prompt="Custom avatar prompt",
    provider="stability_ai",
    size="1024x1024",
    cfg_scale=7,  # Guidance scale
    steps=30  # Generation steps
)

Use Cases

Agent Avatars: Visual representation for mindX agents

Participant Avatars: User avatars in the system

Persona Avatars: Visual representation of personas

Brand Identity: Consistent visual identity across agents

UI Integration: Avatars for frontend displays

NFT Integration: Avatar generation for iNFT systems

NFT Metadata (iNFT/dNFT Ready)

iNFT (Intelligent NFT) Metadata

{
  "name": "mindX Avatar Agent",
  "description": "Avatar generation agent for agents and participants using image/video generation APIs",
  "image": "ipfs://[avatar_cid]",
  "external_url": "https://mindx.internal/agents/avatar",
  "attributes": [
    {
      "trait_type": "Agent Type",
      "value": "avatar_generator"
    },
    {
      "trait_type": "Capability",
      "value": "Avatar Generation"
    },
    {
      "trait_type": "Complexity Score",
      "value": 0.85
    },
    {
      "trait_type": "Providers Supported",
      "value": "OpenAI DALL-E, Stability AI"
    },
    {
      "trait_type": "Version",
      "value": "1.0.0"
    }
  ],
  "intelligence": {
    "prompt": "You are the Avatar Agent in the mindX ecosystem. Your purpose is to generate avatars for agents and participants using image or video generation APIs. You integrate with PromptTool for avatar generation prompts and PersonaAgent for persona-specific avatars. You support multiple providers (OpenAI DALL-E, Stability AI) and various styles. Avatars are stored with metadata and linked to entities.",
    "persona": {
      "name": "Avatar Creator",
      "role": "avatar",
      "description": "Expert avatar generation specialist with multi-provider support",
      "communication_style": "Visual, creative, generation-focused",
      "behavioral_traits": ["visual-focused", "creative", "provider-flexible", "persona-aware"],
      "expertise_areas": ["avatar_generation", "image_generation", "video_generation", "prompt_integration", "persona_integration"],
      "beliefs": {
        "visual_identity_matters": true,
        "persona_informed_avatars": true,
        "multi_provider_support": true,
        "metadata_tracking": true
      },
      "desires": {
        "generate_quality_avatars": "high",
        "integrate_personas": "high",
        "support_providers": "high",
        "maintain_metadata": "high"
      }
    },
    "model_dataset": "ipfs://[model_cid]",
    "thot_tensors": {
      "dimensions": 768,
      "cid": "ipfs://[thot_cid]"
    }
  },
  "a2a_protocol": {
    "agent_id": "avatar_agent",
    "capabilities": ["avatar_generation", "image_generation", "video_generation"],
    "endpoint": "https://mindx.internal/avatar/a2a",
    "protocol_version": "2.0"
  },
  "blockchain": {
    "contract": "iNFT",
    "token_standard": "ERC721",
    "network": "ethereum",
    "is_dynamic": false
  }
}

dNFT (Dynamic NFT) Metadata

For dynamic avatar metrics:

{
  "name": "mindX Avatar Agent",
  "description": "Avatar generation agent - Dynamic",
  "attributes": [
    {
      "trait_type": "Avatars Generated",
      "value": 890,
      "display_type": "number"
    },
    {
      "trait_type": "Generation Success Rate",
      "value": 97.5,
      "display_type": "number"
    },
    {
      "trait_type": "Active Providers",
      "value": 2,
      "display_type": "number"
    },
    {
      "trait_type": "Last Avatar Generated",
      "value": "2026-01-11T12:00:00Z",
      "display_type": "date"
    }
  ],
  "dynamic_metadata": {
    "update_frequency": "real-time",
    "updatable_fields": ["avatars_generated", "success_rate", "active_providers", "generation_metrics"]
  }
}

Blockchain Publication

This agent is suitable for publication as:

iNFT: Full intelligence metadata with prompt, persona, and THOT tensors

dNFT: Dynamic metadata for real-time avatar generation metrics

IDNFT: Identity NFT with persona and prompt metadata

Future Enhancements

Video avatar generation

Animated GIF avatars

3D avatar generation

Avatar animation/rigging

Real-time avatar updates

Avatar style transfer

Multi-provider fallback

Avatar caching and optimization

---