跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

对话状态与内存

最后更新 查看 MarkdownAgent 设置

Agent 需要内存才能在时间上持续有用。没有内存,每次对话都从零开始——Agent 会忘记用户是谁、学到了什么、正在做什么。内存将无状态 LLM 调用变为持久、上下文感知的 Agent。

Session API 为基于 Cloudflare Agents SDK 构建的 Agent 提供内存层。它管理两类内存:对话历史记录(构成 session 的消息和 tool call)和上下文内存(注入 system prompt 的持久块,Agent 可以读取、写入和搜索这些块)。

当你需要的不只是简单同步状态或扁平 chat 历史记录时,请使用本页面。对于小型 UI 状态,请使用存储并同步状态。对于基本 chat 持久化,AIChatAgent 会为你存储消息。对于具有明确约定的长期内存,Think 构建于 Session 和上下文块之上。

对话历史

最基本的内存类型是对话本身:用户与 Agent 之间的消息、Agent 发起的 tool 调用及其收到的结果。Session 将所有内容存入由 Session Provider 支持的树形消息历史,默认为 SQLite。

import { Session } from "agents/experimental/memory/session";

// Append messages as the conversation progresses
await session.appendMessage({
	id: `user-${crypto.randomUUID()}`,
	role: "user",
	parts: [{ type: "text", text: "What's the status of the deployment?" }],
});

// Read the full conversation history
const history = await session.getHistory();
import { Session } from "agents/experimental/memory/session";

// Append messages as the conversation progresses
await session.appendMessage({
    id: `user-${crypto.randomUUID()}`,
    role: "user",
    parts: [{ type: "text", text: "What's the status of the deployment?" }],
});

// Read the full conversation history
const history = await session.getHistory();

对话历史在 Durable Object 休眠与驱逐后仍保留。Agent 唤醒时完整历史可在 SQLite 中获取,无需重放或重建。

消息通过 parent_id 以树结构存储,支持分支对话。对已有子节点的 parentId 调用 appendMessage 会创建分支,适用于响应重新生成等功能。getHistory(leafId) 沿树中任选路径遍历。

Session 还提供对话历史的全文搜索:

const results = await session.search("deployment Friday", { limit: 10 });
const results = await session.search("deployment Friday", { limit: 10 });

对话变长时,压缩 会摘要较早消息,在保留底层数据的同时控制上下文窗口。

上下文内存

上下文内存是注入系统提示词的持久信息,与对话历史分离。它让 Agent 在每一轮次都能访问身份、指令、已学事实、知识库与参考资料。

Session API 支持四类上下文内存,各适用于不同信息。类型由支撑上下文块的 提供商 决定。Session 自动检测提供商能力。

只读上下文

这是传统系统提示词:Agent 的身份、个性与指令。可直接写在代码库、从 R2 的 SOUL.md 加载,或从 API 获取。内容注入系统提示词,Agent 无法修改。

编程助手可有定义个性与约束的 soul:

import { Session } from "agents/experimental/memory/session";

const session = Session.create(this).withContext("soul", {
	provider: {
		get: async () =>
			"You are a senior TypeScript engineer. You write concise, " +
			"well-tested code. You prefer composition over inheritance. " +
			"When you are unsure, you say so rather than guessing.",
	},
});
import { Session } from "agents/experimental/memory/session";

const session = Session.create(this).withContext("soul", {
    provider: {
        get: async () =>
            "You are a senior TypeScript engineer. You write concise, " +
            "well-tested code. You prefer composition over inheritance. " +
            "When you are unsure, you say so rather than guessing.",
    },
});

或从 R2 加载,以便在不重新部署的情况下更新 Agent 个性:

const session = Session.create(this).withContext("soul", {
	provider: {
		get: async () => {
			const obj = await env.CONFIG_BUCKET.get("soul.md");
			return obj ? obj.text() : "You are a helpful assistant.";
		},
	},
});
const session = Session.create(this).withContext("soul", {
    provider: {
        get: async () => {
            const obj = await env.CONFIG_BUCKET.get("soul.md");
            return obj ? obj.text() : "You are a helpful assistant.";
        },
    },
});

只读块通过仅提供带 get() 方法的对象定义。不生成工具。内容出现在系统提示词中,Agent 无法更改。

