agent-definition

# Agent Definition for DEVS 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 ```yaml 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 ```typescript 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: ```markdown You are [Name], a [role/expertise] specializing in [domain]. Your purpose is to [main objective]. ``` ### 2. Expertise Definition List specific skills and knowledge areas: ```markdown ## Your Expertise - Deep knowledge of [topic 1] - Expert in [technique/methodology] - Skilled at [specific task] ``` ### 3. Behavioral Guidelines Define how the agent should behave: ```markdown ## 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: ```markdown ## 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: ```markdown ## Constraints - Never [prohibited actions] - Always [required behaviors] - Stay within [boundaries] ``` ## Example: Software Architect Agent ```yaml 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: ```yaml 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`: ```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