Agent

Agent SDK (@downcity/agent) 是执行 Agent 工作的核心运行时。Agent 实例在执行时进入 Workspace，并通过 AgentWorkspace 组合会话、工具、插件和模型。City 是宿主进程内 Agent 实例的生命周期容器。

Agent 做什么

读取项目配置（构造参数或项目目录）
维护会话和对话历史
在执行过程中调用工具
运行扩展其能力的插件
绑定到模型进行推理

创建 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() }),
});

从历史消息创建 Session 分支

session.fork() 默认保留锚点消息。编辑并重新发送历史消息时，可以排除原消息，让新 Session 从修改后的内容继续：

const forked_session = await session.fork({
  message_id,
  include_message: false,
});

设置 Desktop Agent 头像

Desktop 会从用户级 Agent 目录读取头像。将图片放在对应 Agent ID 目录下即可：

~/.downcity/agents/<agent_id>/avatar.png

也支持 avatar.jpg、avatar.jpeg 和 avatar.webp，头像文件大小限制为 2 MiB。未配置头像时，Desktop 使用默认图标。

在 Desktop 的 Agent 详情页点击头像，可以通过右侧编辑栏随机生成 Downcity Ghost 头像、选择自定义图片或移除头像。

关键概念

City — 持有一个或多个已经实例化的 Agent，并在宿主退出时统一释放。它不读取 Registry，也不决定 Agent 是否应当运行。
Session — 一个执行线程。Agent 按需创建会话，并通过它们路由消息。
Tool — Agent 在执行过程中可调用的函数。直接传给构造函数。
Plugin — 扩展 Agent 能力的模块，如聊天、任务或记忆。也直接传给构造函数。
Model — 推理后端。Agent 持有默认实例，Session 可设置自己的实例并优先使用。

Agent 不做什么

不管理多个项目（那是 CLI / 控制台层）。
不拥有模型目录（那是 City / Federation）。
不持久化全局凭证（那是 City）。

保持这些边界清晰，你很容易回答：模型应该在哪配置？机器人凭证应该放在哪？这是控制平面故障还是项目运行时故障？

执行模型

Agent 执行模型很简单：

接收消息或任务
加载会话上下文（历史、工具、插件、提示词）
调用模型
如果模型要求调用工具，执行它并继续
返回结果

继续阅读：