多Agent主从模式实战：把Subagent当作Tool调用的设计与实现

做过多Agent项目的人应该都遇到过这个场景：任务一复杂，单Agent就开始"思维发散"，一会跑偏主题，一会重复劳动，上下文越滚越长，最后输出质量断崖式下跌。我在PIG项目里也踩过这个坑，所以第二篇设计模式笔记，专门聊聊我们最后趟出来的路子——主从模式，以及背后一个关键的思想转变：把subagent当成一种特殊的tool来调用。

这个思路听起来简单，但真正落地的时候牵扯到接口设计、状态同步、错误传播、资源控制一堆问题。这篇就把我们在PIG里的完整实践拆开讲清楚，包括踩过的坑和最后的解决方案，给准备做多Agent编排的朋友一个可以直接抄作业的参考。

1. 项目背景：从单Agent到主从模式的必然选择

1.1 单Agent结构的天花板

PIG项目早期就是典型的单Agent结构：一个大模型实例，塞进系统提示词、工具列表、历史对话，让它在一次会话里完成所有事情。简单场景下这个方案够用，但一旦任务复杂到需要多步推理、外部工具协作、阶段性验证，问题就全冒出来了。

最直观的问题是上下文窗口。你让Agent先调研、再写方案、再执行、再复盘，这些中间产物全堆在主上下文里，很快就把Token吃光。更恶心的是，模型在处理超长上下文的时候会"遗忘"早期信息，尤其在中间步骤出错需要回退重试的时候，状态一乱，整个任务就废了。

另一个问题是职责混乱。单Agent里，工具调用、结果判断、下一步规划都是同一个模型在干，逻辑耦合严重。我举个例子你就明白了：Agent调用一个搜索工具，返回结果不满意，它到底是该换个关键词再搜一次，还是直接放弃搜索转去写文档？这个决策在单Agent里完全靠模型"临场发挥"，缺乏结构性约束，结果就是行为不可控。

PIG项目真正下定决心改架构，是因为一次压力测试：我们给单Agent塞了一个需要串联5个工具、跨3个阶段的任务，结果它在一个死胡同里反复重试了7次，浪费了几万Token，最后输出还是错的。那次之后我们就明确了，必须做分层编排。

1.2 从单体编排到分层编排的转变

多Agent的设计模式里，主从模式（也叫Supervisor模式、Master-Slave模式）是最基础也最实用的一种。核心思想很简单：一个主管Agent负责拆解任务、分配任务、汇总结果，多个子Agent各自负责一个细分领域，互不干扰，最终由主管整合输出。

你可能会问，这跟传统的函数调用有什么本质区别？区别在于：每个Agent都有自己的模型上下文、自己的工具集、自己的任务边界，它们是"有状态的工作单元"，而不是无状态的函数。主管Agent不关心子Agent内部怎么实现，只关心输入输出是否符合约定，这就形成了一个天然的解耦层。

实际落地中，最开始我们也走了弯路。第一版实现里，主管Agent直接调用子Agent的"内部方法"，比如让子Agent暴露一个do_research()函数、一个write_report()函数，结果子Agent的内部逻辑一变，主管的调用逻辑就得跟着改，耦合得一塌糊涂。

后来又试过"完全独立"的模式：每个子Agent自己启动一个完整会话，跑完把结果写到一个共享文件里，主管再去读。但这个方案更难搞——子Agent之间的状态没法联动，主管对子Agent的执行过程完全不可见，出了问题都不知道该找谁。

这两种弯路走出来，方向就清晰了：用工具的抽象来包装子Agent的调用，让它们像工具一样"即插即用"。

2. 核心思路：把subagent当作另类tool调用

2.1 为什么subagent可以当作tool

在主从模式里，主管Agent和子Agent的交互方式，本质上符合工具调用的全部特征：

• 有明确的输入输出协议——输入是任务描述，输出是执行结果
• 有边界隔离——主管不关心子Agent内部执行细节
• 有错误传播机制——子Agent失败需要以某种方式通知主管
• 有资源和权限控制——子Agent能调什么工具、能访问什么数据，是可以被约束的

