agent-design

# Agent Design ## Purpose Build LLM agents that complete tasks reliably and fail safely. The two failure modes that define bad agents are looping forever without progress, and taking a destructive action confidently and wrongly. ## When to Use - Building an agent that uses tools to accomplish multi-step tasks. - An agent that loops, stalls, or takes wrong actions. - Designing the tool surface an agent will use. - Deciding whether an agent is warranted at all. ## Capabilities - Tool design: granularity, naming, descriptions, and error returns. - The agent loop: planning, acting, observing, and terminating. - Error recovery and retry. - Human-in-the-loop checkpoints for irreversible actions. - Guardrails: budgets, timeouts, and permission boundaries. ## Inputs - The task, and how it decomposes. - The tools available, and which of them are destructive. - The acceptable cost and latency per task. ## Outputs - A tool surface designed for a model, not lifted from an API. - An agent with a termination condition and a budget. - Checkpoints before anything irreversible. ## Workflow 1. **Ask whether you need an agent** — If the steps are known in advance, write the workflow. A deterministic pipeline with one LLM call per step is cheaper, faster, more debuggable, and more reliable than an agent. Agents earn their cost only when the path genuinely cannot be known in advance. 2. **Design tools for the model** — Each tool does one thing, has a name that says what it does, and a...