ADK 的 LlmAgent Task 模式全解结构化委托、finish_task 工具与子代理协作【免费下载链接】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本文以docs/guides/agents/llm_agent/task.md为核心骨架结合 ADK 源码src/google/adk与官方示例contributing/samples/multi_agent/task_sub_agent/展开。读完本文你将掌握task 模式与 chat / single_turn 模式的本质区别、如何用input_schema/output_schema定义结构化任务接口、finish_task工具的校验与重试机制、task 子代理如何在多代理层级中以工具形式被父代理调用以及如何在 workflow 中托管 task 模式代理的生命周期。导语在 ADK 中LlmAgent的modetask面向被委派的、目标明确的一次性任务场景任务代理自己运行思考循环、按需调用工具、必要时与用户对话澄清最终必须显式调用内建finish_task工具并返回经过output_schema校验的结构化结果。本文从行为模型、配置写法、底层实现到完整示例逐步展开帮助你用它构建可靠的多代理委托流水线。1. Task 模式是什么三种委托模式对比LlmAgent.mode字段定义于 llm_agent.py支持三种取值模式语义典型用途chat标准对话代理可通过transfer_to_agent转交控制权支持持续的你来我往前台客服、多代理平级协作task被委派一个具体任务与用户对话以完成任务最终必须调用finish_task返回结构化结果子代理委托、结构化数据抽取single_turn无状态、一次调用立即完成不与用户来回对话单轮查询、即时工具化调用从源码注释看默认值也有讲究作为子代理时默认chat作为 workflow 节点时默认single_turn见 llm_agent.py。当子代理是LlmAgent且未显式声明mode时框架会在model_post_init中将其自动置为chatllm_agent.py。task 模式代理的四个核心特征运行到完成它执行思考 → 调工具的循环直到自己判定任务结束可与用户对话任务不清晰时可以提问澄清框架负责跨轮次暂停与恢复显式结束必须调用内建finish_task工具否则任务无法成功收尾结构化返回最终输出在返回给调用方前会依据output_schema做校验。2. Task 模式作为子代理工具化委托机制2.1 行为模型task 子代理与 single_turn 子代理一样是以工具的形式暴露给父代理的而不是转移目标transfer_to_agent对它无效。调用链如下父代理在思考循环中决定调用该子代理对应的工具父代理执行被挂起框架在子分支sub-branch中运行 task 代理task 代理运行自己的循环、使用自己的工具直到调用finish_taskfinish_task传入的输出被校验后作为工具结果返回给父代理。源码佐证在 llm_agent.py 的model_post_init中框架遍历sub_agentsmode single_turn的包装为_SingleTurnAgentToolmode task的包装为_TaskAgentTool两者定义于 agent_tool.py。_TaskAgentTool有几个值得注意的实现细节agent_tool.py若子代理未定义input_schema默认使用_DefaultTaskInput含request字段见 agent_tool.py工具描述会追加一段强调文案此工具将执行委托给一个专门代理不要与其他工具并行调用_TaskAgentTool._get_declaration见 agent_tool.pyrun_async直接返回None——真正执行由 LLM flow 中的框架委托分发接管见 basic.py 及 workflow/_llm_agent_wrapper.py 中_dispatch_task_fc与_synthesize_task_fr_event的实现这保证了任务历史按 function-call 隔离作用域独立管理。2.2 定义与委托示例官方文档原例from google.adk.agents import LlmAgent from pydantic import BaseModel, Field # 1. 定义输入与输出 Schema class ResearchInput(BaseModel): topic: str Field(descriptionThe topic to research.) depth: str Field(defaultbrief, descriptionDepth of research: brief or detailed.) class ResearchOutput(BaseModel): summary: str Field(descriptionA summary of the findings.) sources: list[str] Field(descriptionList of sources used.) # 2. 定义 Task 代理 researcher_agent LlmAgent( nameresearcher, instructionResearch the given topic and provide a structured summary., modetask, input_schemaResearchInput, output_schemaResearchOutput, # Add tools needed for the task tools[...] ) # 3. 定义父代理 writer_agent LlmAgent( namewriter, instructionWrite a blog post. Use the researcher agent to get info on the topic., sub_agents[researcher_agent] # Exposes researcher agent to writer )要点补充input_schema决定父代理调用该子代理工具时所需的参数结构output_schema决定finish_task必须返回的数据结构。output_schema支持的类型很宽见 llm_agent.py 的字段文档type[BaseModel]、list[type[BaseModel]]、list[primitive]、原生 dict schema以及 Google 的Schema类型。ADK 支持output_schema与tools同时使用——思考循环中照常暴露工具只在最终输出上强制结构见 llm_agent.py。特别地task 模式代理不会在基础 flow 中把output_schema作为模型的 response schema 下发因为结构化输出是通过finish_task工具的参数 schema 收集的见 basic.py 的注释与条件判断。2.3 用户交互与跨轮次恢复task 代理不是一锤子买卖任务不清晰时可以与人对话提问代理输出面向用户的文本而不是调用finish_task暂停框架检测到代理交回控制权但未完成任务暂停执行并把消息送达用户恢复用户回复后框架自动把回复路由回 task 代理恢复其执行循环完成代理继续交互直到最终调用finish_task提交结果。这种暂停-恢复由框架的 runner 与 LLM flow 协同完成任务输出TaskResult与请求TaskRequest的数据模型定义在 _task_models.py两个模型都启用 camelCase 别名并禁止额外字段保证跨会话序列化后依旧可被严格校验。3. finish_task 工具任务完成的唯一出口3.1 自动注入任何modetask的代理都会在初始化时自动获得finish_task工具。源码位于model_post_initllm_agent.pyif self.mode task: from .llm.task._finish_task_tool import FinishTaskTool self.tools.append(FinishTaskTool(self))工具名为常量FINISH_TASK_TOOL_NAME finish_task见 _finish_task_tool.py。3.2 工作机理结合源码系统指令注入FinishTaskTool.process_llm_request在每次出站 LLM 请求时追加一段指令_finish_task_tool.py核心内容为不要在任务未完成时过早调用finish_task。请先用可用工具完整完成被委派任务的每一个方面如果任务不清晰先向用户提问澄清任务彻底完成后单独调用finish_task不要附带任何文本输出。参数 Schema 包装finish_task的 function declaration 依据代理的output_schema生成。若 schema 本身是对象如 BaseModel直接用作参数若是原始类型或列表如list[str]则包装到result键下get_output_wrapper_key_finish_task_tool.py并在包装时把$defs提升到根层以保持$ref引用有效_finish_task_tool.py。校验与失败重试当模型调用finish_task(output...)时工具用TypeAdapter按output_schema校验参数。校验失败会返回错误字典提示模型可以重试该工具调用但必须提供全部必填参数且类型正确_finish_task_tool.py。校验成功后返回固定成功串Task completed.框架依据is_finish_task_terminal_fr_finish_task_tool.py识别该结果为终止信号校验失败的非终止 FR 会让循环继续给 LLM 重试机会。默认 Schema未指定output_schema时默认采用_DefaultTaskOutput——一个仅含必填result: str字段的模型即返回一个简单字符串_task_models.py。3.3 输出在事件流中的落点在 workflow 包装层task 代理运行结束时_llm_agent_wrapper.py会嗅探finish_task的 function call 参数结合终止 FR 事件把最终输出写到该次运行的事件output上见 workflow/_llm_agent_wrapper.py 附近逻辑从而保证父代理拿到的是校验通过的结构化结果而非中间的对话文本。4. Task 模式在 Workflow 中的应用task 模式在 workflow 中完全受支持可以把 task 模式代理作为 workflow 图里的静态节点。workflow runner 会自动管理任务生命周期包括为等待人工输入而暂停以及用正确上下文恢复执行见 workflow/_llm_agent_wrapper.py 对节点模式下 task / single_turn / chat 三种模式的区分处理LlmAgent作为节点仅支持这三种模式task 模式会以节点输入覆盖用户内容。作为节点时task 代理的输入来源与被委托场景不同没有来自父代理的委托 function call因此直接使用节点的node_input源码注释中明确区分了这两种路径见 workflow/_llm_agent_wrapper.py。5. 限制与注意事项不可直接转移不能通过transfer_to_agent转移到 task 代理它们必须以工具形式被调用源码中_TaskAgentTool正是框架委托标记而非转移目标见 agent_tool.py。必须调用finish_task若 task 代理因 bug 或达到调用上限如max_llm_calls耗尽始终未调用finish_task任务将无法成功完成。这一点与_TaskAgentTool返回None的设计呼应——没有终止 FR就没有输出落点。6. 官方示例task_sub_agent 完整实战仓库提供了可直接运行的示例 task_sub_agent演示task 模式代理作为子代理从对话流中抽取结构化数据的完整闭环。6.1 场景与图结构协调者coordinator委托两个 task 子代理order_collector收集用户订单菜单仅有 Pizza / Burger / Salad返回list[OrderItem]payment_collector收集信用卡号与 CVV返回PaymentInfo。任务完成后协调者用两个代理返回的结构化数据调用place_order工具。6.2 关键代码agent.py 节选核心实现位于 agent.pyclass OrderItem(BaseModel): name: str Field(descriptionName of the food item ordered) quantity: int Field(descriptionQuantity ordered) class PaymentInfo(BaseModel): Output schema for the payment collection task. credit_card_number: str cvv: str order_collector Agent( nameorder_collector, modetask, output_schemalist[OrderItem], # 列表类型也受支持 instruction( You are an order collection assistant...\n Ask the user what they would like to order and collect their choice and quantity.\n If the combined quantity of items exceeds 5, you MUST use the confirmation tool ...\n Once you have their final order and confirmation if needed, finish your task. ), descriptionCollects the food order from the user., tools[FunctionTool(confirmation, require_confirmationTrue)], ) payment_collector Agent( namepayment_collector, modetask, output_schemaPaymentInfo, instructionYou are a payment collection assistant. Ask the user for their credit card number and CVV. Once you have both pieces of information, finish your task., descriptionCollects credit card and CVV from the user., ) root_agent Agent( namecoordinator, sub_agents[order_collector, payment_collector], tools[place_order], instructionYou are a helpful coordinator for a food delivery service. You need both order and payment information to place an order., )示例要点输出 Schema 用list[OrderItem]验证了上文list[type[BaseModel]]属于受支持的 output schema 类型由于它是列表而非对象finish_task的参数会自动包装在result键下。任务内嵌工具order_collector拥有自己的confirmation工具且标记require_confirmationTrue说明 task 代理在执行循环中完全可以使用自己的工具集。与用户多轮对话示例输入依次为I would like to order some food please.→I want 2 pizzas and 1 salad.→My credit card is 1234-5678-9012-3456 and my CVV is 123.完整展示了父代理委托 → 子代理向用户提问 → 用户回复 → 子代理恢复执行 → finish_task 收尾的跨轮次协作流程。测试用例目录tests/含3_burgers.json、credit_card.json、order_food.json等可进一步验证各输入组合下的行为。不要与其他工具并行调用协调者同时持有两个 task 子代理工具示例代码与_TaskAgentTool的工具描述都强调串行委托避免并行调用造成任务状态混乱。7. 延伸阅读指南原文LlmAgent Task Mode完整示例task_sub_agent README 与 agent.py 实现核心实现LlmAgent 定义与 mode 字段、FinishTaskTool、TaskRequest/TaskResult 模型、子代理工具包装、workflow 节点包装相关子代理机制single_turn模式与transfer_to_agent转移机制可在 agents 目录 与 agents 指南 中进一步查阅。【免费下载链接】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），仅供参考