Agent Class

The local Agent exposes the following main public API:

• new Agent(options)
• agent.ready()
• agent.dispose()
• agent.sessions
• agent.get_logger()
• agent.get_shell()
• agent.plugins

agent.sessions.create() and agent.sessions.get() return AgentSession.

Hosts use explicit Agent capabilities such as workspace, sessions, plugins, get_logger(), and get_shell(). PluginContext is projected internally to plugins; it is not a host API or a second copy of Agent state.

Sessions

agent.sessions returns an AgentSessions with the following methods:

• agent.sessions.create(input?)
• agent.sessions.get(session_id)
• agent.sessions.list(input?)
• agent.sessions.archive({ id })
• agent.sessions.archived(input?)
• agent.sessions.clean_archive()
• agent.sessions.remove(session_id)
• agent.sessions.clear_messages(session_id)

archive({ id }) moves an existing non-executing session to the archive. archived(input?) lists archived sessions and clean_archive() permanently removes them. remove(session_id) permanently deletes one local Session's Agent-owned data. clear_messages(session_id) clears only its messages and keeps the Session.

Constructor options

• id
• workspace
• tools
• instruction
• model
• plugins
• session_class

There is currently no mode constructor option.

model is the AgentModel instance held by the Agent and can be either an AI SDK LanguageModel or a City CityModel. A local Session can hold its own AgentModel through session.set({ model }); execution prefers the Session model and falls back to the Agent model. The SDK does not persist or restore model instances or model IDs.

Full project and Plugin configuration belongs to an upstream host such as the CLI. The host constructs Plugin instances and passes them through plugins; Agent does not read, mutate, or persist that control-plane configuration.

Workspace env

Environment belongs to Workspace rather than Agent. Workspace reads the project .env, then applies explicit constructor env overrides. Use workspace.get_env(), workspace.set_env(next), and workspace.patch_env(patch) to manage it. Existing Sessions commit changes at the next step checkpoint; an in-flight provider request and its tools keep the already effective snapshot.

ready() and dispose()

After new Agent(...), plugin lifecycle and ActionSchedule start automatically.

• await agent.ready() waits for Plugin lifecycle and ActionSchedule startup. Session entry points already wait for the current Agent before model execution; call ready() when you need an explicit checkpoint.
• await agent.dispose() stops plugin lifecycle, ActionSchedule, and shell.

RPC and HTTP exposure

The Agent itself no longer starts any transport. Use @downcity/server when you need RPC or HTTP:

import { AgentRPC, AgentHTTP } from "@downcity/server";

const rpc = new AgentRPC(agent);
await rpc.listen({ host: "127.0.0.1", port: 15314 });

const http = new AgentHTTP(agent);
await http.server().listen({ host: "127.0.0.1", port: 5314 });