Skip to content

Snippet: Agentic AI / AI Agents

Domain Context

Building AI agents that use tools, plan multi-step actions, maintain memory, and collaborate. Agents amplify both capabilities and failure modes — defensiveness is not optional.

Architecture Principles

  • Define the agent's scope of authority before writing any code — what it can and cannot do
  • Prefer single-purpose agents composed together over one monolithic "do everything" agent
  • Every agent must have a clear system prompt defining: role, constraints, available tools, output format
  • Use explicit state machines or DAGs for multi-step workflows — not open-ended recursion
  • Set a hard maximum on iterations/tool calls per request (default: 25) to prevent infinite loops

Tool Use

  • Every tool must have: a clear description, typed input schema, and documented side effects
  • Tools that modify state (write, delete, execute) require explicit user confirmation or a sandbox
  • Log every tool call with: tool name, input args, output, latency, token usage
  • Implement tool call validation: reject malformed inputs before execution, not after
  • Fallback behavior: define what happens when a tool is unavailable or returns an error

Planning & Reasoning

  • Use structured planning (plan → execute → reflect) rather than single-shot generation
  • Make the agent's plan visible/inspectable — never hide the reasoning chain from the user
  • Implement plan validation: check plan feasibility before execution starts
  • ReAct pattern (Reason → Act → Observe): log each step for debugging
  • If a plan fails mid-execution, the agent should be able to replan from current state, not restart

Memory & Context

  • Short-term memory: conversation history with sliding window + summarization for long sessions
  • Long-term memory: use vector store or structured DB — never rely on context window alone
  • Memory retrieval must be relevance-filtered — don't stuff all memories into every prompt
  • Implement memory expiration: stale information should be deprioritized or removed
  • User corrections should update memory — the agent must learn from feedback within a session

Multi-Agent Systems

  • Define clear communication protocols between agents (structured messages, not free text)
  • Each agent must have a unique role — avoid overlapping responsibilities
  • Implement an orchestrator/router that delegates tasks and aggregates results
  • Error isolation: one agent's failure must not cascade to the entire system
  • Shared state must be explicitly managed — no implicit assumptions about what other agents know

Safety & Guardrails

  • Human-in-the-loop for all irreversible actions (file deletion, API calls with side effects, payments)
  • Rate limit agent actions: max tool calls per minute, max cost per session
  • Implement output validation: check agent's final response against task requirements
  • Sandbox execution: code generated by agents must run in isolated environments
  • Audit trail: every agent action must be logged and replayable for debugging

Evaluation

  • Task completion rate: does the agent actually solve the user's request end-to-end?
  • Efficiency: number of steps/tool calls to complete the task (fewer is better)
  • Error recovery rate: when a tool fails, does the agent recover or get stuck?
  • Safety compliance: rate of guardrail violations in adversarial testing
  • User satisfaction: collect structured feedback on agent interactions

Common Pitfalls

  • Agent loops: retrying the same failed action without changing approach
  • Tool abuse: calling tools unnecessarily when the answer is already in context
  • Context window overflow: agent accumulates so much history it loses coherence
  • Over-autonomy: agent takes irreversible actions without confirmation
  • Prompt injection via tool outputs: external data influencing the agent's behavior