English mirror

This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.

Read the Chinese source page

Workspace

有些信息不适合放进 prompt，也不适合放进 Session 历史。比如一次测试输出、一个生成报告、一份 patch、一个业务 decision、一次命令结果。这些信息可能很长，但后续 turn 又需要能找回来。

Workspace 是多轮任务的持久信息边界。它保存 records、artifacts、links 和 checkpoints；应用代码决定写入什么，模型不自动决定“应该记住什么”。业务上把它理解成“任务证据层”更稳：报告、日志、审查证据、决策和恢复点都能落到这里，下一轮再按目标召回。

什么时候用 Workspace

当前信息	放哪里
当前对话历史	Session
本次请求的背景片段	info(always=False)
大规模可检索知识	Knowledge Base
测试输出、运行日志、报告、patch、decision	Workspace
TriggerFlow execution 的紧凑状态	TriggerFlow state
不可序列化 live 对象	TriggerFlow runtime resources

Workspace 适合“任务证据”。Session 适合“对话历史”。

创建和写入 record

agent = (
    Agently.create_agent("repo-worker")
    .use_workspace("./.agently/runs/issue-123")
)

ref = await agent.workspace.ingest(
    content=pytest_output,
    collection="observations",
    kind="test_output",
    summary="pytest failed in route fallback test",
    scope={"task_id": "issue-123", "turn": 1},
    source={"type": "command", "name": "pytest"},
)

这条 record 可以被后续 search、link、context pack 或 checkpoint 引用。大型命令输出、生成报告、transcript 和 patch 应存进 Workspace，runtime state 里只保留 record refs。

搜索和构造上下文

records = await agent.workspace.search(
    "route fallback",
    filters={"collection": "observations", "kind": "test_output"},
)

context_pack = await agent.workspace.build_context(
    goal="Fix the route fallback failure.",
    scope={"task_id": "issue-123"},
    budget={"tokens": 12000},
    profile="software_dev",
)

build_context(...) 会基于 Recall planner、retriever 和 context-builder profile，把已存 records 打包成 ContextPack。这一步只是打包已存证据，不代表 Workspace 自己变成自主规划器。

召回有预算，也会记录 omission。它适合把“这次任务里和当前目标相关的证据”带回 prompt，而不是把整个工作区一次性塞回模型。

召回不是全量记忆

Workspace 作为“记忆”使用时，重点不是把历史全量重放给模型，而是按当前目标取回该取的内容：

goal + scope + budget + profile
  -> recall plan
  -> retrieve records
  -> build ContextPack
  -> record omissions

这和 Skills 的渐进式披露是同一条工程原则：大块内容放在上下文之外，prompt 里常驻摘要和 ref；真正需要时，再按预算把相关内容取回。预算装不下的内容不应静默丢失，应该进入 omissions，便于后续解释“为什么这次没有带上某些证据”。

生产系统里，自动长期记忆应保持谨慎。推荐把“什么值得写入、能不能覆盖、什么时候遗忘、谁可以回滚”交给应用策略，用 schema、审计和版本记录约束。Workspace 提供 substrate 和 Recall 入口，不替业务决定所有记忆策略。

Checkpoint

checkpoint_ref = await agent.workspace.checkpoint(
    "issue-123",
    {"phase": "debugging", "refs": [ref]},
    step_id="run-tests",
)

state = await agent.workspace.get_data(checkpoint_ref)
latest = await agent.workspace.latest_checkpoint("issue-123")
history = await agent.workspace.checkpoint_history("issue-123")

record 中保存 dict、list 或 checkpoint state 等 JSON-compatible 结构化数据时，用 get_data(...) 取回结构化对象。按文本读取已存内容时，用 get(...)。

Links

Links 用来记录 records 之间的关系：

decision_ref = await agent.workspace.put(
    {"decision": "Patch route fallback"},
    collection="decisions",
    kind="loop_decision",
    scope={"task_id": "issue-123"},
)

await agent.workspace.link(decision_ref, ref, relation="responds_to")
links = await agent.workspace.links(
    source=decision_ref,
    relation="responds_to",
)

这样后续可以知道某个 decision 是回应哪条 evidence，而不是只靠自然语言描述。

文件作业区和 records 存储

agent.use_workspace(...) 同时定义 agent.workspace.files_root。shell、Node.js 和文件 actions 在没有显式 root 或 cwd 时，会继承这个可编辑作业区。

agent.enable_workspace_file_actions(write=True)
agent.enable_shell(commands=["pwd", "pytest"])
agent.enable_nodejs()

enable_workspace_file_actions(...) 不创建第二个 Workspace。它只是把当前 Workspace 文件作业区暴露成 list/search/read/write 文件 actions。

agent.workspace.content_root 是 Workspace records 使用的受管内容存储。不要把这两个 root 混成同一个概念。

能力检查

capabilities = agent.workspace.capabilities()

capabilities() 会报告当前 backend 的 content、metadata、checkpoint、text index、policy 和 vector index 组件。替换 local backend 或调试插件时，可以用它确认 wiring。

Workspace V1 不是什么

Workspace V1 不暴露 remember(...)、observe(...)、decide(...) 这类可被模型直接调用的记忆动词。它是持久 substrate，不是自主记忆策略。

更高阶的 Action、Recall 或 WorkLoop 可以叠加在 Workspace 上，但 V1 中应用代码仍然负责决定写入什么、何时检索、如何打包上下文。

默认本地 backend 是 filesystem content + SQLite metadata/FTS + NoopVectorIndex。高级向量检索、rerank、compression 可以作为插件叠加。

放进长程任务里怎么用

阶段	Workspace 负责
任务开始	创建任务级 root，后续 records 带上 scope={"task_id": ...}
工具或模型产生大块结果	写 observation / artifact，execution state 只保存 ref 和摘要
做出业务决策	写 decision record，并用 link 指向支撑证据
阶段稳定	写 checkpoint，保存可恢复的紧凑状态
下一轮继续	build_context(goal, scope, budget, profile) 生成 ContextPack

如果流程还要等待人工或 webhook，等待点属于 TriggerFlow pause_for(...)；Workspace 保存证据和 checkpoint。完整组合路径见 长程任务状态与恢复 Playbook。

示例

Agently examples 里有两个 Workspace 示例：

• examples/workspace/workspace_loop_foundation.py：TriggerFlow loop 写入 observations，把 decisions link 到 evidence，checkpoint 紧凑状态，并通过 Recall 生成 ContextPack。
• examples/workspace/workspace_with_action_output.py：file action 写入 workspace.files_root，shell action 读取文件，应用代码把 action output 显式 ingest 为 observation，再通过 Recall 打包。

常见误用

• 把长命令输出塞进 Session。
• 把 Workspace 当模型自动记忆系统。
• 把召回理解成“把工作区全部塞回 prompt”。
• 让模型自由决定长期写回策略，缺少 schema、审计和回滚边界。
• 在 TriggerFlow state 里保存大 artifacts，而不是保存 Workspace record refs。
• 把 files_root 和 records 的 content_root 混用。
• 开启文件 actions 后，以为创建了另一个 Workspace。

下一步

• 上下文放哪里：Context Engineering
• 多轮 session：会话记忆
• 长程任务状态与恢复：长程任务状态与恢复 Playbook
• Action 文件作业区：Actions 概览
• TriggerFlow state：State 与 Resources