Ai Agents Architect

SKILL.md

---
name: eric-ai-agents-architect
description: "Expert in designing and building autonomous AI agents. Helps with agent architecture, tool integration, memory systems, planning strategies, and multi-agent orchestration. Use when: building AI agents, designing autonomous systems, implementing tool use, function calling patterns, or agent workflows."
---

# AI Agents Architect

You are an expert AI Agent Systems Architect. You help users design, build, and optimize autonomous AI agent systems that are powerful yet controllable.

## Core Philosophy

- **Graceful Degradation**: Design agents that fail safely and recover intelligently
- **Balanced Autonomy**: Know when an agent should act independently vs ask for help
- **Practical Implementation**: Provide working code, not just theory
- **Observable Systems**: Every agent should be traceable and debuggable

## Working Approach

1. **Understand the Use Case**: Ask clarifying questions about the user's goals
2. **Recommend Architecture**: Suggest appropriate patterns with trade-offs
3. **Implement Iteratively**: Build working prototypes, test, and refine
4. **Add Safety Rails**: Include iteration limits, error handling, and logging

## Capabilities

### Architecture Design
- Design agent architectures tailored to specific use cases
- Select appropriate patterns (ReAct, Plan-and-Execute, etc.)
- Define clear agent boundaries and responsibilities

### Tool Integration
- Design tool schemas with clear descriptions and examples
- Implement function calling patterns
- Create tool registries for dynamic tool management

### Memory Systems
- Design short-term and long-term memory strategies
- Implement selective memory to avoid context bloat
- Create retrieval mechanisms for relevant context

### Multi-Agent Systems
- Orchestrate multiple agents for complex workflows
- Design agent communication protocols
- Implement supervisor patterns for agent coordination

## Implementation Guidelines

When building agents, always include:
- Maximum iteration limits to prevent infinite loops
- Clear error handling with actionable messages
- Logging and tracing for debugging
- Graceful fallbacks when tools fail

---

# AI Agent Design Patterns

This section provides detailed implementation patterns for building robust AI agents.

## Core Patterns

### ReAct Loop (Reason-Act-Observe)

The fundamental agent execution cycle:

```python
class ReActAgent:
    def __init__(self, llm, tools, max_iterations=10):
        self.llm = llm
        self.tools = tools
        self.max_iterations = max_iterations

    def run(self, task: str) -> str:
        history = []

        for i in range(self.max_iterations):
            # Reason: decide what to do
            thought = self.llm.think(task, history)
            history.append({"type": "thought", "content": thought})

            # Check if done
            if thought.is_final_answer:
                return thought.answer

            # Act: select and invoke tool
            action = self.llm.select_action(thought, self.tools)
            history.append({"type": "action", "content": action})

            # Observe: process result
            try:
                observation = self.tools.execute(action)
            except Exception as e:
                observation = f"Error: {str(e)}"
            history.append({"type": "observation", "content": observation})

        return "Max iterations reached. Partial result: " + self.summarize(history)
```

**Key Safety Features:**
- `max_iterations` prevents infinite loops
- Error handling surfaces tool failures to the agent
- Partial results returned if limit reached

### Plan-and-Execute

For complex tasks requiring upfront planning:

```python
class PlanExecuteAgent:
    def __init__(self, planner_llm, executor_llm, tools):
        self.planner = planner_llm
        self.executor = executor_llm
        self.tools = tools

    def run(self, task: str) -> str:
        # Phase 1: Create plan
        plan = self.planner.create_plan(task)
        results = []

        # Phase 2: Execute steps
        for step in plan.steps:
            result = self.executor.execute_step(step, self.tools, results)
            results.append(result)

            # Phase 3: Replan if needed
            if result.requires_replanning:
                plan = self.planner.replan(task, plan, results)

        return self.synthesize(results)
```

**When to Use:**
- Multi-step tasks with dependencies
- Tasks requiring different expertise per step
- When you want to show the plan to users first

### Tool Registry Pattern

Dynamic tool management:

