AI Agent Architecture: The Production Building Blocks

An AI agent is not just a prompt wrapped around a model. In production it is a control loop: receive a task, choose a next action, call a tool, inspect the result, and decide whether to continue or stop. This guide is for platform engineers designing tool-using workflows. It helps you choose boundaries that make decisions, side effects, state, and failures explainable. It does not prescribe one framework or claim that a diagram can replace policy and testing.

At a glance

This diagram is a topic-specific decision aid: connect the article’s context to evidence before taking the next action.

The architecture framework

Use Contract → Boundary → State → Evidence as the design path:

1. Contract: define the task, allowed outcomes, side effects, and terminal states.
2. Boundary: isolate model recommendations, policy decisions, tools, and untrusted data.
3. State: carry only the facts needed for the next decision, with explicit transitions.
4. Evidence: connect decisions, versions, side effects, and outcomes in one trace.

Decision rule: Define the task contract first, isolate trust boundaries, make state explicit, and attach evidence to every consequential transition.

Map the six production layers

The exact implementation can vary, but each layer should have a clear responsibility:

This separation makes AI agent observability an architectural property rather than a dashboard added after launch. It also gives production-ready AI agents a concrete review surface. A layer may share code with another layer, but its contract should remain inspectable.

Begin with a task contract

Write down what enters the system, what it should produce, what side effects are allowed, and what counts as a terminal result. “Answer the user” is not enough for a support agent that may search an account, create a case, or hand work to a person. Distinguish a completed answer, clarification request, policy refusal, dependency failure, and operator handoff.

Use explicit terminal states

Even ordinary application code benefits from a small state machine. Name states such as received, planning, awaiting_tool, awaiting_approval, completed, blocked, and failed. Each transition should have a reason and an owner. This is more useful than a large diagram that no code, test, or runbook reflects.

The contract gives every downstream component a stable reason to exist. The model chooses among allowed next steps. Tools implement those steps. State carries facts forward. Evidence proves which path occurred. Without the contract, each layer invents its own definition of success: a tool can return HTTP 200 while the task is wrong, and a fluent model response can still violate policy.

Keep the model inside a decision boundary

The model should recommend a next action, not directly perform an irreversible one. Return a typed decision with an explicit action kind, tool name, validated arguments, and a reason where that reason is meaningful. The application decides whether the recommendation is allowed. This separation makes it possible to change models without silently changing the permission model.

type AgentStep =
  | { kind: "search"; query: string }
  | { kind: "request_approval"; action: string; reason: string }
  | { kind: "answer"; text: string; citations: string[] }
  | { kind: "stop"; status: "blocked" | "failed"; reason: string };

function allowed(step: AgentStep, policy: Policy): AgentStep {
  if (step.kind === "search" && policy.allowsRead(step.query)) return step;
  if (step.kind === "request_approval") return step;
  if (step.kind === "answer" && step.citations.length > 0) return step;
  return { kind: "stop", status: "blocked", reason: "policy-or-evidence" };
}

This is an illustrative TypeScript shape, not a drop-in implementation: Policy must be supplied by the application and each tool needs its own argument and authorization validation. The important contract is that a model-produced value is still untrusted until the application checks it.

Boundary note: A policy check should happen at the side-effect boundary, immediately before execution. Earlier model confidence or a previous approval does not authorize a changed argument or stale state.

Design tools as product boundaries

A tool is more than a function the model can call. It is a product boundary with an input contract, permission model, timeout, idempotency behavior, typed result, and failure class. Return enough structured information for the next decision without copying unrestricted payloads into every model context or trace.

Make side effects reviewable

For read operations, record the resource class, authorization result, and freshness signal. For writes, record the proposed action, validation result, approval or policy decision, idempotency key, and terminal outcome. A tool success should not automatically finish the parent task; the workflow still needs to evaluate whether the intended outcome was reached.

Treat state as an explicit interface

State should contain the facts needed for the next decision, not an unbounded transcript that every component interprets differently. Separate current task state from durable user or domain state. Mark source, freshness, version, and authority when a stale or user-controlled value could change the action.

