Architect Autonomous AI Agent Systems

This skill provides expert guidance for designing and building autonomous AI agents - tool use, memory systems, planning strategies, and multi-agent orchestration - with a strong emphasis on graceful degradation and knowing when an agent should ask for help versus proceed independently. It covers six concrete agent-architecture patterns: the ReAct loop (reason, act, observe, repeat until done or stuck, with max-iteration limits); Plan-and-Execute (decompose into steps up front, execute each, replan based on results, optionally with separate planner and executor models); a tool registry for dynamic tool discovery (register tools with schema and examples, a selector that picks relevant ones, lazy-loading expensive tools, usage tracking); hierarchical memory (working memory for current context, episodic memory for past interactions, semantic memory for learned facts, RAG for long-term retrieval); the supervisor pattern (a supervisor decomposes and delegates to focused specialist agents, aggregates results, handles errors at the supervisor level); and checkpoint recovery (checkpoint state after each successful step, resume from the last checkpoint on failure, clean up on completion).

It also documents seven named sharp edges with severity, symptoms, root cause, and fix: agent loops with no iteration limit, CRITICAL, runs forever and drains API credits, fixed with max_iterations, max_tokens per turn, timeouts, cost caps, and circuit breakers; vague tool descriptions, HIGH, wrong tool selection and parameter errors, fixed with a one-sentence purpose, when-and-when-not-to-use guidance, typed parameters, example inputs and outputs, and error cases; silently swallowed tool errors, HIGH, the agent continues on bad data, fixed by returning error messages and recovery hints to the agent so it can retry or choose an alternative; unfiltered memory accumulation, MEDIUM, blows the context window and token cost, fixed by summarizing rather than storing verbatim, filtering by relevance, and using RAG; giving an agent 20-plus tools, MEDIUM, confusion and slow responses, fixed by curating 5-10 tools per agent, adding a tool-selection layer, or splitting into specialized agents; reaching for multi-agent when one agent would do, MEDIUM, duplicated work and coordination overhead, fixed by justifying the overhead before adding agents; and no tracing of agent thoughts and actions, MEDIUM, undebuggable failures, fixed by logging every thought, action, and observation and tracking token usage and latency. A related gotcha covers fragile regex or exact-match parsing of LLM output, fixed with structured output modes, fuzzy matching, and retry-with-format-instructions.

Use this skill whenever a task mentions or implies building an agent, tool use, function calling, multi-agent systems, agent memory, agent planning, or specific frameworks like LangChain agents, CrewAI, AutoGen, or the Claude Agent SDK. For adjacent needs it hands off to sibling skills: rag-engineer, prompt-engineer, backend, mcp-builder. It should only be used when the task clearly matches this scope, is not a substitute for environment-specific validation or expert review, and calls for stopping to ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Expected background is LLM API usage, an understanding of function calling, and basic prompt engineering. Output is an agent architecture recommendation matched to the task - which of the six patterns fits, how to structure tools, memory, planning, and multi-agent coordination for it - plus concrete guardrails, iteration limits, error handling, tool curation, tracing, drawn from the sharp-edges list to avoid the documented failure modes.

Framework-agnostic guidance applicable to LangChain agents, CrewAI, AutoGen, and the Claude Agent SDK, and any LLM API such as OpenAI or Anthropic with function or tool calling; works alongside RAG-based memory retrieval.

Developers designing or debugging autonomous AI agent systems who need both architecture patterns, ReAct, Plan-and-Execute, supervisor, checkpointing, and a checklist of common failure modes to design around before they cause production incidents.