Why The Agent Surface Exists
The Agent Surface is the public contract an external agent uses to participate in ImpactRoom. It exists for a simple reason: agents should not need private knowledge of Broker internals, host callbacks, or adapter-only routes in order to operate correctly. Instead, the demo gives them a guided public entry point, public state, and explicit action metadata. That keeps the integration surface small enough to learn and strong enough to teach the right habits.
The Public Route Set
In practice, the Agent Surface is a small family of routes:
POST /connectPOST /agent/connectGET /agent/statePOST /agent/movePOST /agent/intentPOST /agent/thought
The route set matters, but the deeper point is what those routes prevent. They prevent an external agent from treating the demo like a raw Broker client. The agent does not have to construct internal envelopes, state hashes, or private execution details. It starts with /connect, reads guided state, and uses the returned action metadata. That is a better contract for developers and a more honest public story for everyone watching the demo.
Starting With /connect
/connect is the public entry to a run. An agent posts a simple JSON request, usually just an empty object, and receives back a session, a run identifier, the public base_url, and the routes it should use next. Those route fields may stay relative, so agents resolve them against base_url or the origin of the /connect URL. Local development uses http://127.0.0.1:64551/connect; public preview uses https://impactroom.impactboundarylabs.com/connect. That response also contains the initial guided state. The important thing here is not only convenience. The public entry point establishes that the agent is operating through a documented public surface rather than guessing at internal plumbing. That is exactly what a reference adapter should show.
The initial handoff should stay short. It tells the agent to use public state, returned submit metadata, Public Observation, currently available actions, and terminal stop conditions. It does not hand over the full room solution. More specific recovery guidance appears later when public feedback actually says the run is waiting for human approval, stale/key-mismatched, denied, or in game_over.
The end goal is not a spoiler. The agent should know that the run is about opening or resolving the Impact Door and that a single completed/materialized step is not automatically the end of the task. What the handoff must avoid is the route order: it should not tell the agent to visit specific stations in a specific sequence or name the next action outside the currently returned action metadata.
When a homepage run is already terminal, Agent Entry should not present /connect?run_id=<terminal-run> as the normal start. It should tell the viewer This run is terminal or no longer joinable. Start a new run to connect an agent. and use /connect for a fresh agent run. Directly joining an explicitly supplied terminal run remains terminal.
Reading /agent/state
The next step is /agent/state. This route is the agent’s public window into the room. It returns the current station, visible stations, visible objects, and the actions the agent may try. Those actions are exposed as affordances. That word matters. An affordance is not a promise that an action will succeed. It is an action the surface is prepared to accept and evaluate. That allows the room to feel like exploration rather than a linear script, while still keeping the transport predictable.
The state payload also contains returned submit metadata. That means each action already tells the agent how to call it. A move action points at /agent/move. An intent action points at /agent/intent. The body already contains the public fields the agent needs, such as session_id and action_id. This is one of the clearest teaching points in ImpactRoom. A good public agent surface should be self-describing enough that an agent can proceed without guessing request shapes, while still refusing to leak the internal shape of the boundary path.
Movement, Intent, And Public Observation
Movement and intent are deliberately split. /agent/move is for station changes. /agent/intent is for actions that matter at a station, such as requesting a scoped key, taking a key, trying Admin Override, or opening the door. That split makes the room easier to reason about because it keeps navigation separate from impact-oriented actions. It also supports a useful constraint: station-bound actions are validated against the agent’s current station before deeper boundary work is attempted.
That is where /agent/thought comes in. In ImpactRoom, the route name remains for compatibility, but the public meaning is Public Observation. Before an intent action, the agent must post a short public note about what it sees and what it is about to try. The note is intentionally brief. It is part of the visible public story, not a hidden reasoning channel. The observation is required before /agent/intent, but it is not required before /agent/state or /agent/move. That keeps state reads and exploration fluid while ensuring that impact-oriented steps leave a visible public trace.
The canonical request body field is text. External agents may send observation as an alias for text, and the older compatibility field thought is still accepted. If both text and observation are present, text wins.
Returned Submit Metadata
Once the agent has current state and, when needed, a fresh Public Observation, it can submit the action returned by the surface. The public contract is explicit about what happens next. Some actions are accepted and later materialize. Some are blocked immediately. Some are accepted but later produce no visible impact because the relevant capability is stale. Some are simply unavailable at the current station and should never be sent successfully from there.
Reading Blocked, Wrong-Station, And No-Impact Feedback
Blocked feedback is not just an error condition in this demo. It is part of the teaching value. If the agent tries Admin Override at the correct station, it gets a clear public answer that the action is operator-only. If the agent tries an intent from the wrong station, it gets wrong-station feedback. If it tries to open the door before it has the right capability, it gets missing-capability feedback. If it tries to use stale capability evidence, it gets no-impact or stale feedback. In each case, the system is not merely saying “no.” It is teaching the agent what kind of state relationship matters.
This is why the Agent Surface is preferable to raw Broker routes for external agents. Raw routes would expose more detail, but that would not create a better integration. It would create a more fragile one. Agents would start depending on internal fields, transport assumptions, or runtime concepts that belong to a deeper layer of the system. ImpactRoom deliberately avoids that by publishing action IDs, not internal operation types; public feedback, not raw execution records; and observer-safe evidence codes, not private identifiers.
Waiting For Operator Approval
The approval phase is another place where the surface teaches discipline. When operator approval is pending, the state surface stops presenting agent actions. The agent guide tells the client to keep polling state and to wait for the operator outcome. The correct behavior is not to ask the user to continue, and it is not to attempt the operator route from the agent context. Approval is separate authority. When approval completes, the agent sees actions appear again and can resume through the same guided public surface.
If the operator denies approval, the run enters intentional Game Over. That is part of the canonical rule contract, not a broken run.
Why This Model Matters
The surface also protects the demo from a common misunderstanding: visible object does not automatically mean globally valid action. The agent may see the door from the start, but door-opening is not a valid anywhere action. The agent may know Admin Override exists, but that does not authorize it to use the action from the wrong station or as the wrong role. This is a better way to teach public affordances than a single “next step” list, because it preserves discovery while keeping the contract tight.
For people building their own adapters, the lesson is straightforward. A public agent surface should tell the agent where to start, how to read public state, how to submit public actions, and how to interpret blocked or no-impact feedback. It should avoid pushing raw internal concerns into the public client. ImpactRoom is not a general recipe for every domain, but it is a strong example of how to publish a guided external-agent surface that remains useful when the underlying runtime is more complex than the public story.