Agent
Agent
What the Agent SDK is and how it runs agent work
Agent
The Agent SDK (@downcity/agent) is the core runtime for executing agent work. An Agent instance enters a Workspace and creates an AgentWorkspace containing sessions, tools, plugins, and a model. City is the lifecycle container for Agent instances inside one host process.
What an Agent does
- Reads project config (constructor options or a project directory)
- Maintains sessions and conversation history
- Calls tools during execution
- Runs plugins that extend its capabilities
- Binds to a model for inference
Creating an Agent
import { Agent } from "@downcity/agent";
import { Workspace } from "@downcity/workspace";
import { Shell } from "@downcity/workspace";
import { MacOsSeatbeltSandbox } from "@downcity/sandbox-macos";
const agent = new Agent({
id: "repo-helper",
model: myModel,
tools: { my_tool: myTool },
plugins: [myPlugin],
});
const workspace = new Workspace({
id: "project",
path: "/path/to/project",
shell: new Shell({ sandbox: new MacOsSeatbeltSandbox() }),
});Key concepts
- City — owns one or more instantiated Agents and disposes them when the host exits. It does not read the Registry or decide whether an Agent should run.
- 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 — a module that extends the Agent with capabilities like chat, tasks, or memory. Also passed directly to the constructor.
- 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: