Agent 配置完整设计

范围与对象模型

Agent 是可复用的执行配置，可以选择关联持久状态。它不要求专门职责、人格、固定模型、工作目录、长期记忆或后台计划。Agents 页面保存的配置与 Python 临时配置使用同一套执行语义。

保留 AgentSpec 作为持久化对象，AgentConfig 是其中执行字段的类型化投影，不增加第二份磁盘注册表。资源管理、上下文引擎、记忆 backend 与任务控制继续由现有子系统负责。

源码核对与现有差距

这里是源码核对结果，不是重新执行的端到端验收。当前六页界面已在默认 App 中查看；新增目标配置未安装。CodeGraph 没有可用索引，检查使用限定范围的源码读取。文档不声明新增运行能力已完成。

配置结构与默认值

首期不加入任意 provider 参数、命名 Agent 之间多层继承、自定义执行引擎或任意记忆插件。匿名配置从系统默认值开始，不隐式复制调用方 Agent 的其他字段。描述可以为空，保存 Agent 只要求名称；已有可用默认模型时无需再选模型。

线格式与类型边界

以下为目标线格式，ID 均为示例。保留现有扁平 AgentSpec，新增类型字段，不嵌套第二份注册表。POST 接受 name 与可选执行字段；除合法旧版显式 ID 外，id/revision/时间戳由服务端分配。AgentConfig 只含执行字段。导出/导入不携带服务端元数据，导入保存时分配新身份。Python 包在 agent、llm 同一公开位置导出 AgentConfig；允许带 provider 的模型字符串作为简写，统一转成持久化的 provider/id 对象。

{
  "schema_version": 2,
  "id": "general",
  "name": "General",
  "revision": 1,
  "model": {"provider": "provider-id", "id": "model-id"},
  "system_prompt": "",
  "tools": {"mode": "selected", "allowed": ["tool_a"], "disabled": []},
  "skills": {"mode": "none"},
  "mcp": {"mode": "none"},
  "memory": {"mode": "off"},
  "context": {"history": "clean"}
}

PATCH /api/agents/general
{
  "expected_revision": 1,
  "system_prompt": "Use concise answers.",
  "memory": {"mode": "off"},
  "reset_fields": ["model", "thinking_effort"]
}

memory 包含 mode、可选 read_spaces: string[]、write_space: string、required: boolean（默认 false）。启用读取至少需要一个授权空间，read_write 必须有且仅有一个同时可读的写入目标。off 使绑定不生效但不删除已存数据；编辑器可在草稿保留未启用的绑定，实际执行不获得记忆权限。instruction_files 每项包含 path: string 与 required: boolean（默认 true），路径限于 Agent workspace。未知字段、类型错误、同字段同时出现在 reset_fields 与修改值中，均在写入前拒绝。就绪信息与保存配置分开返回。

统一解析与明确合并规则

基础配置只选一个来源，依次是显式 agent_id、显式 config、当前 Agent、系统默认。agent_id 与 config 互斥。只有继续同一 Agent 身份时才应用当前会话覆盖；切换 Agent 或临时配置，不继承旧 Agent 的模型、指令、工具与记忆绑定。随后应用经过授权的本次覆盖，最后执行权限约束；每次有副作用的操作仍重新检查撤销权限。

派发被接受时固定生效快照、Agent revision、策略版本及相关目录/预设版本。排队任务保留此意图，启动时重查撤销和必需资源。重试与恢复使用原快照，不读取后来修改的配置；独立新一轮重新解析。来源记录保存引用与散列，不保存凭据。

公开调用与执行边界

以下 API 是目标接口，尚未实现。在现有 Python agent()、llm() 中加入 agent_id、config、overrides 与历史选择，不建立另一套执行器。llm() 不执行 Python/Program/MCP 工具循环，即使选中 Agent 允许这些工具。保留显式 web_search=True 的 provider 原生搜索，并执行相同原生能力权限检查；仅选择 Agent 不会自动启用搜索。输出校验与返回类型保持不变。

