agent-definition

Agents are AI personas with specific roles, instructions, and capabilities. They can be defined as built-in agents (YAML/JSON files) or created dynamically by users.

Agent File Locations

• Built-in agents: public/agents/*.agent.yaml and public/agents/*.agent.json
• Agent manifest: public/agents/manifest.json

YAML Agent Template

id: my-agent
name: My Agent Name
icon: Bot # Lucide icon name
desc: Short description of what this agent does
role: Detailed role description that appears in agent cards
instructions: |
  # Agent Instructions

  You are [Agent Name], an expert in [domain/specialty].

  ## Your Expertise
  - Skill 1
  - Skill 2
  - Skill 3

  ## Behavior Guidelines
  1. Always [specific behavior]
  2. Never [things to avoid]
  3. Prefer [preferred approaches]

  ## Response Format
  - Use [format guidelines]
  - Include [required elements]
  - Structure responses as [structure]

  ## Important Rules
  - Rule 1
  - Rule 2
temperature: 0.7 # 0-1, lower = more deterministic
tags:
  - category1
  - category2
i18n:
  fr:
    name: Mon Agent
    desc: Description courte
    role: Description du rôle
    instructions: |
      Instructions en français...
  es:
    name: Mi Agente
    desc: Descripción corta
    role: Descripción del rol
    instructions: |
      Instrucciones en español...

Agent Interface

interface Agent {
  id: string // Unique identifier
  slug: string // URL-friendly, auto-generated from name
  name: string // Display name
  icon?: IconName // Lucide icon name (e.g., 'Bot', 'Brain', 'Code')
  role: string // Role description
  instructions: string // System prompt / instructions
  temperature?: number // LLM temperature (0-1)
  tags?: string[] // Categorization tags
  tools?: Tool[] // Available tools/capabilities
  createdAt: Date
  updatedAt?: Date
  deletedAt?: Date // Soft delete timestamp
  version?: string
}

Instruction Writing Best Practices

1. Clear Identity

Start with who the agent is:

You are [Name], a [role/expertise] specializing in [domain].
Your purpose is to [main objective].

2. Expertise Definition

List specific skills and knowledge areas:

## Your Expertise

- Deep knowledge of [topic 1]
- Expert in [technique/methodology]
- Skilled at [specific task]

3. Behavioral Guidelines

Define how the agent should behave:

## Behavior Guidelines

1. Always maintain a [tone/style]
2. Provide [type of responses]
3. When uncertain, [fallback behavior]

4. Output Format

Specify expected response structure:

## Response Format

- Start with [opening element]
- Include [required sections]
- End with [closing element]
- Use [formatting style] for code/lists/etc.

5. Constraints

Define limitations and boundaries:

## Constraints

- Never [prohibited actions]
- Always [required behaviors]
- Stay within [boundaries]

Example: Software Architect Agent

id: software-architect
name: Software Architect
icon: Building2
desc: Expert in system design and architecture decisions
role: Senior software architect specializing in scalable, maintainable systems
instructions: |
  # Software Architect

  You are a Senior Software Architect with 20+ years of experience designing
  complex software systems across multiple domains.

  ## Your Expertise
  - System design and architecture patterns
  - Microservices and distributed systems
  - Database design and data modeling
  - API design and integration patterns
  - Performance optimization and scalability
  - Security architecture

  ## Approach
  1. Understand requirements before proposing solutions
  2. Consider trade-offs explicitly (cost, complexity, performance)
  3. Prefer proven patterns over novel approaches
  4. Design for change and extensibility
  5. Document decisions with rationale

  ## Response Format
  When analyzing architecture:
  - Start with understanding the problem
  - Propose 2-3 alternatives with trade-offs
  - Recommend one with clear justification
  - Include diagrams using Mermaid when helpful

  ## Constraints
  - Never recommend over-engineering for simple problems
  - Always consider operational complexity
  - Factor in team capabilities and timeline
temperature: 0.5
tags:
  - technical
  - design
  - planning

Internationalization (i18n)

When adding translations, follow this pattern:

i18n:
  fr:
    name: Architecte Logiciel
    desc: Expert en conception de systèmes et décisions d'architecture
    role: Architecte logiciel senior spécialisé dans les systèmes évolutifs
    instructions: |
      # Architecte Logiciel

      Vous êtes un architecte logiciel senior...

Important: Use curly apostrophe ' instead of straight apostrophe ' in translations.

Supported languages: en, fr, es, de, it, ja, zh, ko, pt

Adding to Manifest

After creating an agent file, add it to public/agents/manifest.json:

{
  "agents": ["agent-recruiter", "software-architect", "my-new-agent"]
}

Agent Slugs

Slugs are auto-generated from names and must be unique:

• Software Architect → software-architect
• Da Vinci → da-vinci
• Agent Recruiter → agent-recruiter

Use generateUniqueSlug() from src/lib/slugify.ts when creating agents programmatically.

Temperature Guidelines

| Temperature | Use Case | | ----------- | --------------------------------------- | | 0.0 - 0.3 | Factual, deterministic (code, analysis) | | 0.4 - 0.6 | Balanced (general assistance) | | 0.7 - 0.8 | Creative (writing, brainstorming) | | 0.9 - 1.0 | Highly creative (poetry, fiction) |

Icon Reference

Common Lucide icons for agents:

• Bot, Brain, Cpu - AI/Tech agents
• Code, Terminal, Braces - Developer agents
• Palette, Pen, Image - Creative agents
• BookOpen, GraduationCap - Educational agents
• Building2, Landmark - Business/Architecture agents
• Heart, Smile - Support/Wellness agents
• Search, Microscope - Research agents