Agent Architecture

Agents · Module 14 · Page 14.1

The Engineering Problem

The previous modules built the three components that interact with an interface: the sequencer (plans the traffic, Module 11), the driver (drives it onto the pins, Module 12), and the monitor (observes the pins, Module 13). But these three are not independent — they belong together. They share the same virtual interface, the same transaction type, the same protocol knowledge; the driver pulls from the sequencer; the monitor watches what the driver drove. Scattering them loose across the testbench — three separate instances to create, connect, configure, and reuse individually — is fragile and repetitive: every environment that touches this interface must re-wire the same sequencer→driver connection, re-export the monitor's analysis port, and re-decide whether to drive or just observe. The problem this chapter solves is cohesion and reuse: how do you package everything needed to interact with one interface into a single, standard, reusable, configurable unit?

The answer is the agent — UVM's standard container that bundles a sequencer, driver, and monitor into one self-contained component for a single interface protocol. The agent encapsulates the complete capability to drive and observe one interface: it holds the three components, connects them internally (driver↔sequencer, monitor's analysis port exported upward), and exposes a clean boundary to the environment. It is configurable by a single knob — is_active — that selects active (build the sequencer + driver + monitor: drive and observe) or passive (build only the monitor: observe only). And it is the fundamental unit of reuse in UVM: you build a protocol agent once (an AXI agent, an APB agent) and reuse it in every environment, at every level — block, subsystem, SoC — where that interface appears. This chapter is the agent's architecture: what it bundles, why bundling buys cohesion and reuse, where it sits in the hierarchy, and the configurability that makes one class serve both driving and observing.

What is a UVM agent — the reusable, configurable container bundling a sequencer, driver, and monitor for one interface — and why does packaging the three interface components into a single self-contained unit buy cohesion, reuse, and the active/passive flexibility a testbench needs?

Motivation — why bundle the three into one unit

The agent exists because the three interface components form a natural unit that should be built, connected, configured, and reused together. The reasons:

• The three components are coupled by the interface. The sequencer, driver, and monitor share the same virtual interface, transaction type, and protocol; the driver pulls from the sequencer; the monitor watches the interface. They are a cohesive set — bundling them keeps what belongs together, together.
• The connection wiring is always the same. Active mode always connects the driver's seq_item_port to the sequencer's seq_item_export, and the monitor's analysis port is always exported upward. Encapsulating this in the agent means writing it once, not in every environment.
• The interface protocol recurs everywhere. An AXI interface appears in dozens of DUTs; an APB in dozens more. Building the seq+drv+mon once as a protocol agent and reusing it avoids re-implementing the protocol's interaction per project. The agent is the reuse boundary.
• Driving vs observing is a per-instance decision. Sometimes you drive an interface (you control it); sometimes you only observe it (an internal interface between two DUT blocks you watch but don't control). One agent, configured by is_active, serves both — no separate classes, no duplicated monitor.
• Standardization makes testbenches legible. Every uvm_agent has the same structure — predictable build (conditional on is_active), predictable connections, predictable analysis-port export. An engineer opening any agent already knows its shape.

The motivation, in one line: the sequencer, driver, and monitor are a cohesive, recurring, configurably-driven set bound to one interface, so UVM packages them into an agent — a self-contained, standard, reusable unit that bundles and connects them once, exposes a clean boundary, and is configured active or passive — turning per-interface interaction into a build-once, reuse-everywhere component.

Mental Model

Hold the agent as the self-contained crew assigned to one interface:

An agent is the complete crew for one interface — a planner, a pair of hands, and a pair of eyes — packaged as a single unit you deploy wherever that interface appears, and switch between full-duty and observe-only. Picture each interface in your design as a station that needs staffing. The agent is the crew you assign to one station, and it has three roles. The planner (the sequencer) decides what traffic to generate. The hands (the driver) carry out the plan — driving it onto the interface. The eyes (the monitor) watch the interface — observing everything that happens, reporting it outward. These three belong together: they all work the same station, speak the same protocol, and the hands carry out the planner's plan while the eyes watch the result. So you package them as one crew — hire once, deploy anywhere: the same crew works any station of the same type (any AXI interface, any APB interface), in any building (block, subsystem, SoC). And the crew has a duty switch. In full-duty mode (active), the whole crew works — the planner plans, the hands drive, the eyes watch: the agent drives and observes. In observe-only mode (passive), only the eyes work — no planner, no hands, just the monitor watching: the agent observes without driving (for a station you don't control, only witness). The crew is self-contained (everything the station needs is inside it) and standard (every crew has the same three roles and the same duty switch), so deploying one is plug-and-play, and anyone who's seen one crew understands every crew.