from openprogram import Agent



agent(prompt, agent_id="reviewer", history="selected", context_nodes=[node_id])

class ExampleAgent(Agent):
    method_options = {
        'extract': {'tool': True},
        'classify': {'tool': True},
    }

    def extract(self, document):
        return agent(document, agent_id="my-agent",
                     overrides={"memory": {"mode": "off"}},
                     response_format=Result)

    def classify(self, document):
        return llm(document,
                   config=AgentConfig(model="provider:model", memory={"mode": "off"}),
                   response_format=Label)

_example_agent = ExampleAgent()
extract = _example_agent.extract
classify = _example_agent.classify

通过上下文局部作用域绑定不可变生效配置，在 finally 中恢复，包括异常和取消。不得修改共享 Runtime.model 或进程级当前 Agent。指定 Agent 不存在时明确报错，不回退 main。聊天切换 Agent 默认开始新上下文；保留历史必须明确选择，并说明数据已在历史中出现。

可选记忆：访问、保留与写入

read_spaces 保存稳定引用：self、指定项目或明确选择的共享空间。write_space 只有一个，且必须也可读。保存 Agent 的 self 解析成自身空间；匿名配置没有持久身份，因此 self 无效。匿名配置可以显式绑定项目或共享空间，而无需保存 Agent。新 Agent 开启记忆时默认 self，不静默复制原全局记忆。

• 关闭不删除记忆、不关闭会话历史，也不移除用户提供的指令文件。已检索并出现在消息中的内容不能被撤回；需要全新上下文才能避免后续请求继续看到它。关闭读取后，待返回的检索结果在进入模型前也要重新校验。
• 每个执行节点记录记忆写入资格、空间引用和策略 epoch。会话结束 writer、压缩前提取、来源导出、定时整理必须排除 off/read_only 节点，不能通过扫描原始历史再次写入。关闭写入时阻止该范围尚未提交的排队写入，重新开启也不补写关闭期间内容；此前提交的记忆保留。派生输出和摘要继承实际输入上下文中最严格的记忆写入资格，拆分或更换 Agent 不能把受限数据改成可写。off 传播禁止写入限制，但不自动禁止后来执行中独立获授权的读取。对用户手动提供且不在已有来源记录内的文本，不承诺能自动识别其原始策略。
• 后台写入提交前同时验证原执行授权与当前空间策略。撤销权限优先于固定配置；外部 backend 无法取消的操作需要明确说明。不能失败后换到权限更大的空间。
• 关闭是框架记忆策略，不是文件系统沙箱。如果 shell 或文件工具仍可读取记忆文件，应展示限制；严格隔离需要环境策略强制执行。用户指令和上传文件即使包含个人信息，仍属于明确输入。
• 可选记忆 backend 失败时显示降级状态并无记忆继续；required=true 则在模型执行前失败。写入失败保留任务结果，单独显示保存失败。
• 首期不提供 write_only。复用 MemoryBackend；无法强制命名空间与访问范围的 backend 不允许开启空间隔离，不能靠提示词模拟隔离。

上下文、指令与环境

clean 表示不继承对话消息，不表示移除系统或项目策略。指定历史节点必须检查调用方可见范围，同属 DAG 不等于有权访问。存储历史与模型实际上下文分开。默认继续保存执行记录，本设计不增加“无痕运行”的保留承诺。

持久化指令文件使用限定在 Agent workspace 允许列表内的路径引用；内容与散列在现有受保护执行存储中形成快照。Agent workspace 与项目 cwd 分别表达，cwd 不代表访问权限。环境配置不可用或主机/沙箱不兼容时明确失败。上下文长度沿用 Context Engine，不增加第二个摘要器，也不手动拼接原始工具结果。

能力范围与权限

Programs、Skills、MCP 和 provider 目录拥有能力定义与凭据；Agent 保存引用与默认选择。运行时先解析请求范围，再与用户授权、父执行委派上限、项目/环境限制、全局可用性和显式拒绝取交集。all 只表示当前可用且获授权的全部项目，不意味着有权使用所有已安装集成。

