Quick Start Guide for uAgents Framework

This Quickstart guide walks you through the installation process of the uAgents Framework and helps to build a couple of Agents in a few steps.

You can find all supporting code files in our dedicated GitHub repo.

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

1. 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

2. 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:

echo. > interval_task.py

Then, open the interval_task.py file in a text editor of your choice and add the following code:

 
from 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:

echo. > SenderAgent.py

echo. > ReceiverAgent.py

Open SenderAgent.py in your text editor and add the following code into it:

 
from 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:

 
from 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 for any additional inquiry.