Agently Docs

English

中文

English

中文

Appearance

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

长程任务状态与恢复 Playbook ​

有些 Agent 原型在一次请求里很顺，进入真实业务后马上变难：用户隔了半天继续补材料，流程中间要等审批，前面生成过报告草稿，后面又要找回某条审查证据。把这些东西都塞回 prompt，context 很快撑爆；只保存在内存里，服务重启后又接不上。

长程任务的关键不是让模型“记性更好”，而是把归属、状态、产物、恢复点和运行证据放到各自的 owner 里。

先分清五类 owner ​

Owner负责什么不负责什么
Gateway / APIuser_id、tenant_id、session_id、task_id、鉴权和渠道入口不写业务执行步骤
Session当前对话的 chat history、context window、可选 memo不保存任务 artifact、日志和 checkpoint
TriggerFlow execution一次流程的阶段、分支、等待、紧凑 state 和 runtime stream不保存大块文件、live 对象和长期证据
Workspaceobservation、artifact、decision、link、checkpoint 和 ContextPack 来源不自动决定该记住什么，也不替代业务数据库
Observability / EvalRuntimeEvent、trace、评估样例、回放和质量证据不改变业务控制流

这几个 owner 分开后，团队能回答三个上线问题：这是谁的哪次任务、当前跑到哪一步、失败后从哪里恢复。

哪些东西放哪里 ​

信息放置位置原因
用户当前多轮对话Session下一次 request 需要看到最近上下文
当前 execution 的阶段、状态、refTriggerFlow state关闭时能形成小而稳定的 snapshot
生成报告、下载物、审查证据、长日志Workspace artifact / record内容大、需要跨轮查找和复核
业务决策和证据关系Workspace link后续能知道某个 decision 回应哪条 evidence
人工审批等待pause_for(...) interrupt等待点可保存、可展示、可恢复
数据库连接、浏览器、client 对象runtime resourceslive 对象不可序列化，恢复时重新注入
代表性输入和验收标准Eval case / 应用测试发布前判断是否真的变好

一个简单判断：如果这段信息很长、需要复核、要跨轮找回，放 Workspace；如果只是当前流程下一步要读的小状态，放 execution state；如果是活对象，放 runtime resources；如果是对话历史，放 Session。

推荐结构 ​

text
Gateway
  生成 task_id / session_id / trace_id
  鉴权、租户、渠道适配

Agent
  activate_session(session_id)
  use_workspace("./.agently/runs/{task_id}")

TriggerFlow execution
  state: phase + refs + compact decisions
  stream: stable business events for UI
  pause_for: human / webhook / approval wait

Workspace
  records: observations / artifacts / decisions
  checkpoints: run_id + compact state
  build_context(goal, scope, budget, profile)

Observer / Eval
  RuntimeEvent hook
  DevTools optional bridge
  scenario regression before release

这里的重点不是一次性上齐所有模块。只要任务开始跨轮、跨文件或跨人协作，就先把 task_id、Workspace root 和 execution id 设计清楚。

最小代码形态 ​

1. 入口先给任务归属 ​

python
agent = Agently.create_agent("review-worker")
agent.activate_session(session_id=session_id)
agent.use_workspace(f"./.agently/runs/{task_id}")

Session 让当前对话能继续；Workspace 让这次任务的证据和产物有地方落地。两者不是同一件事。

2. 大块产物写入 Workspace，state 只留 ref ​

python
report_ref = await agent.workspace.ingest(
    content=markdown_report,
    collection="artifacts",
    kind="draft_report",
    summary="第一版审查报告",
    scope={"task_id": task_id},
)

await data.async_set_state(
    "draft_report_ref",
    report_ref,
    emit=False,
)

这样 close snapshot 不会被报告正文撑大，后续步骤仍然能通过 ref 找回内容。

3. 稳定边界写 checkpoint ​

python
checkpoint_ref = await agent.workspace.checkpoint(
    task_id,
    {
        "phase": "risk_review_done",
        "draft_report_ref": report_ref,
        "risk_level": "medium",
    },
    step_id="risk-review",
)

checkpoint 里保存的是恢复所需的紧凑状态，不是完整 transcript。需要完整产物时，通过 ref 读 Workspace。

4. 下一轮按目标召回 ​

python
context_pack = await agent.workspace.build_context(
    goal="根据最新审批意见修订审查报告。",
    scope={"task_id": task_id},
    budget={"tokens": 12000},
    profile="document_review",
)

Recall 做的是按目标、范围和预算打包已存 records。它不是自动长期记忆策略，也不会替应用决定哪些事实应该写入 Workspace。

5. 有人工或外部系统等待时，用 pause/resume ​

python
async def wait_for_approval(data):
    return await data.async_pause_for(
        type="approval",
        payload={"task_id": task_id, "report_ref": report_ref},
        resume_to="self",
    )

恢复时，业务系统通过保存的 execution id 找回 execution，重新注入 runtime resources，然后 continue_with(...)。如果只是补充上下文而不需要流程停下，使用 runtime intervention；不要把 intervention 当审批闸门。

Checkpoint / Resume 的验收问题 ​

问题通过标准
哪些步骤可以重跑？可重跑步骤没有不可逆副作用，或有幂等键
哪些步骤不能重跑？外部写入、扣费、发送通知等动作有记录和保护
恢复需要什么 live 依赖？runtime_resources 的 key 明确，恢复端能重新注入
恢复后从哪一步继续？pending interrupt、checkpoint state 或业务 phase 可定位
产物是否可信？每个 artifact 有来源、summary、scope 和必要 link
失败原因怎么排查？RuntimeEvent、execution snapshot 和 Workspace evidence 能串起来

Agently 提供 execution save/load、Workspace checkpoint、RuntimeEvent 和 DevTools 这些基础件；分布式锁、消息队列、幂等表、审批系统、业务数据库仍然属于应用架构。

不要做什么 ​

  • 不要把长报告、工具输出、PDF 内容或完整日志塞进 Session。
  • 不要把 live DB client、浏览器对象、文件句柄放进 execution state。
  • 不要把 flow_data 当 execution 进度；并发执行会互相影响。
  • 不要把“检索到了”当“记住了”。长期写回需要 schema、审核和回滚策略。
  • 不要让前端直接消费 raw instant path。长流程 UI 应消费稳定业务事件。

继续阅读 ​