Long Horizon 架构深度解析基于 ADK 与 Vertex AI 的长时程自进化 Agent 全景图【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples导读本文是 Long Horizonhorizon包 的架构指南它向你解释这个基于 Google Agent Development KitADK 2.x与 Vertex AI 构建的长时程long-horizon、自我改进self-improvingAgent 是如何组装在一起的以及当你想理解或改动某个行为时应该去哪里看代码。读完本文你将掌握Horizon / ADK / Vertex AI 三层的职责边界与归属判断方法、_build_app_object的完整装配顺序模型、工具、有序回调链、插件、App、每一轮对话在回调链中的执行路径以及各子系统的从这里开始读代码地图——无论你是新维护者还是想把这套 harness 的模式搬进自己 ADK 应用的使用者这份地图都能让你不用先通读全部实现就能定位问题。Horizon 运行在用户的 Google Cloud 与 Workspace 中在每用户沙箱里执行代码、按计划触发对话scheduled chats、使用用户自己的密钥而不向模型暴露它们并在回合之间通过把事实写入记忆memory与把技巧写入技能库skill library来改进自身——这一切都构建在托管原语managed primitives之上而不是重新发明 agent 循环、记忆存储或会话持久化。系统形态一张图看懂全貌整个系统可以用下面的流程图概括原文以 Mermaid 描述这里用文字复述其结构Client客户端Vite 聊天壳chat shell、A2A 对等体A2A peer、agents-cli一次性调用通过A2A JSON-RPC SSE与 Runner 通信。RunnerlhaRunner · FastAPI · ADK 2.5包含pluginsIterationBudget · SiblingAgent · Guardrails、prompt三层stable · cached · volatile skills、modelDispatchingLlm → Gemini 3.6 Flash / 3.1 Pro、compactHorizonSummarizer 压缩旧事件。Tools工具层bash·file_ops·web·clarify·memory·subagentblocking fork。Vertex AI托管底座Memory Bank跨会话记忆、Agent Engine会话、Sandboxes每用户沙箱。Sandbox沙箱本地文件系统开发态· BYOC 容器部署态· 每日快照可选。自我改进回路每轮之后judgefork 写记忆、修补技能绝不阻塞回复→ 按计划dream复查读取近期会话并整理用户画像 → 下一轮通过 Memory Bank 与三层系统提示词surface回来闭环回到 Runner。架构的核心思想是托管优先managed-firstADK 拥有 agent 循环Vertex AI 拥有模型 / 记忆 / 会话 / 沙箱自定义代码被严格限制在一小撮自定义接口里。后面每一节都会展开这个思想。分层归属先搞清楚这个行为属于哪一层大多数问题一旦你知道这个行为归哪一层管就会变得简单。三层职责如下Horizon custom interfaces: env interface, guardrails, secrets, delegation HITL, self-improvement, 3-tier prompt ADK agent loop: Runner, callbacks, plugins, App, sessions, memory Vertex AI managed: Gemini, Memory Bank, Agent Platform Sessions, Sandboxes从底层往上看Vertex AI 是被托管的底座模型Gemini、Memory Bank跨会话记忆、Agent Platform Sessions可恢复的会话持久化、Sandboxes每用户 BYOC 沙箱。Horizon 只配置它们不实现它们。ADK 是 agent 运行时Runner驱动循环——调用模型、运行工具、重复执行App持有 agent 以及插件、压缩/缓存/可恢复性配置有序回调链ordered callback chains与插件是挂钩点会话与记忆服务都是可插拔的。Horizon 没有引入新运行时它用的是 ADK 的运行时。Horizon 是构建在 ADK 之上的、有主见的 harness它装配工具集、有序回调链、插件与App并补充了大多数长时程 agent 需要的自定义接口。定位行为的方法如果问题与模型如何被调用、状态如何在步骤间传递、一个回合如何被持久化/恢复有关那就是ADK——先读 horizon/agent.py 的装配再读 ADK。如果是托管能力模型、记忆、沙箱、配额/区域错误那是Vertex——去查区域与启用状态而不是 Horizon 代码。其余一切——提示词组装、guardrails、secrets、环境接口、委托delegation、自我改进——都是Horizon代码就在本仓库里。构建Construction_build_app_object装配了什么agent 定义在horizon/agent.py中——root_agent ADKApp包含完整的工具/回调/插件装配作为模块级app/root_agent单例只构建一次。horizon/fast_api_app.py负责提供服务它从环境解析会话/记忆/工件后端与沙箱构建 ADKRunner并挂载路由。uvicorn horizon.fast_api_app:app --port 8001 # 被服务的 appfrom horizon.fast_api_app import build_runner runner build_runner() # 嵌入时不依赖 FastAPICLI/批处理服务从环境解析几个关键入口horizon.fast_api_app:app—— FastAPI 表面A2A /lha/*/scheduler/*通过模块__getattr__惰性构建因此裸import horizon保持离线。每个 router 都会挂载通过删除attach_*调用可以只发布子集见 security-model.md。build_runner()—— 解析服务session/memory/artifact 沙箱返回一个纯 ADKRunner便于在没有 HTTP 表面时嵌入。配置走环境变量——LHA_ROOT_MODEL、LHA_ENVIRONMENT_BACKEND、服务 URISESSION_DB_URL、AGENT_ENGINE_RESOURCE_NAME、LOGS_BUCKET_NAME。自定义沙箱后端通过set_environment_provider(factory)安装更深层的改动需要编辑horizon/agent.py。完整目录见 configuration.md。agent.py在 import 时执行app _build_app_object()import horizon保持离线因为包的__init__不导入agent——只有读取horizon.agent/horizon.fast_api_app.app才会触发构建。_build_app_object的装配顺序源码中 horizon/agent.py 按以下顺序组装1. 模型Model——_resolve_root_modelNone→build_root_llm()环境默认值LHA_ROOT_MODEL一个 registry 键 → 基于MODEL_REGISTRY的DispatchingLlm一个BaseLlm实例直接透传绕过 registry 与/model。2. 工具Tools—— 一个显式列表见 agent.py工具说明memory覆盖 add默认与 search原session_search两种动作HorizonPreloadMemoryTool把记忆预取放进缓存排除的 contents 尾部而不是污染缓存指纹见下ReadTool合并的文本 媒体读取write/edit/search_files文件操作三件套artifact工件生成bash/process终端与进程管理subagent子 agentblocking 或 fork_SKILL_TOOLSET会话绑定的技能工具集load_skill覆盖 load 与 reloadroutine无人值守的 cron 任务clarify澄清工具AgentTool(agentweb_research_agent)网页研究作为一个 AgentTool 暴露其中PreloadMemoryTool值得一提库存的PreloadMemoryTool把PAST_CONVERSATIONS追加到system_instruction而该块会被 Gemini 的缓存做指纹识别——它每轮都变缓存就永远无法命中。这个子类把它放到缓存排除的 contents 尾部见horizon/memory/preload.py的HorizonPreloadMemoryTool。3. 有序回调链Ordered callback chains—— Agent 上的六条链before_agent、before_model、after_model、before_tool、after_tool、after_agent。顺序就是契约每条链自上而下执行后面的条目可以读取前面条目设置的状态。4. 插件Plugins——IterationBudgetPlugin(max_tool_calls_per_iteration200)、SIBLING_AGENT_PLUGIN、GuardrailsPlugin()在_build_app_object中硬编码。插件在每个 hook 上先于agent 级回调运行GuardrailsPlugin拥有 halt 逻辑。5. App—— 用ResumabilityConfig(is_resumableTrue)、ContextCacheConfig前缀缓存与EventsCompactionConfig包裹root_agent其中压缩摘要器是HorizonSummarizer压缩摘要器——这是 ADK 的旋钮不是接口。App 配置中几个值得注意的默认值源码原文注释context_cache_configContextCacheConfig( min_tokens4096, # Gemini 3* 模型自身的每模型下限就是 40962048 是死配置 ttl_seconds1800, cache_intervals10, ), events_compaction_configEventsCompactionConfig( token_threshold750_000, # 种子值——每轮被 select_model_callback 覆写为活跃模型的窗口百分比阈值 event_retention_size20, compaction_interval8, # 滑动窗口触发同时每 N 次用户发起的调用确定性触发一次 overlap_size2, summarizerHorizonSummarizer(llmGemini(modelgemini-3.7-flash)), ),执行Execution每一轮对话如何穿过回调链每一轮中ADKRunner驱动root_agent穿过有序回调链与其工具插件在每个 hook 上先运行。链的执行顺序如下与 agent.py 中注册顺序一一对应before_agent首次调用带状态守卫——on_session_start_callback解析 workspace 环境、加载用户画像、预置记忆预取→bind_session_skills_callback把模块全局的技能工具集重新指向本会话的 workspace。before_model——select_model_callback打上每会话模型戳→prune_tool_outputs_callback清零旧的、大的工具结果体以回收上下文→normalize_tool_schemas_callback去掉非 pydantic 声明路径的源码缩进→redact_artifact_urls_callback从模型视野中剥掉签名工件 URL→_slash_command_dispatcher拦截/cmd用户回合路由到 BUILTIN_COMMAND_REGISTRY→system_prompt_assembly_callbackstable context 层→reminder_injection_callback在消息尾部注入 volatile 层保持缓存前缀字节级稳定→subagent_description_callback用实时技能目录 子画像重写 subagent 工具描述必须最后运行以看到最终工具集。模型响应文本或工具调用。before_tool——before_tool_log_callback打上state[in_flight_tool_call]让聊天 spinner 显示运行中 · Ns→exfil_guardLayer A 数据外泄守卫先于 policies_guard 运行以拦截携带密钥的调用→policies_guardLayer C 硬拒绝 确认→permission_guardLayer D 交互式询问最后运行对所有幸存者决定 allow/ask。每个工具都通过环境接口在宿主LocalEnvironment或每用户沙箱中行动——绝不直接碰宿主。after_tool——skill_telemetry_callback更新 view/edit/error 计数器供技能策展使用→tool_call_log_callback为 web UI 实时日志发出结构化工具调用事件。循环重复直到模型产生最终回复。after_agent——auto_capture_callback刷新到 Memory Bank带节流→skill_curator_callback技能的 promote/demote→review_fork_callback后台 judge fork提取持久事实。Halt 机制骑在session.state[halt_reason]上GuardrailsPlugin内的守卫迭代预算、无进展、重复失败设置它插件的before_modelhook 在下一轮消费它见 guardrails_plugin.py其中RepeatedFailureGuard(threshold3)、NoProgressGuard(window5)。agent 上的after_model是空的——无进展检测活在插件里。部署态请求路径在部署层面请求通过 FastAPI 表面进入FastAPI 表面horizon/fast_api_app.py暴露 A2A JSON-RPC 端点、OAuth 回调与/lha/*路由器state、sessions、tasks、memories、secrets、feedback、uploads、sandbox。A2A 调用上文描述的 ADKRunner。跨会话记忆是 Memory Bank见 memory.md——每轮通过 ADK 的PreloadMemoryTool预取由后台 judge fork 写回夜间 dream-review 整合结构化画像与一般记忆。会话持久化在 Agent Runtime 中且可恢复。Cloud Scheduler 驱动 routines作为真实的持久化对话经由与 web 相同的 A2A handler 触发与夜间 dream-review。Routine 的触发路径POST /scheduler/routine-tick包裹在三个 routine ContextVar 中set_routine_run一个全新的隔离lhart-id沙箱绝不用用户的、set_routine_secret_scope只暴露 routine 声明的密钥、set_headless_mode无提示词可用shell 在沙箱中运行非 shell 审批自动拒绝——这样它就能无人值守运行而不触碰用户 workspace详见 routines.md。Web UI 是独立的 Vite SPA生产环境由web/server/的 Express proxy 在 IAP 之后提供FastAPI 不服务 web bundle。后端代码地图从哪里开始读Python 包位于horizon/外层仓库目录保持lha/。找到你关心的子系统先打开它的start-here文件再扩散到支撑文件。下表是原文完整保留的代码地图想了解…从这里开始支撑文件深度文档Agent 本身工具、回调顺序、插件、Apphorizon/agent.pyhorizon/fast_api_app.py被服务的 app Runner本文 AGENTS.md记忆与自我改进horizon/memory/add_memory_tool.pyauto_capture.py、review_fork.py、dream_review.py、user_profile.py、skill_curator.pydocs/memory.md沙箱 / workspace / 环境接口horizon/environment/base.pyEnvironment契约、horizon/sandbox/provider.pySandboxProvider、horizon/sandbox/lifecycle.pyhorizon/environment/local.py、horizon/environment/sandbox.py、sandbox/runtime/容器内 shim、horizon/environment_context.py、horizon/workspace_window.pydocs/sandbox-lifecycle.md外泄守卫horizon/guardrails/exfil_guard.pyguardrails/exfil_config.pydocs/security-model.mdA2AJSON-RPC 传输horizon/a2a/routes.pya2a/executor.py流转换器、a2a/user_converter.py认证的 user_id、a2a/datapart.py—系统提示词与每轮转向horizon/conversation/system_prompt.pyconversation/reminders.pyvolatile 层、conversation/session_start.py、conversation/soul_loader.py—Guardrails 与 halthorizon/guardrails/guardrails_plugin.pyguardrails/policies.py、policy_grants.py、no_progress.py、repeated_failure.pydocs/security-model.md工具权限审批horizon/guardrails/permission_guard.pyguardrails/permission_rules.py、guardrails/command_classify.pydocs/permission-model.md工具file/bash/webhorizon/tools/file_ops.pytools/read.py合并文本媒体读取、tools/processes/bashprocess、tools/web_search.py—子 agent / 委托horizon/subagents/subagent.pysubagents/delegate.py阻塞仍为内部、subagents/spawn.pyfire-and-forget仍为内部、subagents/profiles.py、subagents/descriptions.py—上下文压缩horizon/context/summarizer.pycontext/tool_output_pruning.py、context/compaction_context.pydocs/memory.mdSchedulerdream-review / snapshothorizon/scheduler/dream_review_endpoint.pyscheduler/snapshot_endpoint.py、scheduler/auth.py—Routines隔离沙箱中的无人值守 cron 任务horizon/routines/tools.pyroutines/manifest.py、routines/run_context.py、scheduler/routine_store.py、scheduler/routine_postgres_store.py、scheduler/cron.py、scheduler/routine_tick_endpoint.pydocs/routines.mdSecretshorizon/secrets/store.pysecrets/inject.py、secrets/dotenv.py、horizon/auth/oauth.pyConnect Google—Slash 命令horizon/commands/__init__.pycommands/dispatcher.py—模型 / LLM 路由horizon/models/dispatcher.pymodels/registry.py、models/selector.py、models/media.py—HTTP 路由器/lha/*、/feedbackhorizon/api/每条路由一个文件sessions、state、tasks、memories、sandbox、secrets、uploads、feedback在horizon/fast_api_app.py中挂载docs/security-model.md反馈管线horizon/feedback/sink.pyfeedback/context.py、feedback/models.py、horizon/api/feedback.py路由—遥测 / 可观测性horizon/telemetry/otel.pytelemetry/ui.pyweb 面板实时工具日志—DB 韧性 / 基础设施horizon/infrastructure/db_resilience.pyinfrastructure/resilient_session_service.py、infrastructure/memory_config.py、infrastructure/constants.py—自定义代码的价值点接口、旋钮与应用Horizon 尽量把一切都交给 ADK 和 Vertex。剩下的代码被分成三种性质——旧的扁平化六个模式标签把它们混在了一起你拥有的接口interfaces、你设置的旋钮knobs、以及你从接口组合出的应用applications。定位行为时知道它是三者中的哪一种就决定了这里有没有自定义代码值得读。自定义接口ADK/Vertex 不提供的扩展点每一个都是真实接口一个 Protocol、一个 ContextVar 或一条有序回调链自定义代码在这里真正有价值。大约六个1. 环境接口Environment interface—— Horizon 的Environmenthorizon/environment/base.py是 ADKBaseEnvironment的超集新增list_directory/delete_file/make_dir/download_zip/upload_zip/spawn_process与on_host_fs能力标志置于一个 ContextVar 之后。工具按方法/能力分发绝不做isinstance具体类判断因此同一份工具代码既能在本地宿主horizon/environment/local.py的LocalEnvironment上运行也能在每用户 Sandbox 中运行——通过LHA_ENVIRONMENT_BACKEND字符串或set_environment_provider(factory)可插拔。值得注意的是on_host_fs的安全默认值未知后端一律视为远端无宿主文件系统防止健忘的子类意外碰到宿主。2. 工具 guardrailsTool guardrails—— 有序的before_tool链exfil_guardLayer A →policies_guardLayer C →permission_guardLayer DD 最后运行作为中央交互式询问层对于 shell 工具通过command_classify.py分类命令防止良性片段夹带受限命令加上GuardrailsPlugin迭代/无进展/重复失败 halt 共享一个halt_reason。沙箱出口默认封闭部署态本地开发也默认开启LHA_SANDBOX_INTERNET_ACCESS可双向覆盖无论出口模式如何Layer Aexfil_guard都是外泄边界密钥材料、凭据读取、metadata-server 访问、向非白名单主机的上传形命令。见 security-model.md 与 permission-model.md。3. 每用户密钥Per-user secrets—— 一个SecretStoreProtocolSecretManagerStore|InMemorySecretStore由LHA_SECRET_BACKEND选择可通过set_secret_store覆盖加上环境注入secret_env与 Connect Google OAuth 流程。核心承诺是agent 用用户自己的凭据行动而模型永远看不到它们。与环境的形状相同——Protocol 工厂ADK 在这里什么都不提供。horizon/secrets/horizon/auth/oauth.py。实现上每个用户对应一个 Secret Manager secretlha-secret-sha256(user_id)[:32]保存{name: {value: str, created_at: int_ms}}的 JSON blob带短 TTL 缓存以压低 Secret Manager 配额消耗。4. 子 agent 委托 HITL 回升Sub-agent delegation HITL resurfacing—— 阻塞式delegate与 fire-and-forget 的agentspawn/status/result/wait/cancel/list各自有隔离的上下文窗口与工具集。delegate 驱动一个可恢复的子 agentbuild_resumable_child_runner/drive_child在风险操作审批处暂停、冒泡给人类、然后从存储的FunctionResponse恢复——无需重跑整轮就实现持久的 HITL被阻塞的子 agent 还可以ask_parent沿同一路径升级一个自由文本决策。horizon/subagents/5. 自我改进回路Self-improvement loop—— 节流的after_agent工作记忆写回auto_capture_callback、技能 promote/demoteskill_curator_callback、judge forkreview_fork_callback加上压缩前的记忆刷新spawn_flush_fork由摘要器在事实丢失给有损摘要之前触发与 Memory Bank 上的夜间 dream-review 整合。horizon/memory/6. 三层系统提示词3-tier system prompt—— 常量层一次性构建为Agent(static_instructionbuild_static_instruction(...))让 ADK 自己的请求处理器把它放在每个回调之前而不是 Horizon 手搓每会话缓存每会话上下文层cwd 的项目文件按.horizon.md→LHA.md→AGENTS.md→CLAUDE.md→.cursorrules首匹配发现只加载一个仍骑在before_model_callback上每轮 volatile 层迭代计数、最后错误、日期、预算警告、环境提示、密钥行作为尾随系统提醒注入让缓存前缀保持字节级稳定。horizon/conversation/system_prompt.py horizon/conversation/reminders.pyADK / Vertex 旋钮你设置的配置不是你拥有的代码承重但 Horizon 几乎不写任何机制——它设置一个配置值最多提供一个提示词。别把这些误当成接口压缩Compaction——EventsCompactionConfig拥有触发/保留/事件外科ADK 的LlmEventSummarizer拥有生命周期HorizonSummarizer只换入一个结构化摘要提示词 一个 REFERENCE-ONLY 横幅。它唯一真正自定义的点——压缩前的记忆刷新——属于上面的自我改进接口。horizon/context/summarizer.py可恢复性Resumability——ResumabilityConfig(is_resumableTrue)一行持久化是 Vertex Agent Platform Sessions 的。自定义价值在接口 4 的 delegate 子驱动不在可恢复性本身。前缀缓存Prefix caching——ContextCacheConfig。三层提示词接口 6的存在恰恰是为了让这个缓存的前缀保持字节级稳定。应用由接口组合而成完整的功能而非新接口它们把上面的接口接在一起所以住在各自的文档与代码地图里而不在接口列表里。Routines无人值守 cron—— 组合了环境接口一个全新的、互不相交的lhart-沙箱、guardrails无头模式非 shell 审批自动拒绝与 secrets限定到 routine 声明的名字——这就是爆炸半径边界。一次触发驱动同一个共享 A2A handler 对着预打标签的会话运行因此会记录真实的 Task 历史直接驱动 Runner 会让 UI 空白。触发路径scheduler/routine_tick_endpoint.py隔离在routines/run_context.py。routines.mdSchedulerdream-review / snapshot—— 两个 cron 驱动的维护过程都不是 agent 回合dream-review 是自我改进接口的 cron 化无 A2A handler、无 Tasksnapshot 是每用户沙箱的快照修剪用于 TTL 存活。horizon/scheduler/要把某个子系统搬进你自己的 ADK 应用复制其目录并在文档记录的挂钩点接线即可——上面各子系统的文档携带接线图。故障排查按症状定位到它的所有者在改代码之前先把症状定位到所有者。链按执行一节的顺序运行。下表是原文的完整排查表症状去哪里看为什么回合意外 halt[halted: …]GuardrailsPluginhorizon/guardrails/guardrails_plugin.pysession.state[halt_reason]某个守卫迭代预算、无进展、重复失败设置了halt_reason插件的before_modelhook 在下一轮消费它。检查是哪个守卫触发的。工具调用被阻止或拒绝before_tool链exfil_guardA→policies_guardC→permission_guardD守卫按顺序运行确定是哪一个返回的错误。A 是密钥/外泄C 是硬拒绝 确认D 是交互式询问。模型对有效模型名返回 404GOOGLE_CLOUD_LOCATION/ Vertex 启用状态不是模型名Vertex 区域/启用问题例如设了globalregistry 键没问题。这是 Vertex 层问题不是 Horizon 代码。导出的环境变量区域/provider似乎被忽略horizon/agent.py 顶部 ——os.environ.setdefault(...)agent 用setdefault所以在构建之前导出的值生效如果在 import之后设置默认值已经应用了。源码还提示GOOGLE_CLOUD_PROJECT未设置时会回退到 ADC 默认项目并发出警告。某会话用了错误的模型selected_model状态 select_model_callbackhorizon/models/selector.py/model写selected_modelselect_model_callbackbefore_model第一个把它盖到llm_request.model上。如果未设置应用LHA_ROOT_MODEL/ registry 默认值。available_skills显示错误的用户的技能bind_session_skills_callbackhorizon/tools/skill_reload.py技能工具集是模块全局的bind_session_skills_callbackbefore_agent每轮把它重新指向活跃会话的 workspace。某个事实/偏好没有带到下一会话auto_capture_callbackhorizon/memory/auto_capture.py dream-review通过PreloadMemoryTool预取写回是节流的after_agent不是全量 flush跨会话记忆是 Memory Bank每轮预取——miss 是捕获或预取缺口不是状态丢失。模型发出失效的attachment://链接或泄漏签名 URLredact_artifact_urls_callbackhorizon/context/artifact_url_redaction.py_strip_fake_artifact_linkshorizon/a2a/executor.py签名 URL 从模型视野中被涂掉客户端从 FilePart 渲染工件。伪造的attachment:/sandbox:链接作为兜底被剥离。设计权衡这套架构优化了什么、代价是什么架构优化的是托管优先Managed-first—— ADK 拥有 agent 循环Vertex 拥有模型 / 记忆 / 会话 / 沙箱自定义代码被限制在一小撮自定义接口里。每用户隔离Per-user isolation—— 每个用户有自己的沙箱、密钥作用域与记忆routine 有自己的即弃lhart-沙箱。可恢复性Resumability—— 会话持久化在 Agent Platform Sessions 中并可恢复上下文缓存与三层提示词让前缀跨回合保持字节级稳定。可读的接口Readable interfaces—— 有序回调链与一小组命名守卫让控制流清晰可读让本文档可以与代码一一对应。代价是GCP / Vertex 耦合—— 托管优先的选择把部署绑定到 Vertex AI模型、Memory Bank、Agent Platform Sessions、Sandboxes以及配套的 Cloud Run / Cloud SQL / IAP。README 也提示两个 Cloud Run 服务都保持min_instance_count 1每分钟一次的 tick 付不起冷启动Cloud SQL 持续计费——部署不会缩到零。冷启动Cold-start—— 每用户沙箱供给与服务解析增加首轮延迟。需要维护有序回调链与自定义接口—— 回调顺序就是契约所以在错误位置插入回调是真实的失败模式接口必须与它们挂钩的 ADK 版本保持同步。下一步去哪里extending.md —— 运行与改造这个示例环境旋钮、工具、路由与后端。configuration.md —— 环境变量 / extras 目录。security-model.md —— 逐层认证与安全模型。memory.md —— 记忆、自我改进与 dream-review 循环。commands.md —— slash 命令目录/model、/grant、/yolo等。AGENTS.md —— 详尽、始终最新的内部文档回调顺序、状态键、环境变量。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Long Horizon 架构深度解析：基于 ADK 与 Vertex AI 的长时程自进化 Agent 全景图
Long Horizon 架构深度解析基于 ADK 与 Vertex AI 的长时程自进化 Agent 全景图【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples导读本文是 Long Horizonhorizon包 的架构指南它向你解释这个基于 Google Agent Development KitADK 2.x与 Vertex AI 构建的长时程long-horizon、自我改进self-improvingAgent 是如何组装在一起的以及当你想理解或改动某个行为时应该去哪里看代码。读完本文你将掌握Horizon / ADK / Vertex AI 三层的职责边界与归属判断方法、_build_app_object的完整装配顺序模型、工具、有序回调链、插件、App、每一轮对话在回调链中的执行路径以及各子系统的从这里开始读代码地图——无论你是新维护者还是想把这套 harness 的模式搬进自己 ADK 应用的使用者这份地图都能让你不用先通读全部实现就能定位问题。Horizon 运行在用户的 Google Cloud 与 Workspace 中在每用户沙箱里执行代码、按计划触发对话scheduled chats、使用用户自己的密钥而不向模型暴露它们并在回合之间通过把事实写入记忆memory与把技巧写入技能库skill library来改进自身——这一切都构建在托管原语managed primitives之上而不是重新发明 agent 循环、记忆存储或会话持久化。系统形态一张图看懂全貌整个系统可以用下面的流程图概括原文以 Mermaid 描述这里用文字复述其结构Client客户端Vite 聊天壳chat shell、A2A 对等体A2A peer、agents-cli一次性调用通过A2A JSON-RPC SSE与 Runner 通信。RunnerlhaRunner · FastAPI · ADK 2.5包含pluginsIterationBudget · SiblingAgent · Guardrails、prompt三层stable · cached · volatile skills、modelDispatchingLlm → Gemini 3.6 Flash / 3.1 Pro、compactHorizonSummarizer 压缩旧事件。Tools工具层bash·file_ops·web·clarify·memory·subagentblocking fork。Vertex AI托管底座Memory Bank跨会话记忆、Agent Engine会话、Sandboxes每用户沙箱。Sandbox沙箱本地文件系统开发态· BYOC 容器部署态· 每日快照可选。自我改进回路每轮之后judgefork 写记忆、修补技能绝不阻塞回复→ 按计划dream复查读取近期会话并整理用户画像 → 下一轮通过 Memory Bank 与三层系统提示词surface回来闭环回到 Runner。架构的核心思想是托管优先managed-firstADK 拥有 agent 循环Vertex AI 拥有模型 / 记忆 / 会话 / 沙箱自定义代码被严格限制在一小撮自定义接口里。后面每一节都会展开这个思想。分层归属先搞清楚这个行为属于哪一层大多数问题一旦你知道这个行为归哪一层管就会变得简单。三层职责如下Horizon custom interfaces: env interface, guardrails, secrets, delegation HITL, self-improvement, 3-tier prompt ADK agent loop: Runner, callbacks, plugins, App, sessions, memory Vertex AI managed: Gemini, Memory Bank, Agent Platform Sessions, Sandboxes从底层往上看Vertex AI 是被托管的底座模型Gemini、Memory Bank跨会话记忆、Agent Platform Sessions可恢复的会话持久化、Sandboxes每用户 BYOC 沙箱。Horizon 只配置它们不实现它们。ADK 是 agent 运行时Runner驱动循环——调用模型、运行工具、重复执行App持有 agent 以及插件、压缩/缓存/可恢复性配置有序回调链ordered callback chains与插件是挂钩点会话与记忆服务都是可插拔的。Horizon 没有引入新运行时它用的是 ADK 的运行时。Horizon 是构建在 ADK 之上的、有主见的 harness它装配工具集、有序回调链、插件与App并补充了大多数长时程 agent 需要的自定义接口。定位行为的方法如果问题与模型如何被调用、状态如何在步骤间传递、一个回合如何被持久化/恢复有关那就是ADK——先读 horizon/agent.py 的装配再读 ADK。如果是托管能力模型、记忆、沙箱、配额/区域错误那是Vertex——去查区域与启用状态而不是 Horizon 代码。其余一切——提示词组装、guardrails、secrets、环境接口、委托delegation、自我改进——都是Horizon代码就在本仓库里。构建Construction_build_app_object装配了什么agent 定义在horizon/agent.py中——root_agent ADKApp包含完整的工具/回调/插件装配作为模块级app/root_agent单例只构建一次。horizon/fast_api_app.py负责提供服务它从环境解析会话/记忆/工件后端与沙箱构建 ADKRunner并挂载路由。uvicorn horizon.fast_api_app:app --port 8001 # 被服务的 appfrom horizon.fast_api_app import build_runner runner build_runner() # 嵌入时不依赖 FastAPICLI/批处理服务从环境解析几个关键入口horizon.fast_api_app:app—— FastAPI 表面A2A /lha/*/scheduler/*通过模块__getattr__惰性构建因此裸import horizon保持离线。每个 router 都会挂载通过删除attach_*调用可以只发布子集见 security-model.md。build_runner()—— 解析服务session/memory/artifact 沙箱返回一个纯 ADKRunner便于在没有 HTTP 表面时嵌入。配置走环境变量——LHA_ROOT_MODEL、LHA_ENVIRONMENT_BACKEND、服务 URISESSION_DB_URL、AGENT_ENGINE_RESOURCE_NAME、LOGS_BUCKET_NAME。自定义沙箱后端通过set_environment_provider(factory)安装更深层的改动需要编辑horizon/agent.py。完整目录见 configuration.md。agent.py在 import 时执行app _build_app_object()import horizon保持离线因为包的__init__不导入agent——只有读取horizon.agent/horizon.fast_api_app.app才会触发构建。_build_app_object的装配顺序源码中 horizon/agent.py 按以下顺序组装1. 模型Model——_resolve_root_modelNone→build_root_llm()环境默认值LHA_ROOT_MODEL一个 registry 键 → 基于MODEL_REGISTRY的DispatchingLlm一个BaseLlm实例直接透传绕过 registry 与/model。2. 工具Tools—— 一个显式列表见 agent.py工具说明memory覆盖 add默认与 search原session_search两种动作HorizonPreloadMemoryTool把记忆预取放进缓存排除的 contents 尾部而不是污染缓存指纹见下ReadTool合并的文本 媒体读取write/edit/search_files文件操作三件套artifact工件生成bash/process终端与进程管理subagent子 agentblocking 或 fork_SKILL_TOOLSET会话绑定的技能工具集load_skill覆盖 load 与 reloadroutine无人值守的 cron 任务clarify澄清工具AgentTool(agentweb_research_agent)网页研究作为一个 AgentTool 暴露其中PreloadMemoryTool值得一提库存的PreloadMemoryTool把PAST_CONVERSATIONS追加到system_instruction而该块会被 Gemini 的缓存做指纹识别——它每轮都变缓存就永远无法命中。这个子类把它放到缓存排除的 contents 尾部见horizon/memory/preload.py的HorizonPreloadMemoryTool。3. 有序回调链Ordered callback chains—— Agent 上的六条链before_agent、before_model、after_model、before_tool、after_tool、after_agent。顺序就是契约每条链自上而下执行后面的条目可以读取前面条目设置的状态。4. 插件Plugins——IterationBudgetPlugin(max_tool_calls_per_iteration200)、SIBLING_AGENT_PLUGIN、GuardrailsPlugin()在_build_app_object中硬编码。插件在每个 hook 上先于agent 级回调运行GuardrailsPlugin拥有 halt 逻辑。5. App—— 用ResumabilityConfig(is_resumableTrue)、ContextCacheConfig前缀缓存与EventsCompactionConfig包裹root_agent其中压缩摘要器是HorizonSummarizer压缩摘要器——这是 ADK 的旋钮不是接口。App 配置中几个值得注意的默认值源码原文注释context_cache_configContextCacheConfig( min_tokens4096, # Gemini 3* 模型自身的每模型下限就是 40962048 是死配置 ttl_seconds1800, cache_intervals10, ), events_compaction_configEventsCompactionConfig( token_threshold750_000, # 种子值——每轮被 select_model_callback 覆写为活跃模型的窗口百分比阈值 event_retention_size20, compaction_interval8, # 滑动窗口触发同时每 N 次用户发起的调用确定性触发一次 overlap_size2, summarizerHorizonSummarizer(llmGemini(modelgemini-3.7-flash)), ),执行Execution每一轮对话如何穿过回调链每一轮中ADKRunner驱动root_agent穿过有序回调链与其工具插件在每个 hook 上先运行。链的执行顺序如下与 agent.py 中注册顺序一一对应before_agent首次调用带状态守卫——on_session_start_callback解析 workspace 环境、加载用户画像、预置记忆预取→bind_session_skills_callback把模块全局的技能工具集重新指向本会话的 workspace。before_model——select_model_callback打上每会话模型戳→prune_tool_outputs_callback清零旧的、大的工具结果体以回收上下文→normalize_tool_schemas_callback去掉非 pydantic 声明路径的源码缩进→redact_artifact_urls_callback从模型视野中剥掉签名工件 URL→_slash_command_dispatcher拦截/cmd用户回合路由到 BUILTIN_COMMAND_REGISTRY→system_prompt_assembly_callbackstable context 层→reminder_injection_callback在消息尾部注入 volatile 层保持缓存前缀字节级稳定→subagent_description_callback用实时技能目录 子画像重写 subagent 工具描述必须最后运行以看到最终工具集。模型响应文本或工具调用。before_tool——before_tool_log_callback打上state[in_flight_tool_call]让聊天 spinner 显示运行中 · Ns→exfil_guardLayer A 数据外泄守卫先于 policies_guard 运行以拦截携带密钥的调用→policies_guardLayer C 硬拒绝 确认→permission_guardLayer D 交互式询问最后运行对所有幸存者决定 allow/ask。每个工具都通过环境接口在宿主LocalEnvironment或每用户沙箱中行动——绝不直接碰宿主。after_tool——skill_telemetry_callback更新 view/edit/error 计数器供技能策展使用→tool_call_log_callback为 web UI 实时日志发出结构化工具调用事件。循环重复直到模型产生最终回复。after_agent——auto_capture_callback刷新到 Memory Bank带节流→skill_curator_callback技能的 promote/demote→review_fork_callback后台 judge fork提取持久事实。Halt 机制骑在session.state[halt_reason]上GuardrailsPlugin内的守卫迭代预算、无进展、重复失败设置它插件的before_modelhook 在下一轮消费它见 guardrails_plugin.py其中RepeatedFailureGuard(threshold3)、NoProgressGuard(window5)。agent 上的after_model是空的——无进展检测活在插件里。部署态请求路径在部署层面请求通过 FastAPI 表面进入FastAPI 表面horizon/fast_api_app.py暴露 A2A JSON-RPC 端点、OAuth 回调与/lha/*路由器state、sessions、tasks、memories、secrets、feedback、uploads、sandbox。A2A 调用上文描述的 ADKRunner。跨会话记忆是 Memory Bank见 memory.md——每轮通过 ADK 的PreloadMemoryTool预取由后台 judge fork 写回夜间 dream-review 整合结构化画像与一般记忆。会话持久化在 Agent Runtime 中且可恢复。Cloud Scheduler 驱动 routines作为真实的持久化对话经由与 web 相同的 A2A handler 触发与夜间 dream-review。Routine 的触发路径POST /scheduler/routine-tick包裹在三个 routine ContextVar 中set_routine_run一个全新的隔离lhart-id沙箱绝不用用户的、set_routine_secret_scope只暴露 routine 声明的密钥、set_headless_mode无提示词可用shell 在沙箱中运行非 shell 审批自动拒绝——这样它就能无人值守运行而不触碰用户 workspace详见 routines.md。Web UI 是独立的 Vite SPA生产环境由web/server/的 Express proxy 在 IAP 之后提供FastAPI 不服务 web bundle。后端代码地图从哪里开始读Python 包位于horizon/外层仓库目录保持lha/。找到你关心的子系统先打开它的start-here文件再扩散到支撑文件。下表是原文完整保留的代码地图想了解…从这里开始支撑文件深度文档Agent 本身工具、回调顺序、插件、Apphorizon/agent.pyhorizon/fast_api_app.py被服务的 app Runner本文 AGENTS.md记忆与自我改进horizon/memory/add_memory_tool.pyauto_capture.py、review_fork.py、dream_review.py、user_profile.py、skill_curator.pydocs/memory.md沙箱 / workspace / 环境接口horizon/environment/base.pyEnvironment契约、horizon/sandbox/provider.pySandboxProvider、horizon/sandbox/lifecycle.pyhorizon/environment/local.py、horizon/environment/sandbox.py、sandbox/runtime/容器内 shim、horizon/environment_context.py、horizon/workspace_window.pydocs/sandbox-lifecycle.md外泄守卫horizon/guardrails/exfil_guard.pyguardrails/exfil_config.pydocs/security-model.mdA2AJSON-RPC 传输horizon/a2a/routes.pya2a/executor.py流转换器、a2a/user_converter.py认证的 user_id、a2a/datapart.py—系统提示词与每轮转向horizon/conversation/system_prompt.pyconversation/reminders.pyvolatile 层、conversation/session_start.py、conversation/soul_loader.py—Guardrails 与 halthorizon/guardrails/guardrails_plugin.pyguardrails/policies.py、policy_grants.py、no_progress.py、repeated_failure.pydocs/security-model.md工具权限审批horizon/guardrails/permission_guard.pyguardrails/permission_rules.py、guardrails/command_classify.pydocs/permission-model.md工具file/bash/webhorizon/tools/file_ops.pytools/read.py合并文本媒体读取、tools/processes/bashprocess、tools/web_search.py—子 agent / 委托horizon/subagents/subagent.pysubagents/delegate.py阻塞仍为内部、subagents/spawn.pyfire-and-forget仍为内部、subagents/profiles.py、subagents/descriptions.py—上下文压缩horizon/context/summarizer.pycontext/tool_output_pruning.py、context/compaction_context.pydocs/memory.mdSchedulerdream-review / snapshothorizon/scheduler/dream_review_endpoint.pyscheduler/snapshot_endpoint.py、scheduler/auth.py—Routines隔离沙箱中的无人值守 cron 任务horizon/routines/tools.pyroutines/manifest.py、routines/run_context.py、scheduler/routine_store.py、scheduler/routine_postgres_store.py、scheduler/cron.py、scheduler/routine_tick_endpoint.pydocs/routines.mdSecretshorizon/secrets/store.pysecrets/inject.py、secrets/dotenv.py、horizon/auth/oauth.pyConnect Google—Slash 命令horizon/commands/__init__.pycommands/dispatcher.py—模型 / LLM 路由horizon/models/dispatcher.pymodels/registry.py、models/selector.py、models/media.py—HTTP 路由器/lha/*、/feedbackhorizon/api/每条路由一个文件sessions、state、tasks、memories、sandbox、secrets、uploads、feedback在horizon/fast_api_app.py中挂载docs/security-model.md反馈管线horizon/feedback/sink.pyfeedback/context.py、feedback/models.py、horizon/api/feedback.py路由—遥测 / 可观测性horizon/telemetry/otel.pytelemetry/ui.pyweb 面板实时工具日志—DB 韧性 / 基础设施horizon/infrastructure/db_resilience.pyinfrastructure/resilient_session_service.py、infrastructure/memory_config.py、infrastructure/constants.py—自定义代码的价值点接口、旋钮与应用Horizon 尽量把一切都交给 ADK 和 Vertex。剩下的代码被分成三种性质——旧的扁平化六个模式标签把它们混在了一起你拥有的接口interfaces、你设置的旋钮knobs、以及你从接口组合出的应用applications。定位行为时知道它是三者中的哪一种就决定了这里有没有自定义代码值得读。自定义接口ADK/Vertex 不提供的扩展点每一个都是真实接口一个 Protocol、一个 ContextVar 或一条有序回调链自定义代码在这里真正有价值。大约六个1. 环境接口Environment interface—— Horizon 的Environmenthorizon/environment/base.py是 ADKBaseEnvironment的超集新增list_directory/delete_file/make_dir/download_zip/upload_zip/spawn_process与on_host_fs能力标志置于一个 ContextVar 之后。工具按方法/能力分发绝不做isinstance具体类判断因此同一份工具代码既能在本地宿主horizon/environment/local.py的LocalEnvironment上运行也能在每用户 Sandbox 中运行——通过LHA_ENVIRONMENT_BACKEND字符串或set_environment_provider(factory)可插拔。值得注意的是on_host_fs的安全默认值未知后端一律视为远端无宿主文件系统防止健忘的子类意外碰到宿主。2. 工具 guardrailsTool guardrails—— 有序的before_tool链exfil_guardLayer A →policies_guardLayer C →permission_guardLayer DD 最后运行作为中央交互式询问层对于 shell 工具通过command_classify.py分类命令防止良性片段夹带受限命令加上GuardrailsPlugin迭代/无进展/重复失败 halt 共享一个halt_reason。沙箱出口默认封闭部署态本地开发也默认开启LHA_SANDBOX_INTERNET_ACCESS可双向覆盖无论出口模式如何Layer Aexfil_guard都是外泄边界密钥材料、凭据读取、metadata-server 访问、向非白名单主机的上传形命令。见 security-model.md 与 permission-model.md。3. 每用户密钥Per-user secrets—— 一个SecretStoreProtocolSecretManagerStore|InMemorySecretStore由LHA_SECRET_BACKEND选择可通过set_secret_store覆盖加上环境注入secret_env与 Connect Google OAuth 流程。核心承诺是agent 用用户自己的凭据行动而模型永远看不到它们。与环境的形状相同——Protocol 工厂ADK 在这里什么都不提供。horizon/secrets/horizon/auth/oauth.py。实现上每个用户对应一个 Secret Manager secretlha-secret-sha256(user_id)[:32]保存{name: {value: str, created_at: int_ms}}的 JSON blob带短 TTL 缓存以压低 Secret Manager 配额消耗。4. 子 agent 委托 HITL 回升Sub-agent delegation HITL resurfacing—— 阻塞式delegate与 fire-and-forget 的agentspawn/status/result/wait/cancel/list各自有隔离的上下文窗口与工具集。delegate 驱动一个可恢复的子 agentbuild_resumable_child_runner/drive_child在风险操作审批处暂停、冒泡给人类、然后从存储的FunctionResponse恢复——无需重跑整轮就实现持久的 HITL被阻塞的子 agent 还可以ask_parent沿同一路径升级一个自由文本决策。horizon/subagents/5. 自我改进回路Self-improvement loop—— 节流的after_agent工作记忆写回auto_capture_callback、技能 promote/demoteskill_curator_callback、judge forkreview_fork_callback加上压缩前的记忆刷新spawn_flush_fork由摘要器在事实丢失给有损摘要之前触发与 Memory Bank 上的夜间 dream-review 整合。horizon/memory/6. 三层系统提示词3-tier system prompt—— 常量层一次性构建为Agent(static_instructionbuild_static_instruction(...))让 ADK 自己的请求处理器把它放在每个回调之前而不是 Horizon 手搓每会话缓存每会话上下文层cwd 的项目文件按.horizon.md→LHA.md→AGENTS.md→CLAUDE.md→.cursorrules首匹配发现只加载一个仍骑在before_model_callback上每轮 volatile 层迭代计数、最后错误、日期、预算警告、环境提示、密钥行作为尾随系统提醒注入让缓存前缀保持字节级稳定。horizon/conversation/system_prompt.py horizon/conversation/reminders.pyADK / Vertex 旋钮你设置的配置不是你拥有的代码承重但 Horizon 几乎不写任何机制——它设置一个配置值最多提供一个提示词。别把这些误当成接口压缩Compaction——EventsCompactionConfig拥有触发/保留/事件外科ADK 的LlmEventSummarizer拥有生命周期HorizonSummarizer只换入一个结构化摘要提示词 一个 REFERENCE-ONLY 横幅。它唯一真正自定义的点——压缩前的记忆刷新——属于上面的自我改进接口。horizon/context/summarizer.py可恢复性Resumability——ResumabilityConfig(is_resumableTrue)一行持久化是 Vertex Agent Platform Sessions 的。自定义价值在接口 4 的 delegate 子驱动不在可恢复性本身。前缀缓存Prefix caching——ContextCacheConfig。三层提示词接口 6的存在恰恰是为了让这个缓存的前缀保持字节级稳定。应用由接口组合而成完整的功能而非新接口它们把上面的接口接在一起所以住在各自的文档与代码地图里而不在接口列表里。Routines无人值守 cron—— 组合了环境接口一个全新的、互不相交的lhart-沙箱、guardrails无头模式非 shell 审批自动拒绝与 secrets限定到 routine 声明的名字——这就是爆炸半径边界。一次触发驱动同一个共享 A2A handler 对着预打标签的会话运行因此会记录真实的 Task 历史直接驱动 Runner 会让 UI 空白。触发路径scheduler/routine_tick_endpoint.py隔离在routines/run_context.py。routines.mdSchedulerdream-review / snapshot—— 两个 cron 驱动的维护过程都不是 agent 回合dream-review 是自我改进接口的 cron 化无 A2A handler、无 Tasksnapshot 是每用户沙箱的快照修剪用于 TTL 存活。horizon/scheduler/要把某个子系统搬进你自己的 ADK 应用复制其目录并在文档记录的挂钩点接线即可——上面各子系统的文档携带接线图。故障排查按症状定位到它的所有者在改代码之前先把症状定位到所有者。链按执行一节的顺序运行。下表是原文的完整排查表症状去哪里看为什么回合意外 halt[halted: …]GuardrailsPluginhorizon/guardrails/guardrails_plugin.pysession.state[halt_reason]某个守卫迭代预算、无进展、重复失败设置了halt_reason插件的before_modelhook 在下一轮消费它。检查是哪个守卫触发的。工具调用被阻止或拒绝before_tool链exfil_guardA→policies_guardC→permission_guardD守卫按顺序运行确定是哪一个返回的错误。A 是密钥/外泄C 是硬拒绝 确认D 是交互式询问。模型对有效模型名返回 404GOOGLE_CLOUD_LOCATION/ Vertex 启用状态不是模型名Vertex 区域/启用问题例如设了globalregistry 键没问题。这是 Vertex 层问题不是 Horizon 代码。导出的环境变量区域/provider似乎被忽略horizon/agent.py 顶部 ——os.environ.setdefault(...)agent 用setdefault所以在构建之前导出的值生效如果在 import之后设置默认值已经应用了。源码还提示GOOGLE_CLOUD_PROJECT未设置时会回退到 ADC 默认项目并发出警告。某会话用了错误的模型selected_model状态 select_model_callbackhorizon/models/selector.py/model写selected_modelselect_model_callbackbefore_model第一个把它盖到llm_request.model上。如果未设置应用LHA_ROOT_MODEL/ registry 默认值。available_skills显示错误的用户的技能bind_session_skills_callbackhorizon/tools/skill_reload.py技能工具集是模块全局的bind_session_skills_callbackbefore_agent每轮把它重新指向活跃会话的 workspace。某个事实/偏好没有带到下一会话auto_capture_callbackhorizon/memory/auto_capture.py dream-review通过PreloadMemoryTool预取写回是节流的after_agent不是全量 flush跨会话记忆是 Memory Bank每轮预取——miss 是捕获或预取缺口不是状态丢失。模型发出失效的attachment://链接或泄漏签名 URLredact_artifact_urls_callbackhorizon/context/artifact_url_redaction.py_strip_fake_artifact_linkshorizon/a2a/executor.py签名 URL 从模型视野中被涂掉客户端从 FilePart 渲染工件。伪造的attachment:/sandbox:链接作为兜底被剥离。设计权衡这套架构优化了什么、代价是什么架构优化的是托管优先Managed-first—— ADK 拥有 agent 循环Vertex 拥有模型 / 记忆 / 会话 / 沙箱自定义代码被限制在一小撮自定义接口里。每用户隔离Per-user isolation—— 每个用户有自己的沙箱、密钥作用域与记忆routine 有自己的即弃lhart-沙箱。可恢复性Resumability—— 会话持久化在 Agent Platform Sessions 中并可恢复上下文缓存与三层提示词让前缀跨回合保持字节级稳定。可读的接口Readable interfaces—— 有序回调链与一小组命名守卫让控制流清晰可读让本文档可以与代码一一对应。代价是GCP / Vertex 耦合—— 托管优先的选择把部署绑定到 Vertex AI模型、Memory Bank、Agent Platform Sessions、Sandboxes以及配套的 Cloud Run / Cloud SQL / IAP。README 也提示两个 Cloud Run 服务都保持min_instance_count 1每分钟一次的 tick 付不起冷启动Cloud SQL 持续计费——部署不会缩到零。冷启动Cold-start—— 每用户沙箱供给与服务解析增加首轮延迟。需要维护有序回调链与自定义接口—— 回调顺序就是契约所以在错误位置插入回调是真实的失败模式接口必须与它们挂钩的 ADK 版本保持同步。下一步去哪里extending.md —— 运行与改造这个示例环境旋钮、工具、路由与后端。configuration.md —— 环境变量 / extras 目录。security-model.md —— 逐层认证与安全模型。memory.md —— 记忆、自我改进与 dream-review 循环。commands.md —— slash 命令目录/model、/grant、/yolo等。AGENTS.md —— 详尽、始终最新的内部文档回调顺序、状态键、环境变量。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
