The UVM Agent

📋 What an Agent Is

A UVM agent is a self-contained verification component that handles all testbench interactions with a single protocol interface. It bundles together the sequencer, driver, and monitor for that interface into one reusable package — a Verification IP (VIP) unit.

The agent is the lowest-level structural block in a UVM testbench. Once an agent is written for a given protocol (APB, AXI, SPI, I2C, USB), it can be dropped into any testbench that uses that protocol — at block level, at integration level, or at chip level — without modification. The environment does not need to know how the agent was implemented internally; it just instantiates it, configures it, and connects its analysis port.

📋 Active vs Passive Mode

Every UVM agent inherits an is_active field from uvm_agent of type uvm_active_passive_enum. This single flag controls whether the agent drives stimulus or only observes.

The is_active field is set through the agent’s configuration object — not directly on the agent. The test creates the config object, sets is_active to UVM_ACTIVE or UVM_PASSIVE, and places it in config_db. The agent retrieves this config in its build_phase and uses it to decide what to instantiate.

📋 Agent Internals

📋 The Agent Config Object

Every well-designed agent has a configuration object — a uvm_object that holds all the settings the agent needs to be built and operated. The config object decouples the agent’s construction from the test: the test creates and populates the config object, passes it to the agent through config_db, and the agent uses it in build_phase without needing to know who configured it.

The three mandatory members of any agent config object are:

• Virtual interface handle — the agent cannot drive or observe the DUT without access to the interface
• is_active flag — controls active vs passive mode
• has_* flags — optional enable/disable flags for optional sub-components (coverage monitor, scoreboard)

// ── Agent configuration object ───────────────────────────
class apb_agent_config extends uvm_object;
  `uvm_object_utils(apb_agent_config)

  // ① Virtual interface — connects agent to DUT signals
  virtual apb_if  vif;

  // ② Active/passive mode
  uvm_active_passive_enum is_active = UVM_ACTIVE;   // default: active

  // ③ Optional sub-component enables
  bit has_functional_coverage = 0;
  bit has_scoreboard          = 0;

  // Protocol-specific settings
  int num_wait_states  = 0;
  bit error_injection  = 0;

  function new(string name = "apb_agent_config");
    super.new(name);
  endfunction
endclass

📋 Build Phase — Conditional Construction

The agent’s build_phase has three responsibilities: retrieve the config object from config_db, always build the monitor, and conditionally build the sequencer and driver based on is_active.

class apb_agent extends uvm_agent;
  `uvm_component_utils(apb_agent)

  apb_driver    m_drv;
  apb_sequencer m_seqr;
  apb_monitor   m_mon;
  apb_agent_config m_cfg;

  uvm_analysis_port #(apb_seq_item) ap;  // forwarded from monitor

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  function void build_phase(uvm_phase phase);
    super.build_phase(phase);

    // ① Retrieve config — fatal if not found
    if (!uvm_config_db #(apb_agent_config)::get(
          this, "", "cfg", m_cfg))
      `uvm_fatal("CFG", "No agent config found!")

    // ② Create analysis port (always)
    ap = new("ap", this);

    // ③ Create monitor (always — active AND passive)
    m_mon = apb_monitor::type_id::create("m_mon", this);

    // ④ Create sequencer + driver only in active mode
    if (m_cfg.is_active == UVM_ACTIVE) begin
      m_seqr = apb_sequencer::type_id::create("m_seqr", this);
      m_drv  = apb_driver::type_id::create("m_drv", this);
    end

    // ⑤ Pass virtual interface to monitor (and driver if active)
    uvm_config_db #(virtual apb_if)::set(
      this, "m_mon", "vif", m_cfg.vif);
    if (m_cfg.is_active == UVM_ACTIVE)
      uvm_config_db #(virtual apb_if)::set(
        this, "m_drv", "vif", m_cfg.vif);
  endfunction
endclass

📋 Connect Phase — TLM Wiring

The connect_phase has two jobs: wire the driver’s seq_item_port to the sequencer’s seq_item_export (the TLM handshake path for sequence items), and forward the monitor’s analysis port to the agent’s own analysis port so external components can connect to the agent directly without knowing the monitor’s path.

  function void connect_phase(uvm_phase phase);
    // ① Connect driver to sequencer (active only)
    if (m_cfg.is_active == UVM_ACTIVE)
      m_drv.seq_item_port.connect(m_seqr.seq_item_export);

    // ② Forward monitor's analysis port to agent's analysis port
    // External consumers connect to agent.ap — not agent.m_mon.ap
    // This hides the internal structure from the environment
    m_mon.ap.connect(this.ap);
  endfunction

📋 The Agent Analysis Port

The agent exposes a single uvm_analysis_port as its public output interface. This port broadcasts every transaction the monitor captures to all connected subscribers — scoreboard, coverage collector, or any other analysis component in the environment.

The environment wires subscribers to the agent’s analysis port in its own connect_phase:

// In my_env's connect_phase:
function void connect_phase(uvm_phase phase);
  // Connect agent's analysis port to scoreboard and coverage
  m_agent.ap.connect(m_sb.analysis_export);
  m_agent.ap.connect(m_cov.analysis_export);
endfunction

📋 Complete Agent Implementation

The complete APB agent bringing all sections together:

typedef uvm_sequencer #(apb_seq_item) apb_sequencer;  // simple typedef

class apb_agent extends uvm_agent;
  `uvm_component_utils(apb_agent)

  // Sub-component handles
  apb_driver        m_drv;
  apb_sequencer     m_seqr;
  apb_monitor       m_mon;
  apb_agent_config  m_cfg;

  // Public analysis port — env connects subscribers here
  uvm_analysis_port #(apb_seq_item) ap;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

  function void build_phase(uvm_phase phase);
    super.build_phase(phase);
    if (!uvm_config_db #(apb_agent_config)::get(
          this, "", "cfg", m_cfg))
      `uvm_fatal("CFG", "apb_agent: no config found")

    ap    = new("ap", this);
    m_mon = apb_monitor::type_id::create("m_mon", this);

    if (m_cfg.is_active == UVM_ACTIVE) begin
      m_seqr = apb_sequencer::type_id::create("m_seqr", this);
      m_drv  = apb_driver::type_id::create("m_drv", this);
    end

    uvm_config_db #(virtual apb_if)::set(
      this, "m_mon", "vif", m_cfg.vif);
    if (m_cfg.is_active == UVM_ACTIVE)
      uvm_config_db #(virtual apb_if)::set(
        this, "m_drv", "vif", m_cfg.vif);
  endfunction

  function void connect_phase(uvm_phase phase);
    if (m_cfg.is_active == UVM_ACTIVE)
      m_drv.seq_item_port.connect(m_seqr.seq_item_export);
    m_mon.ap.connect(this.ap);   // forward monitor port to agent port
  endfunction

endclass

📋 Agent Reuse Across Levels

A correctly designed agent can be plugged into any environment at any level of the integration hierarchy without modification. The config object controls everything; the agent adapts to whatever context it finds itself in.

📋 Quick Reference