基于 ADK 构建 Long Horizon一个自改进、长时程 Agent Harness 的参考实现【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples导读Long Horizon仓库目录core/python/long-horizon-harness是 ADKAgent Development Kit生态中一个面向长时程任务的 Agent Harness 参考实现它把跨会话记忆、每用户沙箱、工具级 Guardrails、子代理Sub-agents与后台自改进循环组合到同一个 Agent 之上并可直接部署到 Google Agent Platform。本文以该样本的 README.md 为主线结合仓库内的源码、配置与文档讲解它的能力模型、六大自定义接口、本地运行方式、配置项以及部署路径帮助你把它当作可复制的模式库而不是一个只能演示的黑盒。需要先说明该样本不是 Google 官方支持的产品仅用于演示与参考使用前需自行审查、测试与加固。本文中出现的模型名如 Gemini 3.7 Flash、版本与命令均以当前仓库实际内容为准。它解决了什么问题长时程long-horizon任务与单轮问答的本质区别在于Agent 需要跨多个会话持续记住用户的事实与偏好需要在隔离的、可持续复用的执行环境中运行代码需要在无人值守的情况下按计划执行任务并且需要在不拖慢用户响应的前提下不断自我改进。Long Horizon 把这些需求拆成一组可独立理解、可单独移植的能力覆盖四个维度记忆与自改进跨会话记忆cross-session memory在每一轮通过PreloadMemoryTool从 Memory Bank 预取Agent 会保存值得记住的事实并偶尔学习新技术但这一切都在后台完成不阻塞对用户的回复。沙箱与密钥每用户一个 JWT 路由的 BYOC Sandbox回合之间保持热并在下一条消息时重新挂载API 密钥按用户存放在 Secret Manager 中并注入沙箱命令模型只能看到密钥名永远看不到密钥值。集成与扩展原生支持 A2Aagent-to-agent协议任何 Agent 或脚本都能通过 A2A 驱动 Horizon一个subagent工具支持阻塞式委派或backgroundTrue的即发即忘在 workspace 里放下SKILL.md或scripts/name.py后用/reload即可在会话中途加载无需 fork、无需重新部署。可靠性与安全会话可恢复resumable并通过HorizonSummarizer压缩旧轮次迭代预算、无进展、反复失败三类 halt 共享同一个halt_reason并在回合边界一起重置用户在 UI 中提交的结构化反馈通过POST /feedback持久化。技术栈一览README 给出了完整的分层视图这也是理解整个样本的起点层具体选择RunnerADK 2.5.x —— 插件、回调图callback graph、可恢复性、事件压缩ModelGemini 3.6 Flash根 Agent 默认· Flash Latest网络研究子代理MemoryMemory Bank托管存储 自定义自改进循环节流 judge fork、压缩前 flush、夜间 dream-review 整合SessionsAgent Platform SessionsSandboxSandboxesBYOC 容器——每用户一个、JWT 路由、回合间重新挂载快照存活为可选项FrontendVite 8 TanStack Router/Query React 18SurfaceCloud Run Cloud SQL Cloud Scheduler值得注意的部署事实README 明确强调两个 Cloud Run 服务都保持min_instance_count 1因为每分钟一次的 tick 付不起冷启动成本Cloud SQL 会持续计费。这意味着该样本是持续计费的常开资源README 明确建议用完即拆。在托管原语之上Horizon 只添加了一组接口interfaces——即 AGENTS.md 中列出的六项工具 Guardrail 链、EnvironmentContextVar 沙箱层、每用户密钥存储、动态委派 HITL 重新浮出、三层系统提示词组装器、以及基于托管 Memory Bank 的自改进循环。README 还给出了一个重要的概念区分压缩compaction、可恢复性resumability、前缀缓存prefix caching是 ADK/Agent Platform 的旋钮knobsHorizon 只是配置它们而 routines 与 scheduler 则是基于这些接口组合出来的应用applications。这个接口 / 旋钮 / 应用三分法贯穿整个样本的设计值得在阅读源码前先建立起来。六层自定义接口源码级剖析README 的正文只是概述真正的食谱表在 AGENTS.md。这份文件明确写着代码即文档每一行都指向实现该模式的实际生产函数而不是会漂移的玩具示例。以下按该表的 Start-here 列展开。1. Environment 接口工具只调用抽象环境绝不直接碰宿主机horizon/environment/base.py定义了Environment契约——它是 ADKBaseEnvironment的超集额外增加了list_directory/delete_file/make_dir/download_zip/upload_zip/spawn_process返回horizon/environment/process.py中的ProcessHandle以及能力标志on_host_fs和每回合的refresh_auth()。关键设计Environment 实例挂在一个 ContextVar 后面horizon/environment_context.py的active_environment()/set_environment_provider()所有工具都通过active_environment()按方法/能力分发绝不使用isinstance判断具体类仓库中已保证零个具体类isinstance。这让同一份工具代码既能在宿主机LocalEnvironment运行也能在每用户沙箱SandboxEnvironment运行。另一个关键点是每回合认证归 Environment 所有refresh_auth()默认返回True而SandboxEnvironment通过注入的 minter 闭包自行刷新令牌后端消失时返回False触发编排层驱逐。这样对短生命周期令牌的后端而言轻量的set_environment_provider钩子就足够了。完整的 provisioning/reattach/snapshot/upgrade 逻辑则藏在第二个接口SandboxProviderhorizon/sandbox/provider.py之后本地默认是LocalProvider可用set_sandbox_provider覆盖。可移植性提示Environment 契约本身含spawn_process与能力标志是可复制的而 Sandbox REST 后端horizon/environment/sandbox.py及其 provisioning 子系统horizon/sandbox/是 Horizon 特有的可按需跳过。2. 工具 Guardrailsexfil / policy / permission 三层链horizon/guardrails/__init__.py的包文档字符串就是这份接口的契约一个before_tool回调(*, tool, args, tool_context)返回None表示放行返回带error的字典表示阻止。它被加入horizon/agent.py的before_tool_callback列表。在 agent.py 中可以看到完整的执行链顺序即契约before_tool_log_callback—— 记录工具调用供 UI 显示running toolexfil_guardLayer A—— 数据外泄防护拦截携带密钥、读取凭据、访问 metadata server、向非白名单主机发起上传型命令的调用在破坏性规则之前先阻止密钥携带调用policies_guardLayer C—— 硬性禁止破坏性操作、浮出确认层提示ask_is_deny模式下后台子代理/例行任务ask 判定直接硬阻塞permission_guardLayer D—— 交互式逐操作审批yes once / session / always / decline最后运行只对前面守卫的幸存者做 allow/ask 判定保证硬性拒绝的最终裁决权。其中exfil_guard约有 570 行是外泄检测启发式逻辑Layer A 专属移植时可跳过真正值得整体复制的是包文档字符串声明的契约形态以及四层链的编排方式。3. 每用户密钥Protocol 环境选择器 单一注入接口horizon/secrets/store.py定义SecretStoreProtocolSecretManagerStore|InMemorySecretStore由LHA_SECRET_BACKEND选择可用set_secret_store覆盖horizon/secrets/inject.py提供secret_env与set_routine_secret_scopeOAuth 部分在horizon/auth/oauth.pyattach_gcp_oauth_routes/sign_state/verify_state。设计要点Agent 以用户自己的凭据行动而模型只看到密钥名字。OAuth 采用 access-token-only 方案约 1 小时有效不存 refresh tokenstate用 HMAC 签名并与 IAP 身份交叉校验。SecretManagerStore内部完成了 GCPNotFound/AlreadyExists异常翻译因此非 GCP 存储的 fake 实现不需要任何google.api_core导入——这是可测试性优先的细节。4. 子代理委派 HITL 重新浮出horizon/subagents/subagent.py的subagent()是唯一入口内部封装两个仍属内部的 callable阻塞式delegate()subagents/delegate.py与即发即忘的agent()subagents/spawn.py。子代理各自拥有独立的上下文窗口与工具集。最有价值的部分是阻塞路径驱动的可恢复子代理subagents/delegate_runner.py的drive_child子代理遇到危险操作审批时暂停把审批浮出bubble给用户然后从存储的FunctionResponse恢复——这是持久的 HITLhuman-in-the-loop无需重跑整个回合。子代理还可以用ask_parent把一次自由文本决策沿同一条路径升级给父代理。后台子代理与 routines 保持无头模式ask_is_denyask_parent返回优雅的 no-parent 结果。5. 自改进循环三件套 after_agent 压缩前 flushhorizon/memory/auto_capture.py的auto_capture_callback()是入口一个after_agent回调通过 ADK 的CallbackContext.add_session_to_memory()写回配合根 Agent tools 里的PreloadMemoryTool实现跨会话召回两者都接线在horizon/agent.py。after_agent_callback的执行顺序agent.py就是契约auto_capture_callback—— 把刚结束的会话节流式 flush 到 Memory Bank120 秒冷却 每会话 50 条上限skill_curator_callback—— 基于会话遥测计数器对技能做 promote/demotereview_fork_callback—— 派生一个后台 judge agent浮出值得长期保存的事实。记忆的后端访问被隔离在单一接口horizon/memory/adapter.pyMemoryAdapterProtocol memory_adapter()工厂调用方不命名任何具体的 ADK 服务类非 Vertex 后端可优雅降级到NoopMemoryAdapter。README 特别提到它会做梦夜间的一次跨会话 pass 能浮出单次对话无法发现的联系周一提到的事周五浮出并把零散记忆整合成一份用户档案——详见 docs/memory.md。6. 三层系统提示词常量层骑在 ADK 的 static_instruction 上horizon/conversation/system_prompt.py的build_static_instruction()以Agent(static_instruction...)方式接线。常量层是(tool_names, model_name, has_code_executor)的纯函数在 App 构建时只算一次由 ADK 的请求处理器flows/llm_flows/instructions.py确定性地放在每个回调之前——而不是 Horizon 手工维护每会话缓存。上下文层per-cwd 项目文件仍走before_model_callback因为它随会话变化易变层迭代次数/错误/日期 环境提示 密钥行作为尾部的system-reminderContent 注入保证缓存前缀字节稳定。这个字节稳定前缀不是洁癖GeminiContextCacheManager._generate_cache_fingerprint会对整个字符串做哈希任何逐回合变化的内容都会让整段前缀的前缀缓存失效、按全价重新计费。Horizon 为此专门把PreloadMemoryTool子类化为HorizonPreloadMemoryToolhorizon/memory/preload.py把每回合都在变的记忆块放进被缓存排除的 contents 尾部并用LHA_PRELOAD_MAX_MEMORIES/LHA_PRELOAD_MAX_CHARS封顶ADK 的search_memory没有top_k不封顶记忆块会无限增长。旋钮与应用压缩、可恢复性与调度除了六个接口AGENTS.md 还区分了另外两类东西理解它们能避免把配置误当成自定义代码压缩CompactionADK 旋钮App(events_compaction_configEventsCompactionConfig(...))持有触发/保留/事件手术逻辑ADK 的LlmEventSummarizer持有生命周期HorizonSummarizerhorizon/context/summarizer.py只做两件事换上一份结构化总结提示词 REFERENCE-ONLY 横幅以及在压缩前触发spawn_flush_fork让持久事实先落地再被有损摘要吞掉。实际配置值在 agent.pytoken_threshold750_000、event_retention_size20、compaction_interval8、overlap_size2。可恢复性ResumabilityADK 旋钮ResumabilityConfig(is_resumableTrue)一行持久的会话持久化是 Agent Platform Sessions 的事。它的自定义价值在子代理委派接口的子驱动器中。前缀缓存Prefix cachingContextCacheConfigagent.pymin_tokens4096、ttl_seconds1800、cache_intervals10。三层提示词存在的原因正是为了保持该缓存前缀字节稳定。Routines 与 Scheduler应用routines 组合了环境接口全新的、隔离的lhart-沙箱、guardrails无头模式非 shell 审批自动拒绝与密钥限定在 routine 声明的名字内——声明列表就是 blast-radius 边界。一个 routine 触发回合驱动与 Web 共享的同一个 A2A handler、针对预打标的会话运行因此会记录真实的 Task/历史直接驱动 Runner 会让 UI 一片空白。Scheduler 提供夜间 dream-review 与每日 snapshot 两个 cron 驱动的维护 pass。快速上手本地运行README 与 docs/quickstart.md 给出的最低摩擦路径是本地优先工具在宿主机上跑、会话在进程内、Gemini 不需要 Model Garden 开通步骤。推理仍然调用 Vertex没有本地模型。前置条件uvgoogle-agents-cliuvx google-agents-cli setup提供agents-cli命令Google Cloud SDKmakeNode.js 20.19 或 22.12仅 Web UIVite 8 要求Windows 请用 WSL。外加一个已开启计费的 GCP 项目。一次性设置已做过可跳过gcloud auth application-default login # 本地推理凭据 gcloud config set project YOUR_PROJECT_ID # 若 gcloud 默认项目不对则执行 gcloud services enable aiplatform.googleapis.com # Agent Platform 服务的 API克隆并运行# 1. 只克隆这个样本稀疏检出 git clone --depth 1 --filterblob:none --sparse https://github.com/google/adk-samples.git cd adk-samples git sparse-checkout set core/python/long-horizon-harness cd core/python/long-horizon-harness # 2. 运行 —— 首次运行会安装依赖并从 .env.example 生成 .env make dev-localmake dev-local强制LHA_ENVIRONMENT_BACKENDlocal无论.env里写什么首次运行会自动装依赖、生成.env。后端在:8001Web UI 在:3000打开 http://localhost:3000 即可。终端一次性测试用agents-cli run your prompt。本地优先组合在 .env.example 中已有默认值LHA_ENVIRONMENT_BACKENDlocal、USE_IN_MEMORY_SESSIONtrue、LHA_ROOT_MODELgemini-3.7-flash。代价是没有跨会话记忆会话在内存中重启即失、没有隔离沙箱工具在你机器上执行。要获得隔离的每用户沙箱需要进入下一节。可选Vertex 沙箱替代宿主机quickstart 有一条醒目的警告make dev-sandbox单独执行并不会给你隔离沙箱。SandboxProvider.build_environment还需要LHA_RUNTIME_IMAGE和LHA_SANDBOX_CALLER_SA在.env.example中都是空白。离开 Cloud Run 时如果两者任一缺失会记录警告并静默回退到LocalEnvironment——工具继续在你机器上运行。部署后同样条件会抛出SandboxConfigurationError。请先检查后端日志里有没有falling back to LocalEnvironment再假定自己已经隔离。四个一次性步骤# 1. 启用 APImake deploy 时 Terraform 会做但构建镜像需要提前 gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com \ aiplatform.googleapis.com --project$PROJECT_ID # 2. Artifact Registry 仓库terraform/ 里没有任何东西创建这个 gcloud artifacts repositories create lha-sandbox \ --repository-formatdocker --locationus-central1 --project$PROJECT_ID # 3. 构建并推送沙箱运行时镜像用 Cloud Build绝不用本地 docker gcloud builds submit horizon/sandbox/runtime \ --tagus-central1-docker.pkg.dev/$PROJECT_ID/lha-sandbox/runtime:v0.1.0 \ --project$PROJECT_ID # 4. 一个沙箱 LB 校验其 JWT 的 caller SA并授权铸造其令牌 gcloud iam service-accounts create lha-sandbox-caller --project$PROJECT_ID gcloud iam service-accounts add-iam-policy-binding \ lha-sandbox-caller$PROJECT_ID.iam.gserviceaccount.com \ --memberuser:$(gcloud config get-value account) \ --roleroles/iam.serviceAccountTokenCreator --project$PROJECT_ID然后在.env中设置两者并启动LHA_RUNTIME_IMAGEus-central1-docker.pkg.dev/project/lha-sandbox/runtime:v0.1.0 LHA_SANDBOX_CALLER_SAlha-sandbox-callerproject.iam.gserviceaccount.commake dev-sandbox # 或 .env 中设 LHA_ENVIRONMENT_BACKENDsandbox 后 make dev沙箱生命周期细节reattach、快照、版本下限见 docs/sandbox-lifecycle.md。最小的可嵌入 harnessHorizon 完全由环境变量配置因此可以作为一个普通 ASGI 应用嵌入——无 CLI、无 Makefile# my_app.py import os os.environ.setdefault(USE_IN_MEMORY_SESSION, true) # 不需要 Cloud SQL / Agent Engine os.environ.setdefault(LHA_ENVIRONMENT_BACKEND, local) # 工具在本机运行 os.environ.setdefault(LHA_ROOT_MODEL, gemini-3.7-flash) from horizon.fast_api_app import app # 挂载所有路由可在 fast_api_app.py 中裁剪uv run uvicorn my_app:app --port 8001然后通过http://127.0.0.1:8001/a2a用 A2A 驱动它或读取/lha/sessions。注意horizon包__init__刻意不导入agent裸import horizon保持离线不要求 GCP 凭据只有读取horizon.agent/horizon.fast_api_app.app才会触发_build_app_object()的构建。测试确定性测试不需要 GCPuv run pytest tests/unit tests/integration # 确定性测试 —— 不需要 GCP agents-cli eval run # 针对 tests/eval/evalsets/*.json 给行为打分会按调用计费AGENTS.md 给出了更完整的测试矩阵RUN_SMOKE1跑 FastAPI 冒烟不碰 LLM再加RUN_SMOKE_LLM1跑会打 LLM 的冒烟eval 用例用uv sync --extra eval安装google-adk[eval]后用uv run adk eval ...运行。autouse fixturestests/conftest.py提供_hermetic_environment剥离宿主环境变量、_scoped_environment每次测试在 ContextVar 里放一个LocalEnvironment与runner_factory配InMemorySessionService/InMemoryMemoryService的 Runner。有一个需要注意的 CLI 限制AGENTS.md 明确说明非 Horizon 缺陷不要在这里用agents-cli eval run——其推理步骤拒绝任何没有content的 agent 事件而 Horizon 每回合从回调链发出两个仅含 action 的事件导致每个用例都报Malformed agent event: missing content。配置参考按子系统分组的完整环境变量README 指向 docs/configuration.md 作为每个环境变量 依赖 extra的权威目录。.env由make dev-backend加载set -a; . ./.env; set a起点是.env.example。以下按子系统归纳核心项默认值以当前仓库为准核心 / Vertex任何对话必需变量默认说明GOOGLE_CLOUD_PROJECT活动的gcloud配置留空则回退到 ADC 项目make dev会填入GOOGLE_CLOUD_LOCATIONglobal导入期setdefault——你先导出的值优先GOOGLE_GENAI_USE_VERTEXAITrue同上身份 / 认证变量默认说明LHA_AUTH_MODEdevdev所有请求 LHA_DEV_USER_ID·iap校验 IAP JWT·trusted_header原样信任X-LHA-User-Id。dev在K_SERVICE已设置时拒绝运行LHA_DEV_USER_IDdevlocaldev模式下所有请求坍缩到的身份LHA_IAP_AUDIENCE—iap模式下必需Cloud Run audience未设置 ⇒ 500模型变量默认说明LHA_ROOT_MODELgemini-3.7-flash根 Agent 默认horizon/models/registry.py中的键。/model按会话覆盖LHA_VERTEX_SERVICE_TIER关设为priority把 Gemini 钉到 Vertex 的SERVICE_TIER_PRIORITY。默认关闭需要大多数项目没有的 entitlement环境 / 沙箱变量默认说明LHA_ENVIRONMENT_BACKENDlocallocal工具在宿主或sandbox托管 SandboxesLHA_SANDBOX_INTERNET_ACCESSdev 开 / 部署关沙箱出网。0hermetic无出网未设置时本地开发默认开、部署后默认关Cloud Run 设K_SERVICE。出网在创建时烤进沙箱——改动在下一次 provision 生效不能热切换LHA_RUNTIME_IMAGE—沙箱 BYOC 镜像仅sandbox下使用LHA_SANDBOX_CALLER_SA—沙箱 provision 用的服务账号LHA_SANDBOX_LOCATIONus-central1沙箱 provision 的 Agent Platform 区域独立于GOOGLE_CLOUD_LOCATIONLHA_RUNTIME_MIN_VERSION关在 reattach 时强制升级低于此下限的沙箱会话 / 存储变量默认说明USE_IN_MEMORY_SESSION关true⇒ 进程内会话重启即失跳过 Agent Platform Sessions / Cloud SQLSESSION_DB_URL—sqlite/postgres/mysql 会话存储优先级高于 Agent Platform SessionsAGENT_ENGINE_RESOURCE_NAME—会话和Memory Bank 的 Agent Engine 资源LHA_MEMORY_BANK_RESOURCE_NAMEAGENT_ENGINE_RESOURCE_NAME把记忆拆到独立引擎的逃生舱LOGS_BUCKET_NAME—持久化产物的 GCS bucket未设置 ⇒ 内存产物重启即失记忆 / dream-review变量默认说明LHA_DREAM_REVIEW开0在全部路径禁用 dream-reviewLHA_DREAM_SESSION_LIMIT50喂给档案整合的每用户最近会话数上限LHA_DREAM_LOOKBACK_HOURS24/scheduler/dream-review自动发现活跃用户的活动窗口LHA_MEMORY_CONSOLIDATION开0禁用通用记忆的去重/矛盾调和LHA_REVIEW_FORK开0禁用回合后 judge fork记忆 技能策展LHA_PRE_COMPRESS_FLUSH开0禁用压缩前记忆 flush forkLHA_FORK_COOLDOWN120每会话两次后台 fork 之间的秒数上下文 / 压缩变量默认说明LHA_PRUNE_TOOL_OUTPUTS开0禁用对旧的大工具结果体清零LHA_PRELOAD_MAX_MEMORIES20注入每回合PAST_CONVERSATIONS块的记忆条数上限ADKsearch_memory无top_kLHA_PRELOAD_MAX_CHARS4000同块的字符上限LHA_COMPACTION_WINDOW_FRACTION0.75压缩触发的模型输入窗口占比调度 / routines变量默认说明LHA_ROUTINE_STOREmemorymemory不持久或postgres需LHA_REMINDER_DB_URLlha[scheduler]LHA_REMINDER_DB_URL—routines 弹性会话的 Postgres URL名字是历史遗留LHA_SCHEDULER_SA/LHA_SCHEDULER_AUDIENCE—/scheduler/*接受的 OIDC token 的 SA 与aud未设置则端点拒绝快照Phase C代码默认关但terraform/cloud_run.tf在部署后端上设置LHA_SNAPSHOT_ENABLED 1且terraform/cloud_scheduler.tf无条件创建每日任务——所以make deploy后 Phase C 是开的。LHA_SNAPSHOT_TTL默认30d、LHA_SNAPSHOT_KEEP默认2调保留策略。密钥与 Connect GoogleOAuthLHA_SECRET_BACKEND默认secretmanager可选memory选择每用户密钥存储后端LHA_GCP_OAUTH_CLIENT_ID/_CLIENT_SECRET/_REDIRECT_URI启用Connect Google按钮未设置 ⇒/connect返回 503。OAuth 客户端需要你自己在 Google Cloud Console 创建redirect URI 指向your-host/lha/gcp/callback本地开发为http://localhost:3000/lha/gcp/callback。令牌按用户存进密钥存储注入沙箱命令时模型只看到名字永远看不到值token 为 access-token-only约 1 小时不请求 refresh过期后用户重新点击续期。依赖 extraspyproject.toml核心安装不需要任何 extralha[postgres]asyncpg、yoyo-migrations、bcrypt——持久 postgres 存储、lha[scheduler] postgres、lha[data]pandas/matplotlib/seaborn沙箱内数据分析、lha[full]/lha[all]全部。安装示例uv pip install lha[full]。部署一条命令的三步走README 明确说明make deploy一条命令同时完成基础设施 provision 和代码上线分三步Terraformterraform/provision 基础Cloud SQL、Secret Manager、IAM 服务账号与角色、Cloud Scheduler 任务、IAP、GCS bucket、必需 API 启用外加两个 Cloud Run骨架lha后端、lha-webIAP 代理使用占位镜像。agents-cli deploy构建并滚动真实后端镜像到lha。Cloud Build gcloud run deploy构建并滚动 Web 镜像到lha-web。两个服务对镜像都设置了ignore_changes因此步骤 2–3 永远不会与 Terraform 打架。前置条件terraform、agents-cli、gcloud和一个项目gcloud config set project id或PROJECT_IDid make deploy。IAP 访问默认是空的。务必在make deploy前设置TF_VAR_iap_users[user:youexample.com]或之后重跑否则你将被锁在 Web UI 之外。持续计费的常开资源尤其 Cloud SQL外加两个 Cloud Run 服务各一个常驻实例——用完记得全部拆除。推送到 Artifact Registrycloud-run-source-deploy的容器镜像不受 Terraform 管理make destroy后仍然存在如在意存储请单独删除make destroy # 先关掉删除保护然后 terraform destroy 以上全部资源Makefile 中的其他常用目标Makefilemake dev全新克隆友好首次自动装依赖、生成.env然后后端 :8001 Web :3000、make dev-local/make dev-sandbox强制后端类型、make dev-backend/make dev-web只起一半、make dev-stop杀掉 :8001 / :3000、make setup只装依赖生成 .env 不起服务。设计权衡与适用边界README 与 docs/architecture.md 都坦率列出了权衡。Horizon 优化的是托管优先Managed-first——ADK 拥有 agent loopVertex 拥有模型/记忆/会话/沙箱自定义代码被压缩到少数几个自定义接口里每用户隔离——每个用户有自己的沙箱、密钥作用域与记忆routine 有自己的一次性lhart-沙箱可恢复性——会话持久化在 Agent Platform Sessions 并恢复上下文缓存与三层提示词让前缀跨回合字节稳定可读的接口——有序回调链 一组命名守卫让控制流清晰可映射。代价是GCP / Vertex 强耦合——托管优先的选择把部署绑死在 Vertex AI模型、Memory Bank、Agent Platform Sessions、Sandboxes及配套的 Cloud Run / Cloud SQL / IAP冷启动——每用户沙箱 provision 与服务解析增加首回合延迟有序回调链与自定义接口需要维护——回调顺序即契约插错位置就是真实的故障模式接口必须与其钩住的 ADK 版本保持同步。架构文档还给出了一个定位症状的方法论先判断行为属于哪一层——模型如何被调用、回合间状态如何传递、回合如何持久化/恢复是ADK读horizon/agent.py的接线再读 ADK托管能力模型、记忆、沙箱、配额/区域错误是Vertex区域与启用问题不是 Horizon 代码其余一切——提示词组装、守卫、密钥、环境接口、委派、自改进——是Horizon就在本仓库里。结语把模式移植进你自己的 AgentREADME 给的使用方式不是跑起来看看而是读它然后把模式移植进你自己的 Agent。推荐的研读路径AGENTS.md 的 Study order是先通读 docs/architecture.md 建立地图挑一个模式打开它的真实函数读对应的深入文档最后再看维护者视角的完整接线回调顺序、state 键、环境变量都在 AGENTS.md。深潜文档还包括 docs/security-model.md逐层安全模型指向任何真实使用前必读、docs/extending.md扩展点换模型、加工具/路由、插自定义沙箱、教它技能、docs/commands.md斜杠命令目录与 docs/routines.md无人值守例行任务。一句话总结Long Horizon 的价值不在又一个 demo Agent而在于它示范了一种在托管原语之上以最小自定义代码构建生产级长时程 Agent的克制做法——自定义代码只出现在六个接口里其余全部是旋钮与应用。把这六份契约带走你的下一个长时程 Agent 就有了骨架。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
基于 ADK 构建 Long Horizon：一个自改进、长时程 Agent Harness 的参考实现
基于 ADK 构建 Long Horizon一个自改进、长时程 Agent Harness 的参考实现【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples导读Long Horizon仓库目录core/python/long-horizon-harness是 ADKAgent Development Kit生态中一个面向长时程任务的 Agent Harness 参考实现它把跨会话记忆、每用户沙箱、工具级 Guardrails、子代理Sub-agents与后台自改进循环组合到同一个 Agent 之上并可直接部署到 Google Agent Platform。本文以该样本的 README.md 为主线结合仓库内的源码、配置与文档讲解它的能力模型、六大自定义接口、本地运行方式、配置项以及部署路径帮助你把它当作可复制的模式库而不是一个只能演示的黑盒。需要先说明该样本不是 Google 官方支持的产品仅用于演示与参考使用前需自行审查、测试与加固。本文中出现的模型名如 Gemini 3.7 Flash、版本与命令均以当前仓库实际内容为准。它解决了什么问题长时程long-horizon任务与单轮问答的本质区别在于Agent 需要跨多个会话持续记住用户的事实与偏好需要在隔离的、可持续复用的执行环境中运行代码需要在无人值守的情况下按计划执行任务并且需要在不拖慢用户响应的前提下不断自我改进。Long Horizon 把这些需求拆成一组可独立理解、可单独移植的能力覆盖四个维度记忆与自改进跨会话记忆cross-session memory在每一轮通过PreloadMemoryTool从 Memory Bank 预取Agent 会保存值得记住的事实并偶尔学习新技术但这一切都在后台完成不阻塞对用户的回复。沙箱与密钥每用户一个 JWT 路由的 BYOC Sandbox回合之间保持热并在下一条消息时重新挂载API 密钥按用户存放在 Secret Manager 中并注入沙箱命令模型只能看到密钥名永远看不到密钥值。集成与扩展原生支持 A2Aagent-to-agent协议任何 Agent 或脚本都能通过 A2A 驱动 Horizon一个subagent工具支持阻塞式委派或backgroundTrue的即发即忘在 workspace 里放下SKILL.md或scripts/name.py后用/reload即可在会话中途加载无需 fork、无需重新部署。可靠性与安全会话可恢复resumable并通过HorizonSummarizer压缩旧轮次迭代预算、无进展、反复失败三类 halt 共享同一个halt_reason并在回合边界一起重置用户在 UI 中提交的结构化反馈通过POST /feedback持久化。技术栈一览README 给出了完整的分层视图这也是理解整个样本的起点层具体选择RunnerADK 2.5.x —— 插件、回调图callback graph、可恢复性、事件压缩ModelGemini 3.6 Flash根 Agent 默认· Flash Latest网络研究子代理MemoryMemory Bank托管存储 自定义自改进循环节流 judge fork、压缩前 flush、夜间 dream-review 整合SessionsAgent Platform SessionsSandboxSandboxesBYOC 容器——每用户一个、JWT 路由、回合间重新挂载快照存活为可选项FrontendVite 8 TanStack Router/Query React 18SurfaceCloud Run Cloud SQL Cloud Scheduler值得注意的部署事实README 明确强调两个 Cloud Run 服务都保持min_instance_count 1因为每分钟一次的 tick 付不起冷启动成本Cloud SQL 会持续计费。这意味着该样本是持续计费的常开资源README 明确建议用完即拆。在托管原语之上Horizon 只添加了一组接口interfaces——即 AGENTS.md 中列出的六项工具 Guardrail 链、EnvironmentContextVar 沙箱层、每用户密钥存储、动态委派 HITL 重新浮出、三层系统提示词组装器、以及基于托管 Memory Bank 的自改进循环。README 还给出了一个重要的概念区分压缩compaction、可恢复性resumability、前缀缓存prefix caching是 ADK/Agent Platform 的旋钮knobsHorizon 只是配置它们而 routines 与 scheduler 则是基于这些接口组合出来的应用applications。这个接口 / 旋钮 / 应用三分法贯穿整个样本的设计值得在阅读源码前先建立起来。六层自定义接口源码级剖析README 的正文只是概述真正的食谱表在 AGENTS.md。这份文件明确写着代码即文档每一行都指向实现该模式的实际生产函数而不是会漂移的玩具示例。以下按该表的 Start-here 列展开。1. Environment 接口工具只调用抽象环境绝不直接碰宿主机horizon/environment/base.py定义了Environment契约——它是 ADKBaseEnvironment的超集额外增加了list_directory/delete_file/make_dir/download_zip/upload_zip/spawn_process返回horizon/environment/process.py中的ProcessHandle以及能力标志on_host_fs和每回合的refresh_auth()。关键设计Environment 实例挂在一个 ContextVar 后面horizon/environment_context.py的active_environment()/set_environment_provider()所有工具都通过active_environment()按方法/能力分发绝不使用isinstance判断具体类仓库中已保证零个具体类isinstance。这让同一份工具代码既能在宿主机LocalEnvironment运行也能在每用户沙箱SandboxEnvironment运行。另一个关键点是每回合认证归 Environment 所有refresh_auth()默认返回True而SandboxEnvironment通过注入的 minter 闭包自行刷新令牌后端消失时返回False触发编排层驱逐。这样对短生命周期令牌的后端而言轻量的set_environment_provider钩子就足够了。完整的 provisioning/reattach/snapshot/upgrade 逻辑则藏在第二个接口SandboxProviderhorizon/sandbox/provider.py之后本地默认是LocalProvider可用set_sandbox_provider覆盖。可移植性提示Environment 契约本身含spawn_process与能力标志是可复制的而 Sandbox REST 后端horizon/environment/sandbox.py及其 provisioning 子系统horizon/sandbox/是 Horizon 特有的可按需跳过。2. 工具 Guardrailsexfil / policy / permission 三层链horizon/guardrails/__init__.py的包文档字符串就是这份接口的契约一个before_tool回调(*, tool, args, tool_context)返回None表示放行返回带error的字典表示阻止。它被加入horizon/agent.py的before_tool_callback列表。在 agent.py 中可以看到完整的执行链顺序即契约before_tool_log_callback—— 记录工具调用供 UI 显示running toolexfil_guardLayer A—— 数据外泄防护拦截携带密钥、读取凭据、访问 metadata server、向非白名单主机发起上传型命令的调用在破坏性规则之前先阻止密钥携带调用policies_guardLayer C—— 硬性禁止破坏性操作、浮出确认层提示ask_is_deny模式下后台子代理/例行任务ask 判定直接硬阻塞permission_guardLayer D—— 交互式逐操作审批yes once / session / always / decline最后运行只对前面守卫的幸存者做 allow/ask 判定保证硬性拒绝的最终裁决权。其中exfil_guard约有 570 行是外泄检测启发式逻辑Layer A 专属移植时可跳过真正值得整体复制的是包文档字符串声明的契约形态以及四层链的编排方式。3. 每用户密钥Protocol 环境选择器 单一注入接口horizon/secrets/store.py定义SecretStoreProtocolSecretManagerStore|InMemorySecretStore由LHA_SECRET_BACKEND选择可用set_secret_store覆盖horizon/secrets/inject.py提供secret_env与set_routine_secret_scopeOAuth 部分在horizon/auth/oauth.pyattach_gcp_oauth_routes/sign_state/verify_state。设计要点Agent 以用户自己的凭据行动而模型只看到密钥名字。OAuth 采用 access-token-only 方案约 1 小时有效不存 refresh tokenstate用 HMAC 签名并与 IAP 身份交叉校验。SecretManagerStore内部完成了 GCPNotFound/AlreadyExists异常翻译因此非 GCP 存储的 fake 实现不需要任何google.api_core导入——这是可测试性优先的细节。4. 子代理委派 HITL 重新浮出horizon/subagents/subagent.py的subagent()是唯一入口内部封装两个仍属内部的 callable阻塞式delegate()subagents/delegate.py与即发即忘的agent()subagents/spawn.py。子代理各自拥有独立的上下文窗口与工具集。最有价值的部分是阻塞路径驱动的可恢复子代理subagents/delegate_runner.py的drive_child子代理遇到危险操作审批时暂停把审批浮出bubble给用户然后从存储的FunctionResponse恢复——这是持久的 HITLhuman-in-the-loop无需重跑整个回合。子代理还可以用ask_parent把一次自由文本决策沿同一条路径升级给父代理。后台子代理与 routines 保持无头模式ask_is_denyask_parent返回优雅的 no-parent 结果。5. 自改进循环三件套 after_agent 压缩前 flushhorizon/memory/auto_capture.py的auto_capture_callback()是入口一个after_agent回调通过 ADK 的CallbackContext.add_session_to_memory()写回配合根 Agent tools 里的PreloadMemoryTool实现跨会话召回两者都接线在horizon/agent.py。after_agent_callback的执行顺序agent.py就是契约auto_capture_callback—— 把刚结束的会话节流式 flush 到 Memory Bank120 秒冷却 每会话 50 条上限skill_curator_callback—— 基于会话遥测计数器对技能做 promote/demotereview_fork_callback—— 派生一个后台 judge agent浮出值得长期保存的事实。记忆的后端访问被隔离在单一接口horizon/memory/adapter.pyMemoryAdapterProtocol memory_adapter()工厂调用方不命名任何具体的 ADK 服务类非 Vertex 后端可优雅降级到NoopMemoryAdapter。README 特别提到它会做梦夜间的一次跨会话 pass 能浮出单次对话无法发现的联系周一提到的事周五浮出并把零散记忆整合成一份用户档案——详见 docs/memory.md。6. 三层系统提示词常量层骑在 ADK 的 static_instruction 上horizon/conversation/system_prompt.py的build_static_instruction()以Agent(static_instruction...)方式接线。常量层是(tool_names, model_name, has_code_executor)的纯函数在 App 构建时只算一次由 ADK 的请求处理器flows/llm_flows/instructions.py确定性地放在每个回调之前——而不是 Horizon 手工维护每会话缓存。上下文层per-cwd 项目文件仍走before_model_callback因为它随会话变化易变层迭代次数/错误/日期 环境提示 密钥行作为尾部的system-reminderContent 注入保证缓存前缀字节稳定。这个字节稳定前缀不是洁癖GeminiContextCacheManager._generate_cache_fingerprint会对整个字符串做哈希任何逐回合变化的内容都会让整段前缀的前缀缓存失效、按全价重新计费。Horizon 为此专门把PreloadMemoryTool子类化为HorizonPreloadMemoryToolhorizon/memory/preload.py把每回合都在变的记忆块放进被缓存排除的 contents 尾部并用LHA_PRELOAD_MAX_MEMORIES/LHA_PRELOAD_MAX_CHARS封顶ADK 的search_memory没有top_k不封顶记忆块会无限增长。旋钮与应用压缩、可恢复性与调度除了六个接口AGENTS.md 还区分了另外两类东西理解它们能避免把配置误当成自定义代码压缩CompactionADK 旋钮App(events_compaction_configEventsCompactionConfig(...))持有触发/保留/事件手术逻辑ADK 的LlmEventSummarizer持有生命周期HorizonSummarizerhorizon/context/summarizer.py只做两件事换上一份结构化总结提示词 REFERENCE-ONLY 横幅以及在压缩前触发spawn_flush_fork让持久事实先落地再被有损摘要吞掉。实际配置值在 agent.pytoken_threshold750_000、event_retention_size20、compaction_interval8、overlap_size2。可恢复性ResumabilityADK 旋钮ResumabilityConfig(is_resumableTrue)一行持久的会话持久化是 Agent Platform Sessions 的事。它的自定义价值在子代理委派接口的子驱动器中。前缀缓存Prefix cachingContextCacheConfigagent.pymin_tokens4096、ttl_seconds1800、cache_intervals10。三层提示词存在的原因正是为了保持该缓存前缀字节稳定。Routines 与 Scheduler应用routines 组合了环境接口全新的、隔离的lhart-沙箱、guardrails无头模式非 shell 审批自动拒绝与密钥限定在 routine 声明的名字内——声明列表就是 blast-radius 边界。一个 routine 触发回合驱动与 Web 共享的同一个 A2A handler、针对预打标的会话运行因此会记录真实的 Task/历史直接驱动 Runner 会让 UI 一片空白。Scheduler 提供夜间 dream-review 与每日 snapshot 两个 cron 驱动的维护 pass。快速上手本地运行README 与 docs/quickstart.md 给出的最低摩擦路径是本地优先工具在宿主机上跑、会话在进程内、Gemini 不需要 Model Garden 开通步骤。推理仍然调用 Vertex没有本地模型。前置条件uvgoogle-agents-cliuvx google-agents-cli setup提供agents-cli命令Google Cloud SDKmakeNode.js 20.19 或 22.12仅 Web UIVite 8 要求Windows 请用 WSL。外加一个已开启计费的 GCP 项目。一次性设置已做过可跳过gcloud auth application-default login # 本地推理凭据 gcloud config set project YOUR_PROJECT_ID # 若 gcloud 默认项目不对则执行 gcloud services enable aiplatform.googleapis.com # Agent Platform 服务的 API克隆并运行# 1. 只克隆这个样本稀疏检出 git clone --depth 1 --filterblob:none --sparse https://github.com/google/adk-samples.git cd adk-samples git sparse-checkout set core/python/long-horizon-harness cd core/python/long-horizon-harness # 2. 运行 —— 首次运行会安装依赖并从 .env.example 生成 .env make dev-localmake dev-local强制LHA_ENVIRONMENT_BACKENDlocal无论.env里写什么首次运行会自动装依赖、生成.env。后端在:8001Web UI 在:3000打开 http://localhost:3000 即可。终端一次性测试用agents-cli run your prompt。本地优先组合在 .env.example 中已有默认值LHA_ENVIRONMENT_BACKENDlocal、USE_IN_MEMORY_SESSIONtrue、LHA_ROOT_MODELgemini-3.7-flash。代价是没有跨会话记忆会话在内存中重启即失、没有隔离沙箱工具在你机器上执行。要获得隔离的每用户沙箱需要进入下一节。可选Vertex 沙箱替代宿主机quickstart 有一条醒目的警告make dev-sandbox单独执行并不会给你隔离沙箱。SandboxProvider.build_environment还需要LHA_RUNTIME_IMAGE和LHA_SANDBOX_CALLER_SA在.env.example中都是空白。离开 Cloud Run 时如果两者任一缺失会记录警告并静默回退到LocalEnvironment——工具继续在你机器上运行。部署后同样条件会抛出SandboxConfigurationError。请先检查后端日志里有没有falling back to LocalEnvironment再假定自己已经隔离。四个一次性步骤# 1. 启用 APImake deploy 时 Terraform 会做但构建镜像需要提前 gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com \ aiplatform.googleapis.com --project$PROJECT_ID # 2. Artifact Registry 仓库terraform/ 里没有任何东西创建这个 gcloud artifacts repositories create lha-sandbox \ --repository-formatdocker --locationus-central1 --project$PROJECT_ID # 3. 构建并推送沙箱运行时镜像用 Cloud Build绝不用本地 docker gcloud builds submit horizon/sandbox/runtime \ --tagus-central1-docker.pkg.dev/$PROJECT_ID/lha-sandbox/runtime:v0.1.0 \ --project$PROJECT_ID # 4. 一个沙箱 LB 校验其 JWT 的 caller SA并授权铸造其令牌 gcloud iam service-accounts create lha-sandbox-caller --project$PROJECT_ID gcloud iam service-accounts add-iam-policy-binding \ lha-sandbox-caller$PROJECT_ID.iam.gserviceaccount.com \ --memberuser:$(gcloud config get-value account) \ --roleroles/iam.serviceAccountTokenCreator --project$PROJECT_ID然后在.env中设置两者并启动LHA_RUNTIME_IMAGEus-central1-docker.pkg.dev/project/lha-sandbox/runtime:v0.1.0 LHA_SANDBOX_CALLER_SAlha-sandbox-callerproject.iam.gserviceaccount.commake dev-sandbox # 或 .env 中设 LHA_ENVIRONMENT_BACKENDsandbox 后 make dev沙箱生命周期细节reattach、快照、版本下限见 docs/sandbox-lifecycle.md。最小的可嵌入 harnessHorizon 完全由环境变量配置因此可以作为一个普通 ASGI 应用嵌入——无 CLI、无 Makefile# my_app.py import os os.environ.setdefault(USE_IN_MEMORY_SESSION, true) # 不需要 Cloud SQL / Agent Engine os.environ.setdefault(LHA_ENVIRONMENT_BACKEND, local) # 工具在本机运行 os.environ.setdefault(LHA_ROOT_MODEL, gemini-3.7-flash) from horizon.fast_api_app import app # 挂载所有路由可在 fast_api_app.py 中裁剪uv run uvicorn my_app:app --port 8001然后通过http://127.0.0.1:8001/a2a用 A2A 驱动它或读取/lha/sessions。注意horizon包__init__刻意不导入agent裸import horizon保持离线不要求 GCP 凭据只有读取horizon.agent/horizon.fast_api_app.app才会触发_build_app_object()的构建。测试确定性测试不需要 GCPuv run pytest tests/unit tests/integration # 确定性测试 —— 不需要 GCP agents-cli eval run # 针对 tests/eval/evalsets/*.json 给行为打分会按调用计费AGENTS.md 给出了更完整的测试矩阵RUN_SMOKE1跑 FastAPI 冒烟不碰 LLM再加RUN_SMOKE_LLM1跑会打 LLM 的冒烟eval 用例用uv sync --extra eval安装google-adk[eval]后用uv run adk eval ...运行。autouse fixturestests/conftest.py提供_hermetic_environment剥离宿主环境变量、_scoped_environment每次测试在 ContextVar 里放一个LocalEnvironment与runner_factory配InMemorySessionService/InMemoryMemoryService的 Runner。有一个需要注意的 CLI 限制AGENTS.md 明确说明非 Horizon 缺陷不要在这里用agents-cli eval run——其推理步骤拒绝任何没有content的 agent 事件而 Horizon 每回合从回调链发出两个仅含 action 的事件导致每个用例都报Malformed agent event: missing content。配置参考按子系统分组的完整环境变量README 指向 docs/configuration.md 作为每个环境变量 依赖 extra的权威目录。.env由make dev-backend加载set -a; . ./.env; set a起点是.env.example。以下按子系统归纳核心项默认值以当前仓库为准核心 / Vertex任何对话必需变量默认说明GOOGLE_CLOUD_PROJECT活动的gcloud配置留空则回退到 ADC 项目make dev会填入GOOGLE_CLOUD_LOCATIONglobal导入期setdefault——你先导出的值优先GOOGLE_GENAI_USE_VERTEXAITrue同上身份 / 认证变量默认说明LHA_AUTH_MODEdevdev所有请求 LHA_DEV_USER_ID·iap校验 IAP JWT·trusted_header原样信任X-LHA-User-Id。dev在K_SERVICE已设置时拒绝运行LHA_DEV_USER_IDdevlocaldev模式下所有请求坍缩到的身份LHA_IAP_AUDIENCE—iap模式下必需Cloud Run audience未设置 ⇒ 500模型变量默认说明LHA_ROOT_MODELgemini-3.7-flash根 Agent 默认horizon/models/registry.py中的键。/model按会话覆盖LHA_VERTEX_SERVICE_TIER关设为priority把 Gemini 钉到 Vertex 的SERVICE_TIER_PRIORITY。默认关闭需要大多数项目没有的 entitlement环境 / 沙箱变量默认说明LHA_ENVIRONMENT_BACKENDlocallocal工具在宿主或sandbox托管 SandboxesLHA_SANDBOX_INTERNET_ACCESSdev 开 / 部署关沙箱出网。0hermetic无出网未设置时本地开发默认开、部署后默认关Cloud Run 设K_SERVICE。出网在创建时烤进沙箱——改动在下一次 provision 生效不能热切换LHA_RUNTIME_IMAGE—沙箱 BYOC 镜像仅sandbox下使用LHA_SANDBOX_CALLER_SA—沙箱 provision 用的服务账号LHA_SANDBOX_LOCATIONus-central1沙箱 provision 的 Agent Platform 区域独立于GOOGLE_CLOUD_LOCATIONLHA_RUNTIME_MIN_VERSION关在 reattach 时强制升级低于此下限的沙箱会话 / 存储变量默认说明USE_IN_MEMORY_SESSION关true⇒ 进程内会话重启即失跳过 Agent Platform Sessions / Cloud SQLSESSION_DB_URL—sqlite/postgres/mysql 会话存储优先级高于 Agent Platform SessionsAGENT_ENGINE_RESOURCE_NAME—会话和Memory Bank 的 Agent Engine 资源LHA_MEMORY_BANK_RESOURCE_NAMEAGENT_ENGINE_RESOURCE_NAME把记忆拆到独立引擎的逃生舱LOGS_BUCKET_NAME—持久化产物的 GCS bucket未设置 ⇒ 内存产物重启即失记忆 / dream-review变量默认说明LHA_DREAM_REVIEW开0在全部路径禁用 dream-reviewLHA_DREAM_SESSION_LIMIT50喂给档案整合的每用户最近会话数上限LHA_DREAM_LOOKBACK_HOURS24/scheduler/dream-review自动发现活跃用户的活动窗口LHA_MEMORY_CONSOLIDATION开0禁用通用记忆的去重/矛盾调和LHA_REVIEW_FORK开0禁用回合后 judge fork记忆 技能策展LHA_PRE_COMPRESS_FLUSH开0禁用压缩前记忆 flush forkLHA_FORK_COOLDOWN120每会话两次后台 fork 之间的秒数上下文 / 压缩变量默认说明LHA_PRUNE_TOOL_OUTPUTS开0禁用对旧的大工具结果体清零LHA_PRELOAD_MAX_MEMORIES20注入每回合PAST_CONVERSATIONS块的记忆条数上限ADKsearch_memory无top_kLHA_PRELOAD_MAX_CHARS4000同块的字符上限LHA_COMPACTION_WINDOW_FRACTION0.75压缩触发的模型输入窗口占比调度 / routines变量默认说明LHA_ROUTINE_STOREmemorymemory不持久或postgres需LHA_REMINDER_DB_URLlha[scheduler]LHA_REMINDER_DB_URL—routines 弹性会话的 Postgres URL名字是历史遗留LHA_SCHEDULER_SA/LHA_SCHEDULER_AUDIENCE—/scheduler/*接受的 OIDC token 的 SA 与aud未设置则端点拒绝快照Phase C代码默认关但terraform/cloud_run.tf在部署后端上设置LHA_SNAPSHOT_ENABLED 1且terraform/cloud_scheduler.tf无条件创建每日任务——所以make deploy后 Phase C 是开的。LHA_SNAPSHOT_TTL默认30d、LHA_SNAPSHOT_KEEP默认2调保留策略。密钥与 Connect GoogleOAuthLHA_SECRET_BACKEND默认secretmanager可选memory选择每用户密钥存储后端LHA_GCP_OAUTH_CLIENT_ID/_CLIENT_SECRET/_REDIRECT_URI启用Connect Google按钮未设置 ⇒/connect返回 503。OAuth 客户端需要你自己在 Google Cloud Console 创建redirect URI 指向your-host/lha/gcp/callback本地开发为http://localhost:3000/lha/gcp/callback。令牌按用户存进密钥存储注入沙箱命令时模型只看到名字永远看不到值token 为 access-token-only约 1 小时不请求 refresh过期后用户重新点击续期。依赖 extraspyproject.toml核心安装不需要任何 extralha[postgres]asyncpg、yoyo-migrations、bcrypt——持久 postgres 存储、lha[scheduler] postgres、lha[data]pandas/matplotlib/seaborn沙箱内数据分析、lha[full]/lha[all]全部。安装示例uv pip install lha[full]。部署一条命令的三步走README 明确说明make deploy一条命令同时完成基础设施 provision 和代码上线分三步Terraformterraform/provision 基础Cloud SQL、Secret Manager、IAM 服务账号与角色、Cloud Scheduler 任务、IAP、GCS bucket、必需 API 启用外加两个 Cloud Run骨架lha后端、lha-webIAP 代理使用占位镜像。agents-cli deploy构建并滚动真实后端镜像到lha。Cloud Build gcloud run deploy构建并滚动 Web 镜像到lha-web。两个服务对镜像都设置了ignore_changes因此步骤 2–3 永远不会与 Terraform 打架。前置条件terraform、agents-cli、gcloud和一个项目gcloud config set project id或PROJECT_IDid make deploy。IAP 访问默认是空的。务必在make deploy前设置TF_VAR_iap_users[user:youexample.com]或之后重跑否则你将被锁在 Web UI 之外。持续计费的常开资源尤其 Cloud SQL外加两个 Cloud Run 服务各一个常驻实例——用完记得全部拆除。推送到 Artifact Registrycloud-run-source-deploy的容器镜像不受 Terraform 管理make destroy后仍然存在如在意存储请单独删除make destroy # 先关掉删除保护然后 terraform destroy 以上全部资源Makefile 中的其他常用目标Makefilemake dev全新克隆友好首次自动装依赖、生成.env然后后端 :8001 Web :3000、make dev-local/make dev-sandbox强制后端类型、make dev-backend/make dev-web只起一半、make dev-stop杀掉 :8001 / :3000、make setup只装依赖生成 .env 不起服务。设计权衡与适用边界README 与 docs/architecture.md 都坦率列出了权衡。Horizon 优化的是托管优先Managed-first——ADK 拥有 agent loopVertex 拥有模型/记忆/会话/沙箱自定义代码被压缩到少数几个自定义接口里每用户隔离——每个用户有自己的沙箱、密钥作用域与记忆routine 有自己的一次性lhart-沙箱可恢复性——会话持久化在 Agent Platform Sessions 并恢复上下文缓存与三层提示词让前缀跨回合字节稳定可读的接口——有序回调链 一组命名守卫让控制流清晰可映射。代价是GCP / Vertex 强耦合——托管优先的选择把部署绑死在 Vertex AI模型、Memory Bank、Agent Platform Sessions、Sandboxes及配套的 Cloud Run / Cloud SQL / IAP冷启动——每用户沙箱 provision 与服务解析增加首回合延迟有序回调链与自定义接口需要维护——回调顺序即契约插错位置就是真实的故障模式接口必须与其钩住的 ADK 版本保持同步。架构文档还给出了一个定位症状的方法论先判断行为属于哪一层——模型如何被调用、回合间状态如何传递、回合如何持久化/恢复是ADK读horizon/agent.py的接线再读 ADK托管能力模型、记忆、沙箱、配额/区域错误是Vertex区域与启用问题不是 Horizon 代码其余一切——提示词组装、守卫、密钥、环境接口、委派、自改进——是Horizon就在本仓库里。结语把模式移植进你自己的 AgentREADME 给的使用方式不是跑起来看看而是读它然后把模式移植进你自己的 Agent。推荐的研读路径AGENTS.md 的 Study order是先通读 docs/architecture.md 建立地图挑一个模式打开它的真实函数读对应的深入文档最后再看维护者视角的完整接线回调顺序、state 键、环境变量都在 AGENTS.md。深潜文档还包括 docs/security-model.md逐层安全模型指向任何真实使用前必读、docs/extending.md扩展点换模型、加工具/路由、插自定义沙箱、教它技能、docs/commands.md斜杠命令目录与 docs/routines.md无人值守例行任务。一句话总结Long Horizon 的价值不在又一个 demo Agent而在于它示范了一种在托管原语之上以最小自定义代码构建生产级长时程 Agent的克制做法——自定义代码只出现在六个接口里其余全部是旋钮与应用。把这六份契约带走你的下一个长时程 Agent 就有了骨架。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
