ai-agent-architectures

AI Agent Architectures

Purpose

Design a single LLM agent end to end: the control loop, the tool surface, memory, planning strategy, guardrails, and how it is evaluated. This parent skill makes the top-level decisions and hands detail to its children: core-architectures (loop mechanics), tool-calling-principles (tool contracts), memory-systems (state and recall), and multi-agent-topology (when one agent is not enough).

Agent Protocol

Trigger

"build an agent", "agent architecture", "autonomous agent", "agent design review", "agent framework choice", "agent system prompt".

Input Context

• Task domain, success criteria, and expected task length (steps, minutes).
• Tools/APIs available and their side effects.
• Model/provider constraints, latency and cost budget.
• Data the agent must remember across turns or sessions.
• Risk profile: what is the worst action the agent could take?

Output Artifact

Architecture brief: component table, loop diagram (Mermaid sequence), tool list with schemas, memory plan, guardrails, eval plan.

Response Format

Loop: {react|plan-execute|workflow}  Model: {tier}  Max steps: {n}
Tools ({count}; split past ~10-15 or on eval evidence): {name: side-effect level}
Memory: working={strategy} | long-term={store} | episodic={yes/no}
Guardrails: {input, output, action approvals}
Eval: {dataset, metric, pass threshold}
Children to consult: {skill paths}

Completion Criteria

• Each component (loop, tools, memory, planning, guardrails, eval) has an explicit decision.
• Small, cohesive toolset per agent; split only when evals show tool or domain confusion (repo heuristic: ~10-15 tools).
• Destructive tools have human approval or dry-run.
• Eval dataset exists before prompt iteration starts.

Component Map

Component	Decision	Default	Child skill
Control loop	ReAct vs plan-and-execute vs fixed workflow	Fixed workflow if steps known	core-architectures, ../agentic-workflows
Tools	Granularity, schemas, error contract	Few coarse tools with strict schemas	tool-calling-principles
Working memory	What stays in context	System prompt + plan + recent turns	memory-systems
Long-term memory	Retrieval store, write policy	Explicit "remember" writes, hybrid retrieval	memory-systems
Planning	Explicit plan object or implicit	Explicit plan for > ~5 steps	references/planning-strategies.md
Guardrails	Input/output filters, approvals	Approval on irreversible actions	../../harness-engineering/sandbox-execution
Observability	Traces, cost	One span per LLM/tool call	../../harness-engineering/agent-observability