• selected 空列表在存储、发现和调用中都表示空。失效引用保留并显示 Missing。必需 MCP 必须同时允许且可用，矛盾规则保存时拒绝。
• 会话和本次执行可以覆盖偏好，不能扩大强制上限。调用方的范围如果是委派限制，更换 agent_id 后仍然生效。拒绝的覆盖需要说明，不能显示为已应用。
• 能力发现、按名称加载、技能加载和真正调用使用同一解析策略。provider 原生 web search 等动作也受能力控制；tools=[] 本身不代表全面网络限制。
• 账户与服务引用由现有凭据服务解析，AgentSpec、快照、导出和示例不保存原始密钥。Anthropic 只使用官方 API 与合法 API key，并按 API 账户计费。
• Agent allowlist 不会把主机已授权的任意 Python 代码变成沙箱；工具和嵌套 agentic 调用仍在公开入口执行检查。

能力和选择器细节分别由分项文档负责。资源管理文档继续定义准入、用量、取消和配额；本页只引用现有配置并展示生效限制。

多 Agent 组合与选择

运行分支、Job、消息和 attach 的详细契约见协作设计与协作架构图，数量和执行预算见资源治理。保存 Agent 配置与运行分支分别管理；公开执行 ID、查询/取消入口及当前完成回送差距以协作设计的实现状态为准。

选择保存配置不要求指定角色。只选模型、只改表达风格、关闭记忆、使用项目记忆，都属于有效 Agent。并发复用一份配置创建多个 run，不创建多个保存 Agent。

单次成功不自动持久化配置变更、新技能或长期偏好。长期更新使用已有明确配置、技能或记忆写入机制并保留来源。角色编排、自动拓扑生成和市场发布不在本范围。可选 Agent/模型选择由实施计划 P6 完整定义，在所有入口支持显式选择之后实现。

管理 API 与原子持久化

updated_at 仅用于展示和临时旧客户端适配；旧时间戳也在同一写锁内比较，再使用取得的 revision。新客户端使用 expected_revision。两种前置条件均缺少时返回 428，版本过期 409，结构错误 400，范围无权限 403，ID 不存在 404。依赖不可用使用明确预检错误，不回退其他配置。允许保存不可用引用并显示就绪警告，但必需依赖缺失时禁止启动。未知 schema 版本拒绝解析且不重写文件。

文件存储保留唯一 agent.json 并原子替换。创建、默认指针、删除涉及索引和多个资源时使用小型恢复日志，不能把多次 os.replace 称为事务。启动时先处理未完成意图，再接受写入。删除 Agent 不删除共享记忆、全局凭据或任意外部工作目录。会话/DAG 引用按实际存储枚举，不能假设都在 Agent 目录下。

生命周期、导出与失败处理

• 匿名 AgentConfig 不创建侧栏条目、工作目录或记忆目录，保存为 Agent 是独立操作。新建保存对象只初始化配置；可选指令文件由明确操作或旧版兼容初始化创建。
• 复制创建新配置身份，不复制会话、已学习记忆、计划或凭据。共享空间仍是引用，必须在复制预览中显示。复制指令文件正文是可选独立操作，不能与复制引用混淆。
• 导出只包含可移植配置和明确选择的指令文本，排除记忆、历史、机器路径、凭据与自动计划。导入校验格式、解析能力引用、预览权限，不启动执行。
• 删除非默认且空闲的 Agent 时枚举自有与引用资源。私有记忆可以保留或明确删除，共享记忆不能由此操作删除。被标记删除的 ID 不再接受新执行，未完成清理可见且可重试。
• 预检失败不发模型请求、不执行工具。保存失败保留整份草稿。Provider 故障沿用有上限重试，不静默更换模型或策略。取消必须恢复调用作用域，不能被记录为成功。
• 配置编辑影响新执行；显式拒绝和权限撤销在活跃执行的下个访问边界生效。关闭记忆写入还会使未提交写入失效。界面说明区别，不能暗示已经发出的推理请求能够撤回。

