agent-development

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: agent-development
description: >
  Use when the user needs to build AI agents — tool use patterns, memory management, planning strategies,
  multi-agent coordination, evaluation, and safety guardrails. Triggers: user says "agent", "build an agent",
  "tool use", "agent loop", "multi-agent", "memory management", "guardrails", "agent evaluation".
---

# 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