Quick Start Guide for uAgents Framework
This Quickstart guide walks you through the installation process of the uAgents Framework and helps building a couple of Agents in a few steps.
You can find all supporting code files in our dedicated GitHub repo (opens in a new tab).
Let's get started!
Installation
System requirements
- Python 3.8+: it is a popular programming language.
- PIP: it is Python package manager for installing libraries.
- Operating System: Windows, MacOS or Ubuntu.
Installation steps
-
Let's start and create a Project Directory for your Agent project. Open and type the following within your terminal:
mkdir directory_name cd directory_name
-
Proceed and install the uAgents Framework package:
pip install uagents
Troubleshooting
Sometimes you may face errors during installation. Here we list the most common reasons below:
Problem on MacOS/Python 3.11: Installing coincurve (17.0.0) fails.
Solution
Install the necessary tools:
brew install automake autoconf libtool
Creating a simple Agent
Let's create a very basic Agent to get started. Here below you can find the most basic Agent application; we want the Agent to perform a task periodically.
First of all, let's create a new Python script for this project. Open terminal and type the following into it:
windowsecho. > interval_task.py
Then, open the interval_task.py
file in a text editor of your choice and add the following code:
interval_task.pyfrom uagents import Agent, Context # Create an agent named Alice alice = Agent(name="alice", seed="YOUR NEW PHRASE", port=8000, endpoint=["http://localhost:8000/submit"]) # Define a periodic task for Alice @alice.on_interval(period=2.0) async def say_hello(ctx: Context): ctx.logger.info(f'hello, my name is {alice.name}') # Run the agent if __name__ == "__main__": alice.run()
Be sure to update seed
with a unique phrase; the seed will need to be wrapped in "
.
Run Script
Run the script to see the output:
python interval_task.py
Expected Output:
INFO: [alice]: Starting server on http://0.0.0.0:8000 (Press CTRL+C to quit) INFO: hello, my name is alice INFO: hello, my name is alice INFO: hello, my name is alice
Message Handling Example
Let's now explore how Agents handle messages. Let's set up a simple interaction between two Agents: the first will send a message to the second one at regular intervals, and the latter one will handle and log the received messages accordingly.
First, let's create 2 new Python scripts, one for each Agent:
windowsecho. > SenderAgent.py
windowsecho. > ReceiverAgent.py
Open SenderAgent.py
in your text editor and add the following code into it:
SenderAgent.pyfrom uagents import Agent, Context, Model class Message(Model): message: str RECIPIENT_ADDRESS = ( "test-agent://agent1qd8ymq4najh5wycvhvhcw3l5lmkgkvkrqevrs6wpp5ll0khfdq6v2cq6859" ) SenderAgent = Agent( name="SenderAgent", port=8000, seed="SenderAgent secret phrase", endpoint=["http://127.0.0.1:8000/submit"], ) print(SenderAgent.address) @SenderAgent.on_interval(period=2.0) async def send_message(ctx: Context): await ctx.send(RECIPIENT_ADDRESS, Message(message="Hi there. Let's start our conversation!")) @SenderAgent.on_message(model=Message) async def message_handler(ctx: Context, sender: str, msg: Message): ctx.logger.info(f"Received message from {sender}: {msg.message}") if __name__ == "__main__": SenderAgent.run()
Then, open ReceiverAgent.py
in your text editor and add the following code into it:
ReceiverAgent.pyfrom uagents import Agent, Context, Model # NOTE: Run ReceiverAgent.py before running SenderAgent.py class Message(Model): message: str ReceiverAgent = Agent( name="ReceiverAgent", port=8001, seed="ReceiverAgent secret phrase", endpoint=["http://127.0.0.1:8001/submit"], ) print(ReceiverAgent.address) @ReceiverAgent.on_message(model=Message) async def message_handler(ctx: Context, sender: str, msg: Message): ctx.logger.info(f"Received message from {sender}: {msg.message}") # send the response await ctx.send(sender, Message(message="Cool! Let's get started!")) if __name__ == "__main__": ReceiverAgent.run()
Again, be sure to update seed
with a unique phrase.
Run Script
Open two terminal windows, each one for an Agent, and then run the scripts separately to see the Agents communicating:
python SenderAgent.py
python ReceiverAgent.py
Expected Output:
-
SenderAgent:
agent1qdw67s95esk0zwn8qxf0ln22e8zah9rqfrqqa4qyda7mjtpf3hsw640wuwr INFO: [SenderAgent]: Registering on almanac contract... INFO: [SenderAgent]: Registering on almanac contract...complete INFO: [SenderAgent]: Received message from agent1qd8ymq4najh5wycvhvhcw3l5lmkgkvkrqevrs6wpp5ll0khfdq6v2cq6859: Cool! Let's get started! INFO: [SenderAgent]: Received message from agent1qd8ymq4najh5wycvhvhcw3l5lmkgkvkrqevrs6wpp5ll0khfdq6v2cq6859: Cool! Let's get started! INFO: [SenderAgent]: Received message from agent1qd8ymq4najh5wycvhvhcw3l5lmkgkvkrqevrs6wpp5ll0khfdq6v2cq6859: Cool! Let's get started!
-
ReceiverAgent:
agent1qd8ymq4najh5wycvhvhcw3l5lmkgkvkrqevrs6wpp5ll0khfdq6v2cq6859 INFO: [ReceiverAgent]: Registering on almanac contract... INFO: [ReceiverAgent]: Registering on almanac contract...complete INFO: [ReceiverAgent]: Starting server on http://0.0.0.0:8001 (Press CTRL+C to quit) INFO: [ReceiverAgent]: Received message from agent1qdp9j2ev86k3h5acaayjm8tpx36zv4mjxn05pa2kwesspstzj697xy5vk2a: Hello there bob. INFO: [ReceiverAgent]: Received message from agent1qdp9j2ev86k3h5acaayjm8tpx36zv4mjxn05pa2kwesspstzj697xy5vk2a: Hello there bob. INFO: [ReceiverAgent]: Received message from agent1qdp9j2ev86k3h5acaayjm8tpx36zv4mjxn05pa2kwesspstzj697xy5vk2a: Hello there bob.
Reach out to the Team!
Excellent! You are now ready to start exploring the concepts and resources available to start developing your agents on the ASI Network! if you're keen to skip the more code focused guides, the best next steps would be exploring how Agents communicate with other Agents .
Note that our Team is available on Discord (opens in a new tab) for any additional inquiry.