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.id
  • agent.name
  • agent.description
  • agent.workspace
  • agent.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 identifier

Reconfiguring 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:

FieldTakes effect
name, descriptionImmediately, including the tool-call context, Power context, Group prompts, and system identity
instructionImmediately for new Sessions; created Sessions need an explicit syncshot()
modelThe 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 their agent_id, name, responsibility description, default model, and whether they are the current agent.
  • agent.create: create a persistent agent from name, description, instruction, and model_id. Execution requires user approval. The new agent becomes discoverable through agent.list after 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 to id.
  • 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 with prompt({ request_id, query, callback: { name, data } }) for durable delivery after execution. See Managing Sessions.
  • instruction: static Agent-level base instruction.
  • model: default ModelClient; 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.