Agent

Agent SDK 是什么，以及如何运行 Agent 工作

Agent SDK (@downcity/agent) 是执行 Agent 工作的核心运行时。Agent 负责身份、模型、指令、 Tool 与唯一的 AgentSessions 集合；每个 Session 可以接收一个 Workspace。City 持有 Workspace、 Power 唯一实例、Agent/Group 集合与 transport。

Agent 做什么

  • 读取项目配置（构造参数或项目目录）
  • 维护会话和对话历史
  • 在执行过程中调用工具
  • 使用 City 投影到当前作用域的 Power 能力
  • 绑定到模型进行推理

创建 Agent

在 Desktop 中点击“创建 Agent”会进入独立创建页面。你可以用自然语言描述想要的角色，让系统默认模型自动生成名称、简介、角色指令和推荐 Powers；也可以选择“手动配置”，从空白草稿开始填写。AI 只负责生成可编辑草稿，确认后才会真正创建 Agent。

创建时不需要手动设计内部 ID。Desktop 会根据名称生成稳定 ID；例如“研究助手”会生成 yan_jiu_zhu_shou。

AI 生成和 Agent 运行模型都默认选中 Desktop 设置中的系统默认文本模型，也可以分别调整；仅当默认模型不可用时才回退到第一个可用文本模型。Desktop 页面统一展示 Agent 名称，稳定 ID 只用于内部路由和存储。

名称和简介用于联系人列表与对话中的身份展示。内部 ID 继续用于本地目录、API 引用和运行时身份；如果名称生成的 ID 已存在，Desktop 会要求换一个名称，不会隐式追加随机后缀。

创建后可以在 Agent 配置中继续修改名称和简介。修改名称不会改变稳定 Agent ID，因此已有 Session、Group 引用和 Power 数据路径保持不变。

Agent 配置中的“删除 Agent”会永久删除该 Agent 的定义、头像、Session、日志、Schedule 与 Agent 作用域的 Power 数据。正在执行任务或仍属于 Group 的 Agent 不能删除，需要先结束执行或将它移出相关 Group。

Desktop 完成提醒

当 Agent Session 在后台完成一次 Turn 时，Desktop 会在 Chat Sidebar 的 Agent 和下方对话列表的对应 Session 上显示蓝色未读圆点，并在系统应用图标上显示未读 Session 数量。正在前台查看该 Session 时不会产生未读；打开对应 Session 后，圆点和系统角标会同步清除。多次完成同一个 Session 只计为一个未读项。

创建 Group

点击“创建 Group”会进入独立创建页面。你可以描述团队目标，让所选模型根据当前已有 Agent 生成 Group 名称、协作目标和推荐成员；也可以从空白配置手动选择模型与成员。AI 结果在确认前始终只是可编辑草稿。

创建 Group 时只填写用户可见名称，内部 group_id 由 Desktop 根据名称自动生成。创建后可以修改名称、协作目标、模型与成员，但稳定 group_id 不会改变。Group 头像由成员 Agent 的头像组合展示。

import { Agent } from "@downcity/agent";
import { City } from "@downcity/city";
import { create_builtin_power_registrations } from "@downcity/powers";
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],
  powers: create_builtin_power_registrations(),
});
city.agents.add(agent);

从历史消息创建 Session 分支

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

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

需要在当前对话中替换历史时，传入 replace: true：

await session.fork({ message_id, include_message: false, replace: true });

这会原地移除锚点及后续消息，保留当前 Session ID 与配置，不创建分支、不归档、不添加操作提示。当前 Session 必须空闲；省略 message_id 时不改变历史。Desktop 的“替换当前对话”使用该方式。

设置 Desktop Agent 头像

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

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

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

新建 Agent 时，Desktop 会从内置像素头像池随机选择一张并保存为该 Agent 的独立头像。在 Agent 详情页点击头像，可以再次随机选择内置头像或上传自定义图片。

关键概念

  • City — 持有 Workspace、Power 唯一实例、Agent/Group 集合与统一 transport。
  • Session — 一个执行线程。Agent 按需创建会话，并通过它们路由消息。
  • Tool — Agent 在执行过程中可调用的函数。直接传给构造函数。
  • Power — 由 City 提供和维护，并自动投影给全部 Agent 的扩展能力。
  • Model — 推理后端。Agent 持有默认实例，Session 可设置自己的实例并优先使用。

Agent 不做什么

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

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

执行模型

Agent 执行模型很简单：

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

继续阅读：