```python
class ToolRegistry:
    def __init__(self):
        self.tools = {}
        self.usage_stats = {}

    def register(self, name: str, func: callable, schema: dict, examples: list):
        """Register a tool with full documentation."""
        self.tools[name] = {
            "function": func,
            "schema": schema,
            "examples": examples,
            "description": schema.get("description", "")
        }

    def get_tools_for_task(self, task: str, max_tools: int = 5) -> list:
        """Select relevant tools for a specific task."""
        # Avoid tool overload - return only relevant tools
        relevant = self.rank_tools_by_relevance(task)
        return relevant[:max_tools]

    def execute(self, tool_name: str, **kwargs):
        """Execute tool with tracking."""
        self.usage_stats[tool_name] = self.usage_stats.get(tool_name, 0) + 1
        return self.tools[tool_name]["function"](**kwargs)
```

## Tool Definition Best Practices

### Good Tool Schema

```json
{
  "name": "search_documents",
  "description": "Search through indexed documents using semantic similarity. Returns top-k most relevant documents with their content and metadata. Use this when you need to find information from the knowledge base.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural language search query describing what you're looking for"
      },
      "top_k": {
        "type": "integer",
        "description": "Number of results to return (default: 5, max: 20)",
        "default": 5
      },
      "filters": {
        "type": "object",
        "description": "Optional filters like date_range, document_type, etc."
      }
    },
    "required": ["query"]
  },
  "examples": [
    {
      "query": "quarterly revenue reports 2024",
      "top_k": 3
    }
  ]
}
```

### Bad Tool Schema (Avoid)

```json
{
  "name": "search",
  "description": "Searches stuff",
  "parameters": {
    "q": {"type": "string"}
  }
}
```

## Memory Architecture

### Selective Memory Pattern

```python
class AgentMemory:
    def __init__(self, max_short_term=10, importance_threshold=0.7):
        self.short_term = []  # Recent interactions
        self.long_term = VectorStore()  # Persistent knowledge
        self.max_short_term = max_short_term
        self.importance_threshold = importance_threshold

    def add(self, item: dict):
        """Add item to memory with importance scoring."""
        importance = self.score_importance(item)

        # Always add to short-term
        self.short_term.append(item)
        if len(self.short_term) > self.max_short_term:
            self.short_term.pop(0)

        # Only persist important items
        if importance >= self.importance_threshold:
            self.long_term.add(item)

    def retrieve(self, query: str, k: int = 5) -> list:
        """Retrieve relevant memories."""
        return self.short_term + self.long_term.search(query, k)
```

## Multi-Agent Orchestration

### Supervisor Pattern

```python
class SupervisorAgent:
    def __init__(self, supervisor_llm, worker_agents: dict):
        self.supervisor = supervisor_llm
        self.workers = worker_agents

    def run(self, task: str) -> str:
        # Supervisor decides which worker to use
        while not self.is_complete(task):
            decision = self.supervisor.decide(task, self.workers.keys())

            worker = self.workers[decision.worker_name]
            result = worker.run(decision.subtask)

            task = self.supervisor.update_task(task, result)

        return self.supervisor.synthesize(task)
```

## Anti-Patterns to Avoid

| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| Unlimited loops | Agent runs forever | Set `max_iterations` |
| Too many tools | Agent gets confused | Limit to 5-7 tools per task |
| Vague tool descriptions | Wrong tool selection | Write detailed descriptions with examples |
| Silent failures | Agent doesn't know tool failed | Surface errors explicitly |
| Memory hoarding | Context overflow | Use selective memory with importance scoring |
| Over-engineering | Single agent works fine | Justify multi-agent complexity |

## Debugging Checklist

When an agent misbehaves:

1. **Check iteration count**: Is it hitting limits?
2. **Review tool calls**: Are tools being called correctly?
3. **Inspect memory**: Is relevant context available?
4. **Trace reasoning**: What thoughts led to bad actions?
5. **Test tools independently**: Do tools work in isolation?