Make retries safe

Shared mutable state makes retries hard to reason about. Use explicit transition events, bounded attempts, and idempotency keys for side effects. A retry should say what failed, what changed, and whether repeating the action is safe. Do not allow a model to infer completion from a partial state update.

The state model should also describe degraded paths: missing evidence, dependency timeout, invalid tool result, approval expiry, and budget exhaustion. A named fallback is easier to test and explain than an implicit “try again” branch.

Make evidence part of the architecture

Telemetry is not a decorative afterthought. Record the parent task, child model and tool spans, state transitions, policy and prompt revisions, release identifier, retry history, cost, latency, and final outcome. Redact sensitive values and restrict access according to the consequences of the data being stored.

Connect evidence to a decision

An investigator should be able to answer: what task was attempted, which decision changed the path, what evidence supported it, which boundary was applied, and who owns the next action? If a field cannot help answer one of those questions, defer it until a real investigation requires it. The trace shape in LLM tracing explained provides the parent-child model; prompt injection defense covers the trust boundary for untrusted instructions and tool inputs.

Choose a control-loop shape

There is no single correct orchestration shape. Choose based on the task contract and failure cost:

Keep the loop bounded by attempts, time, cost, and allowed transitions. A more elaborate architecture is not automatically safer; it may add more state and more failure surfaces.

A small control loop

receive task
  ↓
validate contract and policy
  ↓
model recommends next step ──→ blocked / approval required
  ↓
validate tool arguments
  ↓
execute bounded tool action
  ↓
record result and update state
  ├─ task complete → final outcome
  └─ more work     → next bounded iteration

The diagram is intentionally simple. Every arrow should correspond to a testable transition and a trace event. If the team cannot name the stop condition, the loop is not ready for production traffic.

Plan for degraded dependencies

Design the unhappy path before the happy path is polished. A dependency can be slow, return a valid-looking but wrong result, change its schema, or become unavailable after the agent has already made a decision. For each case, define the user explanation, safe fallback, owner, retry policy, and evidence to preserve.

Do not hide a policy refusal as a provider error. Do not retry a deterministic schema failure as if it were a network timeout. Do not continue after a missing approval because the model sounds confident. These distinctions are what make an architecture controllable under pressure.

Failure rule: Every degraded path must end in a named state. If the system can only “keep trying,” it has no reliable boundary.

Review the architecture before launch

Start with one workflow and one failure class. Review a successful, degraded, and failed run using only the recorded evidence. Then ask whether the architecture can explain the difference without tribal knowledge.

Production checklist

• Can you name the task contract and terminal states?
• Does every model recommendation pass through policy and argument validation?
• Does every side effect have an owner, authorization rule, and idempotency behavior?
• Is state explicit, bounded, versioned, and safe to retry?
• Can you compare runs by release, workflow, input class, and outcome?
• Are queue, model, tool, validation, and approval events connected?
• Does every degraded path end in a safe, observable state?
• Can an operator pause, resume, or roll back the workflow?

Decision rule: Start with the smallest architecture that makes one real failure explainable. Add a layer only when it owns a distinct contract or removes a demonstrated risk.

Next step: review one control loop

Choose one tool-using workflow and write its task contract, allowed actions, state transitions, terminal states, and evidence fields on one page. Then compare one successful and one failed run. The missing boundary will usually be more valuable than another model instruction or another dashboard panel.

The ai agent architecture operating model

Put ai agent architecture into practice

A useful article should help a reader move from an idea to a safe production decision. Start by stating the user-visible outcome, then identify the inputs, the owner, the evidence, and the terminal states. Do not begin with a tool or framework. Begin with the decision the system must support and the cost of getting that decision wrong. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Define the contract

Write the input and output contract before tuning the model. Name required fields, acceptable values, missing-data behavior, and the response a user receives when the system cannot proceed. A schema validates shape, but it does not prove meaning or authorization. Follow parsing with semantic checks, policy checks, and an explicit fallback. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Separate proposal from authority

