AI Agent Design

When to use

Use this when a task needs the model to take actions in a loop — call tools, observe results, decide the next step — rather than produce a single answer.

Not for: single-shot generation or classification (a plain prompt is cheaper and safer, see ai-prompt-design), or read-only Q&A over docs (see ai-rag-pipeline).

Method

1. Decide if you even need an agent. Decision point: if the steps are known and fixed, write a deterministic pipeline; use an agent only when the path depends on runtime results.
2. Define tools as the narrowest useful set. Each tool: a clear name, a one-line description of WHEN to use it, and a typed input schema with required fields.
3. Write the system prompt: the goal, the available tools, how to decide between them, and when to stop.
4. Choose the control loop: call model → if tool_call, execute and append the result → repeat until a final answer or a stop condition fires.
5. Set hard stop conditions: max iterations, wall-clock/token budget, and a repeated-action detector. Decision point: on limit hit, return partial results with a reason, never loop silently.
6. Add guardrails: validate tool arguments before executing, require confirmation for destructive/irreversible actions, and sandbox side effects (see ai-guardrails).
7. Log every step (thought, tool, args, result) for replay and evaluation (see ai-eval-harness).

Example

Agent: "find the failing test and summarize the cause."

loop (max 8 steps):
  resp = model(history, tools=[grep, read_file, run_tests])
  if resp.tool_call:
    if resp.tool == "run_tests" and !confirmed: ask_user()
    result = execute(validate(resp.tool_call))
    history += result
  else: return resp.text

Step 1 grep "FAIL" → test name. Step 2 read_file → source. Step 3 final summary. The max-8 cap and an "identical grep twice" detector prevent a loop when a tool returns empty.

Pitfalls

• Tool soup. 20 overlapping tools; the model picks wrong. Fewer, sharper tools with distinct "when to use" lines.
• No stop condition. An agent that loops until the budget explodes. Always cap iterations AND detect repeats.
• Unvalidated tool args. Passing "500" where an int is required, or a path outside scope. Validate and coerce before executing.
• Silent destructive actions. Deleting or spending without a confirmation gate. Guard irreversible tools.
• Retrying a failed call unchanged. Same tool, same args, same error, N times. On failure, change exactly one thing (args, tool, or approach) before retrying; after ~3 distinct failures, surface the block instead of burning budget.
• Context flooding. Appending every raw tool result forever until the window is noise. Truncate or summarize large results before appending; keep only what the next decision needs.
• Prompt injection via tool results. Web pages, files, and API payloads can contain instructions ("ignore previous…"). Treat tool output as DATA, never as instructions; scan or sanitize before appending to history.

Error-recovery policy

Every loop needs an explicit failure branch, not just a happy path:

1. Tool errors are observations — append the error text to history and let the model react; never crash the loop on a recoverable failure.
2. Distinguish retryable (timeout, rate-limit, transient 5xx: retry with backoff, max 2) from non-retryable (validation, 4xx, not-found: change the approach).
3. Track a per-goal failure budget separate from the step cap — 3 consecutive failures with no new information ⇒ stop and report what was tried, verbatim errors included.

Output format

# Agent: <name>
GOAL: <one sentence>
TOOLS:
- <name>(<typed args>): <when to use>
CONTROL LOOP: model -> tool -> observe -> repeat
STOP: max_steps=<n> | budget=<tokens/time> | repeat-detector
GUARDRAILS: arg validation | confirm-on={destructive} | sandbox
LOGGING: step{thought,tool,args,result}