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

Run this simple script to get your agents address:

    from uagents import Agent, Context, Model
 
    class Message(Model):
        message: str
 
    # 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()

You should get something similar within your terminal output:

Your agent's address is: agent1qfa53drat8rzau90u4494gx5mhj3v87tm4t5cukd7gkegxcm5vx5pku7kf
INFO:     [alice]: Registering on almanac contract...
INFO:     [alice]: Registering on almanac contract...complete
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 into 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, alice will now print to console any message she receives, provided the message has a type of Message.

from uagents import Agent, Context, Model
 
class Message(Model):
    message: str
 
AGENT_MAILBOX_KEY = "put_your_AGENT_MAILBOX_KEY_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",
)
 
@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}")
 
if __name__ == "__main__":
    agent.run()

Creating an a second agent

Optionally you can create this second agent to send messages to your other agent

You can now restart your agent!

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!