Room agents

A room agent is an embedded Go participant that reacts to selected room events and publishes derived events. Use it for automatic behavior, such as producing an observation when a message arrives.

Choose an event-driven trigger

Use a room agent when the event itself should trigger the behavior. Use a delegation when a client requests a task with a tracked result.

For example, a message-statistics agent reads chat and publishes a word count to measurements. Other clients subscribe to the derived event through the same room API. The agent needs permission to read its input and publish its output.

Implement the small host contract

// Interface excerpt from package rmc.
type RoomAgent interface {
    Descriptor() RoomAgentDescriptor
    Handle(context.Context, RoomAgentRequest) ([]EventInput, error)
}

The descriptor declares the agent's identity, grants, and selected events. The handler receives the event and authorized context, then returns publications that RMC checks and commits under the agent's identity.

The extension tutorial implements the message-statistics example, including validation, registration, and cleanup.

Make lifetime and feedback explicit

Each agent processes events serially in its own per-room worker. Other agents can progress independently; their output still joins the room's shared event order.

Agents skip their own outputs. Events from other registered agents are excluded unless IncludeAgentEvents is enabled. Enable that option only when agents are intended to react to one another.

A worker starts at the room's current position and does not replay missed triggers after restart. Choose a consumer with persisted progress if the product requires that recovery. See extension failure behavior.

Keep the execution boundary clear

Embedded agents are trusted code running inside the RMC process. Participant grants govern their room operations, but do not sandbox their filesystem or network access.

Read the contract and worker implementation when implementing an agent. The work guide compares agents, delegations, and tools.