Transport Behavior

Understand the HTTP and RPC transport behavior used by RemoteAgent

RemoteAgent supports two transport shapes:

  • http://... / https://...: calls the SDK routes mounted by the Downcity City HTTP gateway
  • rpc://...: connects directly to the City RPC server

Session address and local management

Remote Session requests, subscription, model changes, interactions, fork and conditional stop carry origin.category. Roles such as agent or task are origin.type, not storage categories. For example, an Agent chat has category chat and type agent. stop(expected_turn_id) forwards the expected Turn unchanged and rejects a changed Turn.

City CLI verifies the current local host before using its Session transport. Agent/Workspace configuration and pure file-history browsing use the protected local management service; they are not remote HTTP management permissions. For local side-effect-free history, use AgentSessionBrowser as described in Managing Sessions. Event connection loss rejects pending remote waits with code: "transport_lost"; it does not fabricate a failed server Turn result. City CLI/TUI assign request_id before submission and verify reception and terminal state through the local persisted receipt service, without resending the prompt. Other SDK clients must separately verify persisted execution before deciding whether to retry.

Regular requests

For example:

  • create session
  • list sessions
  • prompt
  • history
  • fork

Those use normal JSON request-response exchanges.

Event subscription requests

Over HTTP, events uses an NDJSON-style long-lived response.

Over RPC, the same session events are delivered through the RPC connection.

For HTTP callers, the client receives JSON events one line at a time.

Each line can be treated as an independent session event.

What this means for callers

  • if you only care about one turn result, wait for turn.finished
  • if you are building a real-time UI, use subscribe()

If you want to show tool activity, progressive output, or real-time chat UI, subscribe() is usually the right fit.