Agent Teams协作配置：用共享任务队列让多个代理分工干活
多个 Agent 一起干活，最容易出问题的地方往往不是模型能力，而是任务没人认领、状态互相覆盖、失败后没人接手。
Agent Teams 协作配置的核心，就是先把任务分配和状态记录放到一个共享位置，再让每个代理按固定规则领取和回写。
下面用共享任务队列（一个目录里放任务文件）加代理轮询的方式，说明一套可以直接落地的配置过程。
先定协作边界，再动手配
开始之前需要明确三件事，否则后面越配越乱。
- 任务粒度：每个任务文件只做一件可验证的事，比如“抓取某页面并保存正文”，不要写成“完成整站分析”。
- 状态字段：至少包含
status（pending、running、done、failed）和owner（领取任务的代理标识）。 - 交接方式：代理只修改自己领取的任务文件，不直接改别人的文件；失败时写清错误信息，留给其他代理或人工处理。
环境上只需要一台能运行 Python 3 的机器，所有代理能读写同一个目录即可。
如果代理分布在不同机器，需要把这个目录做成共享存储（如 NFS），并确保文件锁可用；
否则并发领取任务时会出现重复执行。
共享任务队列的目录与文件格式
在共享目录下建两个子目录：tasks/ 放待处理任务，done/ 放已完成任务。
每个任务是一个 JSON 文件，例如 tasks/task-001.json：
{
"id": "task-001",
"title": "抓取示例页面正文",
"status": "pending",
"owner": "",
"input": "https://example.org/page",
"result": "",
"error": ""
}字段含义要固定下来：status 初始为 pending，代理领取后改为 running 并写入 owner，完成后改为 done 并把结果写入 result，出错则改为 failed 并写入 error。
所有代理都按同一套字段读写，避免各自解释。
代理轮询与安全领取任务
每个代理启动后循环扫描 tasks/ 下状态为 pending 的文件。
关键是领取动作要安全，不能两个代理同时改同一个文件。
下面是一个最小示例，用文件锁保证同一时刻只有一个代理能领取：
import json, os, glob, fcntl
TASKS = "/shared/tasks"
DONE = "/shared/done"
def claim_task(agent_id):
for path in sorted(glob.glob(os.path.join(TASKS, "*.json"))):
with open(path, "r+") as f:
fcntl.flock(f, fcntl.LOCK_EX)
task = json.load(f)
if task["status"] != "pending":
fcntl.flock(f, fcntl.LOCK_UN)
continue
task["status"] = "running"
task["owner"] = agent_id
f.seek(0)
json.dump(task, f, ensure_ascii=False)
f.truncate()
fcntl.flock(f, fcntl.LOCK_UN)
return path, task
return None, None领取成功后，代理执行具体逻辑，再把文件移动到 done/ 并更新状态。
移动前要重新加锁，防止其他代理读到中间状态。
如果代理执行时间较长，建议在 running 状态下增加 updated_at 字段，方便人工判断是否卡住。
并发和失败场景要提前处理
共享队列方案简单，但有几个坑需要提前避开：
- 重复领取：如果共享目录不支持文件锁（例如某些对象存储挂载），文件锁会失效。此时应改用带原子操作的队列服务，或者用“创建锁文件”的方式模拟互斥。
- 代理崩溃：代理领取任务后崩溃，任务会一直停在
running。可以约定超时规则，由调度方把超过一定时间未更新的任务重置为pending。 - 结果覆盖：多个代理写同一个结果文件会互相覆盖。要求每个任务的结果只写回自己的文件，最终汇总由单独的步骤完成。
- 路径不一致：不同机器上共享目录的挂载路径必须一致，否则代理找不到任务。建议在配置里统一写绝对路径。
验证协作是否真的生效
配置完成后，用一个最小场景验证：创建 3 个任务文件，启动 2 个代理，观察是否出现重复执行或任务遗漏。
检查点包括：
- 每个任务最终只被一个代理领取，
owner字段唯一； - 所有任务最终进入
done/，status为done； - 人为让一个代理处理失败的任务，确认任务变为
failed且error有内容； - 查看日志中是否有代理反复扫描同一文件却无法领取的情况，若有则检查文件锁是否生效。
如果代理需要跨机器协作，还要额外确认共享目录的读写权限和锁支持。
纯本地多进程场景下，上面的文件锁方式通常够用；
跨主机时建议先做一次并发领取测试，再投入实际任务。
常见疑问
Agent Teams 协作一定要用消息队列吗？
不一定。任务量小、代理数量少时，共享目录加文件锁就能跑通。消息队列适合任务量大、需要重试和监控的场景，但配置成本更高。
代理之间需要直接通信吗？
大多数分工场景不需要。通过任务文件交换状态，代理之间保持解耦，反而更容易排查问题。只有需要实时协商时才考虑代理间直接通信。
任务状态字段可以自定义吗？
可以，但所有代理必须使用同一套定义。建议把状态流转规则写进配置文档，新增状态时同步更新所有代理的读取逻辑。
Agent Teams 协作配置的难点不在写多少代码，而在于把任务边界、状态规则和失败处理定清楚。
先用小规模任务验证领取和回写是否正常，再逐步增加代理数量，比一开始就铺开更稳妥。
