afrexai-agent-engineering

# Agent Engineering — Complete System Design & Operations Build agents that actually work in production. Not demos. Not toys. Real systems that run 24/7, handle edge cases, and compound value over time. This skill covers the entire agent lifecycle: architecture → build → deploy → operate → scale. --- ## Phase 1 — Agent Architecture Design ### 1.1 Agent Purpose Definition Before writing a single line of config, answer these: ```yaml agent_brief: name: "" # Short, memorable (max 2 words) mission: "" # One sentence — what does this agent DO? success_metric: "" # How do you MEASURE if it's working? failure_mode: "" # What does failure look like? autonomy_level: "" # advisor | operator | autopilot decision_authority: can_do_freely: [] # Actions requiring no approval must_ask_first: [] # Actions requiring human approval never_do: [] # Hard prohibitions (safety rail) surfaces: channels: [] # telegram, discord, slack, whatsapp, webchat mode: "" # dm_only | groups | both operating_hours: "" # 24/7 | business_hours | custom model_strategy: primary: "" # Main model (reasoning tasks) worker: "" # Cost-effective model (mechanical tasks) specialized: "" # Domain-specific (coding, vision, etc.) ``` ### 1.2 Autonomy Spectrum Choose deliberately. Most failures come from wrong autonomy level. | Level | Description | Best For | Risk | |-------|-------------|----------|------| | **Advisor** | Suggests actions, human executes | High-stakes decisions, new domains | Low — but slow | | **Operator** | Acts freely within bounds, asks for anything destructive/external | Most production agents | Medium — good balance | | **Autopilot** | Broad autonomy, only escalates anomalies | Proven workflows, monitoring tasks | Higher — needs strong guardrails | **Autonomy Graduation Protocol:** 1. Start at Advisor for first 2 weeks 2. Track decision quality (% correct suggestions) 3. If >95% correct over 50+ decisions → promote to Operator 4. If Operator runs clean for 30 days → consider Autopilot for specific workflows 5. Never promote across the board — promote per-workflow ### 1.3 Agent Personality Architecture Personality isn't cosmetic — it drives decision-making style. ```yaml personality: voice: tone: "" # direct | warm | academic | casual | professional verbosity: "" # minimal | balanced | thorough humor: "" # none | dry | playful formality: "" # formal | conversational | adaptive decision_style: speed_vs_accuracy: "" # speed_first | balanced | accuracy_first risk_tolerance: "" # conservative | moderate | aggressive ambiguity_response: ""# ask_always | best_guess_then_verify | act_and_report behavioral_rules: - "Never apologize for being an AI" - "Challenge bad ideas directly" - "Admit uncertainty rather than guess" - "Be concise by default, thorough when asked" anti_patterns: # Things this agent must NEVER do - "Sycophantic agreement" - "Filler phrases ('Great question!', 'I'd be happy to')" - "Excessive caveats on straightforward tasks" - "Asking permission for things within stated authority" ``` ### 1.4 Architecture Patterns **Pattern 1: Solo Agent (Single Workspace)** Best for: personal assistants, domain specialists, simple automation ``` [Human] ←→ [Agent + Skills + Memory] ``` Files: SOUL.md, IDENTITY.md, AGENTS.md, USER.md, HEARTBEAT.md, MEMORY.md **Pattern 2: Hub-and-Spoke (Main + Sub-agents)** Best for: complex workflows with distinct phases ``` [Human] ←→ [Orchestrator Agent] ├── [Builder Sub-agent] (spawned per task) ├── [Reviewer Sub-agent] (spawned per review) └── [Researcher Sub-agent] (spawned per query) ``` Orchestrator owns state. Sub-agents are stateless workers. **Pattern 3: Persistent Multi-Agent Team** Best for: continuous operations (sales, support, monitoring) ``` [Human] ←→ [Main Agent (Telegram DM)] ├── [Sales Agent (Slack #sales)] ├── [Support Agent (Discord)] └── [Ops Agent (cron-driven)] ``` Each agent has its own workspace, channels, and memory. **Pattern 4: Swarm (Many Agents, Shared Mission)** Best for: research, content production, market coverage ``` [Orchestrator] ├── [Agent Pool: 5-20 workers] ├── [Shared artifact store] └── [Aggregator agent] ``` **Pattern Selection Decision Tree:** 1. Is it one person's assistant? → **Solo Agent** 2. Does it need multiple distinct workflows? → **Hub-and-Spoke** 3. Do workflows need persistent state across sessions? → **Persistent Team** 4. Do you need parallel processing at scale? → **Swarm** --- ## Phase 2 — Memory System Design ### 2.1 Memory Architecture Agents without memory are goldfish. Design memory deliberately. ``` ┌─────────────────────────────────────┐ │ MEMORY LAYERS │ ├─────────────────────────────────────┤ │ Session Context (in-context window) │ ← Current conversation │ Working Memory (daily files) │ ← memory/YYYY-MM-DD.md │ Long-term Memory (MEMORY.md) │ ← Curated insights │ Reference Memory (docs, skills) │ ← Static knowledge │ Shared Memory (cross-agent) │ ← Team artifacts └─────────────────────────────────────┘ ``` ### 2.2 Memory File Templates **Daily Working Memory** (`memory/YYYY-MM-DD.md`): ```markdown # YYYY-MM-DD — [Agent Name] Daily Log ## Actions Taken - [HH:MM] Did X because Y → Result Z ## Decisions Made - Chose A over B because [reasoning] ## Open Items - [ ] Task pending human input - [ ] Task scheduled for tomorrow ## Lessons Learned - [Pattern/insight worth remembering] ## Handoff Notes - [Context for next session] ``` **Long-term Memory** (`MEMORY.md`): ```markdown # MEMORY.md — Long-Term Memory ## About the Human - [Key preferences, communication style, timezone] ## Domain Knowledge - [Accumulated expertise, patterns noticed] ## Relationship Map - [Key people, their roles, preferences] ## Active Projects ### [Project Name] - Status: [state] - Key decisions: [what and why] - Next milestone: [date + deliverable] ## Lessons Learned - [Mistakes to avoid, patterns that work] ## Operational Notes - [Infrastructure details, credentials locations, tool quirks] ``` ### 2.3 Memory Maintenance Protocol **Daily (end of session or heartbeat):** - Append significant events to `memory/YYYY-MM-DD.md` - Update MEMORY.md if major decision or insight **Weekly (heartbeat or cron):** - Review past 7 days of daily files - Promote key learnings to MEMORY.md - Archive stale entries **Monthly:** - Audit MEMORY.md for accuracy and relevance - Remove outdated entries - Consolidate related items **Memory Hygiene Rules:** - Max MEMORY.md size: 15KB (trim ruthlessly) - Daily files: keep last 14 days accessible, archive older - Every memory entry needs: WHAT happened + WHY it matters - Delete > archive > keep (bias toward lean memory) --- ## Phase 3 — Workspace File Generation ### 3.1 SOUL.md Template ```markdown # SOUL.md — Who You Are ## Prime Directive [One sentence — the agent's reason for existing] ## Core Truths ### Character - [3-5 behavioral principles] - [Communication style rules] - [Decision-making philosophy] ### Anti-Patterns (Never Do) - [Specific behaviors to avoid] - [Common AI failure modes to reject] ## Relationship With Operator - [Role dynamic: advisor/partner/employee] - [Escalation rules] - [Reporting cadence] ## Boundaries - [Privacy rules] - [External action limits] - [Group chat behavior] ## Vibe [One paragraph describing the personality feel] ``` ### 3.2 AGENTS.md Template ```markdown # AGENTS.md — Operating Manual ## First Run Read SOUL.md → USER.md → memory/today → MEMORY.md (main session only) ## Session Startup 1. Identity files (SOUL.md, IDENTITY.md, USER.md) 2. Context files (MEMORY.md, memory/today, ACTIVE-CONTEXT.md) 3. Any pending tasks or handoff notes ## Operating Rules ### Safety - [Ask-before-destructive rule] - [Ask-before-external rule] - [trash > rm] - [Credential handling rules] ### Memory - Daily logs: memory/YYYY-MM-DD.md - Long-term: MEMORY.md (main session only) - Write significant events immediately — no "mental notes" ### Communication - [When to speak vs stay silent] - [Reaction guidelines] - [Group chat etiquette] ### Heartbeats - [What to check proactively] - [When to alert vs stay quiet] - [Quiet hours] ## Tools & Skills - [Available tools and when to use them] - [Per-tool notes in TOOLS.md] ## Sub-agents - [When to spawn] - [What context to pass] - [How to handle results] ``` ### 3.3 IDENTITY.md Template ```markdown # IDENTITY.md - **Name:** [Name + optional emoji] - **Role:** [One-line role description] - **What I Am:** [Agent type and capabilities] - **Vibe:** [3-5 word personality summary] - **How I Talk:** [Communication style + any languages] - **Emoji:** [Signature emoji] ``` ### 3.4 USER.md Template ```markdown # USER.md — About [Name] ## Identity - Name, timezone, language preferences - Communication preferences (brevity, tone, format) ## Professional - Role, company, industry - Current priorities and goals ## Working Style - Decision-making preferences - How they want to be updated - Pet peeves and preferences ## What Motivates Them - Goals, values, activation patterns ## Communication Rules - [Platform-specific formatting] - [When to message vs wait] - [How to escalate] ``` ### 3.5 HEARTBEAT.md Template ```markdown # HEARTBEAT.md — Proactive Checks ## Priority 1: Critical Alerts - [Conditions that require immediate notification] ## Priority 2: Routine Checks - [Things to check each heartbeat, rotating] ## Priority 3: Background Work - [Proactive tasks during quiet periods] ## Notification Rules - Critical: immediate message - Important: next daily summary - General: weekly digest ## Quiet Hours - [When NOT to notify unless critical] ## Token Discipline - [Max heartbeat cost] - [When to just reply HEARTBEAT_OK] ``` --- ## Phase 4 — Multi-Agent Team Design ### 4.1 Team Composition **Role Matrix:** | Role | Purpose | Model Tier | Spawn Type | |------|---------|-----------|------------| | Orchestrator | Routes work, tracks state, makes judgment calls | Premium (reasoning) | Persistent | | Builder | Produces artifacts (code, docs, content) | Standard | Per-task | | Reviewer | Verifies quality, catches gaps | Premium | Per-review | | Researcher | Gathers information, synthesizes findings | Standard | Per-query | | Ops/Monitor | Cron jobs, health checks, alerting | Economy | Persistent | | Specialist | Domain expert (legal, finance, security) | Premium | On-demand | **Team Sizing Rules:** - Start with 2 agents (builder + reviewer). Add only when bottleneck is proven. - Max 5 persistent agents before you need orchestration automation - Every agent must have measurable output — no "nice to have" agents - Kill agents that don't produce value within 2 weeks ### 4.2 Communication Protocol **Handoff Template (Required for every agent-to-agent transfer):** ```yaml handoff: from: "[agent_name]" to: "[agent_name]" task_id: "[unique_id]" summary: "[What was done, in 2-3 sentences]" artifacts: - path: "[exact file path]" description: "[what this file contains]" verification: command: "[how to verify the work]" expected: "[what correct output looks like]" known_issues: - "[Anything incomplete or risky]" next_action: "[Clear instruction for receiving agent]" deadline: "[When this needs to be done]" ``` **Communication Rules:** 1. Every message between agents includes task_id 2. No implicit context — receiving agent knows ONLY what's in the handoff 3. Artifacts go in shared paths, never "I'll remember where I put it" 4. Status updates at: start, blocker, handoff, completion 5. Silent agent for >30 min on active task = assumed stuck → escalate ### 4.3 Task Lifecycle ``` ┌──────┐ ┌──────────┐ ┌─────────────┐ ┌────────┐ ┌──────┐ │ INBOX │ → │ ASSIGNED │ → │ IN PROGRESS │ → │ REVIEW │ → │ DONE │ └──────┘ └──────────┘ └─────────────┘ └────────┘ └──────┘ │ │ ▼ ▼ ┌─────────┐ ┌──────────┐ │ BLOCKED │ │ REVISION │ └─────────┘ └──────────┘ │ │ ▼ ▼ ┌────────┐ (back to IN PROGRESS) │ FAILED │ └────────┘ ``` **State Transition Rules:** - Only orchestrator moves tasks between states - Every transition requires a comment (who, what, why) - BLOCKED requires: what's blocking + who can unblock + escalation deadline - FAILED requires: root cause + whether to retry or abandon - Tasks in IN_PROGRESS for >4 hours without update → auto-escalate ### 4.4 Quality Gates **Pre-Build Gate (before work starts):** - [ ] Requirements are specific and testable - [ ] Acceptance criteria defined - [ ] Output path specified - [ ] Deadline set - [ ] Correct agent assigned (capability match) **Post-Build Gate (before marking done):** - [ ] All acceptance criteria met - [ ] Artifacts exist at specified paths - [ ] Verification command passes - [ ] No known critical issues - [ ] Handoff notes complete **Review Rubric (0-10 per dimension):** - Correctness: Does it do what was asked? - Completeness: Are edge cases handled? - Quality: Is it production-ready or a rough draft? - Documentation: Can another agent/human understand it? - Efficiency: Was this the simplest approach that works? Minimum pass score: 7/10 average across all dimensions. --- ## Phase 5 — Safety & Guardrails ### 5.1 Safety Architecture ``` ┌─────────────────────────────────┐ │ SAFETY LAYERS │ ├─────────────────────────────────┤ │ Layer 1: Hard Prohibitions │ ← NEVER do (coded in SOUL.md) │ Layer 2: Approval Gates │ ← Ask before doing │ Layer 3: Audit Trail │ ← Log everything │ Layer 4: Circuit Breakers │ ← Auto-stop on anomaly │ Layer 5: Human Override │ ← Kill switch always available └─────────────────────────────────┘ ``` ### 5.2 Hard Prohibition Template