So the agent is the self-contained, standard crew for one interface: planner (sequencer) + hands (driver) + eyes (monitor), bundled so they deploy as a unit, reused across every environment with that interface, and switched between full-duty (active: drive + observe) and observe-only (passive: observe). The one thing to hold is that the agent is the unit — you don't think about the seq/drv/mon individually when you place an interface's verification; you drop in the agent and set its mode.

Visual Explanation — the agent's internal structure

The defining picture is the agent's internals: a sequencer feeding a driver that drives the interface, a monitor observing the interface, and the monitor's analysis port exported up to the environment — all inside the agent boundary.

The figure shows the agent's self-contained internal structure. Inside the agent boundary sit the three components. The sequencer plans the traffic and feeds transactions to the driver (the driver's seq_item_port pulls from the sequencer's seq_item_export — Module 12.1). The driver drives those transactions onto the interface — the one protocol boundary this agent owns. The monitor observes that same interface — passively, read-only (Module 13.1) — and its analysis port is exported upward, out of the agent, so the environment (and the scoreboard/coverage in it) can subscribe (Module 13.4). The crucial reading is the encapsulation and the clean boundary. Everything needed to drive and observe this one interface is inside the agent: the planning (sequencer), the driving (driver), the observing (monitor), and the internal connection (driver↔sequencer) are all bundled — the environment doesn't wire them. What the agent exposes is a minimal, clean boundary: a sequencer (so a test can run sequences on it) and an analysis port (so the environment can subscribe to what it observed). The warning-colored interface is the agent's one connection to the DUT; the success-colored analysis port is its one connection up to the environment. The diagram is the agent as a sealed unit: internally a complete sequencer-driver-monitor assembly for one interface, externally just "run sequences here, subscribe to observations there." That encapsulation — complete inside, clean boundary outside — is what makes the agent reusable: you drop it in, run sequences on its sequencer, subscribe to its analysis port, and never re-wire its internals.

RTL / Simulation Perspective — building and connecting the agent

In code, the agent is a uvm_agent whose build_phase conditionally builds the driver and sequencer (only when active) and always builds the monitor, and whose connect_phase wires the driver to the sequencer (when active) and exports the monitor's analysis port. The code shows the structure.