可写短格式上下文

可将其视为 Agent 自用的 scratchpad,用于记下需要记住的内容——类似 Claude Code 维护待办列表,或客服 Agent 在对话中跟踪对用户的了解。

const session = Session.create(this)
	.withContext("memory", {
		description: "Important facts learned during conversation",
		maxTokens: 1100,
	})
	.withContext("todos", {
		description: "Task list, track what needs to be done and what is complete",
		maxTokens: 2000,
	});
const session = Session.create(this)
    .withContext("memory", {
        description: "Important facts learned during conversation",
        maxTokens: 1100,
    })
    .withContext("todos", {
        description: "Task list, track what needs to be done and what is complete",
        maxTokens: 2000,
    });

构建器中省略 provider 时,Session 自动连接到 SQLite 支持的可写提供商。Agent 获得 set_context 工具,可替换或追加这些块的内容。强制执行 token 限制,Agent 不能超出 maxTokens 预算。

系统提示词渲染可写块时会显示 token 使用指示,让 Agent 知道剩余空间:

══════════════════════════════════════════════
MEMORY (Important facts learned during conversation) [45% — 495/1100 tokens] [writable]
══════════════════════════════════════════════
User prefers dark mode.
User's project uses React and TypeScript.
Deployment target is Cloudflare Workers.

══════════════════════════════════════════════
TODOS (Task list) [12% — 240/2000 tokens] [writable]
══════════════════════════════════════════════
- [x] Set up project scaffolding
- [ ] Add authentication middleware
- [ ] Write integration tests

内容跨消息持久化并在休眠后存活。始终在系统提示词中可见,Agent 每轮次都能看到,无需额外获取。

可搜索上下文

当有大量信息(知识库、文档、日志、累积笔记)不宜全部塞入系统提示词时,可搜索上下文在系统提示词中保留摘要(例如「已索引 42 条」),并在需要时让 Agent 检索具体条目。

你提供带 search() 方法的提供商。搜索实现完全由你决定:全文搜索、通过 Vectorize 的向量搜索、调用外部 API 等。Session 只关心提供商是否有 search() 方法。

内置 AgentSearchProvider 默认使用 Durable Object SQLite 与 FTS5:

import { AgentSearchProvider } from "agents/experimental/memory/session";

const session = Session.create(this).withContext("knowledge", {
	description:
		"Searchable knowledge base, search for relevant information before answering",
	provider: new AgentSearchProvider(this),
});
import { AgentSearchProvider } from "agents/experimental/memory/session";

const session = Session.create(this).withContext("knowledge", {
    description:
        "Searchable knowledge base, search for relevant information before answering",
    provider: new AgentSearchProvider(this),
});

也可实现由任意搜索机制支持的自定义提供商:

const session = Session.create(this).withContext("knowledge", {
	description: "Searchable knowledge base",
	provider: {
		get: async () => "Product documentation and FAQs",
		search: async (query) => {
			// Use Vectorize, an external API, whatever you need
			const results = await env.VECTORIZE_INDEX.query(
				await generateEmbedding(query),
				{ topK: 5 },
			);
			return results.matches.map((m) => m.metadata.text).join("\n\n");
		},
		set: async (key, content) => {
			// Index new content
		},
	},
});
const session = Session.create(this).withContext("knowledge", {
    description: "Searchable knowledge base",
    provider: {
        get: async () => "Product documentation and FAQs",
        search: async (query) => {
            // Use Vectorize, an external API, whatever you need
            const results = await env.VECTORIZE_INDEX.query(
                await generateEmbedding(query),
                { topK: 5 },
            );
            return results.matches.map((m) => m.metadata.text).join("\n\n");
        },
        set: async (key, content) => {
            // Index new content
        },
    },
});

Agent 获得用于查询的 search_context 工具与用于索引新条目的 set_context 工具。由 Agent 决定搜什么,由你决定如何搜索。

当 Agent 需从大型集合中查找具体信息而非加载整份文档时,这是合适选择。

按需 skill

有些上下文太大,无法保留在每个 prompt 中,例如 runbook、参考指南、模板和脚本。Agent Skills 适用于此情况。Agent 会看到包含 skill 名称和描述的简短 catalog,并且仅在任务需要时使用 activate_skill tool 加载完整 skill。