参考资料与设计取舍

参考资料用于对照产品和配置概念，不作为内部实现已验证的证据。无固定版本的官方页面可能变化，以表内列明能力作为对照范围。不声称研究创新、基准优势或自动路由已实现。

可观察验收契约

场景输入、文件范围、阶段验证和执行顺序由实施计划负责。文档静态检查通过不代表这些运行时验收条件已满足。

已保存的专用 Agent

决策、轻量助手和统筹规划是普通的已保存 Agent。显式安装操作通过现有 manager 在配置锁内创建缺少的记录，保留已有同名 ID、用户修改和默认 Agent。读取列表不创建记录，删除后不自动重建。产品没有模板目录或模板选择。

三者是现有 Agent 类的固定参数配置，通过 AgentSpec 和 Agent.from_spec 解析，不添加角色 system prompt。任务和指令由调用处与 Context 提供，空的保存指令不会清除调用处已有指令。决策通过 Agent.choose 从给定选项中选一项：复用现有选择解析器，执行一次无工具的 llm 请求，不增加角色提示词、顾问式回答或自动重选。它返回选中项的 ID，非法答案直接报错；调用保留当前 Context 和 DAG 作用域。决策和轻量任务关闭工具；统筹规划可以检查证据并委派已授权任务。模型可编辑；本地安装明确指定已配置且可用的模型。角色名称不保证费用或输出质量。

页面布局

页面分为已保存 Agent 列表和完整宽度的编辑区。二级导航复用共享 ManagePage 布局与侧栏宽度变量，不为 Agents 单独设置桌面宽度。详情标题只显示名称、ID 和对话操作。七个顶部标签在所有宽度下都使用横向排列，空间不足时滚动。常规分区只显示名称、用途、模型和思考参数。可选的手动指令在高级分区编辑，保留原有草稿和调用行为。常规分区不设置内部导航列、重复说明标题或配置摘要。输入内容使用正常字重，字段标签使用中等字重。统一沿用应用字体、中性背景、控件尺寸和蓝色选中提示。全部配置分区填满标准内边距之间的可用宽度，不设置固定内容宽度上限。编辑区独立滚动，保存区固定可见。窄屏用下拉选择替代 Agent 列表，身份字段纵向排列。已保存但不兼容的思考强度继续显示，未编辑时不作为新错误播报。

验收

三个保存记录可见且可编辑，没有模板选择；重复安装保留用户修改；Agent.from_spec 能执行保存记录。草稿、冲突、复制和对话操作继续工作。紧凑保存区显示草稿状态；继承的旧设置不在未编辑时触发表单错误。通过真实 React 页面和默认 App 检查桌面与窄屏布局。

专用保存 Agent 已通过独立规格与质量审查。合并后的常规编辑区和顶部配置标签已在源码中实现，审查与验收证据保存在交付记录中。公开登记保留、Agent.from_spec 执行、模型选择、草稿与冲突处理，以及响应式键盘导航均通过检查。安装版 App 验收另行记录。

实现状态

生产 Agents 页面已使用七分区编辑器、共享草稿、模型目录选择、保存冲突比较和原有动态图标。配置增加 description、revision、原子条件保存，以及新配置默认关闭、旧配置保持共享读写的记忆策略。Web 新对话使用已保存 Agent，独立试运行保存只读或关闭记忆的会话快照；必需 MCP 缺失时在模型请求前失败。

记忆权限作用于执行、后台提取、派生结果与恢复入口；提交前重新检查策略 epoch。实际空间为 self 与 legacy_global。产品使用方法见 配置 Agent。

完整 schema 2 迁移、多文件生命周期事务、统一 Python AgentConfig 接口、所有调用入口的解析一致性、任意共享空间目录、有效配置预览、内嵌试运行面板、便携导入导出及自动 Agent/模型选择仍是目标设计。不能将当前 Web 实现视为整个方案验收完成。实际提交、测试命令和安装验收结果由交付记录保存。