uAgents：把 Agent 注册进 Fetch.ai 链上 Almanac 的 Python 框架
A fast and lightweight framework for creating decentralized agents with ease.
秒懂
- 它是什么？
- uAgents 用装饰器定义定时任务与事件处理，启动时把 Agent 注册到 Fetch.ai 区块链上的 Almanac 合约，从而获得可被发现的链上身份。它解决的是 Agent 寻址与身份问题，代价是引入了区块链依赖和一份本地私钥文件。
- 适合谁用？
- 如果你的 Agent 需要跨组织被发现、需要密码学身份、并且接受 Fetch.ai 链上注册这一前提，uAgents 的装饰器模型和 on_interval 调度足够直接，pip install uagents 之后几十行就能跑起来。如果你的 Agent 只在单机或单个内网里调用几个固定端点，引入 Almanac 注册和本地私钥文件只是多了一层需要维护的东西，直接用普通的异步 HTTP 服务更省事。
- 能商用吗？
- 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
uAgents 真正要解决的是 Agent 的寻址问题
多数 Agent 框架把注意力放在编排上：怎么把任务拆开、怎么在多个模型之间路由、怎么保存对话状态。uAgents 的重心不在这里。README 的第一条特性写得很直白，每个 Agent 在启动时会自动注册到 Almanac，这是一个部署在 Fetch.ai 区块链上的智能合约。换句话说，它先解决的是「别的 Agent 怎么找到我」，而不是「我怎么想」。
这个定位决定了它的用户画像。适合的是需要跨进程、跨机器、甚至跨组织互相发现并通信的 Agent 开发者，尤其是已经在 Fetch.ai 体系里工作的人。README 里列出的文档目录包含 Addresses、Storage、Synchronous Communication、Agent Broadcast 这几项，全部围绕通信与身份展开，没有一项是关于提示词编排或模型调用的。如果你要的是 LangGraph 那类工作流引擎，这里的抽象层级对不上。
第二条特性讲安全：消息和钱包由密码学保护。第三条讲易用：用装饰器写代码。三条特性合起来就是它的全部主张，一个带链上身份、能收发签名消息、用装饰器描述行为的 Python 库。
装饰器加事件循环：代码长什么样
README 给出的最小示例只有四行有效代码。Agent 对象在模块层构造，行为通过装饰器挂到它身上，最后在 __main__ 里调用 run()。
from uagents import Agent, Context
alice = Agent(name="alice", seed="alice recovery phrase")
@alice.on_interval(period=2.0) async def say_hello(ctx: Context): ctx.logger.info(f'hello, my name is {ctx.agent.name}')
if __name__ == "__main__": alice.run()
几个细节值得注意。on_interval 接受一个以秒为单位的浮点周期，处理函数是 async 的，第一个参数是 Context。Context 同时暴露 logger 和 agent 两个属性，示例里用 ctx.agent.name 拿到 Agent 自己的名字。这种把上下文对象注入处理函数的写法，和 FastAPI 的依赖注入思路接近，好处是处理函数本身不持有全局状态。
README 只演示了 on_interval 这一种触发器，但开篇描述里提到 Agent 可以「按计划执行任务或对各类事件作出反应」，说明事件驱动的装饰器是存在的，只是主文档把它放在了 uagents.fetch.ai 上，仓库 README 没有展开。想确认具体有哪些装饰器，得去看官方文档或 python 目录下的源码，仅凭这份 README 无法列全。
身份从哪来：seed、private_keys.json 与随机地址
Agent 的地址由私钥推导，README 给了三条互斥的路径，选哪条直接决定你的 Agent 重启后还是不是同一个身份。
第一种，显式传 seed。示例把 seed 从环境变量取出来：
import os alice = Agent(name="alice", seed=os.getenv("ALICE_SEED_PHRASE"))
这是生产环境该用的方式，助记词不落在代码里。第二种，只传 name 不传 seed。README 说这种情况下私钥会被本地保存，和名字一起写进 private_keys.json。这文件一旦进了版本库或被打进镜像，身份就等于公开了，需要自己加 .gitignore 和构建排除规则。第三种，连 name 都不传，直接 Agent()，那么每次运行都会生成一个新地址。适合一次性脚本，不适合任何需要被别人找到的 Agent。
README 没有说明 private_keys.json 的写入位置是当前工作目录还是包目录，也没有说明文件权限。这一点在容器化部署时值得先验证，因为工作目录不同会导致同一个 name 生成出不同的身份。文档在这一点上是薄的。
启动即注册：Almanac 带来的能力与约束
按 README 的描述，Agent 启动时会自动在 Almanac 上注册。这是一个链上写入操作，意味着 Agent 的可发现性依赖于 Fetch.ai 区块链的可用性。
这个设计换来的是跨组织的发现能力：任何接入同一网络的 Agent 都能查到你的地址，不需要预先交换配置。代价有两层。第一层是启动路径上多了一个外部依赖，如果注册环节失败，Agent 能否继续以本地模式运行，README 没有交代，这属于需要自己在代码里验证的行为。第二层是链上交互通常涉及手续费和网络选择，README 完全没有提及测试网与主网的切换方式、注册是否需要代币、以及注册信息的有效期。这些都要去官方文档确认。
把「被发现」这件事交给公共账本，是一个明确的产品判断。它适合开放网络里的 Agent 协作，不适合内网服务注册。如果你的 Agent 只需要被同一个 VPC 里的三个服务调用，用 DNS 或服务网格解决更直接。
存储、同步通信与广播：README 只给了入口
文档目录里列出了三个能力：Storage、Synchronous Communication、Agent Broadcast。README 只给了链接，没有任何代码示例，所以这里只能说明它们的存在和大致意图，具体 API 需要查文档。
Storage 对应 Agent 的持久化状态。这一点在 Agent 场景里很关键，因为 on_interval 这类定时任务经常需要记住上一次执行的结果，而进程重启会清空内存。uAgents 是否把存储也绑定到链上，还是提供本地后端，README 没有说，这是一个影响选型的重要未知项。
Synchronous Communication 对应请求-响应模式，区别于默认的消息投递。Agent Broadcast 对应一对多发送。三者合起来构成一套完整的 Agent 间通信原语，但它们的可靠性语义（消息丢失后是否重试、投递是否至少一次、超时如何配置）在 README 里没有任何交代。对需要严格交付保证的系统来说，这些语义必须在采用前确认。
README 另外提到一个 ASI:One 兼容 Agent 的教程，以及一个独立的 uAgent-Examples 仓库，后者被描述为内部与社区开源应用的官方集合地。想评估真实用法，那个仓库比 README 更有信息量。
和直接写异步 HTTP 服务相比，差别在哪
最直接的替代方案不是另一个 Agent 框架，而是 FastAPI 加一个消息队列。两者的差别在发现机制上。
FastAPI 服务之间的调用需要调用方预先知道地址，地址通常写在配置或服务发现系统里，由运维维护。uAgents 把这一步交给 Almanac，调用方通过链上查询拿到地址，注册和查询都是自动的。代价是你接受了 Fetch.ai 的账本作为信任根，并且承担链上交互的延迟和费用。
如果你的 Agent 数量固定、部署在同一边界内，FastAPI 方案的运维成本更低，调试也更直接，因为你可以用 curl 直接打端点。uAgents 的消息是密码学签名的二进制协议，调试时需要用它自己的工具或日志。
另一类替代是通用 Agent 编排框架。它们提供的是任务图、状态机和模型路由，通常不含跨组织的身份层。uAgents 在编排能力上更薄，在身份和通信上更厚。两者不是同一层的东西，把 uAgents 当作编排框架来选型会失望。
版本、许可与维护成本
仓库最近的发布节奏比较密：v0.25.5 在 2026 年 8 月 20 日，v0.25.4 在 8 月 7 日，另外还有一个 core@0.4.9 在 8 月 6 日。主版本号仍在 0.x，按语义化版本的惯例，这意味着 API 可能在次版本之间发生不兼容变化。README 里的示例代码在升级时需要重新核对，尤其是 Agent 构造函数和 Context 的属性。
仓库结构上有一个值得注意的拆分：python 目录放 Python 库，python/uagents-core 放核心定义，后者被描述为用来构建能与 Fetch.ai 体系及 Agent 市场集成的「类 Agent」软件。core@0.4.9 这个独立 tag 说明核心包有自己的版本线。如果你的项目直接依赖 uagents-core 而不是顶层的 uagents，需要分别跟踪两条版本线，升级成本更高。
许可证是 Apache-2.0。这是一个宽松许可，允许商用和修改，通常要求保留版权声明和许可文本，修改过的文件需要标注。README 末尾有一段免责声明，明确项目按「as-is」提供、不承担任何担保，并提示使用者自行承担数据丢失等风险。这段文字本身不改变 Apache-2.0 的条款，但反映了维护方对责任的立场。具体的合规处理需要咨询法务，这里只陈述仓库里的信息。
依赖方面，README 只说明支持 Python 3.10 到 3.13，没有列出第三方依赖清单。由于 Agent 启动会做链上注册，实际运行时大概率还需要网络访问和相关的加密库，这些需要看 python 目录下的依赖声明。
编辑结论
如果你的 Agent 需要跨组织被发现、需要密码学身份、并且接受 Fetch.ai 链上注册这一前提，uAgents 的装饰器模型和 on_interval 调度足够直接，pip install uagents 之后几十行就能跑起来。如果你的 Agent 只在单机或单个内网里调用几个固定端点，引入 Almanac 注册和本地私钥文件只是多了一层需要维护的东西，直接用普通的异步 HTTP 服务更省事。决定采用之前，先确认三件事：Python 版本是否落在 3.10 到 3.13 之间；seed 从环境变量注入后，private_keys.json 是否还会在工作目录里生成；以及你的部署环境能否稳定访问 Fetch.ai 的 Almanac 合约。
社区笔记