有关该格式的工作方式,请参阅 Agent Skills。Skill 是文件,而不是内存块。将其存储在 Agent 的 Computer Workspace、R2 或代码中。

方面 技能 可写上下文 可搜索上下文
在系统提示词中 仅名称和描述 完整内容 仅条目数
已加载 按需加载完整 skill 始终 按需加载最匹配的 chunk
适用场景 过程、参考资料、脚本 事实、偏好 大型知识库

Agent 如何与内存交互

Session 根据上下文块的提供商类型自动生成工具。将这些工具与自有应用特定工具一并传给 LLM:

const sessionTools = await session.tools();
const allTools = { ...sessionTools, ...myApplicationTools };

const result = streamText({
	model: myModel,
	system: await session.freezeSystemPrompt(),
	messages: await convertToModelMessages(await session.getHistory()),
	tools: allTools,
});
const sessionTools = await session.tools();
const allTools = { ...sessionTools, ...myApplicationTools };

const result = streamText({
    model: myModel,
    system: await session.freezeSystemPrompt(),
    messages: await convertToModelMessages(await session.getHistory()),
    tools: allTools,
});

生成的工具

Session 根据存在的提供商类型动态生成工具:

工具 生成条件 作用
set_context 存在任何可写或可搜索的块 将内容写入命名块。对于可写块,替换或追加内容。对于搜索块,写入带键的条目。
search_context 存在搜索块 在可搜索块内全文搜索。返回按相关性排序的前若干结果。
session_search 使用 SessionManager 跨所有会话搜索(跨对话搜索)。

这些工具包含描述与参数 schema,告诉 LLM 哪些块可用及其用途。Agent 根据对话决定何时及如何使用。

有关完整的 tool signature 和所有 Session 方法,请参阅 Session API 参考。

系统提示词

上下文块组装为带清晰标题与元数据的结构化系统提示词。每个块获得带标签的分区,标签指示其类型与容量:

══════════════════════════════════════════════
SOUL (Identity) [readonly]
══════════════════════════════════════════════
You are a helpful coding assistant who speaks concisely.

══════════════════════════════════════════════
MEMORY (Important facts) [45% — 495/1100 tokens] [writable]
══════════════════════════════════════════════
User prefers dark mode.
User's project uses React and TypeScript.

══════════════════════════════════════════════
KNOWLEDGE (Searchable knowledge base) [searchable]
══════════════════════════════════════════════
12 entries indexed.

标签([readonly]、[writable]、[searchable])会告诉 LLM 每个块支持哪种交互。Token 预算会向 Agent 显示可写块中的剩余空间,帮助其管理自己的内存。

注意事项

Prompt 缓存

LLM 提供商(Anthropic、OpenAI 等)缓存系统提示词前缀。连续请求共享相同系统提示词时,提供商可跳过重新处理该前缀,降低延迟与成本。破坏缓存(更改系统提示词)会丧失此收益。

Session API 设计为与提示词缓存配合:

  • freezeSystemPrompt() 在首次调用时从所有上下文块渲染系统提示词,后续调用返回缓存值。即使 Agent 通过 set_context 写入内存,提示词在轮次之间也不变。
  • withCachedPrompt() 将冻结的提示词持久化到存储,使其在 Durable Object 休眠与驱逐后存活。Agent 唤醒时加载相同提示词,无需从所有提供商重新获取。

当 Agent 使用 set_context 更新可写块时,底层提供商立即更新(数据已保存),但冻结的系统提示词 不会 重新渲染。LLM 仅在显式调用 refreshSystemPrompt() 时在下一轮次看到更新,通常你在对话轮次之间而非轮次中间调用。

这意味着系统提示词在整个多步工具使用轮次中保持稳定,保留提供商的前缀缓存。

const session = Session.create(this)
	.withContext("soul", {
		provider: { get: async () => "You are a helpful assistant." },
	})
	.withContext("memory", { description: "Learned facts", maxTokens: 1100 })
	.withCachedPrompt(); // Persist the frozen prompt across hibernation

// During a conversation turn:
const system = await session.freezeSystemPrompt(); // Same value every call
const tools = await session.tools();

// ... agent calls set_context to update memory ...
// The frozen prompt is NOT changed, prefix cache stays warm

