Understand the Agent SDK public surface in everyday, advanced, and framework-integration layers

SDK Surface

The @downcity/agent root exports the complete extension surface, but ordinary applications do not need every export. Start with the everyday core, then enter the Session, Plugin, or transport integration layer only when required.

Layer 1: everyday core

Most local applications need only:

Workspace: create the project resource and security boundary and receive Shell.
Agent: compose the model, instructions, Tools, plugins, and Sessions.
agent.sessions.create() / get(): create or restore a Session.
session.prompt(): start one Turn.
turn.finished: await the final result.
agent.dispose(): release Agent and its exclusive Workspace.

const workspace = new Workspace({ path, shell });
const agent = new Agent({ id, workspace, model });

try {
  const session = await agent.sessions.create();
  const turn = await session.prompt({ query: "Inspect the project" });
  const result = await turn.finished;
} finally {
  await agent.dispose();
}

The local SDK is session-first: Agent performs composition, while Session owns interaction and execution state.

Layer 2: common advanced APIs

Agent and Workspace

agent.ready(): wait for Plugin runtime when an explicit startup checkpoint is needed.
agent.set_instruction(): update static Agent instructions.
agent.plugins: inspect, control, or call plugins.
workspace.get_env() / set_env() / patch_env(): manage the project execution environment.
agent.get_logger() / get_shell(): host integration entry points.

Session

get_info(): read Session state.
subscribe(): subscribe to live Mutations.
messages(): load message snapshots.
stop(): stop the current execution.
system(): load the current system.
interactions() / respond(): handle approvals, questions, and other user interactions.
fork(): branch from an existing Session.
snapshot() / syncshot(): manage local Session system snapshots.
set({ model }): override the model for one local Session.

For a live UI, load initial Session and Message snapshots before calling subscribe(). Reload snapshots after reconnecting; the event stream is not a complete database.

Layer 3: framework integration

Use these capabilities only when building plugins, servers, or custom runtime components:

PluginContext: the stable capability view projected from Agent to a Plugin; hosts should not acquire or retain it.
SessionTurnContext: the execution context that coordinates identity, lifecycle, steps, input, and output for one Turn; plugins receive only its read-only PluginExecutionContext projection.
create_session_turn_context(...): the standard factory used by custom executors or runtime components to create that Turn Context.
Interfaces such as AgentSession and SessionExecutor: replace or extend default implementations.
RPC/HTTP types: implement a custom transport or protocol integration.

Network server implementations belong to @downcity/server. Local Agent does not listen on ports or manage transport lifecycle.

Local and remote

Capability	Local `Agent`	`RemoteAgent`
Create, get, and list Sessions	Yes	Yes
Prompt, subscribe, messages, stop, approvals, and fork	Yes	Yes
Inject Workspace, Shell, Tools, and plugins	Yes	No
Set the Agent default model	Yes	No
`session.set({ model })`	Yes	No
`session.set({ security })` / `session.status()`	Yes	Yes
`snapshot()` / `syncshot()`	Yes	No
Manage the server transport	Not responsible	Connects only

The server host always owns the model and system persistence policy for a remote Session.

Lifecycle rules

one Workspace instance → one Agent → one agent.dispose()

The caller constructs Workspace; Agent releases it after binding.
Multiple Agents may target the same physical directory, but each needs a separate Workspace instance.
agent.dispose() releases Plugin runtime, Workspace, Shell, PTYs, and Sandbox.
RemoteAgent.close() closes only the client connection, not the server-side Agent.

Continue with the Agent API and Sessions overview.

SDK Surface

Table of Contents