Agent

The Agent SDK (@downcity/agent) is the core runtime for executing agent work. An Agent instance assembles project config, sessions, tools, plugins, and a model into one execution context.

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";

const agent = new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  model: myModel,
  tools: [myTool],
  plugins: [myPlugin],
});

Key concepts

• 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. Passed directly to the constructor or set per-session.

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:

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

Continue with:

• Agent SDK
• Agent Lifecycle