// Between turns (optional, if you want the agent to see its own updates):
await session.refreshSystemPrompt();
const session = Session.create(this)
    .withContext("soul", {
        provider: { get: async () => "You are a helpful assistant." },
    })
    .withContext("memory", { description: "Learned facts", maxTokens: 1100 })
    .withCachedPrompt(); // Persist the frozen prompt across hibernation

// During a conversation turn:
const system = await session.freezeSystemPrompt(); // Same value every call
const tools = await session.tools();

// ... agent calls set_context to update memory ...
// The frozen prompt is NOT changed, prefix cache stays warm

// Between turns (optional, if you want the agent to see its own updates):
await session.refreshSystemPrompt();

压缩(Compaction)

长对话最终会超出 LLM 的上下文窗口。压缩在两个层面解决:宏观压缩 摘要较旧消息范围,微观压缩 截断过大的单条消息。

宏观压缩(Macro-compaction)

宏观压缩摘要较旧消息,但从不删除原文。

它使用 覆盖层:摘要在单独表中存储,以其覆盖的消息范围为键。调用 getHistory() 时,覆盖层在读取时透明应用。被压缩的范围由合成摘要消息替换。底层消息保留在 SQLite 中,保留完整对话供审计、搜索与分支。

Messages:  [1] [2] [3] [4] [5] [6] [7] [8] [9] [10]
                    ↓ compaction ↓
Overlay:   [1] [2] [SUMMARY of 3-7]           [8] [9] [10]
                                                ↑ tail protected

要点:

  • 非破坏性,原始消息从不删除。完整对话始终在数据库中可用。
  • 迭代式,对话再次增长并触发另一次压缩时,现有摘要传给 LLM 更新,而非从头替换。
  • 边界感知,压缩边界会偏移,避免拆分工具调用 / 工具结果对。
  • 可配置,protectHead 保留前 N 条消息(通常是系统上下文),tailTokenBudget 保持最近消息完整。
import { createCompactFunction } from "agents/experimental/memory/utils/compaction-helpers";

const session = Session.create(this)
	.withContext("memory", { maxTokens: 1100 })
	.onCompaction(
		createCompactFunction({
			summarize: (prompt) =>
				generateText({ model: myModel, prompt }).then((r) => r.text),
			protectHead: 3,
			tailTokenBudget: 20000,
			minTailMessages: 2,
		}),
	)
	.compactAfter(100_000); // Auto-compact when token estimate exceeds threshold
import { createCompactFunction } from "agents/experimental/memory/utils/compaction-helpers";

const session = Session.create(this)
    .withContext("memory", { maxTokens: 1100 })
    .onCompaction(
        createCompactFunction({
            summarize: (prompt) =>
                generateText({ model: myModel, prompt }).then((r) => r.text),
            protectHead: 3,
            tailTokenBudget: 20000,
            minTailMessages: 2,
        }),
    )
    .compactAfter(100_000); // Auto-compact when token estimate exceeds threshold

自动压缩在 appendMessage() 后、估计 token 数超过阈值时触发。压缩失败非致命 — 消息已保存。

微观压缩(Micro-compaction)

微观压缩在单条消息层面而非跨范围工作。它处理两个问题:

读取时截断:truncateOlderMessages() 在发送给 LLM 前缩短较旧消息中的工具输出与长文本。最近消息(默认最后 4 条)保持完整。这在副本上操作,不修改已存储消息。

import { truncateOlderMessages } from "agents/experimental/memory/utils";

const history = await session.getHistory();
const truncated = truncateOlderMessages(history);
// Pass truncated history to the LLM
import { truncateOlderMessages } from "agents/experimental/memory/utils";

const history = await session.getHistory();
const truncated = truncateOlderMessages(history);
// Pass truncated history to the LLM

行大小强制:持久化消息时(通常是带大型工具输出的 assistant 消息),检查 SQLite 行大小限制。过大的工具输出替换为预览与建议重新运行工具的说明。这防止单条消息超出存储限制,同时保留对话流程。

相关

Session API 参考

Session 完整 API 参考,涵盖消息、上下文块、压缩、搜索、工具与自定义提供商。

Think

通过 configureSession() 内置 Session 集成的有明确主张的聊天 Agent。

这篇文档对您有帮助吗?