A model can classify, extract, summarize, rank, or propose an action. Deterministic code should own permissions, limits, accounting, retention, and irreversible side effects. This boundary makes the system easier to test and easier to explain after an incident. If a model suggestion is rejected, route it to a visible state instead of silently rewriting it. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Build representative cases

Create a small case set before claiming that an implementation works. Include ordinary examples, empty inputs, ambiguous requests, stale data, conflicting evidence, malformed outputs, permission boundaries, and provider failures. Label the expected user outcome and the unacceptable failure. Keep the cases versioned so a later change can be compared against the same baseline. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Validate the full path

Unit tests are valuable for parsers, transitions, policies, and retry rules, but they do not prove the workflow works end to end. Add scenario tests that exercise retrieval, model calls, tool calls, timeouts, duplicate events, approvals, and partial completion. Preserve the trace for each important scenario and check both the final result and the intermediate evidence. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Make retries safe

Every external write needs a stable identity, a bounded retry policy, and a reconciliation path. A timeout is not proof that an action failed. Record unknown outcomes explicitly, query the provider when possible, and prevent duplicate work with idempotency keys. Never let a generic retry loop decide whether a financial, permission, or communication side effect is safe. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Design human review

Human review should be specific and actionable. Show the proposed action, normalized arguments, evidence, policy version, expected consequence, and expiration. Bind approval to that exact proposal. If a material field changes, invalidate the approval. Record the reviewer, decision, reason, and result so rejection patterns become improvements rather than repeated surprises. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Instrument useful evidence

A trace should connect the original request to each meaningful stage and the final outcome. Capture versions, latency, cost, status, error category, tool arguments after redaction, and the evidence used for the decision. Avoid collecting sensitive payloads merely because they are available. Store references or structured summaries when raw content is not necessary for diagnosis. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Measure outcomes

Completion rate is not enough. Measure correctness, user acceptance, review rate, repair rate, latency, cost, retries, and the frequency of unsafe or unauthorized proposals. Segment the results by version, model, customer cohort, input class, and failure mechanism. A higher automation rate can be a regression when it creates more corrections or delays discovery of mistakes. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Roll out in stages

Use observation, shadow mode, suggestions, prepared drafts, approved execution, and only then broader automation. Give each stage an owner, cohort, success threshold, and rollback condition. Preserve the manual path until the automated path has demonstrated normal and degraded behavior. Keep in-flight work recoverable when a release is paused. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Operate failure states

Make waiting, degraded, unknown, failed, cancelled, and completed distinct states. Tell the user whether the system is waiting for data, approval, a provider, a retry window, or manual repair. Give every waiting state an expiration or escalation path. Silent queues and ambiguous success messages are operational defects, not cosmetic issues. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Review changes

Prompts, models, schemas, retrieval indexes, tools, providers, and policies are all dependencies. Version them and record their versions with each run. When behavior changes, compare a representative cohort with the previous baseline. Review quality, safety, latency, cost, and correction work together; optimizing one dimension can damage another. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Example decision record

For a meaningful release, write a short record with the goal, affected workflow, expected improvement, known risks, evidence set, rollout stage, owner, rollback command, and review date. Link it to representative traces and the test cases that protect the most important boundary. This record turns a vague confidence claim into something another engineer can inspect. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Practical checklist

Before launch, confirm that the workflow has a named owner, a clear contract, policy enforcement, safe side effects, representative tests, useful traces, and a recovery path. After launch, sample successful and failed runs, inspect corrections, update the case set, and retire metrics that do not change a decision. The goal is not maximal automation; it is a dependable user outcome that the team can explain and improve. For an agent architecture, this means making the boundary observable in the run trace and testable without the model.

Failure scenarios in ai agent architecture

The happy path is the least informative path. Rehearse empty input, malformed output, stale context, unavailable dependencies, rate limits, duplicate callbacks, and a provider timeout after an external system may already have accepted the request. For each case, state the expected user-visible result, the durable record that proves what happened, and the person or process responsible for recovery.