所以，与其把subagent当成一个"会思考的对话者"，不如把它当成一个"拥有更强能力的工具"。这不仅仅是叫法上的差别，而是把问题从一个"多Agent协作"的问题，转化成了一个"工具编排"的问题，后者在工程上已经有了成熟的经验。

我在PIG项目里的实际做法，就是给每个子Agent写一个描述文件，说明它能干什么、需要什么参数、返回什么结果，然后注册到主管Agent的工具列表里。主管Agent在做任务规划时，把"调用某个子Agent"当成一次普通的工具调用，只是这个"工具"的参数更复杂，执行时间更长，返回结果更结构化。

这里还引出一个有意思的推论：既然subagent可以当作tool，那么tool也可以当作一种"极简subagent"。有些复杂工具本身就需要多步处理、状态保持，比如一个需要先初始化再执行再收尾的数据处理工具链，用subagent包装反而更清晰。这两者在PIG里是统一建模的。

2.2 统一调用协议的设计

把subagent当作tool，第一步就是定义统一的调用协议。我在PIG里参考了OpenAI Function Calling的格式，做了一点扩展。

一个普通的工具调用是这样：

json复制{
  "tool_name": "web_search",
  "arguments": {
    "query": "设计模式 主从模式",
    "limit": 10
  }
}

而一个subagent调用是这样：

json复制{
  "tool_name": "research_agent",
  "arguments": {
    "task": "调研当前主流的多Agent编排方案",
    "context": {
      "constraints": "重点关注主从模式的实现细节",
      "deadline": "2024-06-30"
    },
    "max_steps": 10
  }
}

关键的区别在max_steps和context这两个字段。max_steps限制子Agent内部最多执行多少步，防止它跑飞；context用来传入主管侧的一些约束信息，相当于给子Agent的"任务简报"。

这样就实现了主管Agent与子Agent之间的解耦：子Agent可以随便换模型、换内部提示词、换工具集，只要满足"输入任务描述、输出结构化结果"的约定就行。

2.3 上下文隔离与数据传递

主从模式最容易出问题的地方，就是上下文管理。我见过很多项目，主管Agent调用子Agent的时候，直接把整个对话历史传过去，让子Agent"基于上文继续"，结果子Agent被无关信息干扰，输出质量一塌糊涂。

PIG里采用的原则是：上下文最小化。主管Agent只把与任务直接相关的信息传给子Agent，子Agent返回的也只是一份结构化的结果摘要，而不是完整的过程记录。主管Agent需要保留的是"全局视角"，子Agent需要保留的是"领域深度"，两者不需要全部共享。

数据传递上，我们定义了统一的Result结构体：

json复制{
  "status": "success",
  "summary": "已完成调研，发现3种主流方案...",
  "data": {
    "key_findings": ["..."],
    "recommendations": ["..."]
  },
  "artifacts": ["file:///data/research_report.md"],
  "errors": []
}

这里artifacts字段很关键，它让子Agent可以"产出物外置"——比如生成一个完整报告文件、一段代码、一张图表，这些大块内容不占主管上下文，需要的时候再按路径读取。这样既能传递丰富结果，又不至于被大段内容撑爆上下文。

3. 主从模式架构落地方案

3.1 总体架构与模块划分

PIG的主从模式架构，核心分四层：入口层、主管层、子代理层、工具层。

入口层负责接收用户请求，做一些基础的前置处理，比如意图分类、任务复杂度评估。如果任务简单，就直接走单Agent快速通道；如果任务复杂，才进入主从编排流程。这个前置判断很重要，能避免"杀鸡用牛刀"，省下大量Token开销。

主管层是核心调度单元，负责把复杂任务拆解成子任务、按依赖关系排序、分发给对应的子Agent，然后收集结果、整合汇总。主管层不执行具体业务，它只做管理和决策。