class my_agent extends uvm_agent;
  `uvm_component_utils(my_agent)
  my_sequencer seqr;                              // built only when ACTIVE
  my_driver    drv;                               // built only when ACTIVE
  my_monitor   mon;                               // ALWAYS built
  uvm_analysis_port #(bus_item) ap;               // exported from the monitor, upward
 
  function new(string n, uvm_component p); super.new(n,p); ap = new("ap", this); endfunction
 
  function void build_phase(uvm_phase phase);
    mon = my_monitor::type_id::create("mon", this);       // monitor ALWAYS
    if (get_is_active() == UVM_ACTIVE) begin               // the configurability knob
      seqr = my_sequencer::type_id::create("seqr", this); //   sequencer + driver only when ACTIVE
      drv  = my_driver   ::type_id::create("drv",  this);
    end
  endfunction
 
  function void connect_phase(uvm_phase phase);
    ap = mon.ap;                                            // export the monitor's analysis port up
    if (get_is_active() == UVM_ACTIVE)
      drv.seq_item_port.connect(seqr.seq_item_export);     // wire driver <- sequencer (active only)
  endfunction
endclass

The code shows the agent's standard, configurable structure. The agent declares all three components — seqr, drv, mon — plus an ap analysis port. The build_phase is conditional on the configurability knob: the monitor is always built (an agent always observes), but the sequencer and driver are built only when get_is_active() == UVM_ACTIVE (an agent drives only when active). The connect_phase does the internal wiring: it exports the monitor's analysis port upward (ap = mon.ap) — always, so the environment can subscribe whether the agent is active or passive — and, only when active, connects the driver to the sequencer (drv.seq_item_port.connect(seqr.seq_item_export)) so the driver can pull transactions. The shape to carry: an agent is a uvm_agent that always builds and exports a monitor, conditionally builds a sequencer + driver based on is_active, and wires the driver to the sequencer when active — a standard, predictable structure that encapsulates the build-and-connect logic once, so every environment that uses the agent gets it for free. The get_is_active() check is the single point where one agent class becomes either a driving agent or an observing agent — the configurability that Modules 14.2 (active) and 14.3 (passive) explore in depth.

Verification Perspective — where the agent sits, and how it's configured

The agent is the reuse boundary in the testbench hierarchy, and its active/passive configuration is what lets one agent class serve every role. Both are essential to how a testbench is assembled.

The figure places the agent in the hierarchy and shows why it's the reuse boundary. At the top, the test configures the environment, sets each agent active or passive, and runs sequences. Below it, the environment instantiates one or more agents — one per interface — and wires them (their analysis ports) to the scoreboard and coverage. Each agent — the brand-colored reuse boundary — bundles the sequencer, driver, and monitor for one interface. At the bottom, those interface-level components are what the agent encapsulates and connects internally. The verification insight is that the agent is the seam in the hierarchy where reuse happens: below the agent is interface-specific, protocol-detailed machinery (how to drive and observe this protocol); above the agent is environment-specific, DUT-detailed structure (which interfaces exist, how their observations feed checking). The agent cleanly separates these: the same agent (the same protocol machinery) drops into a different environment (a different DUT) unchanged — because the agent's boundary (run sequences on its sequencer, subscribe to its analysis port) is independent of which environment holds it. This is why an AXI agent built for one project reuses in another: the environment around it changes, but the agent — the interface machinery — doesn't. And the active/passive knob, set by the test at the top, is what lets the same agent be a driving agent in one environment and an observing agent in another (or even at different instances in the same environment) — one class, configured per instance. The figure is the agent as the architectural pivot: the boundary that separates reusable interface machinery from environment-specific assembly, configured active or passive from above.

Runtime / Execution Flow — assembling an agent into a testbench

Using an agent is a fixed assembly flow: instantiate it in the environment, configure its mode, let it build its (conditional) internals, and subscribe to its analysis port. The flow shows the steps.

The flow is the agent's plug-and-play assembly. Instantiate and set mode (step 1): the environment creates the agent and configures it active or passive (is_active, typically via the config database). Agent builds (step 2): in build_phase, the agent itself constructs its components — the monitor always, the sequencer and driver only if active — deciding from its own mode. Agent connects (step 3): in connect_phase, the agent itself wires its internals (driver↔sequencer when active) and exports the monitor's analysis port upward. Environment subscribes, test runs (step 4): the environment subscribes the scoreboard and coverage to the agent's analysis port, and the test runs sequences on the agent's sequencer (for active agents). The runtime insight is the division of labor: the agent assembles itself (build + connect its internals) — the environment only places it, configures its mode, and subscribes to its output. The environment never reaches inside the agent to wire the driver to the sequencer or to build the monitor — that's encapsulated. This is exactly what makes the agent reusable: all the internal complexity (conditional build, internal connection, port export) is the agent's responsibility, done the same way every time, so using an agent is trivial — instantiate, configure, subscribe, run. The flow shows the agent as a self-assembling unit: hand it a mode, and it builds and wires itself into a complete, connected interface-interaction component, exposing just the sequencer and analysis port the environment needs.

Waveform Perspective — one agent, driving and observing

An active agent's dual nature — it drives and observes the same interface — is visible on a timeline: its driver drives a transaction onto the pins, and its monitor observes that same activity. The waveform shows both paths of one agent.

The waveform shows an active agent's two paths on its one interface. The agent's driver (fed by its sequencer) drives a transaction onto the pins — drv_valid asserts, data=B4 — the drive path (sequencer → driver → pins). The agent's monitor observes that same activity — mon_capture pulses when it samples the pins — and emits the observed transaction on its analysis port (ap_emit) — the observe path (pins → monitor → analysis port). The crucial reading is that one agent contains both paths: it drives the interface and observes the same interface, concurrently, on the same pins. This is the active agent's complete interface interaction — stimulus (drive) and checking-feed (observe) bundled in one unit. The contrast sharpens the picture: a passive agent (Module 14.3) would show only the mon_capture/ap_emit path — observing without the driver's drive — because a passive agent builds no driver. So the waveform distinguishes the two modes visually: an active agent appears as both driving and observing; a passive agent appears as observing only. Reading the interface for which agent owns it — is something driving (active agent) or only observing (passive agent)? — maps the agent's mode onto the pins. The picture to carry: the agent is the unit that owns one interface's complete interaction — in active mode, both driving and observing; in passive mode, observing only — and the waveform shows the agent's mode as the presence or absence of its drive path.

DebugLab — the duplicated monitor that should have been an agent mode

✗ COPY-PASTE the monitor into a standalone instance (forks the protocol logic):
  my_monitor standalone_mon;            // a SECOND copy of the protocol's monitor
  standalone_mon = my_monitor::type_id::create("standalone_mon", this);
  // ... manually wire its analysis port ...
  // agent's monitor gets a reconstruction FIX → standalone copy stays STALE → divergence, missed bug
 
✓ REUSE the agent in PASSIVE mode (one source of truth for the protocol):
  uvm_config_db#(uvm_active_passive_enum)::set(this, "obs_agent", "is_active", UVM_PASSIVE);
  obs_agent = my_agent::type_id::create("obs_agent", this);   // SAME agent, observe-only
  // builds ONLY the monitor (no driver/sequencer); same protocol logic, maintained once
  // any monitor fix applies to BOTH the active and passive instances — no divergence

Common Mistakes

• Copy-pasting an agent's monitor to observe an interface. Use the agent in passive mode (is_active = UVM_PASSIVE) instead; duplication forks the protocol logic and drifts.
• Wiring the sequencer, driver, and monitor loose in the environment. Bundle them in an agent so the connection and export logic is written once, not per environment.
• Building the driver/sequencer regardless of mode. A passive agent must build only the monitor; gate the sequencer and driver on is_active.
• Forgetting to export the monitor's analysis port. The agent must expose the monitor's port upward so the environment can subscribe — in both active and passive modes.
• Making separate classes for active and passive. One agent class with an is_active knob serves both; separate classes duplicate the monitor.
• Reaching into the agent from the environment. The environment places, configures, and subscribes; it must not wire the agent's internals — that breaks encapsulation and reuse.

Senior Design Review Notes

Interview Insights

Exercises

1. Name the bundle. List the three components an agent contains and the role of each, plus the two things the agent connects.
2. Trace the knob. Describe what an agent builds and connects in active mode versus passive mode, and the single check that decides.
3. Place it in the hierarchy. Sketch test → env → agent → components, and explain why the agent is the reuse boundary.
4. Avoid the fork. You need to observe an interface you have an active agent for. State what you do instead of copying the monitor, and why.

Summary

• An agent is UVM's standard, reusable, configurable container that bundles a sequencer, driver, and monitor into one self-contained component encapsulating everything needed to drive and observe a single interface protocol.
• It holds the three components, connects them internally (driver pulls from the sequencer; monitor's analysis port exported upward), and presents a clean boundary: a sequencer to run sequences on and an analysis port to subscribe to.
• A single knob — is_active — configures it: active builds sequencer + driver + monitor (drives and observes), passive builds only the monitor (observes only) — one class, two modes, decided by a single check in build and connect.
• The agent is the reuse boundary: it sits test → env → agent → sequencer/driver/monitor, separating reusable interface machinery (below) from environment-specific assembly (above) — so a protocol agent is built once and reused everywhere that interface appears.
• The durable rule of thumb: package each interface's sequencer, driver, and monitor into one agent, expose only a sequencer and an analysis port, and let the agent build and connect its own internals from is_active — then reuse that one agent everywhere through its configuration (active to drive, passive to observe); never copy-paste its components, because duplicating the protocol logic forks it and the copy drifts into a stale, bug-missing fork.

Next — The Active Agent: the agent's active mode in depth — how an active agent builds and wires its full sequencer-driver-monitor trio to generate stimulus and observe an interface it controls, the connection between the driver and sequencer, and when an interface calls for an active agent.