A concrete runbook

When an incident starts, identify the affected workflow and version, determine whether the problem is global or cohort-specific, pause new side effects if needed, and preserve a representative trace. Compare a failed run with the last known healthy run. Look for the first meaningful divergence rather than the loudest error. Record the hypothesis, reversible change, verification signal, and owner before editing production behavior.

Data and permissions

Review every input source for freshness, scope, and authorization. A technically correct answer built from data the user should not see is still a failure. Propagate tenant and user context through retrieval and tools, filter before the model sees data when possible, and avoid treating a model instruction as permission. Test cross-tenant, revoked-access, and stale-credential cases explicitly.

Cost and capacity

Measure cost per successful outcome, not merely cost per model call. A cheap answer that triggers retries, review, or correction can be more expensive than a larger reliable call. Set token, time, concurrency, and provider budgets. Define what degrades first when capacity is constrained, and ensure that load shedding does not bypass authorization or create untracked work.

Quality drift

Quality can move when user questions, documents, providers, or model behavior changes. Keep a fixed regression set and a recent production sample. Compare not only averages but severe failures, cohort movement, abstention behavior, and correction work. If the system is uncertain, a safe review or explicit limitation is often preferable to a confident unsupported result.

Recovery and replay

Replay only when the workflow is designed for it. Separate read-only analysis from side effects, preserve idempotency keys, and mark whether a run was original, retried, reconciled, or replayed. A replay should not silently send a message, charge an account, or change permissions. Provide operators with a dry-run mode and a clear confirmation step for consequential actions.

What to document

Keep the contract, state machine, dependency versions, permissions, test cases, dashboards, alerts, rollback procedure, and escalation contacts near the workflow. Documentation should answer what the system does, what it cannot do, what evidence it records, and how to stop it safely. Update it after incidents and material changes, not only during an initial launch.

A review question

Ask: if this workflow is wrong for one customer tomorrow, can the team identify the affected runs, stop further harm, explain the mechanism, recover unknown side effects, and prove the fix? If any answer is no, the next improvement belongs in observability, authorization, state management, testing, or the runbook—not in more persuasive output wording.

Closing practice

Choose one representative workflow and perform the full exercise this week. Write its contract, rehearse two degraded cases, inspect one trace, measure one user outcome, and name one rollback condition. Keep the result small enough to use. Reliable systems are built through repeated evidence-based decisions, not through a single promise that the model will behave.

Final review questions

Before treating this guidance as complete, ask what a careful operator would need at the moment the system surprises them. Can they tell which version ran, what evidence was available, which policy applied, and whether an external action is still unknown? Can they stop new work without losing recoverable state? Can they distinguish a model-quality problem from a retrieval problem, a policy problem, a provider problem, or an integration problem? These questions turn a conceptual guide into an operational one.

A useful review compares three runs: one that succeeded cleanly, one that succeeded only after a retry or human correction, and one that failed. Record the timeline, state transitions, inputs, outputs, costs, and user-visible result. The comparison often reveals that the system’s most important missing feature is not another metric but a durable boundary: a missing owner, an ambiguous terminal state, an unlogged approval, an unsafe retry, or an output that was accepted without semantic validation.

Treat the result as a living contract. When a model, prompt, tool, policy, provider, data source, or workflow state changes, update the representative cases and rerun the relevant checks. Keep the old behavior available during staged rollout when the side effects matter. Retire a control only when its replacement covers the same failure and the evidence shows that the new boundary is understood.

The best implementation is usually the smallest one that makes the decision explicit. Prefer a narrow workflow with clear permissions, predictable recovery, and honest uncertainty over a broad agent that can do more but cannot explain what it did. Measure the correction work created for people, not just the work removed from the queue. If the new path saves time while increasing hidden review or incident cost, it has not improved the user outcome.

