Struct Agent 

pub struct Agent<H> {

    pub id: AgentId,
    pub consumer_group: Option<ConsumerGroupName>,
    pub listen_on: AgentTopic<'static>,
    pub handler: H,
    pub respond_on: Option<AgentTopic<'static>>,
    pub inbox_route: InboxRoute,
    pub poll_interval: Option<Duration>,
    pub shutdown_grace: Option<Duration>,
    pub concurrency: Option<ConcurrencyPolicy>,
    pub max_queued_records: Option<usize>,
    pub max_queued_bytes: Option<usize>,
    pub warm_dedup: bool,
    pub middleware: Vec<Arc<dyn AgentMiddleware>>,
    pub on_dead_letter: Option<Arc<dyn DeadLetterSink>>,
    pub operations: Option<Vec<String>>,
    pub sessions: Option<SessionConfig>,
    pub dedup_window: Option<usize>,
    pub retry: Option<RetryPolicy>,
    pub understood_features: u64,
    pub deduplicator: Option<Box<dyn Deduplicator>>,
    pub verifier: Option<Arc<KeyRegistry>>,
    pub signing_key: Option<Arc<SigningKey>>,
    pub capabilities: Vec<CapabilityDescriptor>,
    pub ack_on_pickup: bool,
    pub consolidate_every: Option<Duration>,
    pub consolidator: Option<SharedConsolidator>,
    pub governor: Option<(Arc<dyn ActionGovernor>, GovernorMode)>,
    pub governor_retention: Option<GovernorRetention>,
}

One logical agent defaults to one Iggy consumer group.

spawn derives the group name from id unless consumer_group is set. Horizontal scaling (multiple replicas of the same agent) means multiple processes joining that group, and Iggy load-balances messages across them.

Do NOT put two different agent ids in the same group. The ReliableConsumer skips messages whose agdx.to does not match its own id, which is the right behavior when a publisher addresses a specific agent on a shared topic. If two agents shared a group, Iggy would still deliver each message to exactly one member, and if it landed on the wrong one the filter would drop it and the intended agent would never see it. Each Agent::builder().id(...).spawn(..) call is its own consumer group. Do not bypass that by reusing the consumer group name across distinct agent ids.

Fields

id: AgentId

The agent’s stable logical identity.

consumer_group: Option<ConsumerGroupName>

Deployment group for load balancing replicas. Defaults to the agent id’s spelling but remains a distinct type and may be overridden explicitly.

listen_on: AgentTopic<'static>

The topic this agent consumes.

handler: H

The handler invoked for each message.

respond_on: Option<AgentTopic<'static>>

Default reply topic for AgentCtx::respond (none = respond errors).

inbox_route: InboxRoute

Default route from a resolved target agent to the topic its work is sent on, used by AgentCtx::fan_out and the directed-send helpers. Sticks as this agent’s routing convention. Defaults to InboxRoute::Advertised (resolve each target to its live-presence inbox). Set InboxRoute::Fixed for a workflow topic the caller owns.

poll_interval: Option<Duration>

Override the consumer poll interval (default: the runtime’s reactive 10ms).

shutdown_grace: Option<Duration>

How long AgentHandle::shutdown waits for the in-flight message to finish draining before the consumer is dropped. AgentHandle::abort is the unconditional hard stop. Defaults to the consumer’s 30s grace.

concurrency: Option<ConcurrencyPolicy>

How message handling is scheduled across the partitions this agent is assigned. Defaults to ConcurrencyPolicy::Serial. Set ConcurrencyPolicy::SerialPerPartition so a slow or retrying message on one partition does not stall the others.

max_queued_records: Option<usize>

Override the total records buffered across partition lanes.

max_queued_bytes: Option<usize>

Override the total payload and header bytes buffered across partition lanes.

warm_dedup: bool

middleware: Vec<Arc<dyn AgentMiddleware>>

Cross-cutting hooks wrapped around each handler dispatch, in order, for auth, metrics, and tracing without touching the handler.

on_dead_letter: Option<Arc<dyn DeadLetterSink>>

Notified on every dead-letter with the result of publishing it, so a lost poison message is an observable event rather than only a log line.

operations: Option<Vec<String>>

The command operations the handler serves. Unset serves every operation. A command for another operation is skipped.

sessions: Option<SessionConfig>

The session configuration the agent’s runtime applies: the lens AgentCtx::session opens and SessionConfig::fail_on_dead_letter. Defaults to SessionConfig::default.

dedup_window: Option<usize>

Override the dedup window size (recent idempotency keys kept in memory). Defaults to the ReliableConsumer default when unset.

retry: Option<RetryPolicy>

Override the handler retry policy (attempts + backoff for a retryable handler error). Defaults to the RetryPolicy default when unset.

understood_features: u64

Must-understand AGDX feature bits implemented by this agent. A message requiring any other bit is dead-lettered before the handler runs.

deduplicator: Option<Box<dyn Deduplicator>>

Override the dedup backend (e.g. a durable StateStore-backed one). Defaults to the in-memory sliding window.

verifier: Option<Arc<KeyRegistry>>

The signature verifier for control and effect topics: when set, every message’s envelope signature is verified against this registry before dispatch, and an unsigned or unverified record is dead-lettered. This is the enforcement gate for authorship and authorization, so it is reachable from the primary builder rather than only the lower-level consumer.

signing_key: Option<Arc<SigningKey>>

This agent’s signing identity: when set, AgentCtx::respond answers a correlated command with a signed AGDX response instead of a plain reply, so a caller holding a verifier (and the contract path’s signer binding) can accept this agent’s terminals and no one else’s.

capabilities: Vec<CapabilityDescriptor>

What this agent serves. When non-empty, on spawn the agent publishes a capability card to the registry (so capability routing can discover it) and advertises its inbox (its listen_on topic) as live presence (so a fan-out resolves where to send it work). Empty means a private agent that does not advertise, the prior behavior.

ack_on_pickup: bool

Emit a Working status the moment an AGDX command is picked up, before the handler runs, so a Laser::contract caller can tell the command was consumed. Off by default. Enable it on agents that take contracted work, with a respond_on set.

consolidate_every: Option<Duration>

Run consolidator every consolidate_every off the handler loop (its own task, stopped with the agent). Both must be set for the tick to exist. Absent means no background consolidation, ever. Each pass runs over this agent’s own memory: the scope carries the agent id and nothing else. A zero period fails the agent with LaserError::Config instead of starting.

consolidator: Option<SharedConsolidator>

The consolidation pass the periodic tick runs (see consolidate_every).

governor: Option<(Arc<dyn ActionGovernor>, GovernorMode)>

The pre-effect policy hook applied to everything this agent’s handler publishes (ctx.send/respond/request/fan_out, AGDX verbs, memory writes), with the GovernorMode it runs under. Spawn re-scopes the agent’s Laser with it, so a governor set on the connection is replaced for this agent. See Laser::with_governor.

governor_retention: Option<GovernorRetention>

Process-local evidence-chain retention for this agent’s governor. A restart or eviction begins a new local chain for the conversation.

Implementations

impl<H> Agent<H>

pub fn builder() -> AgentBuilder<H>

Create an instance of Agent using the builder syntax

impl<H> Agent<H>

where H: AgentHandler + Sync + Send + 'static,

pub fn spawn(self, laser: Laser) -> AgentHandle

Spawn the agent on laser as its own consumer group, returning a handle to stop it.