Agent Class
The core public API of the local Agent SDK
Agent is the reusable execution subject of the local SDK. It owns a stable ID, visible name, capability description, instruction, model, custom Tools, and its Session collection. The host provides Powers and Workspace resources. agent.sessions.self() opens its main conversation with type: "chat", kind: "main".
Public API
new Agent(options)agent.idagent.nameagent.descriptionagent.workspaceagent.sessions.self({ workspace? })agent.sessions.create({ workspace })agent.sessions.get(session_id, type?, { workspace? })agent.set_instruction(input)agent.get_instructions()agent.reconfigure(input)agent.get_logger()agent.dispose()
Every Session is created and restored through agent.sessions. Returned Sessions and summaries expose top-level id, type, kind and optional parent. Ordinary work lists use { type: "work", kind: "work" }:
const session = await agent.sessions.self({ workspace });
const turn = await session.prompt({ query: "How is this repository structured?" });
const work = await agent.sessions.create({ workspace });A session writes configuration with set and reads state with get, sharing one handle:
await session.set({ model }); // write
session.get("workspace"); // runtime instance
session.get("workspace_id"); // persisted identifierReconfiguring an Agent in place
reconfigure updates identity and defaults without replacing the instance. Omitted fields keep their current value:
agent.reconfigure({
name: "Writing assistant",
instruction: ["Outline first, then draft."],
model: next_model,
});The difference from rebuilding the Agent is that execution state survives: the instance, its Session collection, and the running Turn all stay, so configuration can be saved while a session is still working. Changes apply to subsequent reads:
| Field | Takes effect |
|---|---|
name, description | Immediately, including the tool-call context, Power context, Group prompts, and system identity |
instruction | Immediately for new Sessions; created Sessions need an explicit syncshot() |
model | The next Step; a Session-level model override still wins |
A running Turn always finishes with the system and model snapshotted when it started. A created Session freezes
its system on first assembly, so a host that wants it to see a new instruction should call session.syncshot()
on idle sessions. Name and description are not part of that snapshot; they are read live in every call context.
Model-facing Agent Power
Once an agent joins a City, its Sessions can use the agent Power:
agent.list: list City agents with theiragent_id, name, responsibility description, default model, and whether they are the current agent.agent.create: create a persistent agent fromname,description,instruction, andmodel_id. Execution requires user approval. The new agent becomes discoverable throughagent.listafter creation.
Desktop and CLI hosts save the definition, assemble the model, and register the agent. Custom City hosts provide this capability through runtime.create_agent; the callback returns an agent that has been persisted and registered in the current City, and rolls back on failure.
Use the separate session Tool to start work with a target agent or continue a conversation. See Managing Sessions.
Constructor options
id: stable Agent identity and private data partition key.name: optional user-visible name; defaults toid.description: optional concise capability profile used for display and semantic Group dispatch.tools: custom Tools available to Sessions created by this Agent.callbacks: request-completion handler registry. Select a handler withprompt({ request_id, query, callback: { name, data } })for durable delivery after execution. See Managing Sessions.instruction: static Agent-level base instruction.model: defaultModelClient; a local Session may override it.workspace: optional default Workspace for new Sessions; existing ownership remains fixed.session_class: optional custom local Session class.
workspace only sets the default directory for new sessions. It does not affect the agent's identity
and does not restrict which directories the agent may use later; when omitted, new sessions have no
project context. Each Session determines its Workspace through the { workspace } option at creation. Restoration accepts only execution resources with the same ID. See Agent chat and
Managing Sessions.
One Agent may work across multiple Workspaces. City provides Powers, and every City Power is
automatically available to every City Agent. Callers create an explicit execution view with
city.powers.scope({ agent_id: agent.id, workspace_id: workspace.id }). agent.dispose() releases Sessions and the current City binding. Network
transports remain owned by the host.