基础篇
进阶篇
高频篇
精选篇
手写篇
面经篇
AI 篇
原理篇
每日一题
小程序题库
  • 知识卡片碎片时间过考点
  • 场景篇按分类整理的大前端场景考点
  • 历年面经按年份追踪真实考点
  • 算法题库NEW在线编码即时判题
  • 专项自测100 题快速查漏
  • 前端基础
    • HTTP从报文一路讲到 HTTPS
    • 浏览器渲染、事件循环、进程
    • 计算机基础Linux、网络、操作系统
  • 进阶专项
    • 设计模式23 种模式怎么用
    • 前端系统进阶学习大型项目工程化
    • 前端综合文章长期沉淀的实践文
  • 工程与工具
    • Node学习指南从环境搭建到服务端
    • NPM工作流script、依赖与发布
    • Docker容器化部署上手
    • Canvas图形与动画实战
  • 路线与导图
    • 思维导图知识点全景图
    • 学习路线按图索骥不跑偏
  • 动态
    • 公众号动态公众号历史文章
    • 博客动态站长的技术博客
    • 开发者导航常用工具与文档站
    • AI 热点每日 AI 资讯与动向
AI 工作台
旧版
AIHT
内容
精选全部 AI 动态热点榜AI 日报收藏
分类
模型行业编程产品技术观点开源
更多
Agent 接入
返回首页开发者导航
AIHT
精选 / 资讯详情
8.0
热点
AI SCORE
技术实践2026-11-22 20:25

用纯 Python 搭建智能体通信闭环

dev.to · AI#Agent#Python#Webhook
Editor brief · 编辑速览

教程使用 Python 标准库实现智能体搜索、结构化消息与签名 Webhook,并提供完整代码和测试。模型接口兼容 OpenAI 格式,通信机制可迁移到支持对应协议的其他网络。

文章思维导图
Knowledge map
拖拽缩放
AI deep read

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 排除出版本控制。
Original source

本文由 AI 通读原文后重新编写,观点部分为站内判断,细节以原文为准,来源 dev.to · AI,原文版权归原作者所有。

阅读原文
上一篇
AI 供应链防泄漏:标记追踪与运行时清单
下一篇
编码智能体的审批规则需要防绕过测试

资讯速览

dev.to · AI · 2026-11-22 20:25

AI 评分 8.0 / 10

相关标签

#Agent#Python#Webhook

继续阅读

  • 用 Kiro 构建旧图像恢复工具,让规格约束实现
  • AI 供应链防泄漏:标记追踪与运行时清单
  • 编码智能体的审批规则需要防绕过测试
  • 用结构化交接减少智能体跨会话返工
  • 低价推理服务曝密钥窃取与请求窥探