Agents and adapters

Clients publish facts and request work. The host decides which directly wired Go implementation handles that work. Keep the distinction between an explicit request, a continuously listening room agent, and a native provider adapter.

Each extension point has its own concept page: delegations, room agents, adapters, and tools.

Choose the smallest extension point

A channel handle is not an adapter, and a selector is not a work queue. A subscription delivers its eligible records to its consumer; it does not distribute each record to exactly one worker in a consumer group.

Request work from a client

Subscribe to progress before starting the request, using replay to cover any handshake race:

const progress = room.subscribe({
  selector: {eventTypes: ["delegation.*"]},
  onEvent: event => updateTaskView(event),
});

Then request the work:

const task = await room.delegate({
  task_key: "shipment-summary",
  revision: 1,
  objective: "Summarize the shipment discussion.",
  capabilities: ["reasoning.ask"],
  idempotency_key: crypto.randomUUID(),
});

updateTaskView is your reducer for the runtime's delegation event payloads. The requester needs delegation:start on shipment-summary. Reading delegation events also requires the applicable event:subscribe grants; reading the snapshot projection requires delegation:read on the task key.

task.id identifies the execution. task_key identifies the logical product task, revision expresses a newer request for that task, and idempotency_key identifies a retry. basis_seq records the room position used as the work's basis; completion may occur after newer room events. A result is not proof that it incorporates every fact visible when it finishes.

⤢ Expand

room.ask(question, idempotencyKey?) is the smaller convenience API for the runtime's ask flow and requires ask on *. The credential-free adapter echoes the objective in a structured result; it does not perform model reasoning. Use the current provider adapter when you want model-backed work.

Understand work lifetime

The runtime records requested work, emits progress, and commits the accepted terminal outcome. A newer revision can supersede older work; cancellation, failures, and restart interruption are distinct from successful completion. Update the task UI for every terminal status, including failures and interruptions.

The SDK exposes statuses requested, running, complete, failed, cancelled, superseded, and interrupted. Use the returned delegation ID to cancel with room.cancelDelegation(id). Cancellation asks the implementation to stop through context cancellation; it cannot undo an external side effect already performed.

Read runtime delegation handling, delegation storage, and the HTTP reasoner tests.

Wire an adapter in Go

The minimal requested-work interface is:

type DelegationAdapter interface {
    Descriptor() AdapterDescriptor
    Run(context.Context, DelegationRequest, RoomSnapshot, ProgressEmitter) (json.RawMessage, error)
}

These names are defined in the rmc package; this is an interface excerpt, not a standalone Go program. An adapter descriptor advertises capabilities. The registry selects an adapter that satisfies all required capabilities, sorts by increasing priority, and uses ID as the tie-breaker. Lower numeric priority wins. There is no runtime adapter-control API to configure here.

For a concrete starting point, the deterministic adapter implements this entire contract in a small file. The server entry point shows direct registration. The example reasoner adapter shows a purpose-built HTTP boundary without a remote processor host.

React to events with a room agent

Use a room agent when selected events should trigger a reaction automatically. The host registers its grants and subscriptions, and clients consume its derived outputs as ordinary room events.

Each agent has its own worker and processes its inputs serially. It starts at the current room position after restart, so it is appropriate only when missed triggers do not need automatic replay. The room-agent concept explains lifetime and feedback; the extension tutorial provides a runnable implementation.

Extend only for a concrete need

Start with the integration catalog to find an existing implementation. For a new service, define its input, result, authority, and failure behavior before choosing an adapter.

Use semantic contracts for the current HTTP reasoner exchange. If the existing contracts cannot support the product flow, record the missing behavior in the open architecture questions.