agent-development

What this skill does

# Agent Development

## Overview

Design and build AI agents that effectively use tools, manage memory, plan multi-step tasks, coordinate with other agents, and operate within safety guardrails. This skill covers the full agent development lifecycle from architecture through evaluation, with emphasis on observable, testable, and safe agent behavior.

## Phase 1: Agent Design

1. Define the agent's purpose and scope
2. Identify required tools and capabilities
3. Design memory architecture (short-term, long-term)
4. Plan agent loop structure (observe, think, act)
5. Define safety boundaries and guardrails

**STOP — Present agent design to user for approval before implementation.**

### Agent Architecture Decision Table

| Agent Type | When to Use | Loop Pattern | Complexity |
|---|---|---|---|
| Single-turn tool user | Simple queries with tool calls | Request -> Tool -> Response | Low |
| ReAct agent | Multi-step reasoning tasks | Thought -> Action -> Observation -> loop | Medium |
| Plan-and-execute | Complex tasks with dependencies | Plan -> Execute steps -> Validate | Medium-High |
| Multi-agent orchestrator | Parallel/specialized sub-tasks | Dispatch -> Collect -> Synthesize | High |
| Autonomous loop (Ralph-style) | Long-running iterative development | Plan -> Build -> Verify -> Exit gate | High |

## Phase 2: Implementation

1. Build the agent loop with tool dispatch
2. Implement memory management (context window, persistence)
3. Add planning and decomposition logic
4. Integrate error recovery and retry patterns
5. Implement output validation

**STOP — Run smoke tests on the agent loop before adding complexity.**

### Tool Use Patterns

#### Tool Definition Best Practices

| Principle | Rule | Example |
|---|---|---|
| Clear naming | verb-noun format | `search_documents`, `create_file` |
| Detailed descriptions | Include when to use AND when NOT to use | "Use for keyword search. Do NOT use for semantic similarity." |
| Well-typed parameters | Descriptions and examples on every param | `query: string // "e.g., 'user authentication'"` |
| Predictable returns | Consistent format across tools | Always return `{ success, data, error }` |
| Self-correcting errors | Help agent recover | "Invalid date format. Expected ISO 8601: YYYY-MM-DD" |

#### Tool Selection Strategy

```
Given a task:
1. Identify required information and actions
2. Map to available tools
3. Determine tool call order (dependencies)
4. Execute with result validation
5. Retry or try alternative tool on failure
```

#### Tool Design Principles

- **Composable**: small tools that combine for complex tasks
- **Idempotent**: safe to retry without side effects (where possible)
- **Observable**: return enough context for the agent to verify success
- **Bounded**: timeouts and size limits on all operations
- **Documented**: every parameter and return value described

### Memory Management

#### Memory Type Decision Table

| Type | Duration | Storage | Use Case |
|---|---|---|---|
| Working Memory | Current turn | Context window | Active reasoning |
| Short-term Memory | Current session | In-context or buffer | Recent conversation |
| Long-term Memory | Across sessions | Database/file | Learned patterns, user prefs |
| Episodic Memory | Specific events | Indexed store | Past task outcomes |
| Semantic Memory | Knowledge | Vector DB | Domain knowledge retrieval |

#### Context Window Management

```
Strategy: Sliding window with importance-based retention

1. Always retain: system prompt, tool definitions, current task
2. Summarize: older conversation turns into compressed summaries
3. Evict: least relevant context when approaching limit
4. Retrieve: pull relevant long-term memory on demand

Budget allocation:
  System prompt + tools: ~20%
  Current task context:  ~40%
  Conversation history:  ~25%
  Retrieved memory:      ~15%
```

#### Memory Update Triggers

| Trigger | Action |
|---|---|
| User correction | Update learned patterns |
| Task completion | Store outcome and approach |
| Error recovery | Record what failed and what worked |
| New domain knowledge | Index for future retrieval |

### Planning Strategies

#### Hierarchical Task Decomposition

```
1. Break high-level goal into sub-goals
2. For each sub-goal, identify required actions
3. Order actions by dependencies
4. Execute with checkpoints between phases
5. Re-plan if intermediate results change the approach
```

#### ReAct Pattern (Reason + Act)

```
Thought: I need to find the user's recent orders to answer their question.
Action: search_orders(user_id="123", limit=5)
Observation: Found 5 orders, most recent is #456 from yesterday.
Thought: The user asked about order #456. I have the details now.
Action: respond with order details
```

#### Plan-and-Execute Pattern

```
1. Create a complete plan before any action
2. Execute each step, checking preconditions
3. After each step, validate the result
4. If a step fails, re-plan from current state
5. Never modify the plan mid-step (finish or abort first)
```

#### Reflection Pattern

```
After completing a task:
1. Was the result correct?
2. Was the approach efficient?
3. What could be improved?
4. Should any memory be updated?
```

## Phase 3: Evaluation and Safety

1. Build evaluation harness with test scenarios
2. Measure accuracy, efficiency, and safety metrics
3. Test edge cases and adversarial inputs
4. Add monitoring and logging
5. Implement circuit breakers for runaway behavior

**STOP — All safety guardrails must be tested before deployment.**

### Multi-Agent Coordination

#### Coordination Pattern Decision Table

| Pattern | Description | Use When |
|---|---|---|
| Orchestrator | Central agent delegates to specialists | Clear task hierarchy |
| Pipeline | Agents process in sequence | Linear workflows |
| Debate | Agents propose and critique | Need diverse perspectives |
| Voting | Multiple agents, majority wins | Uncertainty in approach |
| Supervisor | One agent monitors others | Safety-critical tasks |

#### Communication Protocol

```
Agent-to-Agent message:
{
  "from": "planner",
  "to": "executor",
  "type": "task_assignment",
  "content": { "task": "...", "context": "...", "constraints": "..." },
  "priority": "high",
  "deadline": "2025-01-15T10:00:00Z"
}
```

#### Coordination Rules

- Define clear ownership boundaries
- Use structured messages between agents
- Implement deadlock detection
- Set timeouts for inter-agent communication
- Log all inter-agent messages for debugging

### Evaluation Framework

#### Metrics Decision Table

| Metric | What It Measures | How to Measure | Target |
|---|---|---|---|
| Task Success Rate | Correct completions / total | Automated + human eval | > 90% |
| Efficiency | Steps vs optimal path | Step count comparison | < 2x optimal |
| Tool Accuracy | Correct tool calls / total | Log analysis | > 95% |
| Safety | Violations / total interactions | Guardrail checks | 0 violations |
| Latency | Time to complete task | Wall clock | < SLA |
| Cost | Token usage per task | API usage tracking | Within budget |

#### Evaluation Dataset Structure

```json
{
  "test_cases": [
    {
      "id": "tc_001",
      "input": "Find all orders over $100 from last week",
      "expected_tools": ["search_orders"],
      "expected_output_contains": ["order_id", "amount"],
      "category": "retrieval",
      "difficulty": "easy"
    }
  ]
}
```

### Safety Guardrails

#### Input Guardrails

- Detect and reject prompt injection attempts
- Validate all user inputs before processing
- Rate limit requests per user/session
- Content filtering for harmful requests

#### Output Guardrails

- Validate tool call arguments before execution
- Check outputs for sensitive information (PII, secrets)
- Enforce response format constraints
- Prevent infinite tool call loops

#### Operational Guardrails

- Maximum tool calls per task (circuit breaker)
- Maximum tokens per response
- Timeout for total task duration
- Escalation to human when confidence is low
- Audit l