# Fabioc Aloha Windowswidget AI Agent Design > AI Agent Design Skill - Skill: `tomevault-io/fabioc-aloha-windowswidget-ai-agent-design` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/fabioc-aloha-windowswidget-ai-agent-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/fabioc-aloha-windowswidget-ai-agent-design/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/fabioc-aloha-windowswidget-ai-agent-design --- # AI Agent Design Skill > **Domain**: AI/ML Architecture > **Inheritance**: inheritable > **Version**: 1.0.0 > **Last Updated**: 2026-02-01 --- ## Overview Comprehensive patterns for designing AI agents—autonomous systems that use LLMs to reason, plan, and execute multi-step tasks. Covers single-agent architectures, multi-agent orchestration, tool use, memory systems, and production deployment patterns. --- ## Agent Architecture Fundamentals ### What Is an AI Agent? ```text ┌─────────────────────────────────────────────────────────────┐ │ AI AGENT │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Perceive│ → │ Plan │ → │ Act │ → │ Learn │ │ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ ↑ │ │ │ └──────────────────────────────────────────┘ │ │ Feedback Loop │ └─────────────────────────────────────────────────────────────┘ ``` **Core Components:** - **Perception**: Receive and interpret inputs (user requests, environment state) - **Planning**: Reason about goals, decompose tasks, select actions - **Action**: Execute tools, API calls, or generate outputs - **Learning**: Update memory, refine strategies based on outcomes ### Agent vs. Chatbot vs. Workflow | Aspect | Chatbot | Workflow | Agent | |--------|---------|----------|-------| | Autonomy | Low | None | High | | Planning | None | Predefined | Dynamic | | Tool Use | Limited | Fixed sequence | Flexible | | Memory | Session only | None | Persistent | | Error Recovery | Retry/fail | Fail | Reason & adapt | --- ## Single-Agent Patterns ### ReAct Pattern (Reasoning + Acting) The foundation of most modern agents: ```text ┌──────────────────────────────────────────┐ │ ReAct Loop │ ├──────────────────────────────────────────┤ │ 1. Thought: Reason about the task │ │ 2. Action: Choose and execute a tool │ │ 3. Observation: Process tool output │ │ 4. Repeat until task complete │ └──────────────────────────────────────────┘ ``` **Example Trace:** ```text User: What's the weather in Seattle and should I bring an umbrella? Thought: I need to check Seattle weather to answer this question. Action: weather_api(location="Seattle, WA") Observation: {"temp": 52, "condition": "rain", "precipitation": 80%} Thought: It's raining with 80% precipitation chance. User should bring umbrella. Action: respond("It's 52°F and raining in Seattle with 80% chance of precipitation. Yes, definitely bring an umbrella!") ``` ### Plan-and-Execute Pattern For complex, multi-step tasks: ```text ┌─────────────────────────────────────────────────────────────┐ │ Plan-and-Execute │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ │ │ │ Planner │ Create high-level plan │ │ └──────┬──────┘ │ │ ↓ │ │ ┌─────────────┐ │ │ │ Executor │ Execute each step │ │ └──────┬──────┘ │ │ ↓ │ │ ┌─────────────┐ │ │ │ Replanner │ Adjust plan based on results │ │ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **When to Use:** - Tasks requiring multiple distinct phases - When order of operations matters - When partial failures need recovery ### Reflexion Pattern Self-improvement through reflection: ```text ┌─────────────────────────────────────────────────────────────┐ │ Reflexion │ ├─────────────────────────────────────────────────────────────┤ │ 1. Attempt task │ │ 2. Evaluate outcome (success/failure) │ │ 3. Generate reflection on what went wrong │ │ 4. Store reflection in memory │ │ 5. Retry with reflection context │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Multi-Agent Patterns ### Supervisor Pattern Central coordinator delegates to specialized agents: ```text ┌─────────────────────────────────────────────────────────────┐ │ │ │ ┌────────────┐ │ │ │ Supervisor │ │ │ └─────┬──────┘ │ │ ┌─────────────┼─────────────┐ │ │ ↓ ↓ ↓ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Research │ │ Writer │ │ Reviewer │ │ │ │ Agent │ │ Agent │ │ Agent │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` **Use Cases:** - Content creation pipelines - Research + analysis + reporting - Code generation + review + testing ### Hierarchical Teams Nested supervisor structure for complex organizations: ```text ┌─────────────────────────────────────────────────────────────┐ │ Top Supervisor │ │ ┌─────────────┴─────────────┐ │ │ ↓ ↓ │ │ ┌───────────────┐ ┌───────────────┐ │ │ │ Research Lead │ │ Writing Lead │ │ │ └───────┬───────┘ └───────┬───────┘ │ │ ┌────┴────┐ ┌────┴────┐ │ │ ↓ ↓ ↓ ↓ │ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │ │ │Web │ │Paper │ │Draft │ │Edit │ │ │ │Search │ │Review │ │Writer │ │Writer │ │ │ └───────┘ └───────┘ └───────┘ └───────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### Debate/Adversarial Pattern Multiple agents argue to reach better conclusions: ```text ┌─────────────────────────────────────────────────────────────┐ │ │ │ ┌──────────┐ Argue ┌──────────┐ │ │ │ Agent A │ ◄──────────────► │ Agent B │ │ │ │ (Pro) │ │ (Con) │ │ │ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ └──────────┬──────────────────┘ │ │ ↓ │ │ ┌────────────┐ │ │ │ Judge │ Synthesize best answer │ │ └────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` **Benefits:** - Reduces hallucination through verification - Explores multiple perspectives - Better reasoning on complex questions --- ## Tool Use Patterns ### Tool Definition Best Practices ```json { "name": "search_database", "description": "Search the product database. Returns matching products with prices. Use when user asks about product availability or pricing.", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "Search terms (product name, category, or SKU)" }, "max_results": { "type": "integer", "default": 10, "description": "Maximum results to return (1-100)" }, "filters": { "type": "object", "properties": { "min_price": { "type": "number" }, "max_price": { "type": "number" }, "in_stock": { "type": "boolean" } } } }, "required": ["query"] } } ``` **Tool Design Principles:** 1. **Clear names**: Verb + noun (search_database, send_email) 2. **Rich descriptions**: Include when to use and what it returns 3. **Constrained parameters**: Enums, ranges, validation 4. **Sensible defaults**: Reduce required decisions 5. **Error handling**: Return structured errors, not exceptions ### Tool Selection Strategies | Strategy | Description | When to Use | |----------|-------------|-------------| | Direct | LLM chooses from all tools | < 10 tools | | Categorized | Group tools, select category first | 10-50 tools | | Retrieval | Embed tool descriptions, retrieve relevant | 50+ tools | | Routing | Specialized selector model | Production scale | ### Human-in-the-Loop Tools ```text ┌─────────────────────────────────────────────────────────────┐ │ Human-in-the-Loop Pattern │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Agent Action Request │ │ │ │ │ ↓ │ │ ┌───────────────┐ │ │ │ Risk Check │ │ │ └───────┬───────┘ │ │ │ │ │ Low ──┴── High │ │ │ │ │ │ ↓ ↓ │ │ Execute ┌──────────┐ │ │ Directly │ Human │ │ │ │ Approval │ │ │ └────┬─────┘ │ │ │ │ │ Approve/Reject/Modify │ │ │ └─────────────────────────────────────────────────────────────┘ ``` **High-Risk Actions Requiring Approval:** - Financial transactions - Data deletion - External communications - Permission changes - Irreversible operations --- ## Agent Memory Systems ### Memory Architecture ```text ┌─────────────────────────────────────────────────────────────┐ │ Agent Memory │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Working Memory │ │ │ │ Current conversation + recent context (in prompt) │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Short-Term Memory │ │ │ │ Session state, intermediate results (key-value) │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Long-Term Memory │ │ │ │ Facts, preferences, history (vector DB + graph) │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### Memory Types | Type | Storage | Retrieval | Use Case | |------|---------|-----------|----------| | Episodic | Vector DB | Semantic search | Past conversations, experiences | | Semantic | Graph DB | Structured query | Facts, relationships, knowledge | | Procedural | Code/prompts | Direct lookup | How to perform tasks | | Working | Prompt context | Always present | Current task state | ### Memory Management Patterns **Summarization**: Compress old conversations ```text Full History → Summarize → Store Summary → Discard Full ``` **Forgetting**: Remove low-value memories ```text Memories → Score by (recency × importance × access_count) → Prune lowest ``` **Consolidation**: Merge related memories ```text Similar Memories → Cluster → Create consolidated memory → Archive originals ``` --- ## Planning Strategies ### Task Decomposition ```text Complex Task: "Build a marketing campaign for our new product" │ ┌───────────────┼───────────────┐ ↓ ↓ ↓ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Research │ │ Content │ │ Launch │ │ Phase │ │ Phase │ │ Phase │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ ┌──────┴──────┐ ┌───┴───┐ ┌───┴───┐ ↓ ↓ ↓ ↓ ↓ ↓ Analyze Survey Create Write Schedule Monitor Competitors Users Assets Copy Posts Results ``` ### Goal-Oriented Planning ```text Current State: No marketing campaign Goal State: Campaign live with 10K impressions │ ↓ ┌─────────────────────┐ │ Gap Analysis │ │ What's missing? │ └──────────┬──────────┘ ↓ ┌─────────────────────┐ │ Action Generation │ │ What can close gap? │ └──────────┬──────────┘ ↓ ┌─────────────────────┐ │ Action Selection │ │ Best next step? │ └─────────────────────┘ ``` --- ## Error Handling & Recovery ### Graceful Degradation ```text ┌─────────────────────────────────────────────────────────────┐ │ Error Recovery Ladder │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Level 1: Retry │ │ └── Same action, maybe with backoff │ │ │ │ Level 2: Rephrase │ │ └── Reformulate the action (different query) │ │ │ │ Level 3: Alternative │ │ └── Use different tool for same goal │ │ │ │ Level 4: Partial │ │ └── Return partial results, note limitations │ │ │ │ Level 5: Escalate │ │ └── Ask human for help │ │ │ │ Level 6: Abort │ │ └── Cannot complete, explain why │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### Loop Detection Agents can get stuck. Detect and break loops: ```python def detect_loop(action_history, window=5, threshold=0.8): """Detect if agent is repeating similar actions.""" if len(action_history) < window * 2: return False recent = action_history[-window:] previous = action_history[-window*2:-window] # Compare action patterns similarity = calculate_similarity(recent, previous) return similarity > threshold ``` **Recovery Actions:** - Inject reflection prompt: "You seem to be repeating. What's different now?" - Force tool change: Exclude recently used tools - Replan: Discard current plan, start fresh - Escalate: Ask user for clarification --- ## Production Considerations ### Observability **What to Log:** - Every LLM call (prompt, completion, tokens, latency) - Tool calls (name, parameters, result, duration) - State transitions (plan changes, memory updates) - Errors and recovery attempts **Trace Structure:** ```text Trace: user_request_abc123 ├── parse_intent (50ms) ├── plan_generation (200ms) ├── step_1_research │ ├── tool_call: search_web (150ms) │ └── tool_call: summarize (100ms) ├── step_2_write │ └── llm_call: generate_draft (300ms) └── step_3_review └── llm_call: critique (200ms) ``` ### Cost Control | Strategy | Implementation | |----------|----------------| | Token budgets | Set max tokens per task | | Step limits | Maximum N actions per request | | Tiered models | GPT-4 for planning, GPT-3.5 for execution | | Caching | Cache tool results, LLM responses | | Early termination | Stop when "good enough" | ### Safety Guardrails ```text ┌─────────────────────────────────────────────────────────────┐ │ Safety Layer │ ├─────────────────────────────────────────────────────────────┤ │ │ │ Input Validation │ │ ├── Prompt injection detection │ │ ├── PII/sensitive data filtering │ │ └── Request rate limiting │ │ │ │ Action Validation │ │ ├── Tool parameter sanitization │ │ ├── Scope/permission checks │ │ └── Dangerous action blocking │ │ │ │ Output Validation │ │ ├── Content policy compliance │ │ ├── Hallucination detection │ │ └── Sensitive data redaction │ │ │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Framework Comparison | Framework | Strengths | Best For | |-----------|-----------|----------| | LangChain | Comprehensive, many integrations | Rapid prototyping | | LangGraph | Stateful, graph-based flows | Complex multi-agent | | AutoGen | Multi-agent conversations | Research, code gen | | CrewAI | Role-based teams | Business workflows | | Semantic Kernel | Enterprise, .NET/Python | Microsoft stack | | Agents SDK (OpenAI) | Simple, hosted | Quick single-agent | --- ## Anti-Patterns ### ❌ Over-Autonomous Agent **Problem**: Agent makes too many decisions without checkpoints **Solution**: Add approval gates for significant actions ### ❌ Unbounded Loops **Problem**: No termination conditions **Solution**: Set max iterations, cost limits, time bounds ### ❌ Tool Explosion **Problem**: Too many tools confuse the agent **Solution**: Curate tools, use retrieval for large toolsets ### ❌ Memory Bloat **Problem**: Accumulating context without pruning **Solution**: Summarize, forget, consolidate ### ❌ Monolithic Agent **Problem**: One agent does everything **Solution**: Decompose into specialized sub-agents --- ## Activation Triggers - "agent", "autonomous", "multi-agent" - "tool use", "function calling" - "ReAct", "plan and execute" - "agent memory", "agent planning" - "orchestration", "supervisor agent" - "LangChain", "LangGraph", "AutoGen", "CrewAI" --- ## Quick Reference ### Agent Design Checklist - [ ] Define clear agent persona and capabilities - [ ] Design minimal, well-described tool set - [ ] Implement appropriate memory architecture - [ ] Add human-in-the-loop for high-risk actions - [ ] Set up observability (logging, tracing) - [ ] Configure safety guardrails - [ ] Test with adversarial inputs - [ ] Plan for cost control and scaling ### When to Use Agents ✅ **Good Fit:** - Open-ended research tasks - Multi-step workflows with decisions - Tasks requiring tool orchestration - Personalized, context-aware interactions ❌ **Poor Fit:** - Simple Q&A (use RAG) - Deterministic workflows (use code) - High-stakes with no human oversight - Real-time, latency-critical applications --- *AI Agent Design skill — Building autonomous, reliable AI systems* --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/fabioc-aloha) — claim your Tome and manage your conversions.