子代理层是具体的执行单元，每个子Agent绑定一个专属的任务类型和工具集。比如PIG里有一个资料调研Agent、一个数据清洗Agent、一个报告生成Agent，各管一摊，互不重叠。

工具层是底层资源，子Agent内部调用的搜索、数据库、文件系统等能力。工具层也可能被主管Agent直接调用，比如一些简单的、不需要子Agent的轻量操作。

这里有个经验：子Agent和工具的参数命名规范要统一。PIG里所有参数都用snake_case，所有时间字段用ISO8601格式，所有路径统一用相对路径加根目录前缀。表面上是小事，实际做起来很重要——因为Agent生成的参数经常有格式漂移，规范越严，后续解析越省心。

3.2 主管Agent的状态机与调度逻辑

主管Agent本质上是一个状态机。我们为它定义了五个状态：规划中、调度中、等待子任务、收集中、完成/失败。

规划阶段，主管把任务拆解成DAG（有向无环图），每个节点是一个子任务，节点之间的边是依赖关系。这里最有挑战的是"拆解到什么粒度"。拆得太粗，子Agent内部逻辑太复杂，又回到单Agent的老路；拆得太细，调度开销太大，子Agent之间的通信成本可能超过省下来的推理成本。

我的经验是：一个子任务的执行步骤控制在3~10步之间比较合适。低于3步说明拆得太碎，高于10步说明子Agent承担了太多职责，需要再拆。这个数字不是拍脑袋定的，我们实测过：超过10步后，子Agent的"注意力漂移"概率会明显上升。

调度阶段，主管从当前可执行节点（所有依赖都满足的节点）中选一个，根据任务类型分发给对应的子Agent。这里有一个并发度的控制问题，后面实操篇会细说。

收尾阶段，所有子任务完成后，主管把所有子Agent的summary拼起来，再根据全局目标做最终整合。这个整合步骤不能省，有些项目图省事让主管直接输出子Agent结果拼接，结果就是结构散乱、没有全局逻辑。

3.3 子Agent注册与发现机制

我们把子Agent做成了可注册、可发现的模式。每个子Agent启动时向注册中心上报自己的元信息：

python复制{
    "agent_name": "data_cleaner",
    "description": "对结构化数据进行清洗、去重、格式规范",
    "input_schema": {
        "type": "object",
        "properties": {
            "data_path": {"type": "string"},
            "rules": {"type": "array"}
        }
    },
    "output_schema": {
        "type": "object",
        "properties": {
            "cleaned_path": {"type": "string"},
            "stats": {"type": "object"}
        }
    },
    "tags": ["data", "processing"]
}

主管Agent在规划时，会先拉取一份注册列表，然后根据任务的语义描述匹配最合适的子Agent。匹配逻辑一开始是纯规则匹配（基于关键词），后来升级成了embedding向量匹配，准确率高了不少。

注册机制还解决了两个实际问题。第一是动态扩容：需要新增能力时，不用改主管代码，只要新注册一个子Agent就行。第二是灰度发布：可以把同一个任务类型注册两个版本的子Agent，按比例分配流量，测试新版本的表现。我们后来甚至用这个机制做了"模型投票"——同一个任务分给两个不同模型的子Agent，对比结果取优。

4. 实操过程与核心代码实现

4.1 Agent接口与调度器基础实现

先看主管Agent的提示词设计。这是主从模式里最容易被低估的环节。PIG的V1版本主管提示词写得特别详细，恨不得把子Agent的职责全部写进去，结果主管对子Agent"指手画脚"，反而干扰了子Agent的自主性。

后来我们简化了主管提示词，核心就三段：第一段说明它的身份是"任务协调者"；第二段列出它可用的子Agent清单及其能力摘要（直接来自注册中心）；第三段规定它收到任务后必须遵守的流程——先拆解、再调度、后汇总。

简化后的主管提示词：

