Agent Mailboxes

Introduction

Agents can't always be online; internet loss will cut your agent off from the network, or perhaps your agent is behind a firewall meaning you cannot accept inbound requests. To get around online requirements we created the Mailbox feature on Agentverse (opens in a new tab). A Mailbox is a middleman that acts as a mailbox for all communication to your agent. Messages are stored within the mailbox and your agents will collect them (calls for these in uAgents library (opens in a new tab)) when they're online again.

Let's get an agent using mailbox, and testing this logic. To begin we need our agents address, we use this to register the agent on the Mailbox.

Get your agents address

Prerequisites

Make sure you have read the following resources before going on with this guide:

• Quick Start Guide for uAgents Framework
• Creating your first agent
• Agents address
• Agent Handlers
• Almanac contract
• Register in Almanac

Imports needed

• uAgents (opens in a new tab)

Local agent setup

mailbox_agent.py
 
from uagents import Agent, Context, Model
 
class Message(Model):
    message: str
 
AGENT_MAILBOX_KEY = "put_your_AGENT_MAILBOX_KEY_here"
SEED_PHRASE = "put_your_seed_phrase_here"
 
# Now your agent is ready to join the agentverse!
agent = Agent(
    name="alice",
    seed=SEED_PHRASE,
    mailbox=f"{AGENT_MAILBOX_KEY}@https://agentverse.ai",
)
 
# Copy the address shown below
print(f"Your agent's address is: {agent.address}")
 
if __name__ == "__main__":
    agent.run()
 

Importantly, you need to provide the AGENT_MAILBOX_KEY, SEED_PHRASE, name, seed and mailbox parameters to correctly run this example.

You should get something similar within your terminal output:

Your agent's address is: agent1qfa53drat8rzau90u4494gx5mhj3v87tm4t5cukd7gkegxcm5vx5pku7kf
INFO:     [alice]: Registration on Almanac API successful
INFO:     [alice]: Registering on almanac contract...
INFO:     [alice]: Registering on almanac contract...complete
INFO:     [alice]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8000&address=agent1qfa53drat8rzau90u4494gx5mhj3v87tm4t5cuzkd7gkegxcm5vx5pku7kf
INFO:     [alice]: Starting server on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     [alice]: Connecting to mailbox server at agentverse.ai
INFO:     [alice]: Mailbox access token acquired

Now that you have correctly retrieved your agent's address, let's head over to the Agentverse (opens in a new tab)!

Create a Mailbox in Agentverse

Make sure that you are signed in to the Agentverse (opens in a new tab) platform. We will now create a Mailbox for our local agent above. To do so, copy the local agent address available within your terminal and head over to the Agentverse: My Agents tab. Once there, click on the Local Agents tab and click on Connect Local Agent button.

You will need to paste the address of the local agent you wish to retrieve and wait for confirmation. Note that it may take some time in order for your agent to be retrieved correctly. Make sure your agent is running on your end otherwise the agent won't be retrievable!

Once the agent is correctly retrieved, you will have to give it a name. When you do so and confirm, you will see a Mailbox API Key showing up. Copy and paste it within your local agent code by filling up the AGENT_MAILBOX_KEY field inline.

Updating your agent

Let's update alice agent; alice will now print to console any message it receives, provided the message is of type Message. Remember that you need to provide the AGENT_MAILBOX_KEY, SEED_PHRASE, name, seed and mailbox parameters to correctly run this code:

mailbox_agent_updated.py
 
from uagents import Agent, Context, Model
 
class Message(Model):
    message: str
 
AGENT_MAILBOX_KEY = "put_your_AGENT_MAILBOX_KEY_here"
SEED_PHRASE = "put_your_seed_phrase_here"
 
# Now your agent is ready to join the agentverse!
agent = Agent(
    name="alice",
    seed=SEED_PHRASE,
    mailbox=f"{AGENT_MAILBOX_KEY}@https://agentverse.ai",
)
 
print(f"Your agent's address is: {agent.address}")
 
@agent.on_message(model=Message, replies={Message})
async def handle_message(ctx: Context, sender: str, msg: Message):
    ctx.logger.info(f"Received message from {sender}: {msg.message}")
 
 
 

Creating a second agent

Let's create and run a second agent to message Alice every 3 seconds. You need to provide the ALICE_ADDRESS, name and seed parameters to correctly run this code:

test_agent.py
 
from uagents import Agent, Bureau, Context, Model
from datetime import datetime
 
 
class Message(Model):
    message: str
 
 
agent_2 = Agent(name="agent_2", seed="agent_2 recovery phrase", port=8001, endpoint="http://localhost:8001/submit")
 
ALICE_ADDRESS = "add_address_of_alice_agent"
 
 
@agent_2.on_interval(period=3.0)
async def send_message(ctx: Context):
    await ctx.send(ALICE_ADDRESS, Message(message=f"hello {datetime.today().date()}"))
 
 
if __name__ == "__main__":
    agent_2.run()
 

Testing

With both alice and agent_2 running, stop alice and let agent_2 run for a further 20 seconds, or so.

The output should be similar to the following, depending on the terminal window:

• Alice:

  Your agent's address is: agent1qtpr2xgmml964v44sy78gxhsrvakcgj567tthxeyz5fj844hcft5ww2rwkn
  INFO:     [Alice]: Registration on Almanac API successful
  INFO:     [alice]: Registering on almanac contract...
  INFO:     [alice]: Registering on almanac contract...complete
  INFO:     [Alice]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8000&address=agent1qtpr2xgmml964v44sy78gxhsrvakcgj567tthxeyz5fj844hcft5ww2rwkn
  INFO:     [Alice]: Starting server on http://0.0.0.0:8000 (Press CTRL+C to quit)
  INFO:     [Alice]: Connecting to mailbox server at agentverse.ai
  INFO:     [Alice]: Mailbox access token acquired
  INFO:     [Alice]: Received message from agent1qvfnlashfjq67fsczqfs82mmnxu4ffu3xftsc75w62mfskhdnavtq0cknv9: hello 2024-11-06
  INFO:     [Alice]: Received message from agent1qvfnlashfjq67fsczqfs82mmnxu4ffu3xftsc75w62mfskhdnavtq0cknv9: hello 2024-11-06
  INFO:     [Alice]: Received message from agent1qvfnlashfjq67fsczqfs82mmnxu4ffu3xftsc75w62mfskhdnavtq0cknv9: hello 2024-11-06

• Agent 2:

  INFO:     [agent_2]: Registration on Almanac API successful
  INFO:     [agent_2]: Registering on almanac contract...
  INFO:     [agent_2]: Registering on almanac contract...complete
  INFO:     [agent_2]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8001&address=agent1qvfnlashfjq67fsczqfs82mmnxu4ffu3xftsc75w62mfskhdnavtq0cknv9    
  INFO:     [agent_2]: Starting server on http://0.0.0.0:8001 (Press CTRL+C to quit)

You can now restart your agent!

You will see a bunch of messages being displayed by alice which are sent by agent_2.

Now your agent doesn't need to be running all the time as messages will be waiting when it comes back online.

Great! You correctly enrolled your local agent on the Agentverse using the Mailbox feature!