最近整理代码仓库的时候，反复看到一个叫“agency-agents”的目录名。刚开始没太在意，直到有次跟某位做Agent框架的老朋友聊起多智能体系统设计，才意识到这个命名其实点破了一个很关键的问题：市面上的Agent项目大多在强调“agents”这个复数形态，但决定系统上限的往往是“agency”——也就是每个代理的自主行动能力。今天这篇文章，我想从项目标题的本意出发，结合我实际搭建和维护这类系统的经验，把代理设计、编排、落地中真正重要的东西拆开讲透。
如果你正准备入手AI Agent开发，或者已经在做但经常遇到“代理跑飞”“循环卡死”“多代理结果丢失”这类问题，这篇文章应该能帮你省下不少弯路。
1. 项目核心思路：为什么“agency”比“agents”更值得关注
1.1 从自动化到能动性的认知转变
我们通常聊到的Agent，绝大多数还停留在“自动化”的层面：给定输入，走固定流程，调用固定工具，输出结果。这种模式本质上是把原来写在代码里的业务逻辑换成了一个LLM来驱动，流程的可变性和适应性提升了，但系统本身并不具备“判断接下来该干什么”的能力。
我理解“agency”这个词在Agent系统里的含义，是代理在不确定环境中根据目标自主做出决策的能力。它意味着代理不仅会执行，还会选择执行什么、何时执行、如何纠偏。举个生活化的类比：电梯是自动化系统，按了楼层就运行，路线完全可预期；但电梯操作员拥有的就是agency，他会根据进出的人流判断该停哪层、该等多久、要不要提前关门。这两个层次之间，隔着一种“主动推理”的能力。
押注“agency-agents”这个方向的团队，本质上是在做一个判断：未来的Agent系统不只是执行单元的组合，而是一个由多名具备能动性的成员组成的协作网络。每个成员都有目标、有工具、有决策逻辑，并在必要时把问题拆解、分发、汇总。这个理念对系统设计的要求完全不同——你需要考虑的不再是“调用链”，而是“决策循环”。
1.2 项目要解决的核心痛点
我在实际使用和调研项目时，发现单纯把所有参数和工具塞给一个LLM，让它在一个长上下文里硬推理，会出现几个高频问题：
首先，代理会在复杂任务里“迷失”。任务一多，上下文一长，模型就容易遗忘最初的用户目标，开始自己编造子目标，越跑越偏。
其次，代理会陷入无效循环。一次工具调用失败后，代理不去分析失败原因，反而换个参数反复重试，直到步数耗尽。
再次，多代理协作时，信息传递经常出现断层。子代理返回的结果被父代理漏掉，或父代理只记住了摘要却丢了细节，导致最终答案不完整甚至错误。
agency-agents这类项目的思路，就是尝试解决这些根本性问题。它不追求把每个环节做得更花哨，而是通过合理的代理自主性边界、清晰的状态传递机制，以及严密的执行循环控制，让系统在复杂任务面前保持着稳定性和可控性。这非常接近我自己的工程观：先求稳，再求能。
2. 核心架构设计与决策拆解
2.1 代理执行循环的设计：感知-规划-行动-反思
一个具备现实可用性的代理，在内部跑的往往不是一个简单的“用户提问-模型回答”过程，而是一个循环。这个循环通常包含四个阶段：感知（Perceive）、规划（Plan）、行动（Act）、反思（Reflect）。
- 感知环节负责收集当前任务相关的所有信息，包括用户的原始意图、历史对话、工具返回结果和系统状态。
- 规划环节由LLM根据感知到的信息生成下一步动作计划。这里不同的项目会选择不同粒度的规划方式，有的偏向“一次生成整个任务计划”，有的则偏向“每次只决定下一步动作”。
- 行动环节根据规划执行具体操作，常见的操作是调用工具或向其他代理发送消息。
- 反思环节在执行完行动后，触发LLM对本次结果做一次自检，判断是否已达成目标，是否需要调整计划。
这个循环的最大价值，是让代理的行为具备了闭环调整的能力。没有反思环节，代理规划错了就一路错下去；没有感知环节，代理依赖的上下文信息就会缺失。
2.2 工具注册与调用接口的取舍
实现一个Agent系统，最先遇到的工程问题就是“如何让模型调用工具”。业界常见的做法是给模型提供一份工具清单，每个工具对应一个JSON Schema描述，模型根据输入决定是否调用某个工具，以及传什么参数。设计这个接口时有几个细节值得反复打磨：
工具描述需要足够精确。模型是靠描述来理解工具用途的，写得模糊就会导致选错工具。比如一个函数叫search_files，描述写成“搜索文件”就太笼统了，至少要明确是“按文件名关键字在项目内递归搜索，返回文件路径列表”。
参数校验必须前置。模型生成的参数并不是百分百合法。工具在执行前先跑一遍Pydantic校验，不合法的输入直接返回结构化错误，让代理自己去纠正，要比在工具内部抛异常更可控。
工具调用需要有超时和幂等设计。长耗时工具要设置超时上限，重试型工具（比如网络请求类）要考虑幂等性，防止重复调用产生副作用。
2.3 主从代理协作的消息传递模式
单代理能解决的问题域有限，一旦任务复杂度超过单代理的处理范围，就需要采用多代理协作。多代理协作里，最常见也最稳的是主从模式：一个主代理负责拆解任务、分发给子代理，再收集各子代理结果。
这个模式里最关键的是消息传递协议。我在实践中踩过最痛的坑是：父代理把任务发给子代理之后，子代理返回了详细的长文本结果，父代理因为上下文窗口限制，只保留了一个摘要，丢弃了原始内容。看似省了Token，但后续总结阶段需要细节时，信息已经丢失了。
更稳的作法是，子代理执行完成后，父代理接到的不仅是摘要，还有指向原始结果的关键引用（比如结构化文件路径或数据索引）。当父代理需要细节时，可以按引用去取回原文。这种“引用不搬移”的传递方式，在信息完整性和token消耗之间找到了平衡。
3. 实操：从零实现一个“agency-agents”风格的最小系统
3.1 环境准备与工程基础
在动手前先明确一下技术栈选型。我用的是Python 3.11版本，依赖管理走Poetry，LLM调用部分采用一个统一的接口封装层，这样无论底层模型怎么换，上层逻辑不用改。封装层我选用的是OpenAI兼容的客户端协议，因为目前主流的模型服务商都支持这个协议，切换成本最低。
依赖库里需要关注的有：用于参数校验的Pydantic、用于结构化输出的JsonSchema工具链、以及一个支持并发调用的HTTP客户端。异步并发在真实项目中几乎是刚需，因为代理之间往往是并行执行子任务的。
# pyproject.toml 关键依赖 typing_extensions >= 4.8 pydantic >= 2.5 httpx >= 0.25 dotenv >= 1.03.2 核心类设计：Agent、Tool、Memory
一个最小可运行的Agent系统，我通常会把它拆成三个核心类：Agent（代理主体）、Tool（工具抽象）、Memory（记忆容器）。
Agent类是核心，它拥有名称、角色描述、可用工具列表、记忆存储和一次可执行的最大步数。它的主要职责是跑完整个感知-规划-行动-反思的循环。
class Agent: def __init__(self, name, role, tools, memory, max_steps=10): self.name = name self.role = role self.tools = {tool.name: tool for tool in tools} self.memory = memory self.max_steps = max_steps async def run(self, task): self.memory.add("user", task) for step in range(self.max_steps): # 感知 context = self.memory.get_recent() # 规划+行动 action = await self._decide_next_action(context) if action["type"] == "finish": return action["output"] # 执行 result = await self._execute_action(action) # 反思 self.memory.add("assistant", f"执行结果: {result}")Tool类是代理与外部世界交互的桥梁。在最小系统里，一个工具就是一个函数和处理它元数据的容器。元数据里最重要的是声明输入输出的样子，这决定了大模型是否能正确理解并调用它。
class Tool: def __init__(self, name, description, input_schema, handler): self.name = name self.description = description self.input_schema = input_schema self.handler = handler async def execute(self, **kwargs): # 前置校验 validated = validate_input(kwargs, self.input_schema) if not validated.ok: return {"error": validated.errors} # 正式执行 try: return {"result": await self.handler(**validated.data)} except Exception as e: return {"error": str(e)}Memory类的设计要兼顾容量和引用。我用的方案是双缓冲：一块是结构化历史记录，保留最近N轮对话摘要；另一块是完整过程记录，存放到一个按会话ID组织的存储（可以是本地磁盘或向量库）。需要细节时再按ID拉取。
3.3 执行循环中的关键控制逻辑
执行循环里最容易被忽视但又最要命的，是循环检测和早停机制。没有这个机制，代理会在某个错误结果上反复打转，消耗大量token和时间。
我的实现里加入了两个控制项：重复动作检测和反思偏差阈值。重复动作检测是记录每一步动作的（工具名+参数哈希），如果同一动作出现多次且中间穿插的动作没有改变上下文，直接判定为循环，触发重规划或终止。反思偏差阈值则是在反思阶段让模型判断“当前结果与目标的偏差方向”，如果连续两次反思都是“接近目标但需要重试”，但实际结果指标并没有变化，也主动终止。
# 循环检测示例（简化） action_history = [] def is_repeating(action): signature = f"{action['tool']}:{hash_params(action['args'])}" recent = action_history[-3:] same_actions = recent.count(signature) return same_actions >= 2这个看似粗糙的检测逻辑，实际运行中拦截了大量的无效循环，比单纯依赖大模型“认识错误”可靠得多。
3.4 一个完整可运行的最小示例
为了让你快速理解整体流程，我给你写一个真实的简化场景：一个资料调研代理，用户要求它整理某技术主题的近期关键进展。
这个代理配备了三个工具：
- search_web(keywords)：模拟搜索接口，返回按时间倒序的标题列表
- fetch_page(url)：模拟抓取指定页面正文，返回摘要
- save_note(note)：把内容保存到本地笔记文件
主流程：代理先搜索关键词，然后根据搜索结果的标题判断哪几条值得抓取详情，抓取后提取关键信息，最后整理成一份结构化报告。
from dotenv import load_dotenv import asyncio, json load_dotenv() # 工具定义 async def search_web(keywords): # 这里实际会调用搜索API的具体实现逻辑 return json.dumps([ {"title": "标题A", "url": "https://example.com/a", "date": "2025-02-01"}, {"title": "标题B", "url": "https://example.com/b", "date": "2025-01-20"}, ]) # 初始化代理 research_agent = Agent( name="researcher", role="你是一名IT技术调研助理，负责收集和总结指定主题的最新进展。", tools=[ Tool(name="search_web", description="按关键词搜索网页，返回标题列表", input_schema={"type":"object","properties":{"keywords":{"type":"string"}}}, handler=search_web), # ... 其他工具 ], memory=Memory() ) # 启动 report = asyncio.run(research_agent.run("帮我调研AI智能体可观测性工具的最新发展")) print(report)跑这样一个最小系统，你很快就能体会到“agentic”和“脚本”的本质区别：脚本的每一步都是写死的，而代理会根据搜索结果的实际内容自主决定接下来抓取哪一页、保留哪些信息、忽略哪些噪音。
4. 常见故障与排查实录
这一节是纯实战内容。我把自己和团队成员在开发和试运行中反复踩过的坑梳理了一遍，挑了几个出现频率最高、影响最大的问题，附上排查方法和解决方案。
4.1 代理陷入重复循环
现象：代理反复调用同一个工具、传递几乎相同的参数，有时换一个相近参数又重试，直到步数耗尽。
排查思路：第一步，查看执行日志里的工具调用序列，确认循环的周期长度和触发条件。第二步，检查循环动作前后的memory变化，如果memory里没有增加新的关键信息，说明模型没有从结果里获得有效反馈。第三步，检查工具返回的错误信息是不是过于笼统，比如只返回“查询失败”而没有具体原因，模型无法据此做出调整。
解决方案我试过两种。一种是在系统prompt里强调“当某个行动没有产生新信息时，应当停止并报告障碍”，这个对提高模型识别力有帮助，但不够彻底。另一种是工程化兜底，也就是前面说的重复动作检测，一旦判定循环，强制触发一次“反思-重规划”动作，让模型写一段“为什么我在原地打转”和“下一步怎么调整”。两种结合后，循环问题基本控制在极低概率。
4.2 工具返回了错误但代理没有感知
现象：工具内部出异常，代理却返回了一个看起来正常、但实际内容空洞的结果。有的模型在拿到空结果时会“补全”一个虚构的答案，这最坑人。
排查思路：查看工具返回体的结构。如果工具返回是一个字符串，异常信息和正常结果混在一起，模型就很容易混淆。另一个高发场景是工具返回了极大的JSON，但模型在总结时把关键字段丢了。
解决方案：所有工具的返回都强制使用统一的封装结构，区分status字段（success/error）、data字段和error_message字段。代理在复盘阶段只关注data字段，遇到error字段则单独处理。同时，在prompt里明确要求：当最近一次动作返回error时，必须解释错误原因并提出改进方案，不得直接生成最终答案。
我曾经见过一个极端案例：网络工具因为超时返回了一个空列表，代理把空列表解读成“没有相关内容”，然后编造了一段看起来很有条理但实际上完全虚构的资料。统一返回结构之后，这类问题几乎绝迹了。
4.3 编排上下文爆掉或者信息衰减
现象：任务执行到一半，上下文窗口被塞满，系统强制截断；或者截断后代理忘记早期的关键要求，回答越来越偏。
排查思路：检查每次动作产生的token消耗。搜索、抓取页面这类工具返回的原始内容非常大，如果全部塞进memory里，很快就能把一个128K的上下文塞满。
解决方案：插入一个压缩节点。当memory容量达到阈值时，触发一次摘要压缩，将早期对话总结成一段带有指向原文引用的摘要，保留必要细节的同时释放空间。这里的“指向原文引用”就是前面提到的引用传递方式——摘要记录里保留类似“原始结果位于run_123/file_007.md”这样的指引，后续需要细节时可以按需加载，而不是把全文留在上下文中。
这一步优化后，我的代理系统从只能稳定处理10-15步的小任务，提升到可以稳定处理60-80步的中型调研任务。
4.4 多代理协作时结果丢失或错乱
现象：主代理派发多个子代理并行执行任务，返回结果时，要么某个子代理的结果迟迟等不到，要么子代理A的结果最终被记在子代理B的名下，最后汇总答案张冠李戴。
排查思路：查看消息队列的时序和每个子代理的完成回调。大多数情况下问题出在父代理等待结果的方式——如果父代理使用一个简单的事件循环去收集结果，而没有做结果归属校验，很容易出现错乱。
解决方案：为每个子任务分配一个唯一任务ID，子代理完成时直接回传任务ID和结果封装体。父代理只在任务ID匹配的情况下登记完成状态，并等待全部任务完成后再进入汇总阶段。同时给每个子代理设置独立超时，超过预期时间未返回的就标记为失败，由父代理决定是补发还是豁免。
这个机制看起来朴素，但在生产环境里非常可靠。我见过有些开源项目为了省事省略了这个ID绑定，最终在真实流量下暴露了严重的并发错乱。
5. 上线后的经验与调优建议
5.21 Token成本怎么控制
Agent系统跑起来，token消耗大得让人肉疼。我在一个中等规模的任务里做过统计，一次完整的任务（30步左右）大约消耗掉的输入token是输出token的好几倍，大头几乎全在把历史记录和回溯信息反复塞给模型。
控制成本有以下手段：一是记忆窗口限制，模型每次决策只拿最近若干轮的关键上下文，而不是全部历史；二是工具结果截断，抓取的网页正文最前面做显著摘要，模型需要完整内容时再单独获取；三是模型分级，全局规划用高能力模型，局部工具调用和文本整理可以用低能力模型，成本能大幅下降，性能损失却不大。
还有一个小技巧是延迟工具调用。有的代理系统习惯在每步都调用一次工具确认状态，但绝大多数任务的中间状态不需要实时感知。我后来把“主动检查状态”这类工具的调用改为“按需触发”，即在反思阶段发现信息不足时才调用，节省了接近一半的工具调用量。
5.2 代理可观察性的设计实践
调试一个多步代理，最难的不是看代码逻辑，而是观察模型内部在做什么、为什么这么决策。没有可观察性的代理系统基本没法维护。
我给每个代理运行的每个步骤都加了事件日志，内容包括：当前步骤号、感知到的上下文片段摘要、模型规划出的动作类型和参数、执行结果状态、反思结论文本。日志统一写入一个本地跟踪文件，格式尽量用结构化JSON，方便后续分析。
调试时最常用的操作是“重放”。把日志里记录的每一步感知上下文回放给模型，就能复现它在拿到某条信息时的所有决策过程。这个能力在排查“代理为什么会判断错误方向”时尤其有效。
5.3 从单代理到多代理的演进路线
不少项目一开始是单代理架构，随着任务复杂才逐步演进到多代理。这个演进过程要非常克制，不要一开始就设计几十个代理，否则系统复杂度和维护成本会迅速失控。
我的建议是从“主从分工”这种最简单模式开始：一个主代理负责理解需求，下面一两个专业子代理负责具体环节。确认这种模式跑通后，再根据真实任务流量里的瓶颈决定是否增加新的子代理类型或引入并行机制。每一步演进都保留回退点，确保新结构出现问题时可以快速恢复到上一版本。
我在多个项目里坚持这条路线，结论是：最好的多代理架构不是“设计”出来的，而是“生长”出来的。先让单一代理产生价值，再根据瓶颈一点点扩展，系统整体会稳定得多。
最后再分享一个经验
又回到“agency-agents”这个标题。这段时间反复琢磨下来，我愈发觉得项目起名的用意很深。构建Agent系统时，把精力过多放在“如何加入更多agents”往往是误区；真正值得投入的是打磨每个代理的agency——它的决策能力、纠偏能力和边界内自持能力。一个拥有高 agency 的单代理，远比十个只会机械执行的低 agency 代理更能够在真实任务里创造价值。
如果你也在做类似的项目，我的建议是：先花两周时间，把执行循环、工具返回结构、循环检测这三个基础点打磨扎实，不要急着追新框架。基础打的足够牢，后续无论代理数量怎么变，系统都能稳稳地跑住。这是我的切身体会。
