ADK 集成 AntigravityAgent把 Google Antigravity SDK 代理封装为原生 ADK Agent 节点【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-pythonAntigravityAgent是 ADKAgent Development Kit在labs模块中提供的一个BaseAgent子类它把一个预配置的google.antigravity.AgentConfig如LocalAgentConfig包装成标准的 ADK Agent 节点每一轮对话被委托给 Antigravity SDK 的运行器执行其轨迹步骤模型文本、工具调用、工具响应被流式转换为标准 ADKEvent并写入会话记录。阅读本文后你将掌握如何用 Antigravity SDK 的本地工作区工具与策略来驱动 ADK 应用如何通过modesingle_turn将其作为子代理嵌套进 ADK 父代理以及如何把 ADKsub_agents反向桥接为 Antigravity 的客户端工具。为什么需要 AntigravityAgentAntigravity SDK 擅长在本地工作区中执行任务——它自带工作区workspace管理、文件类工具与安全策略policy例如限制模型只能在指定目录内读写。但 Antigravity SDK 本身不提供 ADK 那样的代理编排多代理、工作流、会话存储与 Web UI 能力。AntigravityAgent解决了这个组合问题它让 ADK 应用直接借用 Antigravity SDK 的本地工作区工具与策略同时保留 ADK 的编排、会话与 UI 能力。官方指南的原话是它将 Antigravity SDK 的运行循环harness与 ADK 的会话/事件体系缝合在一起见 官方指南 与 模块文档字符串。从源码结构看该集成位于labs实验性实验室模块之下与labs/openai并列属于 ADK 提供的非核心、实验性质的集成能力由以下几个文件组成入口与主类AntigravityAgent主实现事件转换器把 Antigravity SDK 的Step翻译为 ADKEvent子代理工具桥接把 ADK 子代理包装为 Antigravity 的客户端工具工具结果捕获通过钩子hook缓冲客户端工具的调用结果包入口依赖检查与AntigravityAgent导出需要特别说明的是使用本模块前必须先安装google-antigravity包。__init__.py在导入时会import google.antigravity若缺失会抛出ImportError并提示运行pip install google-adk[antigravity]见 包入口。快速开始包装一个 Antigravity SDK 代理官方指南给出了最精简的启动代码。第一步先配置 Antigravity SDK 侧的代理第二步将其包装为 ADK 根代理from google.adk.labs.antigravity import AntigravityAgent from google.antigravity import LocalAgentConfig from google.antigravity.hooks import policy # 1. 配置 Antigravity SDK 代理。 # 多轮对话必须设置 save_dir这样临时目录才能在多轮之间被保留。 sdk_config LocalAgentConfig( system_instructionsYou are a helpful local environment assistant., workspaces[./sandbox], policies[*policy.workspace_only([./sandbox])], save_dir./trajectories, ) # 2. 将 Antigravity SDK 配置包装为独立的 ADK 根代理。 root_agent AntigravityAgent( nameantigravity_assistant, descriptionRuns an Antigravity SDK agent inside ADK., configsdk_config, )对这段代码的几个要点说明workspaces与policiespolicy.workspace_only([./sandbox])是一个 workspace 限定策略允许模型在./sandbox内使用内置文件工具进行创建与编辑同时把写入限制在该目录内。这是 Antigravity SDK 本地代理的核心安全机制。save_dir的多轮语义见下文配置选项一节的详细解释。name与descriptionname是 ADK 会话中该代理的标识description会在该代理被作为子代理/工具暴露给模型时被读取。完成包装后root_agent就是一个标准的 ADKBaseAgent可以直接交给 ADK 的Runner运行像使用任何其他 ADK 代理一样进行多轮对话、事件监听与 UI 调试。仓库中有一个完整可运行的真实示例——Game Developer Agent它把上述模式落地为一个网页游戏开发者代理system_instructions要求模型把每个游戏写成单个自包含 HTML 文件内联 CSS/JavaScript无外部依赖并在game_repo工作区内分步增量构建完成后说明如何游玩。示例还演示了工程细节用os.makedirs(..., exist_okTrue)预创建工作区与轨迹目录再传给LocalAgentConfig。工作原理每轮重建 SDK 代理用会话 ID 维持连续性官方指南明确描述了AntigravityAgent的核心运行时模型每轮都构建并进入一个全新的 Antigravity SDKAgent从 ADK 会话状态中读取并恢复会话 IDconversation ID把最新用户输入发送进去并把流式返回的每个Step转换为标准 ADKEvent覆盖模型文本响应、函数调用、函数响应三类轮与轮之间不保持任何打开的资源SDKAgent实例在退出时被关闭下一轮重新连接。连续性完全来自会话 ID——包装器把它读写到 ADK 会话状态中。对应到源码实现主类会话 ID 的存储键为_antigravity_conversation_id_前缀 代理名_conversation_id_state_key见 L317-L320。这意味着同一个 ADK 会话中的两个AntigravityAgent实例各自维护独立的 Antigravity 对话互不干扰。会话 ID 的持久化通过事件携带的EventActions(state_delta...)完成_conversation_id_event见 L322-L336。源码注释特别强调它必须是独立事件而非合并进模型事件因为部分事件partial event不会被追加到会话中而state_delta正是在会话落盘时才被应用。恢复会话时配置会被设置为SessionContinuationMode.CREATE_OR_RESUME见 L360-L367这是唯一能在底层存储已不存在时优雅降级为新建会话的模式否则默认模式下找不到存储会直接抛硬错误。连接 SDK 代理使用了异步上下文管理器async with若__aenter__期间被取消会显式调用__aexit__以避免孤儿化 harness 子进程见 L369-L376。会话 ID 的写入时机经过精心设计即使某轮步骤不产生任何用户可见事件例如 compact 压缩步骤只要对话有历史就仍要记录 ID否则下一轮会孤儿化这段对话见 L403-L432。Step 到 Event 的映射规则转换逻辑被独立抽取到 _event_converter.py以保证映射规则可读、可单独测试。核心入口是convert_step_to_eventsL334-L381每收到一个Step按以下顺序产出事件AntigravityStep内容产出的 ADK 事件思考增量thinking_deltapartialTrue的模型思考事件仅 SSE 流式模式文本增量content_deltapartialTrue的模型文本事件仅 SSE 流式模式完整模型文本响应一个author代理名的最终模型文本事件模型发起的工具调用author代理名的function_call事件工具执行完成/出错author工具名的function_response事件几个值得注意的实现细节均可从源码确认最终文本只在is_complete_response时发出Antigravity SDK 会在响应增长过程中反复重播累积的content若每次都发会造成同一消息被记录多次因此只在完整响应时用最终累积文本生成事件L99-L131。SSE 流式模式下才生成增量事件_run_turn会检查run_config.streaming_mode StreamingMode.SSEL452-L454非流式模式只产出最终事件。工具调用 ID 去重当 SDK 省略调用 ID 时会合成{step_index}-{name}形式的稳定 ID_build_tool_call_idL48-L50并用seen_tool_calls/seen_tool_results集合对跨步骤重播的调用与结果去重。final_model_text用于把事件中的用户可见文本读出来它过滤掉 partial、思考thought与函数部件多段文本以换行拼接L384-L412。已知边界SDK 在回合取消时发出的SYSTEM_MESSAGE步骤目前被丢弃尚未映射为 ADK 事件见 _event_converter.py 顶部 TODO。配置选项官方指南给出了一张配置参数表选项类型默认值说明configAgentConfig必填描述 Antigravity SDK 代理的google.antigravity.AgentConfig。modeLiteral[single_turn] \| NoneNone作为子代理使用时的组合模式。两个参数在源码中的定义与细节如下L161-L178configAntigravity SDK 代理的全部定义config定义了 Antigravity SDK 的指令system_instructions、工作区workspaces与策略policies。源码中它被标记为Field(excludeTrue)——即从序列化中排除因为它持有运行期接线例如可调用工具不是 JSON 可序列化的。当使用LocalAgentConfig时多轮连续对话必须提供save_dir。原因指南与源码双重印证见 L186-L202本地配置在每次连接时会新建一个临时目录如果没有save_dir每一轮写入的位置都不是下一轮会去查找的位置即每轮都是全新对话。源码会在构造时检查并打印警告日志_warn_if_local_without_save_dir若检测到本地配置且未设置save_dir且非单轮模式会警告该代理不会跨轮记住任何东西。注意它检查的是基类BaseLocalAgentConfig而非默认子类因为临时目录的创建逻辑在基类里任何子类缺save_dir都会失忆L265-L271。另外config在每轮运行前会被深拷贝model_copy(deepTrue)见 L296-L299一方面避免修改调用方的配置对象另一方面因为 SDKAgent的AsyncExitStack是单次使用的不能复用同一配置。mode子代理组合模式mode控制AntigravityAgent如何被嵌套在 ADK 父代理之下modeNone默认作为独立的 ADK 根代理运行。modesingle_turn允许该代理拥有 ADK 父代理。此时父LlmAgent会把它暴露为一个内联工具工具签名接收一个request字符串父代理负责组合请求会话历史不会被转发每次单轮调用都是独立对话前后不继承任何内容。源码中mode是frozenTrue的字段因为收养检查adoption guard只在构造时执行一次。该守卫在__setattr__中实现L240-L248如果尝试给AntigravityAgent设置非空的parent_agent而mode ! single_turn会抛出ValueError提示文案为AntigravityAgent may only be an ADK sub-agent when it sets modesingle_turn... Otherwise it must run as an ADK root agent.这与官方指南Limitations一节的第一条限制完全对应AntigravityAgent 运行的是自包含的 Antigravity SDK 对话因此除非设置modesingle_turn否则它必须是 ADK 根代理。高级应用给 AntigravityAgent 挂 ADK 子代理官方指南的进阶场景是AntigravityAgent可以拥有 ADKsub_agents。每个 ADK 子代理会被桥接到 Antigravity SDK 配置上变成一个以子代理名字命名的客户端工具client-side tool。该工具接收一个request字符串因此每个子代理必须提供非空的description——这是 Antigravity SDK 模型在选择是否调用时唯一能读到的信息。子代理在隔离环境中运行只返回其最终文本父会话记录一次工具调用和携带该最终文本的function_response。from google.adk.agents.llm_agent import Agent def get_current_time(city: str) - dict: return {status: success, report: fThe time in {city} is 12:00 PM.} time_agent Agent( nametime_assistant, description( Returns the current time. Always call this for time-related queries. ), instructionAnswer time questions by calling get_current_time., tools[get_current_time], ) root_agent AntigravityAgent( nameantigravity_assistant, descriptionRuns an Antigravity SDK agent inside ADK., configsdk_config, sub_agents[time_agent], )底层机制客户端工具桥接桥接实现在 _sub_agent_tools.py 的make_sub_agent_toolL50-L122子代理的名字成为工具名__name__子代理的description成为工具描述__doc__两者都是模型读取的信息来源。每次调用该工具时会用Runner 全新的InMemorySessionService以隔离会话运行子代理一次返回其最后一个用户可见文本若没有文本则回退到最后一个错误消息再不行返回绝不返回None。这与 ADK 自带的AgentTool非常接近区别是不返回代码执行输出与可执行代码且子代理抛出的异常会原样传播给调用方AgentTool则会把失败包装成错误字符串。工具的Runner在finally中显式关闭以保证子代理的 MCP 会话、工具集等资源被正确释放——否则遗留的 MCP 会话会在后续出现 Attempted to exit cancel scope in a different task 之类的错误。导入Runner被刻意延迟到函数内部L71因为runners会拉入大半个 ADK在 labs 模块顶层立即导入容易形成循环依赖。构造期校验名字与描述在_validate_sub_agentsL204-L238中构造时会校验三种冲突并抛出ValueError子代理缺少description——它作为工具被暴露描述是模型唯一决策依据子代理名字与config.tools中已有工具重名——它们会被追加到同一个config.toolsharness 按名字注册工具重名者会被拒绝两个子代理重名——原因同上。注意该校验在构造后例如model_copy或后续修改sub_agents还会被_build_sdk_config再次调用防止绕过model_post_init。客户端工具的结果捕获一个关键设计点是客户端工具ADK 子代理的执行结果永远不会出现在轨迹trajectory里——其终止Step的tool_calls为空且Step本身没有结果字段。结果只能通过工具钩子到达。因此 _tool_result_capture.py 实现了两个钩子类共用一个ToolResultBufferToolResultCapturePostToolCallHook成功路径在post_tool_call时把ToolResult按id存入缓冲ToolErrorCaptureOnToolErrorHook失败路径在on_tool_error时把ToolExecutionError包装为_FailedToolResult存入缓冲。两个钩子互斥——每次调用恰好触发其一见 _tool_result_capture.py 模块文档。缓冲只在存在sub_agents时才注册因为post_tool_call钩子每次成功调用都会带来一次阻塞往返且只在 AntigravityAgent 拥有子代理时为真L355-L359。回合结束后_run_turn会调用drain_tool_results把已捕获但尚未答复的调用配对成function_response事件再清空缓冲L470-L484。运行模式与运行时约束作为工作流节点Node运行AntigravityAgent同时实现了节点运行路径_run_implL486-L521它把node_input转成用户内容收集整轮最后一段模型文本作为output产出从而可以作为 ADK 工作流workflow中的节点使用支持node_input注入与output输出。这从源码结构看是复用run_async主路径的实现。静默丢失恢复silent-drop detection针对要求恢复某会话但底层已不存在的情况源码对本地连接实现了检测恢复后若对话历史为空判定为静默新建了会话此时会清除存储的 ID 并抛出RuntimeError提示已清除存储的 ID下一轮将开始新对话但本会话之前的回合不可恢复L394-L402。该检测被限定在本地配置类型内因为远程后端在陈旧 ID 上静默新建会话的行为无法在不依赖 SDK 支持的前提下被可靠区分L434-L445。已知限制官方指南明确列出的限制如下并可与源码互证嵌套限制AntigravityAgent运行的是自包含的 Antigravity SDK 对话因此除非设置modesingle_turn否则它必须是 ADK 根代理。这条限制仅适用于该代理被放在 ADK 父代理之下的场景它自己的 ADKsub_agents是被桥接为客户端工具的永远不需要设置mode。子代理的 root 解析AntigravityAgent的 ADK 子代理的root_agent仍指向最外层 ADK 代理树。在三层结构中LlmAgent→AntigravityAgent(modesingle_turn)→ 子代理中间的代理设置modesingle_turn是因为它有 ADK 父代理而不是因为它有子代理此时 ADK 的 transfer 工具会被声明给子代理的模型。建议让AntigravityAgent的子代理保持叶节点形态或者在这些子代理上设置disallow_transfer_to_parent与disallow_transfer_to_peers。并发限制同一 ADK 会话的两轮并发运行是未定义行为因为两者会打开同一个已存储的会话。相关示例与进一步阅读Game Developer Agent一个独立的 Antigravity SDK 代理在工作区内把浏览器游戏写成自包含 HTML。它同时演示了工作区目录预创建、workspace 限定策略与save_dir的标准用法是理解本文全部概念的完整落地样例。模块 README简短索引指向本文档。AntigravityAgent 单元测试覆盖会话 ID 持久化、单轮模式、子代理校验与节点运行路径等行为是理解边界条件的补充材料。事件转换器测试、子代理工具测试、工具结果捕获测试分别验证 Step→Event 映射、子代理工具包装与钩子缓冲逻辑。需要提醒的是labs模块属于实验性集成其 API 面向的是把另一套 Agent 运行时嵌入 ADK这一具体需求生产使用前请确认你的 ADK 版本与google-antigravity包的兼容性并严格按pip install google-adk[antigravity]安装依赖。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 17:11:09 · 阅读 1.2k ADK 集成 AntigravityAgent：把 Google Antigravity SDK 代理封装为原生 ADK Agent 节点
ADK 集成 AntigravityAgent把 Google Antigravity SDK 代理封装为原生 ADK Agent 节点【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-pythonAntigravityAgent是 ADKAgent Development Kit在labs模块中提供的一个BaseAgent子类它把一个预配置的google.antigravity.AgentConfig如LocalAgentConfig包装成标准的 ADK Agent 节点每一轮对话被委托给 Antigravity SDK 的运行器执行其轨迹步骤模型文本、工具调用、工具响应被流式转换为标准 ADKEvent并写入会话记录。阅读本文后你将掌握如何用 Antigravity SDK 的本地工作区工具与策略来驱动 ADK 应用如何通过modesingle_turn将其作为子代理嵌套进 ADK 父代理以及如何把 ADKsub_agents反向桥接为 Antigravity 的客户端工具。为什么需要 AntigravityAgentAntigravity SDK 擅长在本地工作区中执行任务——它自带工作区workspace管理、文件类工具与安全策略policy例如限制模型只能在指定目录内读写。但 Antigravity SDK 本身不提供 ADK 那样的代理编排多代理、工作流、会话存储与 Web UI 能力。AntigravityAgent解决了这个组合问题它让 ADK 应用直接借用 Antigravity SDK 的本地工作区工具与策略同时保留 ADK 的编排、会话与 UI 能力。官方指南的原话是它将 Antigravity SDK 的运行循环harness与 ADK 的会话/事件体系缝合在一起见 官方指南 与 模块文档字符串。从源码结构看该集成位于labs实验性实验室模块之下与labs/openai并列属于 ADK 提供的非核心、实验性质的集成能力由以下几个文件组成入口与主类AntigravityAgent主实现事件转换器把 Antigravity SDK 的Step翻译为 ADKEvent子代理工具桥接把 ADK 子代理包装为 Antigravity 的客户端工具工具结果捕获通过钩子hook缓冲客户端工具的调用结果包入口依赖检查与AntigravityAgent导出需要特别说明的是使用本模块前必须先安装google-antigravity包。__init__.py在导入时会import google.antigravity若缺失会抛出ImportError并提示运行pip install google-adk[antigravity]见 包入口。快速开始包装一个 Antigravity SDK 代理官方指南给出了最精简的启动代码。第一步先配置 Antigravity SDK 侧的代理第二步将其包装为 ADK 根代理from google.adk.labs.antigravity import AntigravityAgent from google.antigravity import LocalAgentConfig from google.antigravity.hooks import policy # 1. 配置 Antigravity SDK 代理。 # 多轮对话必须设置 save_dir这样临时目录才能在多轮之间被保留。 sdk_config LocalAgentConfig( system_instructionsYou are a helpful local environment assistant., workspaces[./sandbox], policies[*policy.workspace_only([./sandbox])], save_dir./trajectories, ) # 2. 将 Antigravity SDK 配置包装为独立的 ADK 根代理。 root_agent AntigravityAgent( nameantigravity_assistant, descriptionRuns an Antigravity SDK agent inside ADK., configsdk_config, )对这段代码的几个要点说明workspaces与policiespolicy.workspace_only([./sandbox])是一个 workspace 限定策略允许模型在./sandbox内使用内置文件工具进行创建与编辑同时把写入限制在该目录内。这是 Antigravity SDK 本地代理的核心安全机制。save_dir的多轮语义见下文配置选项一节的详细解释。name与descriptionname是 ADK 会话中该代理的标识description会在该代理被作为子代理/工具暴露给模型时被读取。完成包装后root_agent就是一个标准的 ADKBaseAgent可以直接交给 ADK 的Runner运行像使用任何其他 ADK 代理一样进行多轮对话、事件监听与 UI 调试。仓库中有一个完整可运行的真实示例——Game Developer Agent它把上述模式落地为一个网页游戏开发者代理system_instructions要求模型把每个游戏写成单个自包含 HTML 文件内联 CSS/JavaScript无外部依赖并在game_repo工作区内分步增量构建完成后说明如何游玩。示例还演示了工程细节用os.makedirs(..., exist_okTrue)预创建工作区与轨迹目录再传给LocalAgentConfig。工作原理每轮重建 SDK 代理用会话 ID 维持连续性官方指南明确描述了AntigravityAgent的核心运行时模型每轮都构建并进入一个全新的 Antigravity SDKAgent从 ADK 会话状态中读取并恢复会话 IDconversation ID把最新用户输入发送进去并把流式返回的每个Step转换为标准 ADKEvent覆盖模型文本响应、函数调用、函数响应三类轮与轮之间不保持任何打开的资源SDKAgent实例在退出时被关闭下一轮重新连接。连续性完全来自会话 ID——包装器把它读写到 ADK 会话状态中。对应到源码实现主类会话 ID 的存储键为_antigravity_conversation_id_前缀 代理名_conversation_id_state_key见 L317-L320。这意味着同一个 ADK 会话中的两个AntigravityAgent实例各自维护独立的 Antigravity 对话互不干扰。会话 ID 的持久化通过事件携带的EventActions(state_delta...)完成_conversation_id_event见 L322-L336。源码注释特别强调它必须是独立事件而非合并进模型事件因为部分事件partial event不会被追加到会话中而state_delta正是在会话落盘时才被应用。恢复会话时配置会被设置为SessionContinuationMode.CREATE_OR_RESUME见 L360-L367这是唯一能在底层存储已不存在时优雅降级为新建会话的模式否则默认模式下找不到存储会直接抛硬错误。连接 SDK 代理使用了异步上下文管理器async with若__aenter__期间被取消会显式调用__aexit__以避免孤儿化 harness 子进程见 L369-L376。会话 ID 的写入时机经过精心设计即使某轮步骤不产生任何用户可见事件例如 compact 压缩步骤只要对话有历史就仍要记录 ID否则下一轮会孤儿化这段对话见 L403-L432。Step 到 Event 的映射规则转换逻辑被独立抽取到 _event_converter.py以保证映射规则可读、可单独测试。核心入口是convert_step_to_eventsL334-L381每收到一个Step按以下顺序产出事件AntigravityStep内容产出的 ADK 事件思考增量thinking_deltapartialTrue的模型思考事件仅 SSE 流式模式文本增量content_deltapartialTrue的模型文本事件仅 SSE 流式模式完整模型文本响应一个author代理名的最终模型文本事件模型发起的工具调用author代理名的function_call事件工具执行完成/出错author工具名的function_response事件几个值得注意的实现细节均可从源码确认最终文本只在is_complete_response时发出Antigravity SDK 会在响应增长过程中反复重播累积的content若每次都发会造成同一消息被记录多次因此只在完整响应时用最终累积文本生成事件L99-L131。SSE 流式模式下才生成增量事件_run_turn会检查run_config.streaming_mode StreamingMode.SSEL452-L454非流式模式只产出最终事件。工具调用 ID 去重当 SDK 省略调用 ID 时会合成{step_index}-{name}形式的稳定 ID_build_tool_call_idL48-L50并用seen_tool_calls/seen_tool_results集合对跨步骤重播的调用与结果去重。final_model_text用于把事件中的用户可见文本读出来它过滤掉 partial、思考thought与函数部件多段文本以换行拼接L384-L412。已知边界SDK 在回合取消时发出的SYSTEM_MESSAGE步骤目前被丢弃尚未映射为 ADK 事件见 _event_converter.py 顶部 TODO。配置选项官方指南给出了一张配置参数表选项类型默认值说明configAgentConfig必填描述 Antigravity SDK 代理的google.antigravity.AgentConfig。modeLiteral[single_turn] \| NoneNone作为子代理使用时的组合模式。两个参数在源码中的定义与细节如下L161-L178configAntigravity SDK 代理的全部定义config定义了 Antigravity SDK 的指令system_instructions、工作区workspaces与策略policies。源码中它被标记为Field(excludeTrue)——即从序列化中排除因为它持有运行期接线例如可调用工具不是 JSON 可序列化的。当使用LocalAgentConfig时多轮连续对话必须提供save_dir。原因指南与源码双重印证见 L186-L202本地配置在每次连接时会新建一个临时目录如果没有save_dir每一轮写入的位置都不是下一轮会去查找的位置即每轮都是全新对话。源码会在构造时检查并打印警告日志_warn_if_local_without_save_dir若检测到本地配置且未设置save_dir且非单轮模式会警告该代理不会跨轮记住任何东西。注意它检查的是基类BaseLocalAgentConfig而非默认子类因为临时目录的创建逻辑在基类里任何子类缺save_dir都会失忆L265-L271。另外config在每轮运行前会被深拷贝model_copy(deepTrue)见 L296-L299一方面避免修改调用方的配置对象另一方面因为 SDKAgent的AsyncExitStack是单次使用的不能复用同一配置。mode子代理组合模式mode控制AntigravityAgent如何被嵌套在 ADK 父代理之下modeNone默认作为独立的 ADK 根代理运行。modesingle_turn允许该代理拥有 ADK 父代理。此时父LlmAgent会把它暴露为一个内联工具工具签名接收一个request字符串父代理负责组合请求会话历史不会被转发每次单轮调用都是独立对话前后不继承任何内容。源码中mode是frozenTrue的字段因为收养检查adoption guard只在构造时执行一次。该守卫在__setattr__中实现L240-L248如果尝试给AntigravityAgent设置非空的parent_agent而mode ! single_turn会抛出ValueError提示文案为AntigravityAgent may only be an ADK sub-agent when it sets modesingle_turn... Otherwise it must run as an ADK root agent.这与官方指南Limitations一节的第一条限制完全对应AntigravityAgent 运行的是自包含的 Antigravity SDK 对话因此除非设置modesingle_turn否则它必须是 ADK 根代理。高级应用给 AntigravityAgent 挂 ADK 子代理官方指南的进阶场景是AntigravityAgent可以拥有 ADKsub_agents。每个 ADK 子代理会被桥接到 Antigravity SDK 配置上变成一个以子代理名字命名的客户端工具client-side tool。该工具接收一个request字符串因此每个子代理必须提供非空的description——这是 Antigravity SDK 模型在选择是否调用时唯一能读到的信息。子代理在隔离环境中运行只返回其最终文本父会话记录一次工具调用和携带该最终文本的function_response。from google.adk.agents.llm_agent import Agent def get_current_time(city: str) - dict: return {status: success, report: fThe time in {city} is 12:00 PM.} time_agent Agent( nametime_assistant, description( Returns the current time. Always call this for time-related queries. ), instructionAnswer time questions by calling get_current_time., tools[get_current_time], ) root_agent AntigravityAgent( nameantigravity_assistant, descriptionRuns an Antigravity SDK agent inside ADK., configsdk_config, sub_agents[time_agent], )底层机制客户端工具桥接桥接实现在 _sub_agent_tools.py 的make_sub_agent_toolL50-L122子代理的名字成为工具名__name__子代理的description成为工具描述__doc__两者都是模型读取的信息来源。每次调用该工具时会用Runner 全新的InMemorySessionService以隔离会话运行子代理一次返回其最后一个用户可见文本若没有文本则回退到最后一个错误消息再不行返回绝不返回None。这与 ADK 自带的AgentTool非常接近区别是不返回代码执行输出与可执行代码且子代理抛出的异常会原样传播给调用方AgentTool则会把失败包装成错误字符串。工具的Runner在finally中显式关闭以保证子代理的 MCP 会话、工具集等资源被正确释放——否则遗留的 MCP 会话会在后续出现 Attempted to exit cancel scope in a different task 之类的错误。导入Runner被刻意延迟到函数内部L71因为runners会拉入大半个 ADK在 labs 模块顶层立即导入容易形成循环依赖。构造期校验名字与描述在_validate_sub_agentsL204-L238中构造时会校验三种冲突并抛出ValueError子代理缺少description——它作为工具被暴露描述是模型唯一决策依据子代理名字与config.tools中已有工具重名——它们会被追加到同一个config.toolsharness 按名字注册工具重名者会被拒绝两个子代理重名——原因同上。注意该校验在构造后例如model_copy或后续修改sub_agents还会被_build_sdk_config再次调用防止绕过model_post_init。客户端工具的结果捕获一个关键设计点是客户端工具ADK 子代理的执行结果永远不会出现在轨迹trajectory里——其终止Step的tool_calls为空且Step本身没有结果字段。结果只能通过工具钩子到达。因此 _tool_result_capture.py 实现了两个钩子类共用一个ToolResultBufferToolResultCapturePostToolCallHook成功路径在post_tool_call时把ToolResult按id存入缓冲ToolErrorCaptureOnToolErrorHook失败路径在on_tool_error时把ToolExecutionError包装为_FailedToolResult存入缓冲。两个钩子互斥——每次调用恰好触发其一见 _tool_result_capture.py 模块文档。缓冲只在存在sub_agents时才注册因为post_tool_call钩子每次成功调用都会带来一次阻塞往返且只在 AntigravityAgent 拥有子代理时为真L355-L359。回合结束后_run_turn会调用drain_tool_results把已捕获但尚未答复的调用配对成function_response事件再清空缓冲L470-L484。运行模式与运行时约束作为工作流节点Node运行AntigravityAgent同时实现了节点运行路径_run_implL486-L521它把node_input转成用户内容收集整轮最后一段模型文本作为output产出从而可以作为 ADK 工作流workflow中的节点使用支持node_input注入与output输出。这从源码结构看是复用run_async主路径的实现。静默丢失恢复silent-drop detection针对要求恢复某会话但底层已不存在的情况源码对本地连接实现了检测恢复后若对话历史为空判定为静默新建了会话此时会清除存储的 ID 并抛出RuntimeError提示已清除存储的 ID下一轮将开始新对话但本会话之前的回合不可恢复L394-L402。该检测被限定在本地配置类型内因为远程后端在陈旧 ID 上静默新建会话的行为无法在不依赖 SDK 支持的前提下被可靠区分L434-L445。已知限制官方指南明确列出的限制如下并可与源码互证嵌套限制AntigravityAgent运行的是自包含的 Antigravity SDK 对话因此除非设置modesingle_turn否则它必须是 ADK 根代理。这条限制仅适用于该代理被放在 ADK 父代理之下的场景它自己的 ADKsub_agents是被桥接为客户端工具的永远不需要设置mode。子代理的 root 解析AntigravityAgent的 ADK 子代理的root_agent仍指向最外层 ADK 代理树。在三层结构中LlmAgent→AntigravityAgent(modesingle_turn)→ 子代理中间的代理设置modesingle_turn是因为它有 ADK 父代理而不是因为它有子代理此时 ADK 的 transfer 工具会被声明给子代理的模型。建议让AntigravityAgent的子代理保持叶节点形态或者在这些子代理上设置disallow_transfer_to_parent与disallow_transfer_to_peers。并发限制同一 ADK 会话的两轮并发运行是未定义行为因为两者会打开同一个已存储的会话。相关示例与进一步阅读Game Developer Agent一个独立的 Antigravity SDK 代理在工作区内把浏览器游戏写成自包含 HTML。它同时演示了工作区目录预创建、workspace 限定策略与save_dir的标准用法是理解本文全部概念的完整落地样例。模块 README简短索引指向本文档。AntigravityAgent 单元测试覆盖会话 ID 持久化、单轮模式、子代理校验与节点运行路径等行为是理解边界条件的补充材料。事件转换器测试、子代理工具测试、工具结果捕获测试分别验证 Step→Event 映射、子代理工具包装与钩子缓冲逻辑。需要提醒的是labs模块属于实验性集成其 API 面向的是把另一套 Agent 运行时嵌入 ADK这一具体需求生产使用前请确认你的 ADK 版本与google-antigravity包的兼容性并严格按pip install google-adk[antigravity]安装依赖。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考