text复制你是PIG系统的任务主管。你的职责是：
1. 分析用户任务，拆解为可并行或串行执行的子任务
2. 为每个子任务选择合适的子Agent或工具
3. 汇总子Agent返回的结果，形成最终交付

你可以调用的子Agent：
- research_agent: 资料调研，返回结构化发现
- data_cleaner: 数据清洗与格式规范化
- report_generator: 生成最终报告

要求：先做规划，再逐步执行。每个子Agent调用后，检查返回状态。如果有子Agent失败，分析原因并决定重试或调整方案。

调度器是主管层的核心代码，我们基于asyncio实现了一个轻量级调度模块：

python复制import asyncio
import json
from typing import Dict, List, Optional


class AgentScheduler:
    def __init__(self, registry):
        self.registry = registry  # 子Agent注册中心
        self._semaphore = asyncio.Semaphore(3)  # 并发度限制

    async def execute_task(self, task: Dict) -> Dict:
        """
        执行一个子任务，内部负责调用具体的子Agent或工具
        task格式: {"type": "research", "params": {...}, "deps": []}
        """
        async with self._semaphore:
            agent = self.registry.match(task["type"])
            if agent is None:
                return {
                    "status": "failed",
                    "error": f"no agent matched for task type: {task['type']}"
                }
            # 统一通过call_agent调用
            result = await self.call_agent(agent, task["params"])
            return result

    async def run_pipeline(self, tasks: List[Dict]) -> List[Dict]:
        """
        执行一批可并行的子任务
        tasks是一组没有依赖关系的任务节点
        """
        results = await asyncio.gather(
            *(self.execute_task(t) for t in tasks),
            return_exceptions=True
        )
        # 统一处理异常，转成结构化错误
        for task, res in zip(tasks, results):
            if isinstance(res, Exception):
                res = {
                    "status": "failed",
                    "error": f"{type(res).__name__}: {str(res)}"
                }
            task["result"] = res
        return tasks

scheduler本身不做重试，重试逻辑放到了主管的决策层，让主管模型根据失败原因决定是重试、换方案还是放弃。这一点是有意设计的——让"是否重试"成为一个可被观察和控制的决策，而不是藏在框架里不可见的机械行为。

4.2 子Agent的调用封装与tool化实现

子Agent的调用封装是整篇文章的关键。先说我们踩过的坑：V1版本里，子Agent调用直接走LLMClient.chat()，相当于主管让子Agent"自由发挥"，子Agent内部步骤、工具调用全都没有约束。结果就是：子Agent的输出格式千奇百怪，有的给我纯文本，有的给Markdown，有的给JSON还带多余的注释。

后来我们给子Agent套了一层"AgentRunner"，把调用封装成标准流程：

python复制class AgentRunner:
    """
    把子Agent封装成工具调用
    所有子Agent共享这个Runner，通过配置区分行为
    """

    def __init__(self, config: Dict):
        self.agent_name = config["name"]
        self.system_prompt = config["system_prompt"]
        self.available_tools = config["available_tools"]
        self.max_steps = config.get("max_steps", 8)
        self.llm = config.get("llm_client")
        self.output_parser = config.get("output_parser", JSONParser())

    async def call(self, task_description: str, context: Optional[Dict] = None) -> Dict:
        """
        子Agent的统一调用入口，相当于tool的execute方法
        """
        messages = [
            {"role": "system", "content": self.system_prompt},
            {"role": "user", "content": task_description}
        ]
        if context:
            messages.append({"role": "user", "content": f"附加约束：{json.dumps(context)}"})

        step_count = 0
        while step_count < self.max_steps:
            step_count += 1

            response = await self.llm.chat(
                messages=messages,
                tools=self.available_tools
            )

            # 如果模型想调用工具，执行工具并把结果附加到对话
            if response.tool_calls:
                messages.append(response.message)
                for tc in response.tool_calls:
                    tool_result = await self.execute_tool(tc)
                    messages.append({
                        "role": "tool",
                        "tool_call_id": tc.id,
                        "content": json.dumps(tool_result, ensure_ascii=False)
                    })
            else:
                # 模型认为任务完成了，解析最终输出
                return self._finalize(response.content)

            # 检查是否进入死循环（连续调用同一工具超过N次）
            if self._detect_loop(messages):
                return {
                    "status": "failed",
                    "error": "agent loop detected, aborted",
                    "steps": step_count
                }

        # 超步数限制
        return {
            "status": "failed",
            "error": f"max steps exceeded ({self.max_steps})",
            "messages": messages[-5:]  # 返回最近的上下文，方便排查
        }

    async def execute_tool(self, tool_call):
        """子Agent内部执行工具，具体工具实现略"""
        tool_name = tool_call.function.name
        args = json.loads(tool_call.function.arguments)
        tool = self.tool_map.get(tool_name)
        if tool is None:
            return {"error": f"unknown tool: {tool_name}"}
        try:
            return await tool.execute(args)
        except Exception as e:
            return {"error": f"tool failed: {str(e)}"}

