The Active Agent

Agents · Module 14 · Page 14.2

The Engineering Problem

The agent bundles a sequencer, driver, and monitor and switches between active and passive (Module 14.1). This chapter drills into the active configuration — the one that generates stimulus. An active agent is the testbench's instrument for an interface it controls: it drives transactions onto the interface and observes the result. But "active" is more than "has a driver" — it's a complete capability: a sequencer (so tests can run sequences to generate traffic), a driver (so that traffic reaches the pins), the connection between them (so the driver pulls from the sequencer), and a monitor (so the agent witnesses what it drove). The active agent must both act and observe on the same interface — and, subtly, its monitor must observe independently of its own driver, or it can't catch its own driving bugs. The problem this chapter solves is what makes an agent active, how the trio works together as a stimulus-and-observe loop, and when an interface calls for it — because making an agent active on the wrong interface makes its driver fight the DUT.

An active agent is the agent configured to drive and observe an interface the testbench controls. It builds the full trio — sequencer, driver, monitor — and wires the stimulus path: the driver's seq_item_port connects to the sequencer's seq_item_export, so a test can run sequences on the agent's sequencer to generate traffic that the driver drives onto the pins. Simultaneously, the agent's monitor observes that interface — independently of the driver (Module 13.1) — feeding the scoreboard and coverage. So an active agent is a complete cause-and-effect unit: it runs the experiment (drives stimulus) and independently measures the result (observes the pins). It is the configuration you use when the testbench masters the interface — driving requests into the DUT, or responses back to it. This chapter is the active agent: the sequencer-driver path that defines it, the act-and-observe loop, the driver/monitor independence inside one agent, and the contention bug from making an agent active where the DUT drives.

What makes an agent active — the sequencer-driver stimulus path that lets tests generate traffic onto an interface the testbench controls — and how does an active agent both drive stimulus and independently observe the result on the same interface?

Motivation — what "active" really provides

"Active" is a capability, not just a component count. The reasons it means stimulus generation on a controlled interface:

• Active is the stimulus-generating configuration. The whole point of an active agent is to put traffic on the interface. That requires a sequencer (to plan it), a driver (to drive it), and their connection (so the driver gets it) — the stimulus path that only active builds.
• Tests reach the interface through the agent's sequencer. A test generates traffic by running a sequence on agent.seqr — the sequencer only an active agent has. The sequencer is the active agent's user-facing handle: "run your stimulus here."
• An active agent both causes and witnesses. It drives the interface and its monitor observes the result — so a single active agent closes the loop: stimulus in, observation out, on the same interface. It's the complete interaction.
• The monitor stays independent of the driver — even inside one agent. The active agent's monitor observes the actual pins, not the driver's intent (Module 13.1). This independence is why the monitor can catch the driver's own bugs — the agent checks its own work against ground truth.
• Active means the testbench controls the interface. You make an agent active only where the testbench masters (drives) the interface. An active agent's driver asserts the interface signals — so it must be the rightful driver, or it collides with whoever else drives them.

The motivation, in one line: "active" means stimulus generation on a controlled interface — the active agent builds the sequencer-driver path so tests can run sequences to drive the interface, and keeps a monitor independently observing the result, making it a complete act-and-observe unit for an interface the testbench masters.

Mental Model

Hold the active agent as the experimenter who runs the experiment and independently measures the result:

An active agent is an experimenter at one apparatus: it runs the experiment — driving the inputs — and independently measures the outcome with its own instrument, so it both causes the behavior and witnesses the truth of it. Picture an interface as a lab apparatus the experimenter controls. The active agent is the experimenter, and it does two things. It runs the experiment — the sequencer decides what conditions to apply (the plan), and the driver is the hands that set the dials and push the inputs (drives the stimulus onto the apparatus). And it independently measures the outcome — the monitor is a separate instrument that reads what actually happens at the apparatus, regardless of what the experimenter intended. The crucial property is that the measuring instrument is independent of the hands: it reads the actual state of the apparatus, not "what the experimenter meant to do" — so if the hands slip (a driver bug) and set the wrong dial, the instrument shows the wrong reading, and the experiment catches its own mistake. This is what makes the active agent trustworthy even though one experimenter both acts and measures: the acting and the measuring are separate faculties, and the measuring is anchored to reality. Now, the experimenter only works at an apparatus it controls — its inputs to set. If it tried to "run the experiment" at an apparatus someone else was already driving, the two would fight over the same dials — both turning them, neither winning, the readings garbage. So an active experimenter belongs only at an apparatus it masters.

