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 create a local Agent and connect it to the Agentverse via a Mailbox.

Prerequisites

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

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
 
SEED_PHRASE = "put_your_seed_phrase_here"
 
# Now your agent is ready to join the agentverse!
agent = Agent(
    name="alice",
    seed=SEED_PHRASE,
    port=8000,
    mailbox=True
)
 
# 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 SEED_PHRASE, name, seed and port parameters to correctly run this example. You also need to set mailbox=True to correctly connect your Agent to the Agentverse through the Mailbox.

You should get something similar within your terminal output:


INFO:     [Alice]: Starting agent with address: agent1qw8jn3nfl2fyyhe7v4x8pfmsge4hs9zqrqw9eq7h7hluzmd0da8z7j0uacx
INFO:     [Alice]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8002&address=agent1qw8jn3nfl2fyyhe7v4x8pfmsge4hs9zqrqw9eq7h7hluzmd0da8z7j0uacx
INFO:     [Alice]: Starting server on http://0.0.0.0:8002 (Press CTRL+C to quit)
INFO:     [Alice]: Starting mailbox client for https://agentverse.ai
INFO:     [Alice]: Mailbox access token acquired
INFO:     [Alice]: Registration on Almanac API successful
INFO:     [Alice]: Registering on almanac contract...
INFO:     [Alice]: Registering on almanac contract...complete

Create a Mailbox in Agentverse

Now that we defined our local Agent and have successfully run it, we can go on and connect it to the Agentverse (opens in a new tab) via a Mailbox. To do so, make sure your Agent is running. Then, click on the Local Agent Inspector URL provided in your terminal output. You will be redirected towards the Inspector UI and will be able to see multiple details about this local Agent.

Here, click the Connect button.

You will be presented with 3 different choices: Mailbox, Proxy and Custom. Select Mailbox.

You will then see some code details available for the Agent. You do not need to do anything, just click on Finish.

You should now be able to see an additional line within your terminal output like shown below:


INFO:     [Alice]: Starting agent with address: agent1qw8jn3nfl2fyyhe7v4x8pfmsge4hs9zqrqw9eq7h7hluzmd0da8z7j0uacx
INFO:     [Alice]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8002&address=agent1qw8jn3nfl2fyyhe7v4x8pfmsge4hs9zqrqw9eq7h7hluzmd0da8z7j0uacx
INFO:     [Alice]: Starting server on http://0.0.0.0:8002 (Press CTRL+C to quit)
INFO:     [Alice]: Starting mailbox client for https://agentverse.ai
INFO:     [Alice]: Mailbox access token acquired
INFO:     [Alice]: Registration on Almanac API successful
INFO:     [Alice]: Registering on almanac contract...
INFO:     [Alice]: Registering on almanac contract...complete
INFO:     [mailbox]: Successfully registered as mailbox agent in Agentverse

You can view your recently connected local Agent by heading to the Agentverse My Agents tab and by clicking on Local Agents. You will see a box for the local Agent recently connected.

Cool! You have correctly set up a mailbox for the Agent. You can additionally add some further details to the local Agent such as the README.md file. To do so, create a file in your local Agent folder and name it README.md (You can instead provide the path towards it if you wish). In the file, add all the needed details and save it. Then, add the following bits to your local Agent code:


 
agent = Agent(
    name="Alice",
    seed=SEED_PHRASE,
    port=8000,
    mailbox=True,
    readme_path="README.md",
    publish_agent_details=True
)

Then, run the Agent once again and head over to the Inspector UI and connect the Agent again through the Mailbox as we previously showed. Once you do so, you can the head over to the Local Agents tab under Agentverse My Agents page and click on the local Agent box. You should be able to see the README.md file opening up with the content you provided locally:

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:


INFO:     [Alice]: Starting agent with address: agent1qw8jn3nfl2fyyhe7v4x8pfmsge4hs9zqrqw9eq7h7hluzmd0da8z7j0uacx
INFO:     [Alice]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8002&address=agent1qw8jn3nfl2fyyhe7v4x8pfmsge4hs9zqrqw9eq7h7hluzmd0da8z7j0uacx
INFO:     [Alice]: Starting server on http://0.0.0.0:8002 (Press CTRL+C to quit)
INFO:     [Alice]: Starting mailbox client for https://agentverse.ai
INFO:     [Alice]: Mailbox access token acquired
INFO:     [Alice]: Registration on Almanac API successful
INFO:     [Alice]: Registering on almanac contract...
INFO:     [Alice]: Registering on almanac contract...complete
INFO:     [mailbox]: Successfully registered as mailbox agent in Agentverse
INFO:     [Alice]: Received message from agent1qvzc3svtjv6dt9pql8ec7sfeuwfjmdg6ptafs9zc55ppvdwl5fe82j5m70v: hello 2024-12-18
INFO:     [Alice]: Sending message to bob
INFO:     [Alice]: Received message from agent1qvzc3svtjv6dt9pql8ec7sfeuwfjmdg6ptafs9zc55ppvdwl5fe82j5m70v: hello 2024-12-18
INFO:     [Alice]: Sending message to bob
INFO:     [Alice]: Received message from agent1qvzc3svtjv6dt9pql8ec7sfeuwfjmdg6ptafs9zc55ppvdwl5fe82j5m70v: hello 2024-12-18
INFO:     [Alice]: Sending message to bob

Agent 2:


2024-12-18 16:16:38	Info	System	Interval 0 period set to 5
2024-12-18 16:16:38	Debug	System	Envelope sent to agent1qw8jn3nfl2fyyhe7v4x8pfmsge4hs9zqrqw9eq7h7hluzmd0da8z7j0uacx
2024-12-18 16:16:40	Debug	System	Processing envelope from agent1qw8jn3nfl2fyyhe7v4x8pfmsge4hs9zqrqw9eq7h7hluzmd0da8z7j0uacx...

You can now restart your agent!

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

⚠️

Whenever working with mulitple local Agents, you need a different dedicated Mailbox for each one of them!

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!

Was this page helpful?

You can also leave detailed feedbackon Github

Broadcast Agent with Proxy