用纯 Python 搭建智能体通信闭环
教程使用 Python 标准库实现智能体搜索、结构化消息与签名 Webhook,并提供完整代码和测试。模型接口兼容 OpenAI 格式,通信机制可迁移到支持对应协议的其他网络。
AI 深度解读
让两个 AI agent 找到彼此、交换任务并继续协作,难点不只在模型能不能理解需求,还在消息如何送达、何时调用模型、对话什么时候必须停。作者用一个仅依赖标准库、运行于 Python 3.10+ 的小程序,把这些环节串了起来。
这套教程最有用的部分,是把 agent 协作拆成可检查的程序规则:模型负责选动作,代码负责限制执行,网络负责发现、投递和过滤。不过,它在 LobsterMatch 上观察到的行为,与一般团队可以直接复用的设计,需要分开看。
先把循环跑通,再让 agent 上网
作者把 agent 定义成一个循环:接收输入,选择工具,观察结果,继续执行或等待。这里没有记忆系统、子 agent 或 TUI,文件也只有三个职责:agent.py 管循环和网络调用,cards.py 管消息卡片和冻结策略,webhook.py 管 HTTP 接收。
模型调用集中在 llm(),通过 OpenAI-compatible 的 /chat/completions 接口读取 choices[0].message.content。运行前必须配置 LLM_BASE_URL、LLM_MODEL;本地模型的 LLM_API_KEY 可以留空。python agent.py demo "List what you can do." 会立即调用模型,并非离线演示。
下面这段循环解决的是:让模型提出动作,同时由程序控制工具执行和停止条件。
def run(event, tools, decide=None, max_steps=4):
history = []
for _ in range(max_steps):
step = (decide or model_step)(event, history, tools)
name = step.get("tool")
if name not in tools:
return step.get("stop", f"unknown tool: {name}")
try:
obs = tools[name](**step.get("args", {}))
except (ToolError, CardError, TypeError) as e:
obs = {"error": str(e)}
history.append({"tool": name, "observation": obs})
if isinstance(obs, dict) and obs.get("stop"):
return obs["stop"]
return "max steps reached"
关键是 decide=None 和 max_steps=4:前者允许测试注入固定决策,不需要模型或网络;后者给单次执行设上限。工具异常会成为下一步观察,但模型输出解析失败并不在这段捕获范围内。
教程用提示词要求模型返回工具调用 JSON,再从文本中截取花括号解析,传入上下文取最后 8000 个字符。这是教学级实现:截取可能破坏 JSON,提示词也不能保证输出合法。它展示了循环如何工作,没有提供完整的输出容错方案。
找到协作者之后,先约定消息怎么说
测试网络是 LobsterMatch,入口为 https://lobstermatch.com/mcp。客户端向它发送 JSON-RPC tools/call,并使用自定义 User-Agent: build-your-own-agent/0.1,因为该网络拒绝默认 Python urllib 标识。
注册用 register_agent,搜索用带 q 参数的 search_agents,两者都不需要 LM_AUTH。注册资料应写真实能力,例如翻译短 README,而不是宽泛宣传。搜索最多展示 10 个结果,默认返回首个 id;无结果就退出,不持续重试,也不广播。
注册凭证只返回一次,程序写入创建权限为 0o600 的文件。LM_AUTH 应填顶层 agentId 与 credential.token,格式为 YOUR_AGENT_ID:YOUR_TOKEN,不能直接复制已经带 Bearer 的 credential.authorization。
真正发送任务要先调 open_dialog,读取 dialogId,再调 send_message。原文特意提醒:返回字段不是 id。
消息卡片有四种类型:request 提需求,answer 回答、澄清或交付部分工作,result 交付完成结果,close 结束会话。它们是该网络推荐的格式,并非强制 schema;示例客户端主动收紧约束:
task、deadline、expected_format分别最多 120、40、80 个字符。summary最多 280 个字符,body最多 2000 个字符。- 标签最多 8 个,每个最多 24 个字符;超限直接报错,不静默裁剪。
结构化消息的价值,是让程序可以判断对话状态,而不必每次都请模型阅读长段文字。
示例请求翻译一份 1200 词的 README,要求保留代码块和命令名称,期限为三天。卡片把任务、期限、交付格式拆开了,但没有自动证明对方能按时完成。发现能力与可信交付,仍是两回事。
Webhook 管唤醒,冻结规则管停下
轮询即使没收到消息,也可能触发检查。作者改用公开 HTTPS Webhook,让事件到达后再启动处理。webhook.py 默认监听 PORT=8080,前面需要反向代理,localhost 地址无法直接接收网络投递。
调用 set_webhook 首次成功会返回 signingSecret,并置 signingSecretIssued=true,应立即保存到 LM_SIGNING_SECRET。再次设置 URL 不会重复返回密钥;丢失后,需要先用空 url 清除,再重新设置。
验签必须使用收到的原始请求体:
def signature(secret, timestamp, raw_body):
mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256)
return "sha256=" + mac.hexdigest()
def verify(secret, timestamp, raw_body, sig): # 使用收到的原始请求体,不重新序列化 JSON
expected = signature(secret, timestamp, raw_body)
return bool(secret and timestamp and sig) and hmac.compare_digest(expected, sig) # 常量时间比较
要盯住 timestamp.encode() + b"." + raw_body:x-lobstermatch-timestamp 是秒级 Unix 时间,不能替换为 JSON 内带毫秒和 Z 的 ISO-8601 occurredAt。结果加上 sha256=,再与 x-lobstermatch-signature 作常量时间比较。
签名错误返回 401,不启动模型;JSON 无法解析返回 400;合法请求快速返回 200,再用后台线程处理。事件只有标识,没有消息正文,因此还要调用 read_dialog。处理器只继续处理带 dialogId 的 dialog.* 事件,并排除 dialog.close;卡片类型位于 message.card.type。
这里还有一组防止空转的规则。默认连续 6 轮没有 answer、result 或 close,会话就冻结,阈值可设为 2 到 24。第 6 条仍接收,但返回 frozen: true 和 summaryRequest;第 7 条普通消息被拒绝,错误为 dialog-frozen。收到冻结提示后,agent 只发送一条 type: answer 的单行摘要,然后停止。
限流也要停得下来。示例遇到 429、maxPerMinute 或 rate limit,最多尝试 3 次;退避基数 15 秒、上限 120 秒,按指数增长,耗尽后交还控制权。
网络还会过滤问候、被屏蔽发送者、不属于 acceptedTopics 的主题和低信誉发送者。它们进入低优先级队列,agent 不应期待被唤醒。同一发送者在 10 分钟内发送字段完全相同的消息,则返回 delivered: false、filterReasons: ["duplicate"],不入过滤队列,也不发 Webhook;任何字段变化都可能使它成为新消息。
我的判断
我认同作者先做本地循环,再接发现与消息网络的顺序。它把模型替换点、工具边界和可测试入口留得很清楚,比一开始就堆多个 agent 更容易定位失败原因。
但「更便宜」目前只是机制推断。原文没有轮询与 Webhook 的调用量、成本或延迟对照,也没有证明卡片能提升任务完成率。冻结计数中的 answer 可以只是澄清问题,因此计数重置不等于业务真的推进。
Webhook 验签能验证投递来源,不能证明消息内容可信。
示例只检查签名并用内存集合记录 eventId,没有检查时间戳新鲜度,也没有持久化去重或任务队列。快速返回 200 后,后台线程若失败或进程退出,怎样补偿,原文没有交代。用于演示足够,接正式业务还需要补上可靠接收与执行记录。
相比定时拉取,Webhook 适合低频、事件驱动的协作;但作者没有给出丢事件后的对账策略。相比自由文本,卡片便于校验和控制长度,却不能替代权限检查、交付验收或对外部内容的审查。
能拿来做什么
- 为日常 AI 编程助手先写一个最多执行 4 步的本地循环,用固定
decide测试工具失败、正常停止和达到上限,再接真实模型。 - 为 README 翻译或文档协作定义消息卡片,把任务、期限和预期格式分开校验,超限明确报错,让发送方修正输入。
- 在 Node 接收同类 Webhook 时保留原始请求体,先验签再解析,并将可靠入队、持久化去重作为正式部署前的补充。
- 为自动回复设置停止条件、有限退避和明确的进度类型;Webhook 跑通后停止轮询,同时把
.env、.lobstermatch-credential.json、.lobstermatch-webhook.json排除出版本控制。