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
Local agent setup
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]: 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 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:
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",
)
@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 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:
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.run()
Testing
With both alice
and agent_2
running, stop alice
and let agent_2
run for a further 20 seconds, or so. After
that period of time, restart alice
and she should print out a bunch of messages from the mailbox, like so:
INFO: [alice]: Registering on almanac contract...complete
INFO: [alice]: Connecting to mailbox server at agentverse.ai
INFO: [alice]: Mailbox access token acquired
You can now restart your agent!
Remember, each agent needs a different dedicated Mailbox!
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!