这样封装之后，所有子Agent行为都被约束在"系统提示词 + 可用工具 + 最大步数"这三个维度里。主管调用子Agent时，唯一的入口就是call()方法，返回值是标准化的Dict，不再需要关心子Agent内部的模型厂商、提示词版本、工具实现等细节。

这里面有一个我觉得特别重要的设计：把"循环检测"做进了Runner。我不止一次遇到子Agent在同一个工具调用上反复横跳的情况——它可能连续5次用稍微不同的参数调同一个搜索接口，这通常说明它陷入了混乱。我们的循环检测阈值是3次相同工具的连续调用，一旦触发就强制终止，返回失败。

4.3 DAG任务拆解与编排策略

DAG拆解是整个主从模式里最"软"的部分，因为这需要LLM的理解能力。我们在PIG里采取的方案是：拆解结论由模型给出，但拆解结果的合法性由代码校验。

主管Agent的规划输出格式：

json复制{
  "plan": [
    {
      "task_id": "t1",
      "type": "research",
      "params": {"topic": "多Agent编排方案对比", "sources": ["arxiv", "github"]},
      "deps": []
    },
    {
      "task_id": "t2",
      "type": "data_cleaner",
      "params": {"data_path": "upload/raw_data.csv"},
      "deps": []
    },
    {
      "task_id": "t3",
      "type": "report_generator",
      "params": {"template": "research_report"},
      "deps": ["t1", "t2"]
    }
  ]
}

收到规划后，先做合法性校验：

python复制def validate_plan(plan: List[Dict]) -> bool:
    """
    校验DAG合法性：
    1. 必须有任务
    2. 依赖的task_id必须存在
    3. 不能有循环依赖
    4. 不能有孤立节点（没有产出、也没有被依赖）
    """
    task_ids = set()
    for t in plan:
        tid = t.get("task_id")
        if not tid or tid in task_ids:
            return False
        task_ids.add(tid)

    # 构建依赖图，检测环
    graph = {t["task_id"]: t.get("deps", []) for t in plan}
    visited = set()
    recursion_stack = set()

    def dfs(node):
        if node in recursion_stack:
            return False
        if node in visited:
            return True
        visited.add(node)
        recursion_stack.add(node)
        for dep in graph.get(node, []):
            if dep not in graph:
                return False
            if not dfs(dep):
                return False
        recursion_stack.remove(node)
        return True

    for tid in task_ids:
        if not dfs(tid):
            return False

    return True

校验通过后，按"可并行优先"的拓扑排序执行：没有依赖的先跑，依赖满足的随时补充调度。一个常见的优化是"关键路径识别"——如果主管知道哪条链路最长，可以优先调度链路上的任务，减少整体等待时间。这个优化在我们实测中能把总耗时降低20%左右，效果很可观。

4.4 错误处理与重试机制

主从模式里的错误处理，比单Agent要复杂得多。因为错误来源多了好几层：主管层的规划错误、子Agent内部执行错误、工具调用错误、输出解析错误，每一层都需要不同的处理策略。

