Quick Start Guide for uAgents Framework

This quickstart guide quickly guides you through installing the uAgents Framework and 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)

Installation

System requirements

• Python 3.8+: A popular programming language.
• PIP: Python package manager for installing libraries.
• Poetry (optional): For managing virtual environments and dependencies.
• Windows, Mac or Ubuntu.

Installation steps

1. Create a Project Directory. Open your terminal and create a new directory for your project:

   mkdir directory_name
   cd directory_name

2. Initialize and activate virtual environment. Use Poetry to initialize and activate a virtual environment (optional but recommended):

   poetry init -n && poetry shell

3. Install uAgents Framework.

   poetry add uagents

4. Verify installation. Check if the installation was successful.

   poetry show uagents

Troubleshooting

Sometimes you may face errors installing, 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

We should create something simple to get started, below the most basic of agents performs a task periodically.

Create a new Python script:

windows
echo. > interval_task.py

Open interval_task.py in your text editor and add the following code:

interval_task.py
 
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, your 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

This guide will walk you through creating a simple interaction between two agents. The first will send a message to the second one at regular intervals, and this latter one will handle and log the received messages.

Create 2 new Python scripts:

windows
echo. > SenderAgent.py

windows
echo. > ReceiverAgent.py

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

SenderAgent.py
 
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:

ReceiverAgent.py
 
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

Run the scripts 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 Fetch Network! if you're keen to skip the more code focused guides, your best next steps would be Communicating with agents.

Note that our Team is available on Discord (opens in a new tab) for any additional inquiry.