Use this guide to produce a concrete next action. Pick one workflow, name its owner, write the contract, collect representative traces, choose one quality and one safety signal, and set a rollback condition. Review the result with engineering, security, and the people who handle exceptions. Their questions are part of the system design. A dependable production workflow is not defined by a long prompt or a high demo score; it is defined by a user-visible outcome that remains explainable, bounded, and recoverable as conditions change.

From ai agent architecture draft to durable practice

A production article should leave the reader with a sequence they can execute and inspect. Start with a baseline: one representative input, one expected outcome, one failure case, and one trace or record that makes the result visible. Change one meaningful variable at a time. If the result improves, record why; if it regresses, preserve the case so the regression becomes a durable test instead of a forgotten anecdote.

When choosing between alternatives, state the tradeoff plainly. Simpler systems are easier to operate but may provide less coverage. More retrieval, more tools, or more model calls may improve one quality measure while increasing latency, cost, privacy exposure, and failure surface. The right choice depends on the user outcome and the risk budget. A recommendation is only useful when the reader knows when not to use it.

Make uncertainty visible. Use abstention, escalation, citations, confidence bands, or a clear “not enough evidence” state when the workflow cannot support a reliable result. Do not convert missing evidence into confident prose. Define which uncertainties are acceptable, which require human review, and which should stop execution. Then test those boundaries with examples that are deliberately incomplete or adversarial.

Plan ownership beyond launch. Someone should own the workflow contract, dependency updates, dashboards, incident response, and review cadence. The owner should be able to answer how a release is evaluated, how a bad change is rolled back, and how users are informed during degradation. Shared ownership without a named decision-maker usually becomes no ownership when the first failure crosses team boundaries.

Include the maintenance loop in the implementation. Sample production results, inspect correction work, refresh the regression set, review costs and latency, and remove metrics that do not guide action. Feed confirmed incidents into tests, policies, or state transitions. A fix that changes only wording may hide a symptom; a durable fix changes the mechanism that allowed the failure or makes the failure safe and visible.

Finally, define completion precisely. A workflow is not complete because the demo passed or because the model produced a plausible answer. It is complete when its inputs and outputs are bounded, its authority is explicit, its evidence is traceable, its side effects are safe to retry or reconcile, its degraded states are honest, and its owner can prove the result with representative cases. Use that standard to decide what to build next and what to leave out.

Frequently asked questions

Turn the architecture into an executable boundary

An agent architecture becomes useful when each box in the diagram owns a decision that can be tested. The task contract defines what the user is asking and what completion means. The policy layer defines what the system may do. The model proposes a next step. The tool validates and performs bounded work. State records facts needed for the next transition. Evidence connects the entire path. If two layers both own the same decision, an incident will produce competing explanations.

Draw the side-effect line

Place the side-effect boundary as close as possible to the system that owns authorization and current state. Before execution, validate tenant, actor, resource, arguments, freshness, policy version, and idempotency key. Do not rely on a model’s earlier reasoning or a reviewer’s approval if the action changed after approval. For high-consequence actions, make the proposed command visible and require a terminal confirmation.

Choose state deliberately

Keep transient reasoning separate from durable domain state. Transient state can include the current plan, tool result, and iteration budget. Durable state should have a source, owner, version, freshness, and retention rule. Never let an unbounded transcript become an accidental database. When state is missing or contradictory, use a named blocked or review state instead of allowing the model to silently choose a convenient interpretation.

Bound the control loop

Set maximum iterations, wall-clock time, token spend, tool calls, and side-effect count. Define what happens when each budget is exhausted. A loop that stops only when the model says it is finished has no dependable terminal condition. Record every transition with its reason and parent run so an operator can distinguish a legitimate multi-step task from an accidental retry storm.

Validate the architecture with traces

Review one successful, one degraded, and one failed run. Can the team identify the task contract, model recommendation, policy decision, tool result, state transition, and final user outcome? If not, add the smallest missing evidence field or boundary test. Architecture quality is demonstrated by explainable behavior under failure, not by the number of boxes in a diagram.

Architecture rule: Add a component only when it owns a distinct contract, removes a demonstrated risk, or creates evidence the operator can use.