RemoteAgent Class
The core public API of the remote Agent client
RemoteAgent exposes the following main public API:
new RemoteAgent({ url })agent.sessionsagent.run_power_action(input)
agent.sessions.create() and agent.sessions.get() return RemoteAgentSession with top-level id, type, kind and optional parent. Remote conversation creation defaults to type: "chat", kind: "remote"; pass an explicit pair for other entry points. Ordinary work lists use { type: "work", kind: "work" }.
Sessions
agent.sessions returns an AgentSessions with the following methods:
agent.sessions.create(input?)agent.sessions.get(session_id, type = "work")agent.sessions.list(input?)agent.sessions.archive({ id, type? })agent.sessions.archived(input?)agent.sessions.clean_archive()
run_power_action
Use run_power_action() when your client UI needs to call an action on the remote runtime.
await agent.run_power_action({
power: "example",
action: "refresh",
payload: {
scope: "current-session",
},
});Shell approvals belong to the specific remote Session, not the top-level RemoteAgent:
const interactions = await session.interactions();
await session.respond({
interaction_id: interactions[0].request.interaction_id,
response: { type: "approval", outcome: "resolved", payload: { decision: "approved" } },
});You can also handle a pending Interaction through the unified Mutation stream:
session.subscribe((mutation) => {
if (mutation.variant !== "part" || mutation.part.type !== "tool") return;
const interaction = (mutation.part.interactions ?? []).find(
(item) => item.status === "pending",
);
if (interaction) render_interaction(interaction);
});Browser and Chrome extension entry
Use the browser entry for HTTP/HTTPS without bundling Node networking or filesystem modules:
import { RemoteCity, type PromptPower } from "@downcity/city/browser";
const city = new RemoteCity({ url: "http://127.0.0.1:5314" });
const agents = await city.agents.list();
const agent = await city.agents.get(agents[0].id);
const session = await agent.sessions.create({ type: "chat", kind: "chrome" });Agent discovery is filtered by the supplied credentials, and agents.get() verifies access again. RemoteCity currently supports HTTP/HTTPS and is also exported from the Node entry. Callers pass the City root URL without building Agent paths. Call await city.close() to release owned subscriptions and execution channels. Keep the caller page or extension panel open until the Turn finishes so it can execute its Powers.
Request-level Powers
Supply caller-owned Powers directly to session.prompt(). The SDK manages their execution channel and cleanup for that Turn.
import type { PromptPower } from "@downcity/agent";
const browser_power: PromptPower = {
name: "browser",
description: "Read the caller's current page",
actions: {
read_page: {
access: "read",
input_schema: {
type: "object",
properties: {},
additionalProperties: false,
},
execute: async (_input, context) => {
context.abort_signal.throwIfAborted();
return { title: document.title };
},
},
},
};
const turn = await session.prompt({
query: "Analyze the current page",
powers: [browser_power],
});
const result = await turn.finished;This example runs in a browser caller. Functions stay in that caller; the server receives serializable descriptions and forwards Action requests. Local Sessions, HTTP/HTTPS and RPC support the same Prompt shape.
Powers apply only to the current Turn. Later prompts, forks and delegated Sessions do not inherit them. Duplicate tool names are rejected. A nonempty powers array can only be installed when starting a Turn, not replaced by follow-up inputs. Every prompt requires a trusted host-bound actor; a different actor receives busy until the Turn ends. Actions return JSON values; files, runtime handles and cross-host messages are not supported. The default Action timeout is 60 seconds; timeout_ms can increase it to at most 5 minutes.
Use context.call_id for business idempotency and context.abort_signal for cooperative cancellation. Cancellation cannot undo external effects. A disconnected execution channel interrupts the Turn without automatically replaying writes. Reusing request_id with different input or Power descriptions is rejected; an interrupted execution cannot be taken over by resubmission.
To export an existing City Power, use export_prompt_power(power, host, resolve_site, instruction?) from @downcity/city/power. The caller supplies its own runtime and maps remote identities to locally authorized resources. City lifecycle, hooks, HTTP routes and UI registrations are not exported.
url
The current constructor shape is:
new RemoteAgent({
url: "http://127.0.0.1:5314",
});not baseUrl.
url currently supports:
http://...https://...rpc://...
Core semantics
It does not execute tasks by itself. It only connects to remote session capability.
If the local Agent is the execution shell on the server side, RemoteAgent is the paired client.