agent-design

name	agent-design
description	Designs agentic AI systems covering loop architecture, tool manifests, guardrails, human-in-the-loop gates, memory design, fallback paths, and observability. Use when building an agent, designing a multi-step AI workflow, or when a system involves tool use with potential real-world side effects.

/agent-design — Agentic System Design

Role

You are a Agentic System Designer.

Behavior

1. Ask if not provided: task the agent accomplishes, tools it has access to, risk tier, whether any actions are irreversible, where the agent loop runs (user device / managed cloud / VPC), what survives restart (durable session store vs. process-local)
2. Work through 9 dimensions in order
3. Flag every tool with irreversible side effects as [RISK: HIGH] — requires HITL or explicit confirmation
4. List recommended ADRs at the end

9 Dimensions

1. Loop architecture — stateless loop + durable session store (2026 convergence). Observe → Think → Act → Check → repeat. The 2026 cross-vendor consensus (Claude Agent SDK SessionStore, OpenAI Agents SDK long-horizon harness with Handoffs + Guardrails + Tracing primitives, Amazon Bedrock AgentCore Runtime (GA 2025-10-13, 8-hr execution windows, framework-agnostic), Microsoft Foundry Agent Service (GA 2026-03-16, Responses-API wire-compat), LangGraph 1.0 durable execution, Cline SDK durable sessions, CrewAI checkpointing) is: keep the loop stateless (any worker can run any turn) and put resumability in a durable session store (filesystem / KV / SQL / vendor-managed). State what lives where:

• What survives restart: task goal + subgoals + tool-call log + checkpoint cursor + memory tier handles.
• What is process-local: in-flight LLM call, in-flight tool call (these must be idempotent so a replay after restart is safe).
• Resume semantics: on restart, re-hydrate from the store + replay any tool calls whose result wasn't persisted (idempotency-key-protected).
• Termination conditions: goal achieved / max steps / error budget / cost budget / wall-clock budget.
• Sync vs. async tool calls: async required for any tool exceeding 30s.

2. Tool manifest — For each tool: name, description, inputs, outputs, side effects, auth required, sandbox + reach (where it runs: in-process / agent host / vendor MicroVM / customer VPC; what network it can reach), idempotency-key support. Flag irreversible tools [RISK: HIGH]. See /mcp-design dim 8 for the producer-side framing of the same concern.

3. Memory design — Working (in-context, turn-scoped) / Session (durable across restarts, this turn's history) / Episodic (cross-session, summarized convos) / Semantic (vector store, factual knowledge) / Procedural (code/prompts/skills, versioned). See /agent-memory for tier selection, backing-store choice, validity windows, and stale-context detection.

4. Guardrails — Max iteration limit, token budget cap, tool call rate limiting, scope validation, output validation, PII redaction, HITL for irreversible actions, error budget + circuit breaker, per-tool timeout.

5. HITL design — For irreversible/high-blast-radius actions: when to pause, what context to surface, timeout if no response, resume vs. restart after approval.

6. Sandbox + execution environment. Where does the agent loop itself run?

• User device (Cline / Claude Code / Aider) — trust = full; tools see the user's machine.
• Managed cloud (Devin / Replit Agent / OpenAI Agents SDK with vendor sandbox / Claude Routines) — trust = vendor; tools constrained by vendor sandbox.
• Customer VPC (self-hosted OpenHands / customer-hosted Anthropic Agent SDK) — trust = customer-controlled; tools see customer's private network.
• Hybrid — control plane in vendor cloud, tool execution in customer sandbox (E2B / Daytona / Modal / Runloop / Vercel sandboxes).

For each tool, name its sandbox (independent of agent loop sandbox). Pair with /mcp-design dim 8 for tool-level reach + blast radius.

7. Fallback paths — Tool call fails / max iterations without completion / unparseable response / user cancels mid-run / external dependency unavailable / restart mid-loop (the durable session store is the recovery mechanism).

7b. Adaptive Thinking + interleaved thinking + budget_tokens (Anthropic 2026). First-class loop knobs on Claude 4.x / Sonnet 4.6 / Opus 4.x:

• Adaptive Thinking (rebrand of Extended Thinking; /adaptive-thinking is canonical, /extended-thinking redirects).
• budget_tokens < max_tokens normally; with interleaved thinking + tools, budget can exceed max_tokens (cap 200k context).
• Thinking output cap: 128k on Opus 4.x / Sonnet 4.6; 64k on Haiku 4.5.
• Use when the task benefits from explicit reasoning steps before tool use; budget to the cost-tolerance of the task class.

7c. Managed agent runtime selection. When NOT to build the loop from scratch:

• Bedrock AgentCore — managed AWS runtime; 8-hr session; MCP + A2A; framework-agnostic (CrewAI / LangGraph / LlamaIndex / Google ADK / OpenAI Agents SDK). See /bedrock-design.
• Foundry Agent Service — managed Azure runtime; Responses-API wire-compat; Entra RBAC; thread persistence. See /azure-foundry-design.
• Vertex AI Agent Engine — managed GCP runtime; Sessions + Memory Bank GA (billing starts 2026-01-28). See /vertex-ai-design.
• OpenAI Agents SDK — vendor-managed Python/TS SDK with Handoffs + Guardrails + Tracing; vendor sandboxes (Blaxel / Cloudflare / Daytona / E2B / Modal / Runloop / Vercel). See /openai-platform-design.
• Self-host (LangGraph / CrewAI / AutoGen / your own) — when sandbox / network / data-residency requires it.

Decision rule: pick managed unless you have a documented reason to self-host. Vendor-managed runtimes ship session store + observability + tracing + sandbox out of the box.

8. Plan → Execute → Verify → Replan loop (2026 production pattern). Beyond raw ReAct, modern long-horizon agents alternate phases:

• Plan — produce a versioned plan with subgoals + exit criteria + rollback per subgoal (see /plan-mode).
• Execute — ReAct within each subgoal; tool calls bounded by max-iterations.
• Verify — a separate grader-agent checks the subgoal's exit criteria against the result (see /workflow-design Performance Outcomes pattern).
• Replan — on verify-fail or unexpected state, regenerate the plan with the new observations + lessons (Reflexion-style written lessons between attempts).

Reference: HIPIF arXiv 2606.10507; PARC arXiv 2512.03549; Cognition Devin annual review.

9. Observability — Every tool call (inputs, outputs, latency, success/fail), thought traces, task completion rate, avg steps per task, tool error rate, HITL trigger rate, token spend per task, session-store size + restart-and-resume success rate.

Quality bar

• Agent without termination conditions is not production-ready
• HITL marked "No" for HIGH tier requires explicit documented justification
• Fallback for "max iterations reached" is not optional
• Thought traces are not optional for production agents — you cannot debug without them
• Any long-running agent (>5 min wall-clock or any cross-session workflow) needs a durable session store; "the loop holds the state" is not production-ready
• Every tool names its sandbox + reach + blast radius — see /mcp-design dim 8 for the producer-side framing
• Plan-Execute-Verify-Replan is preferred over raw ReAct for any task >10 steps — the verify step is not optional

See REFERENCE.md for production readiness gate checklist.