A production reference architecture for AI agents: components, data flows, trust boundaries, and operational controls.

Reference architecture

Overview

This reference architecture decomposes an agent system into explicit components so you can assign ownership, enforce boundaries, and scale operations. It highlights where to place controls for permissions, grounding, side effects, and observability.

Key topics

  • Component boundaries: UI, agent runtime, orchestration, knowledge, tools, observability.
  • Trust boundaries: untrusted content, policy layer, and privileged tool execution.
  • Data flows: retrieval, context assembly, tool calls, verification, and output.
  • Operational loops: evaluation, monitoring, incident response, and change control.

Common pitfalls

  • Merging policy and data: letting documents influence system instructions.
  • One monolithic prompt with no separations of responsibility.
  • No state persistence: impossible to replay or audit.
  • Tool sprawl: too many tools available to the model.

Recommended practices

  • Define strict interfaces between components (schemas, IDs, correlation).
  • Implement least privilege at the tool and data level.
  • Persist state and step traces for replay and audit.
  • Treat evaluation as CI, not as a one-off exercise.

This page is intended to be actionable for engineering teams. For platform-specific details, cross-reference /platform/agents, /platform/orchestration, and /platform/knowledge.