Agent 运行时上下文

本页解释 Yuxi 如何从持久化 Agent 配置构建一次运行，以及配置、权限、文件和 LangGraph state 在运行中分别负责什么。Agent 配置和扩展开发见配置和开发智能体。

运行入口

普通聊天、恢复审批和子智能体运行都会从服务端事实重建 Context：

flowchart LR
    Request["请求 / resume"] --> Binding["Conversation 与 Agent 绑定"]
    Binding --> Config["Agent config_json.context"]
    Config --> Identity["uid / thread / run / request"]
    Identity --> Workspace["AGENTS.md / USER.md"]
    Workspace --> Prepare["按用户权限归一化资源"]
    Prepare --> Graph["get_graph(context)"]
    Graph --> State["LangGraph state + PostgreSQL checkpoint"]
    State --> Result["消息、事件、文件和产物"]

具体顺序是：

1. 新线程根据 agent_slug 查找当前用户可访问的 Agent；已有线程使用已绑定的 Agent。
2. 服务读取 config_json.context，加入当前用户和运行身份。
3. 运行入口读取用户工作区的 agents/AGENTS.md 和 agents/USER.md，把非空内容追加到系统提示词；文件不存在或不可读不会阻断运行，每个文件最多读取 64 KiB。
4. prepare_agent_runtime_context 重新按当前用户权限过滤工具、知识库、MCP、Skills 和子智能体，并展开 Skill 依赖。
5. 没有配置模型时，系统读取管理员设置的默认模型；然后 get_graph(context) 创建模型、工具和中间件。
6. LangGraph state 保存消息、待办、文件、产物和子智能体状态；checkpoint 只使用 PostgreSQL。

API/worker 不信任浏览器内存中的完整配置。请求可以提供受限的单次覆盖值，例如模型或工具审批模式；其余配置从已保存的 Agent 和用户权限重新计算。

配置和运行态的区别

数据	来源	生命周期
config_json.context	Agent 管理页面/管理 API	跨运行保存的配置
runtime.context	配置 + 用户身份 + 运行身份 + 权限快照	当前 Run
LangGraph state	Graph 执行和中间件	当前 checkpoint thread
PostgreSQL Message/AgentRun	服务和 worker 提交	业务事实和运行结果

中间件可以在 Graph 创建和模型请求之间派生运行时字段，例如 _visible_knowledge_bases、_effective_skill_slugs 和 token 快照。这些字段不是用户可以任意提交的权限声明。

资源权限

• tools、knowledges、mcps 和 skills 未配置时，使用当前用户可访问的全部资源；显式列表只保留列表中的资源；显式空列表不启用该类资源。
• ChatBotContext.subagents 未配置或保存空列表时，使用当前用户可见的全部子智能体；显式列表才会收窄范围。
• Agent 的知识库选择只能缩小用户已经拥有的读取权限。
• Skill 选择控制 Prompt 和工具激活；共享 Skill 的文件投影按用户授权生成，个人 Skill 位于 UserWorkspace。
• LITE 模式会关闭知识库、图谱和评估能力，知识库资源和 knowledge-base Skill 不会进入运行时。

资源快照只解决运行时“能看见哪些资源”。产生文件、知识库、MCP 或外部系统副作用的工具还要在执行处校验具体目标和当前身份。

文件和 Memory

当前 Project 的 workdir_path 决定 Agent 的默认工作目录。普通 Agent 和子 Agent 共享根 Conversation 的 Workdir 与 execution runtime；子 Agent 的 child thread 只隔离 LangGraph checkpoint，不隔离文件。

agents/MEMORY.md 只有在用户配置 enable_memory=true，且该文件存在并包含非空内容时，才由主 Agent 的 Memory middleware 读取并提供受限的记忆工具。它是用户主动维护的参考资料，不是系统指令；子 Agent 不直接使用该 middleware。Memory 读取和更新有独立的用户、Run、worker 和文件大小校验。

Viewer、附件和 artifact API 通过持久化 Workspace/Workdir 读取文件，不连接 Agent execution runtime。沙盒虚拟路径、Viewer scope、对象 URL 和宿主机路径在各自边界中转换，不能互相替代。

恢复和失败

审批或用户问题中断时，系统把中断信息保存在对应 Run/checkpoint。resume 会根据线程绑定的 Agent 和当前用户重新构建 Context，再创建新的 Run；它不会从相邻 Run 猜测模型、工具或文件结果。

如果 Agent 配置、模型、权限或工作区文件在两个 Run 之间发生变化，新的运行会使用新的有效配置；已完成 Run 的输出和事件仍绑定原来的 request_id、run_id 和消息。

源码和验证入口

• Context 与资源归一化
• BaseAgent
• Chatbot graph
• SubAgent graph
• Memory middleware
• 运行时上下文 unit
• Agent 主链路 E2E

修改配置、权限、模型可见输入、文件作用域或恢复语义时，同时验证对应的 unit、integration 或 E2E，并回读最终 state、消息、文件或协议结果。