new-hire-onboarding基于 ADK 构建可暂停、可恢复的跨天数级 HR 入职长时运行 Agent【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai本篇基于generative-ai仓库中agents/adk/new-hire-onboarding示例的 README 与配套源码完整讲解如何用 Google ADKAgent Development Kit Gemini Flash-Lite 构建一个时间无关的 HR 新员工入职协调 Agent它用枚举驱动的持久状态机替代原始对话历史来维持跨数天工作流的推理链通过 webhook 式 resume 回调实现休眠/唤醒并提供一套 FastAPI React 双视角实时演示 UI。读完后你可以掌握持久记忆 schema、事件驱动休眠门控、多 Agent 委托三类长时运行 Agent 的架构模式并能本地运行、测试、评测乃至部署该示例。为什么多日工作流需要持久状态机而不是向量库记忆多数聊天机器人教程把整段对话历史 JSON 灌进向量数据库来记住历史轮次。在跨数天甚至数周的工作流里等员工签字、等物流送达这种非结构化方案会带来严重的提示词上下文污染、token 成本膨胀和推理幻觉。该仓库给出的答案是设计一套轻量、可持久化的 Agent 记忆 schema用严格的枚举状态OnboardingStep作为推理锚点把所有关键事实新员工信息、待处理信号压缩成几个可序列化字段写入会话状态本地 SQLiteAgent 在数周延迟后仍能精确恢复逻辑推理链而不依赖原始聊天记录。协调者同时负责人在环human-in-the-loop任务推进与自动化系统配置IT 账号、硬件保证每个入职步骤按顺序完成、检查点不可被跳过。README 将这种从无状态聊天机器人到可靠后台 Agent的转变归纳为三种范式迁移无状态聊天机器人模式持久后台 Agent 模式本仓库为什么重要无状态记忆把原始 JSON 日志/对话历史灌进向量库持久记忆 schema基于枚举序列化到 SQLite/Cloud SQL消除跨数周等待期的上下文污染、token 膨胀与推理幻觉主动轮询/阻塞线程保持循环运行或主动轮询 API事件驱动休眠门控scale-to-zero 的休眠等待由 webhook 唤醒节省计算资源Agent 的睡眠态持久驻留直到外部事件触发唤醒单体单 Agent所有工具塞进一个 system instruction多 Agent 委托HR 协调者把 IT 配置委托给专用子 Agent解耦复杂工作流保持提示词聚焦维护逻辑推理链入职状态机与空闲时间暂停门协调 Agent 不阻塞线程运行而是在两个关键空闲时间Idle Time窗口进入持久休眠门控等待员工签字、等待物流商送达回调。状态转移图如下继承自 README 原文状态定义集中在 app/state_schema.pyOnboardingStep是六个字符串常量START→WELCOME_SENT→DOCUMENTS_SIGNED→IT_PROVISIONED→HARDWARE_DELIVERED→COMPLETED。从源码结构看它刻意采用轻量类常量而非 Pythonenum.Enum便于直接作为会话状态中的可序列化值存入 SQLite。各步骤对应的动作、工具与转移处理器README 的六步流程与源码中的对应关系如下START收集新员工姓名、个人邮箱与入职日期调用 send_welcome_packet。WELCOME_SENT暂停等待签字webhook 回调触发文档签署校验转移处理为 receive_signed_documents_callback。DOCUMENTS_SIGNED收集期望的企业账号前缀调用 provision_software_accounts 配置企业邮箱与 Slack。IT_PROVISIONED收集笔记本硬件跟踪号如HW-12345调用 check_hardware_delivery 或触发 receive_hardware_delivery_callback。HARDWARE_DELIVERED完成硬件步骤并生成个性化首日行程调用 send_day_one_schedule。COMPLETED打印完整议程并祝贺新员工。源码剖析状态如何被写入、冻结与唤醒根 Agent 与子 Agent 委托app/agent.py 定义了hr_onboarding_coordinator根 Agent模型为Gemini(modelgemini-3.1-flash-lite)并配置retry_optionstypes.HttpRetryOptions(attempts3)做请求级重试工具集只挂载协调者自己负责的三个工具send_welcome_packet、check_hardware_delivery、send_day_one_scheduleIT 配置被拆分为it_agent子 Agentagent.py#L66-L83它只持有provision_software_accounts工具并在完成后把执行权交还父协调者——这正是 README 表格中多 Agent 委托范式的落地。根 Agent 的 instructionagent.py#L49-L64是一个模板运行时注入{current_step}、{new_hire_details}、{pending_signals}三个状态字段并逐条写死当前步骤为 X 时应做什么、禁止做什么例如WELCOME_SENT状态下明确要求不要调用其他工具。最后一句指令Do not skip steps or invent details是防跳过、防幻觉的兜底约束。before_agent_callbackinitialize_onboarding_stateagent.py#L38-L46在每轮执行前保证current_step、new_hire_details、pending_signals三个键一定存在——这是持久状态机防 KeyError的入口保险。另外该文件在导入时通过google.auth.default()取项目 ID并设置GOOGLE_CLOUD_LOCATIONglobal、GOOGLE_GENAI_USE_ENTERPRISETrueagent.py#L32-L35说明该示例面向 Gemini Enterprise Agent Platform 的企业环境运行。工具状态机转移的写者四个工具全部是读ToolContext.state→ 改状态 → 返回结果的纯状态迁移函数send_welcome_packet写入new_hire_details、把current_step置为WELCOME_SENT、把pending_signals置为[document_signed]provision_software_accounts生成企业邮箱usernameexample.com推进到IT_PROVISIONED并维护pending_signals移除document_signed、追加hardware_deliveredcheck_hardware_delivery模拟承运商查询仅当tracking_id以HW-前缀开头时才判定delivered并推进到HARDWARE_DELIVERED否则返回in_transit——这是一个典型的外部事实未就绪则不转移的守门逻辑send_day_one_schedule清空pending_signals并把状态置为COMPLETED返回固定四段式的 Day One 行程。pending_signals是这个 schema 里很关键的字段它显式声明Agent 正在等哪些外部信号让休眠门控有据可查而不是靠提示词猜测。Resume Handlerwebhook 唤醒与 state_deltaapp/resume_handler.py 的OnboardingResumeHandler是整个暂停/恢复模式的核心。两个回调receive_signed_documents_callback、receive_hardware_delivery_callback做同样的事以结构化 JSON 日志记录webhook_received/state_transition事件供 Cloud Logging 原生解析调用self.runner.run_async(user_id, session_id, new_message..., state_delta...)其中new_message是一条模拟用户消息如Resume onboarding: Contract has been signed.state_delta直接覆写current_step为DOCUMENTS_SIGNED/HARDWARE_DELIVERED并清空pending_signalsresume_handler.py#L63-L78。这种设计把状态推进和模型执行分离webhook 先确定性地改状态state_delta再让 Runner 用恢复消息触发一个 ambient 执行轮次让模型基于新状态产出下一步动作。任何异常都会被结构化记录为runner_turn_failure后重新抛出保证失败可观测。Live Onboarding 演示FastAPI React 双视角驾驶舱README 强调演示的行为是honest的UI 不乐观地推进工作流Sign packet必须等后端 ADK resume 轮次完成后才出现签字后的 packet/状态Confirm laptop delivered同理硬件完成后员工门户先展示Hardware delivery receipt再自动过渡到Day One schedule。本地 HTML artifact 是 FastAPI 后端真实生成并经/api/live-onboarding/cases/{case_id}/artifacts/{artifact_id}服务的文件。案例状态与 artifact 生成app/live_onboarding.py 用LiveOnboardingCasedataclasslive_onboarding.py#L14-L29承载案例的会话 ID、当前步骤、待处理信号、事件流与 artifact 清单create_live_caselive_onboarding.py#L490-L538在创建 ADK 会话时就把初始状态WELCOME_SENT 预置的new_hire_details写入会话并生成未签字的welcome_packet.html。演示使用的是一名固定示例员工Olivia Bennett跟踪号HW-55443。mark_document_signed/mark_hardware_deliveredlive_onboarding.py#L541-L647是 UI 按钮与 webhook 共用的同一条恢复路径写入签字/收货 artifact → 调用与/webhooks/*相同的 resume handler → 成功后推进adk_status与current_step失败则记录*_resume_failed事件。artifact 实体文件落盘在local_artifacts/onboarding/{case_id}/目录通过artifact_response以 HTMLResponse 返回。服务与 API 端点app/fast_api_app.py 基于 ADK 官方的get_fast_api_app工厂构建fast_api_app.py#L57-L70会话持久化session_service_uri sqliteaiosqlite:///sessions.db配合DatabaseSessionService与独立Runnerwebhook_runner即 README 所说状态序列化到 SQLite的本地形态artifact 服务设置了LOGS_BUCKET_NAME环境变量时用gs://{bucket}否则省略该变量由 Terraform 部署链路注入静态挂载React 构建产物挂在/live-onboarding业务端点POST /api/live-onboarding/start、GET /api/live-onboarding/cases/{case_id}、POST .../sign、POST .../deliver-hardware、GET .../artifacts/{artifact_id}、GET /api/live-onboarding/current幂等保护已签字/已送达会直接返回当前状态不重复触发 resumewebhook 端点POST /webhooks/document_signed与POST /webhooks/hardware_delivered后者多一个tracking_id字段直接调用 resume handler 唤醒 Agent。本地运行与开发命令运行前提uvPython 包管理器README 中的外部安装链接已省略按 uv 官方文档安装即可agents-cliGemini Enterprise Agent Platform 的官方 CLI管理项目脚手架、本地 playground、golden 评测与推理引擎部署全局安装命令uv tool install google-agents-cliGoogle Cloud SDK已认证到 Google Cloud 项目。依赖版本以 pyproject.toml 为准Python3.11,3.14google-adk1.15.0,2.0.0另有google-cloud-logging、google-cloud-aiplatform[agent-engines,evaluation]、opentelemetry-instrumentation-google-genai等eval可选依赖组包含google-adk[eval]。启动 Live Demo先完成 Application Default Credentials 认证gcloud auth application-default login gcloud config set project your-project-id安装并启动 FastAPI 应用uv sync uv run uvicorn app.fast_api_app:app --host 127.0.0.1 --port 8000然后打开http://127.0.0.1:8000/live-onboarding/若修改了 React 前端需要重新构建静态资源构建直接写入 FastAPI 服务的app/static/live-onboardingcd frontend/live-onboarding npm install npm run build演示完整流程新开 case → 查看未签字 packet → 点击 Sign packet → 等待 ADK 签字恢复轮次 → 查看签字 packet → 点击 Confirm laptop delivered → 等待 ADK 硬件恢复轮次 → 先见硬件签收凭证、后见 Day One 行程。常用开发命令速查继承自 README命令用途agents-cli install通过uv安装项目依赖agents-cli playground在交互式本地聊天沙箱中运行 Agentuv run uvicorn app.fast_api_app:app --host 127.0.0.1 --port 8000运行 FastAPI 应用与 live onboarding UIcd frontend/live-onboarding npm run build把 React UI 构建到app/static/live-onboardingagents-cli lint校验代码结构与格式化ruff/codespell 配置见 pyproject.tomluv run pytest tests/unit运行确定性的 live onboarding 状态与 artifact 测试uv run pytest tests/integration运行流式集成测试与 FastAPI E2E 服务校验.venv/bin/adk eval ./app evalset.json直连本地虚拟环境的评测 runner绕过系统包注册表评测与验证闭环Golden Set 守护状态机状态机的转移正确性用正式 golden 评测集验证位于 tests/eval/评测配置eval_config.json 定义了两条判据tool_trajectory_avg_score阈值 1.0 且要求工具调用顺序IN_ORDER即严格校验工具序列不跳步final_response_match_v2阈值 0.8由gemini-3.5-flash模型做单次判分。标准用例集onboarding_eval.json 覆盖常规状态推进。空闲时间延迟用例集dead_time_delay_eval.jsoneval_set_id为idle_time_delay_eval注意 README 中写作idle_time_delay_eval.json仓库内实际文件名为dead_time_delay_eval.json验证长期延迟后状态门控仍安全、原始新员工上下文仍被正确恢复。其中一个用例专门验证暂停安全门在WELCOME_SENT状态下用户要求跳过签字直接开通企业账号期望模型回答等待签字、且tool_uses为空——即检查点不可被提示词绕过。本地运行评测README 建议使用直连虚拟环境 runner避免凭据/包冲突覆盖.venv/bin/adk eval ./app tests/eval/evalsets/dead_time_delay_eval.json --config_file_path tests/eval/eval_config.json单元测试 tests/unit/test_live_onboarding.py 用FakeSessionService/FakeResumeHandler确定性验证了完整链路创建 case 后初始状态为WELCOME_SENTpending_signals[document_signed]签字恢复后状态推进到IT_PROVISIONED、生成signed-packetartifact硬件恢复后状态为COMPLETEDartifact 顺序为day-one-schedule、hardware-receipt、signed-packet、welcome-packet——与 README 描述的先签收凭证、后 Day One 行程的 UI 行为一一对应。部署到 Agent Runtime 与可观测性pyproject.toml 中的[tool.agents-cli]段声明base_template adk、deployment_target agent_runtime即该项目的部署目标已在脚手架阶段预配置为Agent RuntimeAgent Enginesgcloud config set project your-project-id agents-cli deploy agents-cli scaffold enhance # 可选追加 CI/CD 或适配配置部署入口是 app/agent_runtime_app.pyAgentEngineApp继承 vertexai 的AdkApp在set_up()中完成vertexai.init()与遥测初始化并按LOGS_BUCKET_NAME是否存在在GcsArtifactService与InMemoryArtifactService之间切换 artifact 后端同时注册了register_feedback操作。Agent Runtime 托管服务本身提供持久会话管理并把 trace span 原生接入 Cloud Trace 做实时环境监控。可观测性方面app/app_utils/telemetry.py 的setup_telemetry()通过 OpenTelemetry 把 trace span、API 日志与模型执行元数据导出到 Cloud Trace、Cloud Logging 与 BigQuery设置LOGS_BUCKET_NAME后会启用 prompt-response 日志固定NO_CONTENT模式仅元数据不落对话内容上传格式为jsonl并以COMMIT_SHA作为service.version资源属性未设置时仅打印禁用提示。FastAPI 服务则通过otel_to_cloudTrue参数在 fast_api_app.py#L57-L64 中开启 OTel 到 Cloud 的导出。项目结构与小结new-hire-onboarding/ ├── app/ │ ├── agent.py # 根 Agent it_agent 子 Agent、模型配置与系统提示词 │ ├── tools.py # 四个状态迁移工具 │ ├── state_schema.py # OnboardingStep 状态定义 │ ├── resume_handler.py # webhook 恢复回调签字、硬件送达 │ ├── live_onboarding.py # Live demo 案例状态、本地 artifact 生成与 API helper │ ├── fast_api_app.py # FastAPI 服务ADK 工厂 自定义端点 静态挂载 │ ├── agent_runtime_app.py # Agent RuntimeAgent Engines部署包装 │ ├── static/live-onboarding/ # FastAPI 服务的 React 构建产物 │ └── app_utils/ # 共享工具telemetry、feedback 类型 ├── frontend/live-onboarding/ # React Vite 前端源码 ├── tests/ # unit / integration / eval 三层测试 └── pyproject.toml # uv 依赖与 agents-cli 元数据这个示例把跨天工作流的 Agent拆成了四个可独立验证的构件可序列化的枚举状态机state_schema.pytools.py的状态写入、确定性的 webhook 恢复通道resume_handler.py的state_deltarun_async、不乐观推进的双视角演示层live_onboarding.py FastAPI 端点以及 golden set 驱动的状态转移回归评测tests/eval。这套枚举状态 信号清单 事件唤醒的组合是可以直接迁移到其他审批流、采购流、跨部门协同类长时运行 Agent 场景的通用骨架。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 new-hire-onboarding：基于 ADK 构建可暂停、可恢复的跨天数级 HR 入职长时运行 Agent
new-hire-onboarding基于 ADK 构建可暂停、可恢复的跨天数级 HR 入职长时运行 Agent【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai本篇基于generative-ai仓库中agents/adk/new-hire-onboarding示例的 README 与配套源码完整讲解如何用 Google ADKAgent Development Kit Gemini Flash-Lite 构建一个时间无关的 HR 新员工入职协调 Agent它用枚举驱动的持久状态机替代原始对话历史来维持跨数天工作流的推理链通过 webhook 式 resume 回调实现休眠/唤醒并提供一套 FastAPI React 双视角实时演示 UI。读完后你可以掌握持久记忆 schema、事件驱动休眠门控、多 Agent 委托三类长时运行 Agent 的架构模式并能本地运行、测试、评测乃至部署该示例。为什么多日工作流需要持久状态机而不是向量库记忆多数聊天机器人教程把整段对话历史 JSON 灌进向量数据库来记住历史轮次。在跨数天甚至数周的工作流里等员工签字、等物流送达这种非结构化方案会带来严重的提示词上下文污染、token 成本膨胀和推理幻觉。该仓库给出的答案是设计一套轻量、可持久化的 Agent 记忆 schema用严格的枚举状态OnboardingStep作为推理锚点把所有关键事实新员工信息、待处理信号压缩成几个可序列化字段写入会话状态本地 SQLiteAgent 在数周延迟后仍能精确恢复逻辑推理链而不依赖原始聊天记录。协调者同时负责人在环human-in-the-loop任务推进与自动化系统配置IT 账号、硬件保证每个入职步骤按顺序完成、检查点不可被跳过。README 将这种从无状态聊天机器人到可靠后台 Agent的转变归纳为三种范式迁移无状态聊天机器人模式持久后台 Agent 模式本仓库为什么重要无状态记忆把原始 JSON 日志/对话历史灌进向量库持久记忆 schema基于枚举序列化到 SQLite/Cloud SQL消除跨数周等待期的上下文污染、token 膨胀与推理幻觉主动轮询/阻塞线程保持循环运行或主动轮询 API事件驱动休眠门控scale-to-zero 的休眠等待由 webhook 唤醒节省计算资源Agent 的睡眠态持久驻留直到外部事件触发唤醒单体单 Agent所有工具塞进一个 system instruction多 Agent 委托HR 协调者把 IT 配置委托给专用子 Agent解耦复杂工作流保持提示词聚焦维护逻辑推理链入职状态机与空闲时间暂停门协调 Agent 不阻塞线程运行而是在两个关键空闲时间Idle Time窗口进入持久休眠门控等待员工签字、等待物流商送达回调。状态转移图如下继承自 README 原文状态定义集中在 app/state_schema.pyOnboardingStep是六个字符串常量START→WELCOME_SENT→DOCUMENTS_SIGNED→IT_PROVISIONED→HARDWARE_DELIVERED→COMPLETED。从源码结构看它刻意采用轻量类常量而非 Pythonenum.Enum便于直接作为会话状态中的可序列化值存入 SQLite。各步骤对应的动作、工具与转移处理器README 的六步流程与源码中的对应关系如下START收集新员工姓名、个人邮箱与入职日期调用 send_welcome_packet。WELCOME_SENT暂停等待签字webhook 回调触发文档签署校验转移处理为 receive_signed_documents_callback。DOCUMENTS_SIGNED收集期望的企业账号前缀调用 provision_software_accounts 配置企业邮箱与 Slack。IT_PROVISIONED收集笔记本硬件跟踪号如HW-12345调用 check_hardware_delivery 或触发 receive_hardware_delivery_callback。HARDWARE_DELIVERED完成硬件步骤并生成个性化首日行程调用 send_day_one_schedule。COMPLETED打印完整议程并祝贺新员工。源码剖析状态如何被写入、冻结与唤醒根 Agent 与子 Agent 委托app/agent.py 定义了hr_onboarding_coordinator根 Agent模型为Gemini(modelgemini-3.1-flash-lite)并配置retry_optionstypes.HttpRetryOptions(attempts3)做请求级重试工具集只挂载协调者自己负责的三个工具send_welcome_packet、check_hardware_delivery、send_day_one_scheduleIT 配置被拆分为it_agent子 Agentagent.py#L66-L83它只持有provision_software_accounts工具并在完成后把执行权交还父协调者——这正是 README 表格中多 Agent 委托范式的落地。根 Agent 的 instructionagent.py#L49-L64是一个模板运行时注入{current_step}、{new_hire_details}、{pending_signals}三个状态字段并逐条写死当前步骤为 X 时应做什么、禁止做什么例如WELCOME_SENT状态下明确要求不要调用其他工具。最后一句指令Do not skip steps or invent details是防跳过、防幻觉的兜底约束。before_agent_callbackinitialize_onboarding_stateagent.py#L38-L46在每轮执行前保证current_step、new_hire_details、pending_signals三个键一定存在——这是持久状态机防 KeyError的入口保险。另外该文件在导入时通过google.auth.default()取项目 ID并设置GOOGLE_CLOUD_LOCATIONglobal、GOOGLE_GENAI_USE_ENTERPRISETrueagent.py#L32-L35说明该示例面向 Gemini Enterprise Agent Platform 的企业环境运行。工具状态机转移的写者四个工具全部是读ToolContext.state→ 改状态 → 返回结果的纯状态迁移函数send_welcome_packet写入new_hire_details、把current_step置为WELCOME_SENT、把pending_signals置为[document_signed]provision_software_accounts生成企业邮箱usernameexample.com推进到IT_PROVISIONED并维护pending_signals移除document_signed、追加hardware_deliveredcheck_hardware_delivery模拟承运商查询仅当tracking_id以HW-前缀开头时才判定delivered并推进到HARDWARE_DELIVERED否则返回in_transit——这是一个典型的外部事实未就绪则不转移的守门逻辑send_day_one_schedule清空pending_signals并把状态置为COMPLETED返回固定四段式的 Day One 行程。pending_signals是这个 schema 里很关键的字段它显式声明Agent 正在等哪些外部信号让休眠门控有据可查而不是靠提示词猜测。Resume Handlerwebhook 唤醒与 state_deltaapp/resume_handler.py 的OnboardingResumeHandler是整个暂停/恢复模式的核心。两个回调receive_signed_documents_callback、receive_hardware_delivery_callback做同样的事以结构化 JSON 日志记录webhook_received/state_transition事件供 Cloud Logging 原生解析调用self.runner.run_async(user_id, session_id, new_message..., state_delta...)其中new_message是一条模拟用户消息如Resume onboarding: Contract has been signed.state_delta直接覆写current_step为DOCUMENTS_SIGNED/HARDWARE_DELIVERED并清空pending_signalsresume_handler.py#L63-L78。这种设计把状态推进和模型执行分离webhook 先确定性地改状态state_delta再让 Runner 用恢复消息触发一个 ambient 执行轮次让模型基于新状态产出下一步动作。任何异常都会被结构化记录为runner_turn_failure后重新抛出保证失败可观测。Live Onboarding 演示FastAPI React 双视角驾驶舱README 强调演示的行为是honest的UI 不乐观地推进工作流Sign packet必须等后端 ADK resume 轮次完成后才出现签字后的 packet/状态Confirm laptop delivered同理硬件完成后员工门户先展示Hardware delivery receipt再自动过渡到Day One schedule。本地 HTML artifact 是 FastAPI 后端真实生成并经/api/live-onboarding/cases/{case_id}/artifacts/{artifact_id}服务的文件。案例状态与 artifact 生成app/live_onboarding.py 用LiveOnboardingCasedataclasslive_onboarding.py#L14-L29承载案例的会话 ID、当前步骤、待处理信号、事件流与 artifact 清单create_live_caselive_onboarding.py#L490-L538在创建 ADK 会话时就把初始状态WELCOME_SENT 预置的new_hire_details写入会话并生成未签字的welcome_packet.html。演示使用的是一名固定示例员工Olivia Bennett跟踪号HW-55443。mark_document_signed/mark_hardware_deliveredlive_onboarding.py#L541-L647是 UI 按钮与 webhook 共用的同一条恢复路径写入签字/收货 artifact → 调用与/webhooks/*相同的 resume handler → 成功后推进adk_status与current_step失败则记录*_resume_failed事件。artifact 实体文件落盘在local_artifacts/onboarding/{case_id}/目录通过artifact_response以 HTMLResponse 返回。服务与 API 端点app/fast_api_app.py 基于 ADK 官方的get_fast_api_app工厂构建fast_api_app.py#L57-L70会话持久化session_service_uri sqliteaiosqlite:///sessions.db配合DatabaseSessionService与独立Runnerwebhook_runner即 README 所说状态序列化到 SQLite的本地形态artifact 服务设置了LOGS_BUCKET_NAME环境变量时用gs://{bucket}否则省略该变量由 Terraform 部署链路注入静态挂载React 构建产物挂在/live-onboarding业务端点POST /api/live-onboarding/start、GET /api/live-onboarding/cases/{case_id}、POST .../sign、POST .../deliver-hardware、GET .../artifacts/{artifact_id}、GET /api/live-onboarding/current幂等保护已签字/已送达会直接返回当前状态不重复触发 resumewebhook 端点POST /webhooks/document_signed与POST /webhooks/hardware_delivered后者多一个tracking_id字段直接调用 resume handler 唤醒 Agent。本地运行与开发命令运行前提uvPython 包管理器README 中的外部安装链接已省略按 uv 官方文档安装即可agents-cliGemini Enterprise Agent Platform 的官方 CLI管理项目脚手架、本地 playground、golden 评测与推理引擎部署全局安装命令uv tool install google-agents-cliGoogle Cloud SDK已认证到 Google Cloud 项目。依赖版本以 pyproject.toml 为准Python3.11,3.14google-adk1.15.0,2.0.0另有google-cloud-logging、google-cloud-aiplatform[agent-engines,evaluation]、opentelemetry-instrumentation-google-genai等eval可选依赖组包含google-adk[eval]。启动 Live Demo先完成 Application Default Credentials 认证gcloud auth application-default login gcloud config set project your-project-id安装并启动 FastAPI 应用uv sync uv run uvicorn app.fast_api_app:app --host 127.0.0.1 --port 8000然后打开http://127.0.0.1:8000/live-onboarding/若修改了 React 前端需要重新构建静态资源构建直接写入 FastAPI 服务的app/static/live-onboardingcd frontend/live-onboarding npm install npm run build演示完整流程新开 case → 查看未签字 packet → 点击 Sign packet → 等待 ADK 签字恢复轮次 → 查看签字 packet → 点击 Confirm laptop delivered → 等待 ADK 硬件恢复轮次 → 先见硬件签收凭证、后见 Day One 行程。常用开发命令速查继承自 README命令用途agents-cli install通过uv安装项目依赖agents-cli playground在交互式本地聊天沙箱中运行 Agentuv run uvicorn app.fast_api_app:app --host 127.0.0.1 --port 8000运行 FastAPI 应用与 live onboarding UIcd frontend/live-onboarding npm run build把 React UI 构建到app/static/live-onboardingagents-cli lint校验代码结构与格式化ruff/codespell 配置见 pyproject.tomluv run pytest tests/unit运行确定性的 live onboarding 状态与 artifact 测试uv run pytest tests/integration运行流式集成测试与 FastAPI E2E 服务校验.venv/bin/adk eval ./app evalset.json直连本地虚拟环境的评测 runner绕过系统包注册表评测与验证闭环Golden Set 守护状态机状态机的转移正确性用正式 golden 评测集验证位于 tests/eval/评测配置eval_config.json 定义了两条判据tool_trajectory_avg_score阈值 1.0 且要求工具调用顺序IN_ORDER即严格校验工具序列不跳步final_response_match_v2阈值 0.8由gemini-3.5-flash模型做单次判分。标准用例集onboarding_eval.json 覆盖常规状态推进。空闲时间延迟用例集dead_time_delay_eval.jsoneval_set_id为idle_time_delay_eval注意 README 中写作idle_time_delay_eval.json仓库内实际文件名为dead_time_delay_eval.json验证长期延迟后状态门控仍安全、原始新员工上下文仍被正确恢复。其中一个用例专门验证暂停安全门在WELCOME_SENT状态下用户要求跳过签字直接开通企业账号期望模型回答等待签字、且tool_uses为空——即检查点不可被提示词绕过。本地运行评测README 建议使用直连虚拟环境 runner避免凭据/包冲突覆盖.venv/bin/adk eval ./app tests/eval/evalsets/dead_time_delay_eval.json --config_file_path tests/eval/eval_config.json单元测试 tests/unit/test_live_onboarding.py 用FakeSessionService/FakeResumeHandler确定性验证了完整链路创建 case 后初始状态为WELCOME_SENTpending_signals[document_signed]签字恢复后状态推进到IT_PROVISIONED、生成signed-packetartifact硬件恢复后状态为COMPLETEDartifact 顺序为day-one-schedule、hardware-receipt、signed-packet、welcome-packet——与 README 描述的先签收凭证、后 Day One 行程的 UI 行为一一对应。部署到 Agent Runtime 与可观测性pyproject.toml 中的[tool.agents-cli]段声明base_template adk、deployment_target agent_runtime即该项目的部署目标已在脚手架阶段预配置为Agent RuntimeAgent Enginesgcloud config set project your-project-id agents-cli deploy agents-cli scaffold enhance # 可选追加 CI/CD 或适配配置部署入口是 app/agent_runtime_app.pyAgentEngineApp继承 vertexai 的AdkApp在set_up()中完成vertexai.init()与遥测初始化并按LOGS_BUCKET_NAME是否存在在GcsArtifactService与InMemoryArtifactService之间切换 artifact 后端同时注册了register_feedback操作。Agent Runtime 托管服务本身提供持久会话管理并把 trace span 原生接入 Cloud Trace 做实时环境监控。可观测性方面app/app_utils/telemetry.py 的setup_telemetry()通过 OpenTelemetry 把 trace span、API 日志与模型执行元数据导出到 Cloud Trace、Cloud Logging 与 BigQuery设置LOGS_BUCKET_NAME后会启用 prompt-response 日志固定NO_CONTENT模式仅元数据不落对话内容上传格式为jsonl并以COMMIT_SHA作为service.version资源属性未设置时仅打印禁用提示。FastAPI 服务则通过otel_to_cloudTrue参数在 fast_api_app.py#L57-L64 中开启 OTel 到 Cloud 的导出。项目结构与小结new-hire-onboarding/ ├── app/ │ ├── agent.py # 根 Agent it_agent 子 Agent、模型配置与系统提示词 │ ├── tools.py # 四个状态迁移工具 │ ├── state_schema.py # OnboardingStep 状态定义 │ ├── resume_handler.py # webhook 恢复回调签字、硬件送达 │ ├── live_onboarding.py # Live demo 案例状态、本地 artifact 生成与 API helper │ ├── fast_api_app.py # FastAPI 服务ADK 工厂 自定义端点 静态挂载 │ ├── agent_runtime_app.py # Agent RuntimeAgent Engines部署包装 │ ├── static/live-onboarding/ # FastAPI 服务的 React 构建产物 │ └── app_utils/ # 共享工具telemetry、feedback 类型 ├── frontend/live-onboarding/ # React Vite 前端源码 ├── tests/ # unit / integration / eval 三层测试 └── pyproject.toml # uv 依赖与 agents-cli 元数据这个示例把跨天工作流的 Agent拆成了四个可独立验证的构件可序列化的枚举状态机state_schema.pytools.py的状态写入、确定性的 webhook 恢复通道resume_handler.py的state_deltarun_async、不乐观推进的双视角演示层live_onboarding.py FastAPI 端点以及 golden set 驱动的状态转移回归评测tests/eval。这套枚举状态 信号清单 事件唤醒的组合是可以直接迁移到其他审批流、采购流、跨部门协同类长时运行 Agent 场景的通用骨架。【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考