aiase-agent-fundamentals

name	aiase-agent-fundamentals
description	Agent architecture fundamentals — ReAct pattern, 4-element agent model, 5 sophistication levels, tool schema design, HITL risk matrix, 4-layer error handling, observability (traces/metrics/logs), framework selection, and deployment models. Load when the user asks about building agents, tool design, agent observability, ReAct, HITL, or agent frameworks.

Agent Architecture Fundamentals

From AIASE 2026 (NCKU), Week 3. The foundations before adding multi-agent complexity.

The 4-Element Agent Model

Perception (input)
    ↓
Memory (storage/retrieval)
    ↓
Reasoning (thought process)
    ↓
Action (tool execution)
    ↓
[Feedback loop back to Perception]

Design each layer independently. Garbage perception → garbage reasoning. Weak memory → lost context. Poor action schema → failed execution.

Five Agent Sophistication Levels

Level	Tool Type	Human Role	Example
1	IDE autocomplete	Writer	Copilot inline
2	Chat interface	Asker	Claude.ai
3	Supervised agent	Monitor	Cursor Agent Mode
4	Autonomous agent	Reviewer	Claude Code CLI
5	Self-improving agent	Strategist	(Research phase)

Target: Level 4 — agent autonomously plans and executes; human reviews, not approves every step.

ReAct Pattern (Reason + Act)

Thought: [What is my next step and why?]
Action: [Call tool / invoke function]
Observation: [Parse result]
→ Loop until success or max_steps reached

This is the backbone of most production agents. Master it before adding complexity.

Common failure modes:

• Tool hallucination — agent invents calls to tools that don't exist
• Circular reasoning — agent repeats same tool call, same result
• Goal drift — agent loses track of original objective mid-execution

Tool Schema Design

Bad schema (causes wrong tool selection):

{"name": "search", "parameters": {"query": {"type": "string"}}}

Good schema (guides correct selection):

{
  "name": "search_internal_docs",
  "description": "Search company tech docs. Use for: API specs, architecture. Don't use for: external searches (use web_search). Returns: max 5 docs with source links.",
  "parameters": {
    "query": {
      "type": "string",
      "description": "Supports AND/OR/NOT syntax"
    },
    "top_k": {"type": "integer", "default": 5, "minimum": 1, "maximum": 10}
  },
  "required": ["query"]
}

Key principle: Include when NOT to use a tool. This dramatically improves tool selection accuracy.

HITL (Human-in-the-Loop) Risk Matrix

Risk Level	Examples	Action
Low	read, search, query	Execute automatically
Medium	write, notify, API call	Recommend + confirm
High	delete, transfer, $$ spend	Require explicit approval

Least Privilege Principle:

• File system: Restrict read/write to specific directories
• Database: Separate read/write credentials
• APIs: Rate limits + whitelisted endpoints only
• Code execution: Always sandbox (Docker, VMs)

4-Layer Error Handling

1. Input Guardrails — format validation, injection detection, content filtering
2. Execution Retry — exponential backoff, circuit breaker, fallback tools
3. Output Guardrails — format validation, PII masking, safety checks
4. Human Escalation — automatic incident notification on critical failure

Observability: Three Pillars

Traces

Trace ID: task_001
├─ Span: agent.think [450ms, 1024 tokens]
├─ Span: tool.web_search [1200ms]
│   └─ Result: 5 docs retrieved
└─ Span: agent.respond [200ms, 256 tokens]

Metrics (alert thresholds)

Metric	Alert Threshold
P95 response time	> 30s
Token usage	> 80% of budget
Task success rate	< 90%
Tool call count per task	> 50 (infinite loop risk)
Retry rate	> 20% (API instability)

Logs (structured, queryable)

{
  "timestamp": "2026-03-11T10:30:00Z",
  "trace_id": "task_001",
  "event": "tool_call",
  "tool": "search",
  "status": "success",
  "duration_ms": 1200
}

"If you can't observe it, you can't maintain it. Observability is engineering requirement #1."

Recommended tools: Langfuse (open source), Helicone (proxy-based), LangSmith (LangChain).

Framework Selection

Need fast MVP?
├─ YES → CrewAI or Dify (low code)
└─ NO → ↓

Need complex workflows (branches, loops)?
├─ YES → LangGraph
└─ NO → ↓

Need multi-agent debate / code generation?
├─ YES → AutoGen
└─ NO → Pure SDK (maximum control, highest effort)

Red flag: Choosing framework first, then shoehorning the problem to fit. Choose based on constraints, not hype.

Deployment Models

Model	Duration	Tech	When to Use
Serverless	<30s	Lambda/Vercel	Simple, infrequent tasks
Container	Minutes–hours	Docker+K8s	Stateful, complex agents
Queue	Async	Redis/SQS	Reliable long-running tasks

Production reality: Most serious agents use containers or queues — agent execution routinely exceeds 30 seconds.

Incremental Build Order (Snowball Pattern)

Week 1: Single agent + 1 tool (verify basic tool calling works)
Week 2: Agent + 3 tools (verify tool selection logic)
Week 3: Add ReAct loop (verify multi-step reasoning)
Week 4: Add memory (verify state persistence)
Week 5: Add Reflection (verify self-critique)
Week 6: Decompose to Multi-Agent (ONLY after single agent is proven reliable)

Each step is independently verifiable with evals. Never skip steps — "why is it broken?" chaos comes from building everything at once.

System Prompt as Architectural Spec

# Role
[What this agent can and cannot do]

# Goal
[Success metric — make it measurable]

# Constraints
[What's forbidden, safety guardrails]

# Output Format
[Exact structure — testable spec]

Anti-Patterns

Layer	Failure	Prevention
Reasoning	Goal drift mid-execution	Explicit goal state in every step
Tool	Non-reversible action before confirmation	HITL medium/high risk gates
Process	Infinite loop (no exit condition)	max_steps + circuit breaker
Resource	Context overflow	Monitor token usage; compact at 40%
Resource	Rate limiting	Exponential backoff + retry budget

---

See also: [[aiase-multi-agent]] for scaling beyond single agent, [[aiase-harness]] for production harness setup, [[aiase-token-economics]] for cost/observability tooling.