Integrating the Agent Rooms HTTP API into your application

The API adapter does not choose your infrastructure

@agentplat/rooms-api wraps injected Room services using Hono. It does not select a database or server for the application. The API reference specifies core routes and identifies optional routes by the service that enables them.

Document the capabilities your host actually exposes. A client built against an execution or planner route cannot assume that every AgentPlat deployment has configured that service. A missing optional route may indicate composition, rather than a temporary networking problem.

Resolve identity before handling domain input

The health endpoint is public; other routes require authenticated tenant context. The development header authenticator is only a trusted local convenience. Production identity must come from verification performed by the host.

Check both tenant access and actor authorization. The API reference describes reserved-field handling and actor binding for specific lifecycle actions, while the integration guidance requires application authorization around actor-controlled operations. Do not generalize one route's protection to every body field in every package version.

Read the envelope and status together

Successful responses use a data envelope; failures use an error object with a code and message. Creation, accepted asynchronous work and successful reads have different status codes.

For example, a documented intervention request returning 202 means work was accepted. It does not mean the provider applied it. A client should retain the returned identity and inspect the subsequent execution state. Keep diagnostic details restricted to the intended environment rather than exposing raw adapter errors to end users.

Treat a revision conflict as new information

Operations exposing expectedRevision use compare-and-set semantics. If a write conflicts, re-read the resource and decide whether the intended transition still applies. Repeating the stale payload indefinitely cannot resolve the competing change.

Preserve stable logical identities during retries. A new identifier can accidentally turn a retry into separate work. Work-management retry also has a current lease-token requirement, so it should not share a generic blind-retry handler with ordinary reads.

Build a small integration contract test

• Verify that health is reachable under the intended network policy.
• Reject missing identity and unauthorized tenant access.
• Create and retrieve one Room through the documented envelope.
• Exercise one asynchronous operation and observe its later outcome.
• Trigger a revision conflict and confirm deliberate re-reading.
• Handle an absent optional service without misreporting completion.

Use the exact TypeScript exports and package README for request bodies. This article explains client behavior; it does not replace the version-specific API contract.