Agent Development

Overview

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

Agent Architecture Decision Table

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

Tool Use Patterns

Tool Definition Best Practices

search_documents

create_file

query: string // "e.g., 'user authentication'"

{ success, data, error }

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

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

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

Multi-Agent Coordination

Coordination Pattern Decision Table

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

Evaluation Dataset Structure

{
  "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 logging for all actions

Circuit Breaker Thresholds

Prompt Engineering for Agents

System Prompt Structure

1. Identity and purpose (who the agent is)
2. Available tools (what it can do)
3. Constraints (what it must not do)
4. Output format (how to respond)
5. Examples (few-shot demonstrations)
6. Error handling (what to do when stuck)

Key Prompt Patterns

• Scratchpad: encourage step-by-step reasoning before action
• Self-correction: "If your first approach fails, try..."
• Confidence calibration: "Only proceed if you are confident"
• Graceful degradation: "If you cannot complete the task, explain why"

Anti-Patterns / Common Mistakes

Integration Points

mcp-builder

planning

autonomous-loop

dispatching-parallel-agents

circuit-breaker

verification-before-completion

test-driven-development

Skill Type