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. It owns neither Powers nor a Workspace; chat() exposes the conversation that belongs to the agent itself.

Public API

  • new Agent(options)
  • agent.id
  • agent.name
  • agent.description
  • agent.workspace
  • agent.session({ workspace? })
  • agent.sessions.create({ workspace })
  • agent.sessions.get(session_id, origin_type?, { workspace? })
  • agent.set_instruction(input)
  • agent.get_instructions()
  • agent.get_logger()
  • agent.dispose()

The agent itself is a session; get it with session(). Every session, including that one, is created and restored through agent.sessions:

const session = await agent.session({ 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, workspace });   // write
session.get("workspace");                   // runtime instance
session.get("workspace_id");                // persisted identifier

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.
  • instruction: static Agent-level base instruction.
  • model: default ModelClient; a local Session may override it.
  • workspace: optional default directory for new sessions; not a binding, and switchable per session.
  • 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 picks its own directory through session.set({ workspace }) or the { workspace } option at creation. 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.