Agent Design Fundamentals

# Agent Design Fundamentals

## Core Components
| Component | Responsibility | Example |
|-----------|----------------|---------|
| Perception | Normalize/parse inputs | User text → structured intent |
| Planning | Break goal into steps | High-level plan tree |
| Memory | Persist relevant info | Conversation history store |
| Tooling | Extend capabilities | Web search, DB query |
| Reasoning | Infer intermediate states | Hypothesize missing facts |
| Action Execution | Perform step | Call API, write file |
| Evaluation | Score outputs | JSON validity, factuality |
| Governance | Enforce policies | Output filter, rate limiter |

## Control Loop Pseudocode
```
while not goal_reached and iterations < max_iters:
    observe_state()
    plan = planner.decide(next_goal)
    if plan.requires_tool:
        tool_result = tool_executor.execute(plan.tool, plan.args)
    reasoning = reasoner.reflect(plan, tool_result)
    updated_state = state_updater.apply(tool_result, reasoning)
    if governance.blocked(updated_state):
        escalate_or_abort()
```

## Autonomy Levels
1. Scripted sequence
2. Tool suggestions (human approve)
3. Semi-autonomous loops (bounded iterations)
4. Fully autonomous with guardrails & budget caps

## Memory Strategy
| Type | Lifetime | Storage |
|------|----------|---------|
| Working | Single loop | In-prompt tokens |
| Short-term | Session | Redis / in-memory buffer |
| Long-term | Persistent | Vector store + metadata |

## Safety Considerations
- Explicit tool allowlist
- Hard iteration cap
- Cost/time budget enforcement
- Output classification (toxicity / PII)

## Design Anti-Patterns
| Anti-Pattern | Why Harmful | Alternative |
|--------------|------------|------------|
| Monolithic giant prompt | Unmaintainable, costly | Layered modular prompts |
| No evaluation loop | Stagnant quality | Golden set regression eval |
| Blind tool execution | Security risk | Validate tool schema & intent |
| Infinite loops | Resource drain | Iteration + timeout cap |

## Extensibility Tips
- Use registries for tools & skills
- Keep data schemas explicit (Pydantic or dataclasses)
- Centralize model client selection

## Minimal File Layout Example
```
src/
  agents/base.py
  llm/clients.py
  prompt/templating.py
  tools/registry.py
  eval/metrics.py
```