So the active agent is the experimenter who acts and independently measures: it runs the experiment (sequencer plans, driver drives the stimulus) and independently measures the outcome (monitor reads the actual pins) — causing the behavior and witnessing its truth, with the witnessing anchored to reality so it catches its own acting's errors. And it belongs only at an interface it controls — acting at an interface someone else drives means fighting over the dials.

Visual Explanation — the stimulus path defines "active"

The defining picture is the stimulus path — sequencer → driver → interface — present only in an active agent, alongside the monitor's observe path.

The figure shows the stimulus path that defines active. A test runs a sequence on the agent's sequencer — the sequencer is present only in active mode, and it's the handle tests use to generate traffic. The driver pulls each transaction from the sequencer (seq_item_port ↔ seq_item_export) and drives it onto the interface — this sequencer → driver → interface chain is the stimulus path, the defining structure of an active agent (it's exactly what passive lacks). Concurrently, the monitor observes that same interface and broadcasts what it saw to the scoreboard and coverage (Module 13.4) — the observe path, present in every agent. The crucial reading is that an active agent has both paths on one interface: the brand-colored stimulus path (sequencer, driver) drives the interface, and the success-colored observe path (monitor, analysis port) witnesses it. The interface is warning-colored because it is controlled by the testbench — the active agent's driver is its rightful master. What makes this agent active is precisely the presence of the brand-colored stimulus path: remove the sequencer, the driver, and their connection, and you have a passive agent (Module 14.3) — just the monitor path, observing without driving. The diagram is the anatomy of active: a complete trio where the stimulus path generates traffic and the monitor path witnesses it, both on the one interface the testbench controls — the do-and-watch unit in full.

RTL / Simulation Perspective — running a sequence through the active agent

In code, the active agent is used by a test that runs a sequence on the agent's sequencer; the driver pulls and drives, and the monitor observes. The code shows the test-to-agent stimulus flow.

// === The active agent builds the trio and wires the stimulus path (Module 14.1) ===
class my_agent extends uvm_agent;          // get_is_active() == UVM_ACTIVE
  my_sequencer seqr;  my_driver drv;  my_monitor mon;
  function void connect_phase(uvm_phase phase);
    drv.seq_item_port.connect(seqr.seq_item_export);  // STIMULUS PATH (active only)
    ap = mon.ap;                                       // observe path (always)
  endfunction
endclass
 
// === A test generates stimulus by running a sequence ON THE AGENT'S SEQUENCER ===
class my_test extends uvm_test;
  task run_phase(uvm_phase phase);
    my_sequence seq = my_sequence::type_id::create("seq");
    phase.raise_objection(this);
    seq.start(env.agent.seqr);             // ← run the sequence on the ACTIVE agent's sequencer
    phase.drop_objection(this);            //   driver pulls each item and drives it onto the pins
  endtask
endclass
 
// === Inside the driver: pull from the sequencer, drive the interface (Module 12.1) ===
task my_driver::run_phase(uvm_phase phase);
  forever begin
    seq_item_port.get_next_item(req);      // pull the next transaction from the sequencer
    drive(req);                            // drive it onto the interface
    seq_item_port.item_done();             // signal completion → sequencer sends the next
  end
endtask
// Meanwhile the monitor independently observes the SAME pins and broadcasts (Module 13).

The code shows the active agent's stimulus flow, from test to pins. The agent (active) builds the trio and, in connect_phase, wires the stimulus path (drv.seq_item_port.connect(seqr.seq_item_export)) and exports the monitor's port. The test generates stimulus by running a sequence on the agent's sequencer — seq.start(env.agent.seqr) — and this is the key: the test reaches the interface through agent.seqr, the sequencer only an active agent has. Once started, the driver (Module 12.1) pulls each transaction (get_next_item), drives it onto the interface, and signals item_done (which lets the sequencer send the next) — the stimulus path in motion. Meanwhile, the monitor independently observes the same pins and broadcasts (Module 13). The shape to carry: an active agent is driven by tests through its sequencer — seq.start(agent.seqr) is the entry point for all stimulus — and the driver-sequencer handshake (get_next_item/item_done) is the engine that turns sequences into pin activity. The monitor's concurrent, independent observation of those same pins is what closes the loop: the active agent drives the traffic and witnesses it, all from one unit a test steers by running sequences on its sequencer.

Verification Perspective — independent observation inside one agent

A subtle, critical property of the active agent: although the same agent contains both the driver and the monitor, they remain independent — the monitor observes the actual pins, not the driver's intent — which is what lets the agent catch its own driving bugs.

The figure shows the independence that makes an active agent self-checking. The driver — inside the agent — drives its intent onto the pins, and it may mis-drive (a driver bug). The monitor — in the same agent — observes the actual pins, not the driver's intent (Module 13.1's independence principle, unchanged by co-location). So if the driver mis-drove, the monitor reports the actual (wrong) pin values, the scoreboard compares actual vs expected, and the driver bug is caught — even though it's the agent's own driver. The verification insight is that co-locating the driver and monitor in one agent does not couple them: the monitor's observation is anchored to the pins (the observe path), not to the driver (the drive path), so the two remain independent faculties. This is essential — if the monitor trusted the driver's intent (read what the driver meant to drive instead of the actual pins), it would always agree with the driver and could never catch the driver's own bugs; the agent would be blind to itself. Because the monitor is independent, the active agent checks its own work: it drives via one path and witnesses via another, and the witness can contradict the driver — which is exactly what catches a driving error. The practical consequence: an active agent's monitor must observe the pins, even for the traffic its own driver generated — never short-circuit by having the monitor "know" what the driver drove. The figure is the argument that act and observe must stay separate even when bundled: the active agent is trustworthy because its observing is independent of its acting, so it can catch itself getting the acting wrong.