PIG的V2版本引入了错误分类：

"可替代"这一类最考验主管Agent的能力。举个实际例子：PIG里有个"摘要生成"子Agent，用的模型A不太稳定，偶尔返回空内容。最开始我们简单重试，后来发现重试3次还是空。改进方案是让主管在发现model A失败后，尝试用另一个轻量模型B生成摘要，同时把原始文本分段处理降低复杂度。结果成功率从82%提升到了97%。

错误传播的路径也需要注意：子Agent内部的错误，不能直接透出给用户，而是要先汇总到主管层，由主管决定下一轮行动。如果主管是智能体（LLM），它最好能看到"子Agent为什么失败"的原因，而不仅仅是失败状态码。这个原因可以做进错误信息里，比如：

json复制{
  "status": "failed",
  "error": "research_agent exceeded max_steps",
  "agent_debug_info": {
    "steps": 10,
    "last_action": "web_search(query='design patterns master slave')",
    "tool_results": "..."
  }
}

重试的退避策略也别偷懒，直接写死重试3次是最省事但对LLM API不友好的做法。我们用的是：第一次失败等1秒，第二次等3秒，第三次等9秒。实测能有效避开限流窗口。

5. 实战中的坑与排查技巧

5.1 上下文污染的坑

主从模式里最常见的问题是上下文污染。主管Agent在调度多个子Agent时，如果处理不当，子Agent A的中间输出会留在主管上下文里，干扰后续的规划判断。

举一个真实案例：PIG的一个任务需要先调研、后生成报告。调研Agent返回了一大堆参考文献，主管把这些原始文献直接粘进了自己的开发历史，然后让报告Agent开始生成。结果报告Agent基于这些片段发挥，生成了一份引用错误、结构混乱的报告——因为它看到的不是结构化的调研结论，而是零散的原始素材。

解决方案就是我们前面提到的两件事：第一，子Agent返回必定经过summary压缩，主管侧只保留精简摘要；第二，主管在每次子任务完成后，把该任务的详细结果移到"已完成区"，从"待处理区"移除，这样Agent的注意力焦点始终保持在当前待办上。

另外还有一个容易被忽略的坑：LLM的上下文有"中间遗忘"效应，开头和结尾的信息权重最高。如果主管上下文中塞了太多中间步骤的历史记录，它很容易忘记最开始的目标。所以我们在主管提示词里加了一个"任务目标速览"字段，并定期在关键节点重新注入原始任务描述，提醒模型别跑偏。

5.2 循环调用与死锁排查

多Agent系统里，循环调用是最让开发者头疼的问题。PIG早期版本里出现过一次事故：调研Agent为了搞清楚"某个概念的定义"，调用了"文档查询Agent"，文档查询Agent觉得自己信息不足，又调用了"资料调研Agent"——恰好调研Agent就是它自己。两个Agent互相踢皮球，直到触发了最大调用深度才停下来，白白烧了几万Token。

排查这类问题，必须要做调用链路追踪。我们在每个子Agent调用时生成一个trace_id，记录完整的调用链：

text复制supervisor(plan) -> research_agent(task="查询XX概念")
  -> doc_query_agent(task="查找XX章节")
    -> research_agent(task="查询XX概念")  # 死循环检测点

检测到重复的(agent_name, task_key)组合出现两次以上，就终止调用并告警。task_key是任务描述的一个哈希，用来判断任务内容是否重复。

另外，在提示词层面也加了一层约束：明确告诉子Agent"如果你发现自己正在重复执行某个已完成的任务，立即终止并报告失败，而不是尝试循环调用其他Agent"。这是提示词层面的软约束，不能完全依赖，但能在大多数情况下避免无意义的循环。

5.3 上下文窗口与Token成本控制

主从模式虽然解决了单Agent的上下文膨胀问题，但代价是Token总消耗量上升了——多个Agent各自维持独立的上下文。所以在实际应用中，Token成本控制是必须要做的。

