uAgents: Fetch.ai's Python Framework for Agents With On-Chain Identity

The Problem uAgents Solves Is Identity, Not Scheduling

Most Python agent libraries stop at the loop: a function that runs on a timer or reacts to a message. uAgents does that too, but the README is explicit that the framework's differentiator is what happens on startup. Each agent joins what the project calls the network of uAgents by registering on the Almanac, described in the README as a smart contract deployed on the Fetch.ai blockchain. That registration is the product. It means an agent has an address other agents can look up, and the README states that uAgent messages and wallets are cryptographically secured. So the target reader is not someone who wants a nicer asyncio loop. It is someone building a system where two processes owned by different people need to find each other and exchange signed messages without a central directory service they operate themselves. If you only need one process to call another on localhost, this framework is heavier than the problem.

Agent, Context, and the Decorator Runtime

The runtime surface is small. You construct an Agent, attach handlers with decorators, and call run(). The README's first example is two lines: importing Agent and Context, then instantiating Agent(name="alice"). Behaviour is bound through decorators, and the example given is @alice.on_interval(period=2.0) on an async function that receives a Context. The Context object is the handle to the running agent: the sample handler reads ctx.agent.name and logs through ctx.logger. That is the whole data flow in the quickstart. A scheduler fires the decorated coroutine on the given period, the coroutine reads and writes agent state through Context, and the agent process stays alive until run() returns. The README also names a second decorator family for events, describing agents that perform tasks on a schedule or take action on various events, but the quickstart only demonstrates the interval case. The docs index lists separate guides for communication, send and receive, broadcast, and storage, so those mechanisms exist; they are simply not shown in the README body. Treat the quickstart as a smoke test, not as an architecture description.

Addresses, Seeds, and What Happens Without a Name

Identity handling is the part worth reading twice, because the README spells out three distinct behaviours. Give the agent a seed and you get a fixed address; the README shows seed=os.getenv("ALICE_SEED_PHRASE") as the pattern and notes elsewhere in the quickstart that seed="alice recovery phrase" works inline. Omit the seed but keep the name, and the README states the agent's private key will be stored locally alongside its name in private_keys.json. Omit the name entirely, writing Agent() with no arguments, and a new address is generated each time you run the agent. That third case is the one that catches people. An agent whose address changes per run cannot be messaged by anyone who learned its address earlier, which makes it fine for a throwaway demo and wrong for anything that persists. The private_keys.json fallback also deserves attention: it is a plain file on disk, and the README does not describe any encryption or permissions model for it. If you deploy with that path, key custody becomes your problem, and the README does not tell you how to solve it.

Getting an Agent Running

Installation is a single command, pip install uagents, and the README states support for Python 3.10 to 3.13. The full quickstart script is short enough to reproduce mentally: import Agent and Context from uagents, instantiate alice = Agent(name="alice", seed="alice recovery phrase"), decorate an async function with @alice.on_interval(period=2.0), and guard alice.run() behind if __name__ == "__main__". Run it with python agent.py and the README says you should see the results in your terminal, which in the sample means the log line printing the agent name every two seconds. The only configuration key shown anywhere in the README is seed, and it is passed as a constructor argument rather than read from a config file. Everything else (storage, broadcast, synchronous send and receive) is deferred to the documentation site at uagents.fetch.ai, which the README links section by section. Note the versioning detail visible in the release list: the repository ships the uagents package and a separate uagents-core package, which the README describes as core definitions and functionalities for building agent-like software that integrates with the Fetch.ai ecosystem and agent marketplace. The release feed carries separate tags for the two, core@0.4.9 alongside v0.25.5, so the two artifacts version independently. Pin both if you depend on both.

Where the Framework Gets in the Way

The Almanac registration is the design choice with the largest blast radius, and the README presents it as automatic rather than optional: on startup, each agent joins the network by registering on the smart contract. That couples agent boot to a blockchain endpoint. The README does not describe an offline mode, a local registry, or a way to skip registration, and it does not discuss what happens when registration fails. For a developer building a closed system of two agents on one machine, that startup dependency is pure overhead. The second limitation is the key material. The three identity paths in the README are seed, private_keys.json, and a fresh address per run, and only the first is obviously suited to production. The README does not document key rotation, key storage hardening, or what the local file contains beyond the private key itself. Third, the README's feature list is three bullets long and the quickstart demonstrates exactly one decorator. Anyone evaluating this for a multi-step LLM pipeline will find no prompt handling, no tool-calling abstraction, and no model provider integration in the README at all, even though the repository is tagged with llm and ai-agents. Those topics are tagged onto the repo, not described in it. That gap between tags and documentation is itself a signal about where the project's centre of gravity sits.

uAgents Versus a Plain asyncio Service or a Graph Orchestrator

The honest comparison is not against another agent framework with a similar name. It is against writing the thing yourself. A plain asyncio service with an HTTP or message-queue interface gives you a loop, a transport, and nothing else; you supply identity, discovery, and signing. uAgents supplies all three, at the cost of accepting the Almanac as your registry and the Fetch.ai address scheme as your namespace. If your agents will only ever talk to each other inside one deployment, the self-built route is smaller and has no blockchain dependency. The other comparison is against graph-style orchestration libraries, where you declare nodes and edges and a runtime executes the graph. Those give you deterministic, inspectable control flow and are a better fit when the hard part is deciding which step runs next. uAgents is the opposite shape: independent long-lived processes that discover each other and exchange messages, with control flow living inside each agent's handler. Pick based on whether your problem is coordination of a fixed pipeline or coexistence of autonomous parties. The README's own example repository, uAgent-Examples, is where the project points for integrations, and that is the material to read before deciding.

Maintenance, Versioning, and the Apache-2.0 Terms

The release cadence visible in the feed is steady: v0.25.5 in August 2026, v0.25.4 earlier the same month, and core@0.4.9 between them. A minor version still below 1.0 after that many releases means the API has not been declared stable, and the README's disclaimer reinforces this, stating the project is provided as-is without warranty and that users assume all risks including unexpected behaviour and data loss. Budget for reading release notes before upgrading, and pin uagents and uagents-core separately since they carry independent version tags. On licensing, the repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; it also requires that you preserve notices and state significant changes. That is a permissive licence, and it does not extend to the Fetch.ai blockchain or the Almanac contract, which are separate systems with their own terms that this repository's licence does not cover. I am not a lawyer and this is not legal advice; if you are shipping a product that registers agents on a public network, have counsel look at the network side separately from the library side.

Editorial conclusion

Adopt uAgents if your agents need persistent, cryptographically derived identities and a discovery layer you do not want to build, and if you are comfortable with registration on the Fetch.ai Almanac as part of startup. Do not adopt it if you need a general multi-agent orchestration layer for LLM pipelines, or if you cannot accept an agent whose address changes on every run when no name is given. Before writing production code, verify three things against the live docs: whether the Almanac registration step is optional or mandatory in your target version, how private_keys.json is protected on your deployment host, and whether the Python version you run is inside the stated 3.10 to 3.13 range.

Official sources

1. fetchai/uAgents on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases