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 gatewayrpc://...: 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
prompthistoryfork
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.