我们的成本优化策略大致分五档：

1. 任务分级：简单任务直接单Agent处理，不启主从流程。我们在入口层加了一个复杂度预估器，基于任务长度、涉及工具数、行业领域给出0~1的复杂度评分，超过阈值才走主从。
2. 摘要压缩：子Agent返回结果统一经过"摘要模型"压缩成一段200字以内的summary，再传给主管。摘要模型用轻量级小模型，成本很低。
3. 缓存复用：同类型的子任务如果输入相似，直接命中缓存返回历史结果。比如"查询XX行业政策"这种调研任务，在一周内有很高的重复率。
4. 模型分级：主管Agent用推理能力强的模型，子Agent内部的具体执行可以用相对便宜的模型，但如果任务要写代码或者做数学推理，子Agent也要用强模型。这个分级要按任务类型配置，不能一刀切。
5. 自动收敛：子Agent任务完成判断不能只看模型"觉得完成了"，还要校验输出是否满足schema要求，避免模型提前结束导致返工重跑。

这五档策略叠加下来，我们在保持同样输出质量的前提下，Token成本比无脑全用大模型的主从模式降了50%左右，效果非常明显。

5.4 可观测性设计：保姆级日志与追踪

多Agent系统的排查，最大的痛点是"不可见"：多个Agent各自独立思考，出了问题你根本不知道是哪个环节跑偏了。所以可观测性设计必须从一开始就做，不是可选项。

我们给PIG加的追踪数据，核心是三类：

第一类是计划与决策日志：记录主管每一次拆解、每一次选择子Agent的理由。日志里带上了"候选方案列表"，能看到主管是在哪几个选项中选了这个。

第二类是子Agent执行轨迹：包括模型每轮的输入Token数、输出Token数、工具调用序列及其结果。这些数据量比较大，我们用了采样策略，正常任务只存摘要，失败任务全量存储。

第三类是质量指标：比如每个子Agent的返回值解析失败率、工具调用成功率、平均步数。这些指标可以按Agent维度聚合，方便判断哪个子Agent的提示词需要优化。

排查问题的时候，这三类数据配合trace_id串联起来，基本能还原整个决策链路。有一次线上报告Agent生成了错误表格，我们通过轨迹发现是它内部调用了过期的数据清洗工具版本。定位到具体工具版本号之后，5分钟就找到了根因。

6. 从PIG实践到你的项目：落地方案与演进建议

说了这么多PIG的实现细节，最后聊一下这套东西怎么迁移到其他项目里，以及未来可以怎么演进。

如果是从零开始做多Agent编排，我建议按三步走。第一步，先用单Agent跑通业务逻辑，明确哪些环节是真瓶颈——是上下文不够、是频繁出错、还是响应太慢。第二步，选1~2个最痛的环节拆成子Agent，验证主从模式的收益。第三步，把调度器、注册中心、追踪体系逐步补齐，形成一个完整的编排框架。千万不要一上来就搞一个五Agent大矩阵，排障成本会让你怀疑人生。

Agent的模型配置不要一刀切。我们做了一个配置表，按任务类型指定模型、温度、步数上限、工具集，这样既方便调优，也方便切换不同的模型供应商。配置表用YAML维护，改动不用重启服务，实时生效。

PIG的主从模式后续还衍生出了几个变体，值得提一下。一个是"议会模式"：多个子Agent各出方案，主管不直接决定，而是让所有Agent对方案投票，多数胜出。适合高风险决策场景。另一个是"团队复制模式"：同一组Agent跑多份，各自独立执行后比较结果，选出最优。适合对准确性要求极高、成本不那么敏感的任务。

但无论变体怎么演进，底层的思维始终是一样的：Agent之间的协作不是靠自由的自然语言对话，而是靠结构化的协议和边界约束。把subagent当作tool，本质上就是让Agent之间的交互变得更加可预期、可调试、可复用。这个思想，比任何具体的代码实现都更有价值。