Agent

The Agent SDK (@downcity/agent) is the core runtime for executing agent work. An Agent owns identity, model, instructions, Tools, and one AgentSessions collection. Each Session may receive a Workspace. City owns Workspaces, unique Plugin instances, Agent/Group collections, and transports.

What an Agent does

Reads project config (constructor options or a project directory)
Maintains sessions and conversation history
Calls tools during execution
Uses Plugin capabilities projected by City into the current scope
Binds to a model for inference

Creating an Agent

Selecting “Create Agent” opens a dedicated creation page. Describe the role in natural language to let the system default model draft its name, description, instructions, and recommended plugins, or choose manual configuration to start with an empty draft. AI output remains editable and nothing is persisted until you confirm creation.

The editor preselects the system default text model and only falls back when it is unavailable. Desktop surfaces display Agent names throughout the UI; stable IDs remain internal routing and storage references.

The name and description identify the Agent in contacts and conversations. The generated ID remains the stable reference used by local directories, APIs, and runtime ownership. If the generated ID already exists, Desktop asks for another name instead of silently adding a random suffix.

You can edit the name and description later without changing the stable Agent ID. Desktop also supports permanent deletion of the Agent definition, avatar, sessions, logs, schedules, and Agent-scoped plugin data. An Agent cannot be deleted while it is running or still belongs to a Group.

Desktop completion notifications

When an Agent Session finishes a Turn in the background, Desktop shows a blue unread dot on the Agent and on the corresponding Session in the lower conversation list of the Chat Sidebar. The system app icon also shows the number of unread Sessions. No unread item is created while you are actively viewing that Session; opening it clears both the dots and the system badge. Multiple completed Turns in the same Session are grouped into one unread item.

Setting a Desktop Agent avatar

When creating an Agent, Desktop randomly selects an image from its built-in pixel avatar pool and saves it as that Agent's independent avatar. Click the avatar on the Agent details page to select another built-in avatar at random or upload a custom PNG, JPEG, or WebP image up to 2 MiB.

Creating a Group

Selecting “Create Group” opens a dedicated creation page. Describe the collaboration goal to let the selected model draft a Group name, collaboration instructions, and recommended members from the existing Agents, or start with manual configuration. AI output remains an editable draft until you confirm it.

You only provide the visible Group name. Desktop derives the stable internal group_id from that name. The name, instructions, model, and members remain editable later without changing the stable ID. The Group avatar is composed from its member Agent avatars.

import { Agent } from "@downcity/agent";
import { City } from "@downcity/city";
import { create_builtin_plugin_registrations } from "@downcity/plugins";
import { Workspace } from "@downcity/city";
import { Shell } from "@downcity/city";
import { MicrosandboxProvider } from "@downcity/sandbox-microsandbox";

const agent = new Agent({
  id: "repo-helper",
  model: myModel,
  tools: { my_tool: myTool },
});
const workspace = new Workspace({
  id: "project",
  path: "/path/to/project",
  shell: new Shell({
    sandbox_provider: new MicrosandboxProvider(),
  }),
});
const city = new City({
  workspaces: [workspace],
  plugins: create_builtin_plugin_registrations(),
});
city.agents.add(agent);

Key concepts

City — owns Workspaces, unique Plugin instances, Agent/Group collections, and unified transports.
Session — one execution thread. The Agent creates sessions on demand and routes messages through them.
Tool — a function the Agent can call during execution. Passed directly to the constructor.
Plugin — an extension capability provided and owned by City, then projected to every Agent.
Model — the inference backend. The Agent holds the default instance, and a Session can override it with its own instance.

What an Agent is not responsible for

Managing multiple projects (that is the CLI / Console layer).
Owning the model catalog (that is City / Federation).
Persisting global credentials (that is City).

Keeping these boundaries clear makes it easy to answer: where should I configure a model? Where should a bot credential live? Is this a control-plane failure or a project-runtime failure?

Execution model

The Agent execution model is simple:

Receive a message or task
Load the session context (history, tools, plugins, prompts)
Call the model
If the model asks for a tool, execute it and continue
Return the result

Continue with:

Agent

Table of Contents