Long-Horizon Harness 配置完全指南：环境变量、路由与依赖 Extras 实战解析

Long-Horizon Harness 配置完全指南环境变量、路由与依赖 Extras 实战解析【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samplesLong-Horizon HarnessHorizon是构建在 Google ADK Vertex AI 之上、面向长时程任务的自进化 Agent 工程化骨架。本文是它的**配置参考Configuration Reference**的完整展开以core/python/long-horizon-harness/docs/configuration.md为骨架逐项讲解服务挂载的路由、按子系统分组的环境变量全目录、以及可选依赖 extras并结合仓库源码.env.example、fast_api_app.py、env.py等说明每个配置项背后的实际行为。读完你将能独立完成本地开发环境搭建、按需裁剪路由面、并在 Cloud Run 上以默认拒绝default-deny的安全姿态部署完整服务。无本地模型。每一次聊天调用都走 Vertex 进行推理。LHA_ENVIRONMENT_BACKENDlocal只是把工具执行搬到你的宿主机上模型推理始终在 Vertex。本文结构Routes路由— 服务应用挂载了哪些端点环境变量全目录— 按子系统分组核心/Vertex、身份、模型、沙箱、会话、记忆、调度器、OAuth……的完整清单Dependency extras依赖可选组— 每个lha[…]extra 拉入什么、服务于什么场景。Routes服务挂载了什么被服务的应用是horizon.fast_api_app:app。_build_app()在 fast_api_app.py 中构建并挂载了全部路由A2A 路由attach_a2a_routes挂载 A2A JSON-RPC 端点agent card、任务执行、task store 等/lha/*系列会话sessions、状态state、任务tasks、记忆memories、上传uploads、沙箱sandbox、进程processes、密钥secrets、例程routines分别由horizon/api/下的attach_*_routes挂载/feedbackUI 的 Have a suggestion? 按钮对应的反馈上报端点attach_feedback_routesOAuth 回调attach_gcp_oauth_routesConnect Google 按钮的 Web OAuth 流程/scheduler/*dream_review_endpoint、snapshot_endpoint、routine_tick_endpoint三个 router分别对应记忆梦审、快照备份、例程触发。此外app.add_middleware(IdentityMiddleware)为所有非公开路径做身份解析。只发布子集的方式很直接删除 fast_api_app.py 中不需要的attach_*调用即可例如不需要沙箱就删掉attach_sandbox_routes。每个路由暴露了什么、secrets/oauth路由注入的凭据是什么详见 security-model.md。另外注意_UNAUTHENTICATED_PATHS/_UNAUTHENTICATED_PREFIXES见 identity.py健康检查/、agent card、/docs、/openapi、/scheduler/前缀等路径跳过身份解析Cloud Scheduler 用自带的 OIDC token 直接调用/scheduler/*端点。反馈数据留在你自己的项目里。feedback面UI 的 Have a suggestion? 按钮 →POST /feedback会把结构化记录写入你自己的 Cloud Logging实现在 feedback/sink.py含 stdlib-log 回退绝不会发送给项目作者或任何外部端点。环境变量.env由make dev-backend加载set -a; . ./.env; set a从.env.example起步复制为.env再填写。注意.env已被 gitignore模板没有——永远不要把真实密钥提交进仓库。更深入的设计依据见 AGENTS.md分层安全模型见 security-model.md。环境变量的解析有两个统一入口理解它们能解释表中大量默认值的语义env_flag(name, defaultFalse)仅当变量不存在时回退到默认值值为1/true/yes不区分大小写时为真空值按假处理env.pyenv_str(name, default)去空白后返回空值同样回退到默认——因此.env.example里只留变量名、不留值的条目不会覆盖代码默认值env.py。Core / Vertex任何聊天都必需变量默认值说明GOOGLE_CLOUD_PROJECT当前gcloud配置留空则回退到 ADCApplication Default Credentials项目make dev会自动填入。GOOGLE_CLOUD_LOCATIONglobal通过 import 期setdefault设置——你显式导出的值优先。GOOGLE_GENAI_USE_VERTEXAITrue同样是 import 期setdefault显式导出的值优先。从源码看setdefault语义意味着这三项是给了就用没给用默认的最低摩擦设计本地开发时make dev用你gcloud的激活项目即可跑通无需手工配置。Identity / auth身份认证变量默认值说明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。实现层面identity.pyget_auth_mode()解析LHA_AUTH_MODE若在 Cloud Run 环境检测到K_SERVICE仍解析为dev会抛出DevAuthInProductionError——因为dev会把所有请求折叠成一个身份、无鉴权本地安全部署后就是跨用户数据泄露因此fail closed。iap模式下还支持用 Google OAuth access tokenAuthorization: Bearer做 agent-to-agent 调用Gemini Enterprise 场景通过 tokeninfo 校验aud LHA_GCP_OAUTH_CLIENT_ID后取email作为 user_id。Model模型变量默认值说明LHA_ROOT_MODELgemini-3.7-flash根 Agent 默认模型须是 models/registry.py 里的键。/model命令可按会话覆盖。LHA_VERTEX_SERVICE_TIER关闭设为priority时把 Gemini 钉到 Vertex 的SERVICE_TIER_PRIORITY每轮生效。默认关闭——priority tier 需要大多数项目没有的 Vertex 授权entitlement。模型注册表当前内置两个后端gemini-3.7-flash与gemini-3.1-pro-preview均声明 1,000,000 token 输入窗口注册表采用惰性构建_LazyModelRegistryimport horizon不需要 GCP 凭据只有真正构建某个后端时才探测 ADC 项目registry.py。LHA_VERTEX_SERVICE_TIERpriority时由_PriorityGemini包装类在每次generate_content_async中注入service_tierregistry.py。Environment / sandbox执行环境与沙箱变量默认值说明LHA_ENVIRONMENT_BACKENDlocallocal工具跑在宿主机或sandbox托管 Sandbox。LHA_SANDBOX_INTERNET_ACCESSdev1部署0沙箱出网开关。0 封闭无出站1 联网。未设置时本地开发默认开、部署默认关Cloud Run 会设K_SERVICE所以make dev开箱即用、生产保持默认拒绝。出网能力在沙箱创建时烧入——修改后要到下一次沙箱供给才生效不是热更新。LHA_RUNTIME_IMAGE—沙箱 BYOC 镜像仅sandbox模式下。示例us-central1-docker.pkg.dev/project/lha-sandbox/runtime:vX.Y.Z。LHA_SANDBOX_CALLER_SA—沙箱供给用的服务账号。LHA_SANDBOX_LOCATIONus-central1Agent Platform 的沙箱供给区域独立于GOOGLE_CLOUD_LOCATION。LHA_RUNTIME_MIN_VERSION关闭重挂载时强制把低于此版本下限的沙箱升级。.env.example还列出了沙箱相关扩展项LHA_SANDBOX_ENGINE_NAME、LHA_SANDBOX_TTL、LHA_LOCAL_ROOT、SANDBOX_WORKSPACE、SANDBOX_EXEC_TIMEOUT_SEC。LHA_ENVIRONMENT_BACKENDlocal是零摩擦起步的关键不需要准备沙箱镜像工具直接在宿主机进程内执行。Sessions / storage会话与存储变量默认值说明USE_IN_MEMORY_SESSION关闭true⇒ 进程内会话重启即丢跳过 Agent Platform Sessions / Cloud SQL。SESSION_DB_URL—sqlite/postgres/mysql 会话存储优先级高于Agent Platform Sessions。AGENT_ENGINE_RESOURCE_NAME—Agent Engine 资源用于会话和Memory Bank。LHA_MEMORY_BANK_RESOURCE_NAMEAGENT_ENGINE_RESOURCE_NAME逃生舱把 Memory Bank 拆到另一个独立 engine。LOGS_BUCKET_NAME—GCS 桶用于持久化 artifactsGcsArtifactService未设置 ⇒ 内存 artifacts。ARTIFACT_SERVICE_URIgs://$LOGS_BUCKET_NAME显式 artifact-service URI 覆盖优先级高于LOGS_BUCKET_NAME。未设置且无桶 ⇒ 内存。会话存储的解析逻辑在 fast_api_app.py 的_resolve_service_uris()本地开发且未显式配置时默认落到sqlite:///repo/.data/lha_sessions.db重启后聊天仍在避免强迫开发者起一个真实 Agent Engine一旦设置SESSION_DB_URL会警告并优先使用DatabaseSessionService此时AGENT_ENGINE_RESOURCE_NAME被忽略仅用于 Memory Bank。SQL 型会话/任务存储还会被ResilientSessionService/_ResilientTaskStore包装对断连做指数退避重试fast_api_app.py。A2A 任务存储同理TASK_DB_URL→DatabaseTaskStoreUSE_IN_MEMORY_TASK_STOREtrue→InMemoryTaskStore否则默认 sqlitelha_tasks.db保证 Web UI 能跨重启恢复在途 A2A 任务。Memory / dream-review记忆与梦审变量默认值说明LHA_DREAM_REVIEWon0在所有路径上禁用 dream-review。LHA_DREAM_SESSION_LIMIT50喂给用户画像整合profile consolidation的最近会话数上限。LHA_DREAM_LOOKBACK_HOURS24/scheduler/dream-review自动发现用户的活跃时间窗。LHA_MEMORY_CONSOLIDATIONon0禁用通用记忆的去重/矛盾调和。LHA_LIVE_MEMORY_TESTS关闭1运行 Memory Bank 实时往返 smoke 测试。LHA_REVIEW_FORKon0禁用回合后的 judge fork记忆 技能策展。LHA_PRE_COMPRESS_FLUSHon0禁用压缩前的记忆 flush fork。LHA_FORK_COOLDOWN120每个会话后台 fork 之间的间隔秒数。这些开关控制的是 Horizon 自进化机制——后台 fork独立子代理回合负责记忆沉淀与技能策展本地调试时可用0逐一关掉以观察行为差异。IdentitySOUL.md 人格身份~/.lha/SOUL.md若存在将替换DEFAULT_AGENT_IDENTITY作为系统提示词的开头行实现在 conversation/soul_loader.py。它在App 构建时读取一次作为组装Agent.static_instruction的一部分conversation/system_prompt.py 的build_static_instruction——因为常量前缀不再按会话重建编辑 SOUL.md 需要重启进程才生效而不是新开会话。未提供 SOUL.md 时使用内置默认人格You are a helpful, knowledgeable, and direct AI assistant…见 soul_loader.py。.env.example中没有这个条目——它是文件配置而非环境变量。Context / compaction上下文与压缩变量默认值说明LHA_PRUNE_TOOL_OUTPUTSon0禁用对旧的大块工具结果体清零。LHA_PRELOAD_MAX_MEMORIES20注入每轮PAST_CONVERSATIONS块的记忆条数上限。ADK 的search_memory没有top_k没有这个上限块会随用户记忆数无限增长。LHA_PRELOAD_MAX_CHARS4000同一块的字符数上限在条数上限之后应用。ADK_DISABLE_JSON_SCHEMA_FOR_FUNC_DECLunset全进程选择 ADK 的精简声明路径。根 Agent 已不再需要它context/declaration_compaction.py 把这个开关限定在自己的工具构建上每轮为工具面省下 2,549 字符。只有当你也想给子 Agent 生效、且确认进程中其他东西不会被它重新渲染时才自己设置。LHA_COMPACTION_WINDOW_FRACTION0.75模型输入窗口的 (0,1) 比例阈值达到该比例时触发压缩。上下文预算的完整推导见 context-budget.md。Scheduler / routines调度器与例程变量默认值说明LHA_ROUTINE_STOREmemorymemory不持久或postgres需要LHA_REMINDER_DB_URL需要lha[scheduler]。LHA_REMINDER_DB_URL—routines 弹性会话的 Postgres URL。名字是历史遗留早于 reminder 能力的移除保留原样。LHA_SCHEDULER_SA—/scheduler/*接受的服务账号其 OIDC token。未设置 ⇒ 端点拒绝。LHA_SCHEDULER_AUDIENCE—该 token 期望的aud。未设置 ⇒ 端点拒绝。LHA_SCHEDULER_AUTH_DISABLED关闭跳过调度器 token 校验。仅限本地测试。SnapshotPhase C代码默认关——make deploy后开代码默认是关闭的但 terraform/cloud_run.tf 会在部署的后端上设置LHA_SNAPSHOT_ENABLED 1terraform/cloud_scheduler.tf 无条件创建每日任务。因此make deploy交付的版本 Phase C 是开启的。若不需要在cloud_run.tf中把该环境变量设为0。变量默认值说明LHA_SNAPSHOT_ENABLED本地关经 Terraform 在 Cloud Run 上为1每日快照修剪任务与会话启动时恢复的总开关。LHA_SNAPSHOT_TTL30d快照保留 TTL。LHA_SNAPSHOT_KEEP2每用户保留的快照数。Secrets密钥变量默认值说明LHA_SECRET_BACKENDsecretmanager按用户的密钥存储后端secretmanager/gcpGCP Secret Manager需要GOOGLE_CLOUD_PROJECT或memoryInMemorySecretStore不持久。可用set_secret_store()注册自定义后端。Connect GoogleOAuth客户端逐步配置见 quickstart.md 的6. Connect Google (optional OAuth)。自带 Web OAuth 客户端服务端路由在 auth/oauth.py未设置 ⇒ 功能关闭。变量默认值说明LHA_GCP_OAUTH_CLIENT_ID—Connect Google 按钮的 Web OAuth 客户端。未设置 ⇒/connect返回 503。iap模式下也是 GE bearer 校验的 audience。LHA_GCP_OAUTH_CLIENT_SECRET—签名state的 HMAC 密钥。LHA_GCP_OAUTH_REDIRECT_URI—公开的https://web-host/lha/gcp/callback本地开发用http://localhost:3000/...。注意LHA_GCP_OAUTH_CLIENT_ID的双重身份既是 OAuth 流程的 client id又是iap模式下 OAuth access token 校验的预期 audienceidentity.py验证通过后还会把 token 存入请求作用域供secret_env()以CLOUDSDK_AUTH_ACCESS_TOKEN叠加委托式 Google 访问。Dependency extras可选依赖组核心import horizon 默认 Gemini Agent不需要任何 extra。Provider/子系统依赖是 pyproject.toml 中的可选 extras本仓库自己的 dev/test 环境通过devdependency-group 里的long-horizon-harness[full]自引用把它们全部拉回来。Extra拉入用途lha[postgres]asyncpg、yoyo-migrations、bcrypt持久化 postgres 存储routines、弹性会话lha[scheduler]lha[postgres]调度器持久化LHA_ROUTINE_STOREpostgreslha[data]pandas、matplotlib、seaborn沙箱内数据分析harness 自身不 importlha[full]/lha[all]postgres,scheduler,data完整部署面uv pip install lha[full] # 全部 uv pip install lha[postgres] # 最小切片 持久化存储full与all互为别名all依赖full。另有两个与运行无关的组evalgoogle-adk[eval]跑评测用与lintruff/ty/codespell静态检查用。核心运行时依赖google-adk[mcp,otel-gcp,a2a]2.8.0,3.0.0支持 Python3.11,3.14。下一步quickstart.md — 本地优先的 5 分钟上手路径extending.md — 抬升/改造 harnessarchitecture.md — 架构地图commands.md — 斜杠命令目录security-model.md — 分层认证与安全模型sandbox-lifecycle.md · routines.md · memory.md — 子系统深潜【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考