ADK-Python 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-pythonAgent Development KitADKPython 版中Agent是绝大多数用户实例化智能体时直接使用的类型——但它到底是什么它与BaseAgent、BaseNode是什么关系run_async、run_live、run三个入口方法分别何时调用本文以 ADK 架构文档interface-agent.md为主线结合仓库源码 src/google/adk/agents/base_agent.py、src/google/adk/agents/llm_agent.py 与 src/google/adk/workflow/_base_node.py系统梳理 ADK 的 Agent 接口体系、关键字段校验、生命周期回调与三种入口方法的适用场景帮助你写出符合 ADK 设计约束的智能体代码。Agent 是什么类型别名而非新类在 ADK 中Agent并不是一个独立的类而是一个类型别名。源码中定义在 src/google/adk/agents/llm_agent.py#L1346Agent: TypeAlias LlmAgent也就是说Agent就是LlmAgent——一个由大模型驱动model-backed、绝大多数用户直接实例化的智能体类。这一点在架构文档中被刻意强调Agent与BaseAgent不是一回事。BaseAgent是定义在 src/google/adk/agents/base_agent.py#L112 的抽象基类class BaseAgent(BaseNode, abc.ABC)是所有智能体包括LlmAgent、SequentialAgent、ParallelAgent、LoopAgent、RemoteA2aAgent等的共同祖先但它本身不可直接实例化。因此代码中的Agent(...)与LlmAgent(...)完全等价你可以按习惯选用任一写法from google.adk.agents import Agent, LlmAgent a1 Agent(namehelper, modelgemini-3.5-flash) a2 LlmAgent(namehelper, modelgemini-3.5-flash) # 与 a1 等价Agent 即 Node智能体与工作流的统一抽象BaseAgent继承自BaseNode见 src/google/adk/workflow/_base_node.py#L44 的class BaseNode(BaseModel, abc.ABC)。这一设计带来一个关键推论Agent 就是 Node它既可以作为一个独立的智能体挂在Runner下直接运行也可以作为一个节点node嵌入Workflow图中参与编排当智能体作为 Workflow 的图节点时Workflow 通过run()调用它当智能体被直接调用时调用方使用run_async()。这种Agent 与 Node 同构的设计使得单个智能体可以被自由地组装进顺序、并行、循环等复杂工作流而无需改变智能体自身的实现——这是 ADK 支持从单智能体到多智能体编排平滑演进的基础。关键字段与校验规则BaseAgent的核心字段Pydantic 模型字段如下均定义于 src/google/adk/agents/base_agent.py字段说明name智能体树中的唯一标识符必须通过校验见下文description能力描述模型在决定把控制权委托给哪个子智能体时参考它一行描述足够且推荐sub_agents子智能体列表树内名称必须唯一父指针自动接线before_agent_callback/after_agent_callback拦截智能体生命周期运行前 / 运行后回调支持单个回调或回调列表name 的硬性校验name的校验实现在 src/google/adk/agents/base_agent.py#L657-L672通过 Pydantic 的field_validator(name, modeafter)完成规则有两条必须是合法的 Python 标识符以字母a-z、A-Z或下划线_开头只能包含字母、数字0-9和下划线即str.isidentifier()必须为真user被拒绝user是为终端用户输入保留的名字智能体不得占用。违反任一条都会抛出ValueError。例如namemy agent含空格或nameuser都无法通过校验。sub_agents 的唯一性与父指针自动接线sub_agents同样有校验逻辑树内名称唯一校验器 base_agent.py#L674-L711 会收集所有子智能体名称发现重名时打印logger.warning注意是警告而非异常父指针自动设置在model_post_init阶段调用__set_parent_agent_for_sub_agentsbase_agent.py#L713-L722把每个子智能体的parent_agent指向当前智能体。若某个子智能体已有父智能体则抛出ValueError。由此派生的一个实践约束一个智能体实例只能被添加为子智能体一次。如果想把同一份配置的智能体挂到树中两处应当创建两个配置相同但name不同的实例。入口方法按调用方选择而非按新旧选择BaseAgent提供三个入口方法架构文档用一张表给出明确分工方法用途run_async(parent_context)文本对话入口。产出Event流围绕_run_async_impl执行 before/after 回调、错误回调与调用插桩instrumentationrun_live(parent_context)音视频对话入口。标记为final子类应重写_run_live_impl而非run_live本身run(ctx..., node_input...)继承自BaseNode同样final。当智能体作为 Workflow 图节点时由 Workflow 调用它路由到_run_impl而BaseAgent._run_impl又委托给run_async需要特别澄清的是选择哪个方法取决于调用方而非方法是否过时。源码中没有任何一处将run_async标记为deprecated它至今仍是每个智能体真实逻辑_run_async_impl必然流经的执行路径。run_async文本对话的主干路径实现在 base_agent.py#L325-L365执行顺序为通过_create_invocation_context(parent_context)从父上下文派生本次调用的InvocationContext在_instrumentation.record_agent_invocation上下文内记录调用遥测执行 before 回调含插件层run_before_agent_callback若回调返回 truthy 内容则生成事件并置end_invocation跳过主体逻辑以异步生成器方式消费_run_async_impl(ctx)产出的所有Event执行 after 回调truthy 返回值会作为追加的智能体响应事件写入事件历史主体或回调抛异常时进入_handle_agent_error_callback通知型、尽力而为原异常始终重新抛出。值得注意的细节before 回调返回 truthy 内容时智能体运行被跳过该内容直接返回给用户而 after 回调返回 truthy 内容时会作为额外的一次智能体响应追加到事件历史中二者语义不同。回调的绑定规则为优先按关键字传参失败则按位置顺序绑定。run_live音视频对话入口run_live在 base_agent.py#L386-L424 实现被final装饰执行骨架与run_async对称before/after 回调、错误回调、插桩区别仅在于核心逻辑是_run_live_impl。由于final的存在扩展 live 行为的正确姿势是重写_run_live_impl默认实现抛出NotImplementedError而不是重写run_live。LlmAgent 的默认 live 模型常量定义在 llm_agent.py#L281DEFAULT_LIVE_MODEL gemini-live-2.5-flash-native-audio。run作为工作流节点被调用run继承自BaseNode且为finalBaseAgent._run_implbase_agent.py#L367-L384以override重写其实现就是遍历run_async的事件流并在Context中维护event_author与node_info.path保证事件带正确的作者与节点路径信息交给NodeRunner。这也是Agent 即 Node落地的关键一环无论智能体身处何处真实逻辑始终收敛到run_async。其他方法克隆、查找与根节点clone(updateNone)— 复制一个智能体实例并与其父智能体脱离关系。实现在 base_agent.py#L249-L323支持传入update映射如{name: cloned_agent}覆盖字段若回调是原智能体自身的方法会自动重绑定rebind到克隆体未在update中提供的列表字段做浅拷贝sub_agents会递归克隆并让克隆子智能体的parent_agent指向克隆体克隆体的parent_agent最终置为None。注意update中不允许出现parent_agent也不能包含类上不存在的字段否则抛ValueError。find_agent(name)/find_sub_agent(name)— 在智能体树中按名称搜索find_agent先匹配自身再递归到后代find_sub_agent仅在后代中查找base_agent.py#L466-L491。root_agent— 沿parent_agent链向上走到树顶返回根智能体base_agent.py#L458-L464。from_config(config, config_abs_path)— 从配置对象构建智能体。该方法同时带有deprecated与experimental装饰器base_agent.py#L724-L769官方建议不要在其上构建业务BaseAgent.from_config已弃用应改用google.adk.agents.config_agent_utils.from_config或直接在类上定义字段 / 使用动态 YAML 加载器。深入 LlmAgentAgent 别名背后的完整能力面既然Agent就是LlmAgent理解Agent的完整能力面还需要看 llm_agent.py#L259 起的字段定义。除继承自BaseAgent的通用字段外LlmAgent还提供modelllm_agent.py#L290— 使用的模型可为字符串或BaseLlm实例。未设置时从祖先智能体继承仍无则使用LlmAgent.set_default_model配置的默认模型内建默认值为gemini-3.5-flash常量DEFAULT_MODEL见 llm_agent.py#L278instruction/static_instruction— 动态指令与静态指令。instruction可含{variable_name}占位符运行期用会话状态解析static_instruction不处理占位符、原样发送主要服务于上下文缓存优化tools— 智能体可用的工具列表modellm_agent.py#L404-L413— 委托模式chat标准对话经transfer_to_agent可达、task与用户对话以完成任务、single_turn不与用户对话直接完成任务。子智能体默认chat作为工作流节点默认single_turndisallow_transfer_to_parent/disallow_transfer_to_peer— 控制 LLM 主导的控制权转移范围include_contents—default模型接收相关对话历史或none仅基于当前指令与输入运行input_schema/output_schema— 作为工具时的输入模式与回复的结构化输出模式output_schema支持BaseModel、list[BaseModel]、list[primitive]、原生 dict 与 GoogleSchema类型output_key— 将智能体输出存入会话状态的键名便于工具、回调及其他智能体取用。一个值得了解的机制LlmAgent会在初始化时llm_agent.py#L1320-L1343根据子智能体的mode将其包装成工具——single_turn子智能体包装为_SingleTurnAgentTooltask子智能体包装为_TaskAgentTool未声明mode的子智能体不会被包装而是作为 LLM 转移transfer的目标。这与mode字段的语义相互印证。实际使用最小示例与验证一个同时体现Agent 即 Node与生命周期回调的最小示例from google.adk.agents import Agent from google.adk.workflow import Workflow def before_agent_callback(callback_context): print(fbefore: {callback_context.agent.name}) def after_agent_callback(callback_context): print(fafter: {callback_context.agent.name}) sub Agent( namesub_helper, modelgemini-3.5-flash, descriptionHandles subtasks delegated by the root agent., ) root Agent( nameroot, modelgemini-3.5-flash, descriptionRoot coordinator., sub_agents[sub], before_agent_callbackbefore_agent_callback, after_agent_callbackafter_agent_callback, ) # 直接文本调用走 run_async作为 Workflow 节点时由 Workflow 调 run() assert root.find_agent(sub_helper) is sub assert root.root_agent is root clone root.clone(update{name: root_clone}) assert clone.parent_agent is None上述断言find_agent、root_agent、clone脱离父智能体在 tests/unittests/agents/test_base_agent.py 等测试中均有覆盖可作为理解接口行为的实证参考。小结ADK 的 Agent 接口看似简单实则暗含三条关键设计Agent是LlmAgent的类型别名、所有智能体继承自BaseNode因而既是 Agent 又是 Node、三个入口方法run_async/run_live/run按调用方各司其职而真实逻辑统一收敛于run_async。理解name校验、sub_agents唯一性与父指针自动接线、before/after 回调的短路语义以及clone、find_agent、root_agent等辅助方法的行为是写出符合 ADK 约束、可复用的智能体代码的前提。若要继续深入可阅读 src/google/adk/agents/base_agent.py 与 src/google/adk/agents/llm_agent.py 的完整字段注释或浏览 src/google/adk/workflow 了解 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-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ADK-Python Agent 接口全解：从类型别名到生命周期入口
ADK-Python 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-pythonAgent Development KitADKPython 版中Agent是绝大多数用户实例化智能体时直接使用的类型——但它到底是什么它与BaseAgent、BaseNode是什么关系run_async、run_live、run三个入口方法分别何时调用本文以 ADK 架构文档interface-agent.md为主线结合仓库源码 src/google/adk/agents/base_agent.py、src/google/adk/agents/llm_agent.py 与 src/google/adk/workflow/_base_node.py系统梳理 ADK 的 Agent 接口体系、关键字段校验、生命周期回调与三种入口方法的适用场景帮助你写出符合 ADK 设计约束的智能体代码。Agent 是什么类型别名而非新类在 ADK 中Agent并不是一个独立的类而是一个类型别名。源码中定义在 src/google/adk/agents/llm_agent.py#L1346Agent: TypeAlias LlmAgent也就是说Agent就是LlmAgent——一个由大模型驱动model-backed、绝大多数用户直接实例化的智能体类。这一点在架构文档中被刻意强调Agent与BaseAgent不是一回事。BaseAgent是定义在 src/google/adk/agents/base_agent.py#L112 的抽象基类class BaseAgent(BaseNode, abc.ABC)是所有智能体包括LlmAgent、SequentialAgent、ParallelAgent、LoopAgent、RemoteA2aAgent等的共同祖先但它本身不可直接实例化。因此代码中的Agent(...)与LlmAgent(...)完全等价你可以按习惯选用任一写法from google.adk.agents import Agent, LlmAgent a1 Agent(namehelper, modelgemini-3.5-flash) a2 LlmAgent(namehelper, modelgemini-3.5-flash) # 与 a1 等价Agent 即 Node智能体与工作流的统一抽象BaseAgent继承自BaseNode见 src/google/adk/workflow/_base_node.py#L44 的class BaseNode(BaseModel, abc.ABC)。这一设计带来一个关键推论Agent 就是 Node它既可以作为一个独立的智能体挂在Runner下直接运行也可以作为一个节点node嵌入Workflow图中参与编排当智能体作为 Workflow 的图节点时Workflow 通过run()调用它当智能体被直接调用时调用方使用run_async()。这种Agent 与 Node 同构的设计使得单个智能体可以被自由地组装进顺序、并行、循环等复杂工作流而无需改变智能体自身的实现——这是 ADK 支持从单智能体到多智能体编排平滑演进的基础。关键字段与校验规则BaseAgent的核心字段Pydantic 模型字段如下均定义于 src/google/adk/agents/base_agent.py字段说明name智能体树中的唯一标识符必须通过校验见下文description能力描述模型在决定把控制权委托给哪个子智能体时参考它一行描述足够且推荐sub_agents子智能体列表树内名称必须唯一父指针自动接线before_agent_callback/after_agent_callback拦截智能体生命周期运行前 / 运行后回调支持单个回调或回调列表name 的硬性校验name的校验实现在 src/google/adk/agents/base_agent.py#L657-L672通过 Pydantic 的field_validator(name, modeafter)完成规则有两条必须是合法的 Python 标识符以字母a-z、A-Z或下划线_开头只能包含字母、数字0-9和下划线即str.isidentifier()必须为真user被拒绝user是为终端用户输入保留的名字智能体不得占用。违反任一条都会抛出ValueError。例如namemy agent含空格或nameuser都无法通过校验。sub_agents 的唯一性与父指针自动接线sub_agents同样有校验逻辑树内名称唯一校验器 base_agent.py#L674-L711 会收集所有子智能体名称发现重名时打印logger.warning注意是警告而非异常父指针自动设置在model_post_init阶段调用__set_parent_agent_for_sub_agentsbase_agent.py#L713-L722把每个子智能体的parent_agent指向当前智能体。若某个子智能体已有父智能体则抛出ValueError。由此派生的一个实践约束一个智能体实例只能被添加为子智能体一次。如果想把同一份配置的智能体挂到树中两处应当创建两个配置相同但name不同的实例。入口方法按调用方选择而非按新旧选择BaseAgent提供三个入口方法架构文档用一张表给出明确分工方法用途run_async(parent_context)文本对话入口。产出Event流围绕_run_async_impl执行 before/after 回调、错误回调与调用插桩instrumentationrun_live(parent_context)音视频对话入口。标记为final子类应重写_run_live_impl而非run_live本身run(ctx..., node_input...)继承自BaseNode同样final。当智能体作为 Workflow 图节点时由 Workflow 调用它路由到_run_impl而BaseAgent._run_impl又委托给run_async需要特别澄清的是选择哪个方法取决于调用方而非方法是否过时。源码中没有任何一处将run_async标记为deprecated它至今仍是每个智能体真实逻辑_run_async_impl必然流经的执行路径。run_async文本对话的主干路径实现在 base_agent.py#L325-L365执行顺序为通过_create_invocation_context(parent_context)从父上下文派生本次调用的InvocationContext在_instrumentation.record_agent_invocation上下文内记录调用遥测执行 before 回调含插件层run_before_agent_callback若回调返回 truthy 内容则生成事件并置end_invocation跳过主体逻辑以异步生成器方式消费_run_async_impl(ctx)产出的所有Event执行 after 回调truthy 返回值会作为追加的智能体响应事件写入事件历史主体或回调抛异常时进入_handle_agent_error_callback通知型、尽力而为原异常始终重新抛出。值得注意的细节before 回调返回 truthy 内容时智能体运行被跳过该内容直接返回给用户而 after 回调返回 truthy 内容时会作为额外的一次智能体响应追加到事件历史中二者语义不同。回调的绑定规则为优先按关键字传参失败则按位置顺序绑定。run_live音视频对话入口run_live在 base_agent.py#L386-L424 实现被final装饰执行骨架与run_async对称before/after 回调、错误回调、插桩区别仅在于核心逻辑是_run_live_impl。由于final的存在扩展 live 行为的正确姿势是重写_run_live_impl默认实现抛出NotImplementedError而不是重写run_live。LlmAgent 的默认 live 模型常量定义在 llm_agent.py#L281DEFAULT_LIVE_MODEL gemini-live-2.5-flash-native-audio。run作为工作流节点被调用run继承自BaseNode且为finalBaseAgent._run_implbase_agent.py#L367-L384以override重写其实现就是遍历run_async的事件流并在Context中维护event_author与node_info.path保证事件带正确的作者与节点路径信息交给NodeRunner。这也是Agent 即 Node落地的关键一环无论智能体身处何处真实逻辑始终收敛到run_async。其他方法克隆、查找与根节点clone(updateNone)— 复制一个智能体实例并与其父智能体脱离关系。实现在 base_agent.py#L249-L323支持传入update映射如{name: cloned_agent}覆盖字段若回调是原智能体自身的方法会自动重绑定rebind到克隆体未在update中提供的列表字段做浅拷贝sub_agents会递归克隆并让克隆子智能体的parent_agent指向克隆体克隆体的parent_agent最终置为None。注意update中不允许出现parent_agent也不能包含类上不存在的字段否则抛ValueError。find_agent(name)/find_sub_agent(name)— 在智能体树中按名称搜索find_agent先匹配自身再递归到后代find_sub_agent仅在后代中查找base_agent.py#L466-L491。root_agent— 沿parent_agent链向上走到树顶返回根智能体base_agent.py#L458-L464。from_config(config, config_abs_path)— 从配置对象构建智能体。该方法同时带有deprecated与experimental装饰器base_agent.py#L724-L769官方建议不要在其上构建业务BaseAgent.from_config已弃用应改用google.adk.agents.config_agent_utils.from_config或直接在类上定义字段 / 使用动态 YAML 加载器。深入 LlmAgentAgent 别名背后的完整能力面既然Agent就是LlmAgent理解Agent的完整能力面还需要看 llm_agent.py#L259 起的字段定义。除继承自BaseAgent的通用字段外LlmAgent还提供modelllm_agent.py#L290— 使用的模型可为字符串或BaseLlm实例。未设置时从祖先智能体继承仍无则使用LlmAgent.set_default_model配置的默认模型内建默认值为gemini-3.5-flash常量DEFAULT_MODEL见 llm_agent.py#L278instruction/static_instruction— 动态指令与静态指令。instruction可含{variable_name}占位符运行期用会话状态解析static_instruction不处理占位符、原样发送主要服务于上下文缓存优化tools— 智能体可用的工具列表modellm_agent.py#L404-L413— 委托模式chat标准对话经transfer_to_agent可达、task与用户对话以完成任务、single_turn不与用户对话直接完成任务。子智能体默认chat作为工作流节点默认single_turndisallow_transfer_to_parent/disallow_transfer_to_peer— 控制 LLM 主导的控制权转移范围include_contents—default模型接收相关对话历史或none仅基于当前指令与输入运行input_schema/output_schema— 作为工具时的输入模式与回复的结构化输出模式output_schema支持BaseModel、list[BaseModel]、list[primitive]、原生 dict 与 GoogleSchema类型output_key— 将智能体输出存入会话状态的键名便于工具、回调及其他智能体取用。一个值得了解的机制LlmAgent会在初始化时llm_agent.py#L1320-L1343根据子智能体的mode将其包装成工具——single_turn子智能体包装为_SingleTurnAgentTooltask子智能体包装为_TaskAgentTool未声明mode的子智能体不会被包装而是作为 LLM 转移transfer的目标。这与mode字段的语义相互印证。实际使用最小示例与验证一个同时体现Agent 即 Node与生命周期回调的最小示例from google.adk.agents import Agent from google.adk.workflow import Workflow def before_agent_callback(callback_context): print(fbefore: {callback_context.agent.name}) def after_agent_callback(callback_context): print(fafter: {callback_context.agent.name}) sub Agent( namesub_helper, modelgemini-3.5-flash, descriptionHandles subtasks delegated by the root agent., ) root Agent( nameroot, modelgemini-3.5-flash, descriptionRoot coordinator., sub_agents[sub], before_agent_callbackbefore_agent_callback, after_agent_callbackafter_agent_callback, ) # 直接文本调用走 run_async作为 Workflow 节点时由 Workflow 调 run() assert root.find_agent(sub_helper) is sub assert root.root_agent is root clone root.clone(update{name: root_clone}) assert clone.parent_agent is None上述断言find_agent、root_agent、clone脱离父智能体在 tests/unittests/agents/test_base_agent.py 等测试中均有覆盖可作为理解接口行为的实证参考。小结ADK 的 Agent 接口看似简单实则暗含三条关键设计Agent是LlmAgent的类型别名、所有智能体继承自BaseNode因而既是 Agent 又是 Node、三个入口方法run_async/run_live/run按调用方各司其职而真实逻辑统一收敛于run_async。理解name校验、sub_agents唯一性与父指针自动接线、before/after 回调的短路语义以及clone、find_agent、root_agent等辅助方法的行为是写出符合 ADK 约束、可复用的智能体代码的前提。若要继续深入可阅读 src/google/adk/agents/base_agent.py 与 src/google/adk/agents/llm_agent.py 的完整字段注释或浏览 src/google/adk/workflow 了解 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-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考