uAgents: a Python framework for agents that register themselves on the Fetch.ai Almanac

The problem uAgents solves: identity and discovery for Python agents

Most agent code starts as a script with a loop and a prompt. It works until a second process has to find the first one. Then you need an address, a key, a way to publish where you are listening, and a rule for what happens when a peer restarts with a new identity. uAgents packages those four concerns into a Python library. The README describes the target plainly: agents that perform tasks on a schedule or react to events, created with decorators.

The audience is Python developers building multi-agent systems who do not want to write a discovery service. The framework's own framing is that on startup each agent joins the uAgents network by registering on the Almanac, described in the README as a smart contract deployed on the Fetch.ai blockchain. That single sentence explains both the appeal and the coupling. You get discovery without running a registry. You also inherit a dependency on Fetch.ai's chain and its contract.

If your agents only ever talk to each other inside one process, uAgents is more machinery than the problem needs. The value appears when agents are separate programs, possibly on separate hosts, that must find one another by name or address.

How a uAgent works: decorators, an event loop, and the Almanac

The mechanism visible in the README is small. You construct an Agent object, attach handlers with decorators such as on_interval, and call run(). The framework supplies the event loop; your handler receives a Context that carries a logger, the agent object, and, per the documentation links, storage and messaging helpers.

Identity is the part worth reading twice. An agent created with a name but no seed stores its private key locally alongside its name in private_keys.json. An agent created without a name generates a new address on every run. Passing a seed fixes the address, and the README shows the seed being read from an environment variable. That is the difference between an agent that keeps its identity across restarts and one that appears to the network as a stranger each time. For anything long-lived, the seed is not optional.

Registration is the second half. The README states that on startup each agent automatically registers on the Almanac. The repository layout reflects the split: the python folder holds the library, and a separate uagents-core folder holds core definitions for software that integrates with the Fetch.ai ecosystem and agent marketplace. If you are embedding agent-like behaviour into an existing service rather than running a standalone agent, uagents-core is the layer to look at first.

Installing uAgents and running a first agent

Installation is a single pip command. The README specifies support for Python 3.10 to 3.13, so check your interpreter before anything else.

pip install uagents

A minimal agent needs two imports and one decorator. The README's first snippet creates an agent with a name only; the full example adds a seed and an interval handler.

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()

Run it with python agent.py. The README says you should see the results in your terminal, which for this handler means the greeting logged every two seconds. Note that the seed is written directly in the snippet for brevity. In real code, follow the README's other example and read it from the environment instead.

import os
alice = Agent(name="alice", seed=os.getenv("ALICE_SEED_PHRASE"))

The README does not show what the startup registration prints, so the first thing to watch for in your terminal is whatever the framework logs when it contacts the Almanac. The documentation site at uagents.fetch.ai covers installation, addresses, storage, synchronous communication and broadcast in more depth than the README.

Where uAgents gets awkward: the Almanac dependency and key handling

The automatic registration is convenient and it is also the sharpest edge in the design. The README does not document an offline mode, a self-hosted registry, or a rollback path when registration fails. If your deployment environment cannot reach the Fetch.ai blockchain, the framework's central feature is unavailable, and the README is silent on what the agent does in that state. That is not a criticism of the idea; it is a gap you have to close by reading the documentation site before committing.

Key storage deserves the same scrutiny. The default behaviour writes private keys to private_keys.json next to the agent's name. That is fine on a laptop and questionable in a container image, a shared volume, or a CI job, where the file can be committed or copied by accident. The seed-from-environment pattern the README shows is the safer route, and it should be the default in any code you write.

The third limitation is conceptual. uAgents gives you identity and discovery. It does not give you a planner, a memory store, or a model client. The topics list llm and ai-agents, but the README's own example logs a greeting. Everything above the message layer is yours to build, and the framework's job is to stay out of the way while you do it.

uAgents compared with a general-purpose agent framework

The obvious alternative for a Python developer is a general-purpose agent framework that focuses on model orchestration, tool calling and prompt management, and treats networking as an afterthought. The difference in approach is where the abstraction sits. Those frameworks start from the model call and build outward. uAgents starts from the agent as a network participant with a wallet and an address, and builds inward toward whatever that agent does.

That ordering has consequences. A model-first framework will feel faster to prototype against a single LLM and will usually have richer helpers for prompts and tools. uAgents will feel heavier for that same prototype, because you are paying for identity and registration you may not use. Flip the scenario: several agents, separate processes, needing to find each other and exchange signed messages. The model-first framework leaves you writing the registry, and uAgents has already done it.

The README points to the uAgent-Examples repository as the official place for applications built on the framework, and the documentation lists an ASI:One compatible agent example. Those are the references to read if you want to see the network side exercised rather than the hello-world loop.

Maintenance, releases and what the Apache-2.0 licence means here

The repository is not archived, and the last push was on 2026-09-07. Releases are frequent and granular: v0.25.5 on 2026-08-20, v0.25.4 on 2026-08-07, and a separate [email protected] tag on 2026-08-06. The presence of two version lines is the practical upgrade detail. If you depend on the python package, track uagents versions; if you build against uagents-core, you are tracking a different number that moves on its own schedule. Pinning both is the cheap insurance.

The project is licensed under Apache License 2.0. That is a permissive licence with an explicit patent grant, which matters for a framework that touches wallets and signed messages. It does not settle questions about the Fetch.ai blockchain, the Almanac contract, or any tokens involved; those are separate from the library's licence and the README does not address them. The README also carries a disclaimer stating the software is provided as-is without warranty and that users assume all risks, including data loss. Read that alongside the licence rather than instead of it.

Upgrade cost is mostly the usual Python dependency work. The README does not publish a deprecation policy or a support window for older versions, so the release tags are the only signal available.

Editorial conclusion

Adopt uAgents if you want a Python agent loop with a built-in identity, a fixed address derived from a seed, and automatic registration on the Fetch.ai Almanac, and you accept that the network side is Fetch.ai infrastructure. Do not adopt it if you need a framework that runs entirely offline or on a chain of your choosing; the registration step and the Almanac dependency are not optional decorations. Before writing production code, verify three things in the official documentation: what happens to a running agent when the Almanac is unreachable, how private_keys.json is protected on your deployment host, and whether the agent wallet needs funding for the messages you plan to send.

Frequently asked questions

Official sources

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