Runtime / Execution Flow — the act-and-observe loop

At run time, the active agent runs a cause-and-effect loop: the test runs a sequence, the driver drives it, the DUT responds, the monitor observes, the scoreboard checks. The flow shows the loop.

The flow is the active agent's cause-and-effect loop on one interface. Run (step 1): the test runs a sequence on the agent's sequencer — stimulus enters through agent.seqr, the only entry point for an active agent's traffic. Drive (step 2): the driver pulls each transaction and drives it onto the controlled interface — the act, the agent causing behavior. Respond (step 3): the DUT reacts to the stimulus on the interface. Observe (step 4): the monitor independently observes the resulting interface activity — the witness — and broadcasts it; the scoreboard checks it against expected. The runtime insight is that the active agent owns both ends of the cause-and-effect chain on its interface: it generates the cause (drive) and captures the effect (observe), feeding the check. This is why an active agent is the complete interface unit — a test needs only to run a sequence on its sequencer, and the agent handles the entire round trip: driving the stimulus, and witnessing (independently) what the DUT did with it. The loop also makes the active/passive distinction operational: an active agent participates in step 2 (it drives), while a passive agent (Module 14.3) skips steps 1–2 entirely (no test-driven stimulus through it) and only does step 4 (observe) — it witnesses an interface someone else drove. The flow is the active agent running the full experiment: steer it with a sequence, and it drives the cause and measures the effect, all on the interface it controls.

Waveform Perspective — driving and independently witnessing

The active agent's dual action is visible on a timeline: its driver drives the interface, and its monitor independently observes the actual pins — and that independence is what lets the monitor catch a driver discrepancy. The waveform shows both, including a caught mis-drive.

The waveform shows the active agent acting and independently witnessing — and the payoff of that independence. The agent's driver drives stimulus: drv_valid asserts and the interface carries the driven value. The first transaction is correct — the intended C7 appears on the pins, and the monitor observes it (mon_capture pulses, mon_value = C7). But the second transaction is a mis-drive: the sequence intended C7, yet the driver drove A0 onto the pins (a driver bug). The crucial visual is what the monitor reports: it observes the actual pins, so mon_value shows A0 — the real pin value, not the intent. The scoreboard, comparing the monitor's A0 against the expected C7, catches the agent's own driver bug — precisely because the monitor is anchored to the pins, not the driver's intent. The picture to carry is the two-path nature of the active agent on the waveform: the drive path (drv_valid, the driven pins) causes the activity, and the observe path (mon_capture, mon_value) witnesses it — and the witness reports what the pins actually carried, even when its own agent's driver got it wrong. Reading a waveform for active-agent behavior — is the driver driving the controlled interface? does the monitor's reported value match the actual pins (not the intent)? — confirms both that the agent acts and that its witness is independent. The independence is not academic: it's visible here as the monitor reporting A0 (truth) instead of C7 (intent), which is exactly what makes the active agent able to catch itself.

DebugLab — the active agent that fought the DUT

✗ ACTIVE agent on an interface the DUT DRIVES → two drivers fight → X:
  uvm_config_db#(uvm_active_passive_enum)::set(this, "out_agent", "is_active", UVM_ACTIVE);
  // out_agent builds a DRIVER → driver asserts the SAME signals the DUT drives
  // DUT drives the result bus  AND  agent's driver drives it  →  contention → X
 
✓ PASSIVE agent on a DUT-driven interface → observe only, no contention:
  uvm_config_db#(uvm_active_passive_enum)::set(this, "out_agent", "is_active", UVM_PASSIVE);
  // out_agent builds ONLY a monitor → observes the bus, drives NOTHING
  // DUT drives the result bus alone  →  clean values, monitor witnesses them

Common Mistakes

• Making an agent active on a DUT-driven interface. An active agent's driver fights the DUT (contention, X); use a passive agent to observe interfaces the DUT drives.
• Expecting stimulus from a passive agent. Only an active agent has a sequencer; running a sequence requires agent.seqr, which passive agents don't build.
• Letting the monitor trust the driver's intent. Even inside one active agent, the monitor must observe the actual pins, or it can't catch its own driver's bugs.
• Forgetting the sequencer-driver connection. Active mode must wire drv.seq_item_port to seqr.seq_item_export, or the driver's get_next_item hangs and no stimulus flows.
• Driving through the wrong handle. Tests generate stimulus via seq.start(agent.seqr); reaching into the driver directly bypasses the sequencer and the protocol.
• Assuming active is always right. Active is the default for controlled interfaces, but observe-only interfaces need passive — match the mode to who controls the interface.

Senior Design Review Notes

Interview Insights

Exercises

1. Identify the stimulus path. Name the three elements an active agent has that a passive one lacks, and the connection that links two of them.
2. Drive through the agent. Write the test code that generates stimulus on an active agent, and name the handle it targets.
3. Defend the independence. Explain why an active agent's monitor must observe the pins rather than the driver's intent, with an example of what it catches.
4. Choose the mode. For each, pick active or passive: a bus the testbench drives into the DUT; a result bus the DUT outputs; an internal DUT-to-DUT interface.

Summary

• An active agent is the agent configured to drive and observe an interface the testbench controls — it builds the full sequencer + driver + monitor trio and wires the stimulus path (driver's seq_item_port to sequencer's seq_item_export).
• The sequencer-driver path defines active: it's exactly what a passive agent lacks. Tests generate stimulus by running sequences on the agent's sequencer (seq.start(agent.seqr)) — the active agent's user-facing handle.
• An active agent is a complete cause-and-effect unit: it drives stimulus (the act) and its monitor independently observes the result (the witness), closing the loop on one interface and feeding the scoreboard.
• The monitor stays independent of the driver even inside one agent — it observes the actual pins, not the driver's intent — which is what lets the active agent catch its own driver's bugs.
• The durable rule of thumb: make an agent active only where the testbench masters the interface — it builds a driver that asserts the interface signals, so an active agent on a DUT-driven interface fights the DUT (contention, X); drive stimulus through the agent's sequencer, keep the monitor anchored to the actual pins so the agent checks its own work, and use a passive agent wherever you only observe.

Next — The Passive Agent: the active agent's counterpart — the passive mode in depth: an agent that builds only a monitor, observing an interface without driving it, for buses the DUT masters or internal interfaces you watch but don't control — and why passivity is the right (and only safe) choice there.