深入理解 ADK Session State 生命周期：基于 Callback 的持久化时序剖析与实战

深入理解 ADK Session State 生命周期基于 Callback 的持久化时序剖析与实战【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python导读在 Google ADKAgent Development Kit中Session State 是跨对话、跨调用保留 Agent 记忆的核心机制而它何时从「内存中的临时写入」变成「持久化到会话存储」直接决定了你的 Agent 在多轮交互中的行为是否可预测。本篇文章以仓库中的官方示例 session_state_agent 为主线完整剖析 Session State 在before_agent_callback、before_model_callback、after_model_callback、after_agent_callback四个回调阶段的读写可见性与持久化时序并结合 State 文档与底层源码说明 Delta 机制的实现原理。读完本文你将掌握如何编写回调验证 Session State 的缓存与持久化行为、ADK 内部 state delta 的提交时机以及哪些行为属于可依赖的契约、哪些属于随时可能变化的实现细节。示例概览一个验证 Session State 生命周期的 Agent示例位于 contributing/samples/context_management/session_state_agent包含三个文件文件作用agent.py定义root_agent并在四个回调中写入不同的 state key同时断言各阶段的可见性input.json供adk run --replay使用的输入文件包含一条用户查询hello world!README.md生命周期说明与运行指引该示例要演示的核心规则是通过 Context 对象tool_context、callback_context或readonly_context写入 state 之后该 state 立即可以在后续回调中读取而它真正持久化到 Session 中则要等到承载它的 Event 被 Runner 处理并追加到 Session 之后。这一「先缓存、后持久化」的两阶段模型是理解 ADK Session 机制的钥匙。下面先看示例代码。Agent 定义与回调实现agent.py 中定义了root_agent通过四个回调参数挂载了四个异步回调函数root_agent Agent( nameroot_agent, descriptiona verification agent., instruction( Reply to the user. Must always remind user you cannot answer a second query because your setup. ), modelgemini-3.5-flash, before_agent_callbackbefore_agent_callback, before_model_callbackbefore_model_callback, after_model_callbackafter_model_callback, after_agent_callbackafter_agent_callback, )示例使用Agent即LlmAgent定义其回调字段与签名在 src/google/adk/agents/llm_agent.py 中有完整声明。四个回调都接收CallbackContext而 src/google/adk/agents/callback_context.py 显示CallbackContext已被统一为Context的别名保留ReadonlyContext以向后兼容因此在回调中callback_context.state与工具函数中tool_context.state是同一套机制。每个回调的逻辑分两步写入 state例如callback_context.state[before_agent_callback_state_key] before_agent_callback_state_value调用assert_session_values断言分别检查 key 是否已缓存在 Context 的 session 中、是否已持久化在 session service 中、以及是否尚未持久化。assert_session_values的实现值得仔细看agent.pyasync def assert_session_values( ctx: CallbackContext, title: str, *, keys_in_ctx_session: Optional[list[str]] None, keys_in_service_session: Optional[list[str]] None, keys_not_in_service_session: Optional[list[str]] None, ): session_in_ctx ctx._invocation_context.session session_in_service ( await ctx._invocation_context.session_service.get_session( app_namesession_in_ctx.app_name, user_idsession_in_ctx.user_id, session_idsession_in_ctx.id, ) ) ...它从两个维度对比状态session_in_ctx内存视角直接取invocation_context.session即本次调用运行中、尚未被存储层回读的 Session 对象session_in_service持久化视角通过session_service.get_session()从存储层重新读取代表已真正持久化的状态。这种「内存 vs 存储」的双视角对比正是整个示例的灵魂它用断言清晰地区分了「我能读到什么」和「存储里已经有什么」。运行示例并观察输出示例文档给出的运行命令如下adk run contributing/samples/context_management/session_state_agent --replay contributing/samples/context_management/session_state_agent/input.json其中--replay指定 input.json其内容为{ state: {}, queries: [ hello world! ] }--replay模式下CLI 会从输入文件读取初始state和queries列表并逐条执行。从 src/google/adk/cli/cli.py 可以看到InputFile的解析与create_session(stateinput_file.state)的流程同时该文件也校验了query与--replay不能同时提供Error: Cannot provide both query and --replay.。运行后的输出如下来自示例文档[user]: hello world! In before_agent_callback ** Asserting keys are cached in context: [before_agent_callback_state_key] pass ✅ ** Asserting keys are already persisted in session: [] pass ✅ ** Asserting keys are not persisted in session yet: [before_agent_callback_state_key] pass ✅ In before_model_callback ** Asserting keys are cached in context: [before_agent_callback_state_key, before_model_callback_state_key] pass ✅ ** Asserting keys are already persisted in session: [before_agent_callback_state_key] pass ✅ ** Asserting keys are not persisted in session yet: [before_model_callback_state_key] pass ✅ In after_model_callback ** Asserting keys are cached in context: [before_agent_callback_state_key, before_model_callback_state_key, after_model_callback_state_key] pass ✅ ** Asserting keys are already persisted in session: [before_agent_callback_state_key] pass ✅ ** Asserting keys are not persisted in session yet: [before_model_callback_state_key, after_model_callback_state_key] pass ✅ [root_agent]: Hello! How can I help you verify something today? In after_agent_callback ** Asserting keys are cached in context: [before_agent_callback_state_key, before_model_callback_state_key, after_model_callback_state_key, after_agent_callback_state_key] pass ✅ ** Asserting keys are already persisted in session: [before_agent_callback_state_key, before_model_callback_state_key, after_model_callback_state_key] pass ✅ ** Asserting keys are not persisted in session yet: [after_agent_callback_state_key] pass ✅ 这段输出揭示了非常关键的渐进式持久化规律before_agent_callback写入后key 在内存中可见但存储中什么都没有before_model_callback阶段before_agent_callback_state_key已出现在存储中说明before_agent_callback的 delta 已被提交而本阶段新写入的 key 尚未持久化after_model_callback阶段before_model_callback_state_key也已持久化本阶段新写入的 key 仍未持久化after_agent_callback阶段after_model_callback_state_key已持久化只有本阶段新写入的 key 尚未持久化。注意before_agent_callback写入的 key 在before_model_callback阶段就已经被持久化了——这与before_agent_callback产生独立事件有关详见下文源码剖析。四阶段持久化时序官方契约示例文档明确给出了当前各回调阶段 state delta 的持久化行为before_agent_callbackstate delta 在所有回调处理完毕后持久化before_model_callbackstate delta 与最终的LlmResponse一起持久化即after_model_callback处理完成之后after_model_callbackstate delta 与LlmResponse事件一起持久化after_agent_callbackstate delta 在所有回调处理完毕后持久化。文档特别强调NOTE上述行为属于实现细节未来可能改变。不要依赖它。这条警告意味着如果你的业务逻辑依赖「某个 key 恰好在某次get_session之后才可见」那么它与 ADK 的演进方向是相悖的。正确的依赖方式是——任何通过 Context 写入的 state在写入之后的后续回调/工具调用中都可以立即读取而持久化只保证「最终会随事件落库」具体时机不构成 API 契约。源码级原理State 的 Delta 机制要理解上述时序需要先理解State的设计。官方指南 State 指出Session携带的是一个普通dictSession.state但 Agent 内部代码并不直接写这个 dict而是写一个State对象通过ctx.state访问。src/google/adk/sessions/state.py 中State的实现清晰展示了「双写」机制class State: def __init__(self, value, delta, schemaNone): self._value value self._delta delta ... def __setitem__(self, key, value): ... self._value[key] value # 立即更新当前值下一条代码可读 self._delta[key] value # 记录待提交的 delta随事件持久化也就是说一次ctx.state[key] value会同时写入_valueSession 的当前值保证后续代码立即可读写入_deltaEventActions 的state_delta等待被事件携带并提交。官方文档将这条链路总结为五个步骤见 docs/guides/sessions/state/index.mdctx.state[k] v同时写入 Session 当前值与event.actions.state_deltaAgent 产出事件Runner 将事件交给 session service 的append_eventappend_event先把temp:前缀的 key 应用到内存 Session供本次调用内后续读取再从 delta 中剔除temp:key剩余 delta 按app:、user:、会话级三种范围拆分并写入各自存储get_session将三个存储合并回一个 dict 并重新补上前缀。在 src/google/adk/sessions/base_session_service.py 中可以看到append_event的实现骨架_apply_temp_state处理temp:前缀、_trim_temp_delta_state剔除临时 key、_update_session_state将 delta 合并进session.state。这正是「事件被追加后delta 才落库」这一核心时序的底层实现。值得补充的是 State 中关于四种作用域前缀的说明它在解读示例输出时非常有用Key 形式存储位置是否持久化可见范围draft无前缀Session 记录是仅当前会话app:model_tierapp_name是该应用的所有会话、所有用户user:display_name(app_name, user_id)是该用户在该应用内的所有会话temp:token_count无否仅当前调用temp:前缀的值只存在于内存中_apply_temp_state应用到内存 Session 后被_trim_temp_delta_state剔除因此适合存放临时计算值。而示例中的回调 state key 均无前缀属于会话级状态。源码级原理各阶段事件如何携带 deltabefore_agent_callback 的独立事件为什么before_agent_callback写入的 key 在before_model_callback阶段就已持久化关键在于 src/google/adk/agents/base_agent.py 中_handle_before_agent_callback的实现if callback_context.state.has_delta(): return Event( invocation_idctx.invocation_id, authorself.name, branchctx.branch, actionscallback_context._event_actions, )如果before_agent_callback产生了 state deltahas_delta()为真它会立刻构造一个携带event_actions内含 state_delta的独立 Event 返回。该事件被 Runner 处理、追加到 Session 时append_event便会把其中的 delta 应用到session.state——于是到了before_model_callback阶段这个 key 已经出现在存储中了。这正是示例输出第二段「keys are already persisted in session: [before_agent_callback_state_key]」的直接原因。callback_context.state.has_delta()判断的正是State._delta是否非空见 state.py 中has_delta的定义。before_model_callback / after_model_callback 与 LlmResponse 事件before_model_callback与after_model_callback的处理位于 LLM 流程层。在 src/google/adk/flows/llm_flows/base_llm_flow.py 中_handle_before_model_callback先运行插件回调再运行 agent 的 canonical 回调返回可选的LlmResponse覆盖值_handle_after_model_callback则接收llm_response与model_response_event并以CallbackContext(invocation_context, event_actionsmodel_response_event.actions)构造回调上下文——注意这里把model_response_event.actions传入了回调上下文意味着after_model_callback中写入的 delta 会直接落在模型响应事件上与LlmResponse一起持久化。这也解释了示例输出第三、四段的规律before_model_callback写入的 key 与最终LlmResponse一起即after_model_callback处理之后持久化after_model_callback写入的 key 随LlmResponse事件一起持久化因此到after_agent_callback阶段时它已经落库。after_agent_callback 的收尾提交after_agent_callback与before_agent_callback类似在 base_agent.py 的_handle_after_agent_callback中处理。它处于一次 Agent 调用的收尾阶段其 delta 同样在所有回调处理完毕后才随事件持久化——因此示例最后一段输出中after_agent_callback_state_key是唯一「尚未持久化」的 key。实战要点如何在业务代码中正确使用 Session State综合示例与源码可以提炼出以下可落地的实践准则写入后立即读取是安全的。只要在同一个调用链内后续回调、工具函数ctx.state[key]读到的一定是最新值因为__setitem__同步更新了_value。不要依赖精确的持久化时机。示例文档明确声明各阶段持久化时机属于实现细节。请把「state 最终会持久化」当作契约把「某个具体阶段是否已落库」当作不可依赖的观测。想要立即落库可借助独立事件。从before_agent_callback的源码可见回调产生 delta 时会构造独立 Event 提交。但这同样是当前实现业务上不应据此设计逻辑。善用前缀控制作用域。无前缀 key 仅属于当前会话需要跨会话共享用户偏好使用user:需要跨用户共享应用配置使用app:临时中间值用temp:不会落库。注意State不是普通 dict——它实现了__getitem__、__setitem__、__contains__、get、setdefault、update、to_dict但没有keys、items、pop、迭代或del遍历请使用state.to_dict()。不要直接改Session.statedict。官方文档明确警告直接赋值Session.state只是本地可见的快照修改由于没有事件携带 delta下一次get_session时改动就消失了。总结Session State 的生命周期可以概括为「写入即缓存随事件落库」八个字缓存ctx.state[key] value通过State的双写机制让后续代码立即可见持久化delta 必须搭上某个 Event经由 Runner 交给 session service 的append_event才会真正写入存储时序before_agent_callback的 delta 随其独立事件提前提交before_model_callback/after_model_callback的 delta 随LlmResponse事件提交after_agent_callback的 delta 在收尾提交——但这一精确时序属于实现细节官方明确建议不要依赖。官方示例 session_state_agent 通过assert_session_values的「内存 vs 存储」双视角断言把这条生命周期完整地可视化了出来。理解这套机制后你在设计多轮对话 Agent、跨会话记忆和回调编排时就能准确预判 state 在何时可用、何时持久从而写出行为可预测、健壮的 Agent 应用。延伸阅读State 官方指南四种作用域前缀、Delta 落库五步流程与常见误区Context 源码ctx.state、ctx.session与 delta-aware 状态的完整 APICallbackContext 源码CallbackContext与Context的统一关系base_agent.py 回调处理before_agent_callback与after_agent_callback的事件构造逻辑base_llm_flow.py 模型回调before/after_model_callback与LlmResponse事件的绑定Session 数据模型Session.state、Session.events等字段定义【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考