Options for running your Agents

Run a local agent with an endpoint

In some scenarios, you may want to run an agent on your own hardware or infrastructure; luckily this is very easy to do on any system that support Python 3.10.

This system is pretty simple, as to get you started as quickly as possible. We're going to run this agent on any device you'd like, in this scenario we're running on a VM, but you could run this on your laptop, raspberry pi or tweak for Agentverse. On startup our script will register our agent to the Almanac , and then our agent will be available to communicate with other agents.

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
• Almanac contract
• Register in Almanac
• Agents protocols
• Exchange protocol
• Agent Functions
• Agent Mailboxes
• Make your agents AI Engine compatible

Imports needed

• uAgents (opens in a new tab)
• AI Engine (opens in a new tab)

The agent

Consider the following Agent:

agent_endpoint.py
 
from uagents import Agent, Context, Protocol, Model
import random
from uagents import Field
from ai_engine import UAgentResponse, UAgentResponseType
import sys
 
agent = Agent(
    name="dungeonsanddragonsdiceroll",
    port=6145,
    seed="RANDOM STRINGS",
    endpoint=["http://YOUR_IP:6145/submit"],
)
 
 
@agent.on_event("startup")
async def hi(ctx: Context):
    ctx.logger.info(agent.address)
 
 
class Request(Model):
    dice_sides: int = Field(description="How many sides does your dice need?")
 
 
dice_roll_protocol = Protocol("DungeonsAndDragonsDiceRoll")
 
 
@dice_roll_protocol.on_message(model=Request, replies={UAgentResponse})
async def roll_dice(ctx: Context, sender: str, msg: Request):
    result = str(random.randint(1, msg.dice_sides))
    message = f"Dice roll result: {result}"
    await ctx.send(
        sender, UAgentResponse(message=message, type=UAgentResponseType.FINAL)
    )
 
 
agent.include(dice_roll_protocol, publish_manifest=True)
 
agent.run()
 

To correctly run this code, you need to provide the name, seed, port and endpoint parameters. Also, make sure your Agent has enough funds to register in Almanac contract.

You'll need to be running this agent on infrastructure that allows you to open a port; in our example, we run on port 6145.

The agent is initialized with an endpoint, and a port; this is so that we can receive messages, and other agents know where to send them. And we define our protocol, which is just an int as seen in the Request object.

Our on_message() doesn't do much other than return a number between 1 and the defined dice_sides from the message inclusive. However, the response type is of UAgentResponse which is essential to communicate with DeltaV .

.run() initializes the agent.

Finally, we run our agent as follows: python agent_endpoint.py

Expected output:

INFO:     [dungeonsanddragonsdiceroll]: Manifest published successfully: DungeonsAndDragonsDiceRoll
INFO:     [dungeonsanddragonsdiceroll]: Registration on Almanac API successful
INFO:     [dungeonsanddragonsdiceroll]: Registering on almanac contract...
INFO:     [dungeonsanddragonsdiceroll]: Registering on almanac contract...complete
INFO:     [dungeonsanddragonsdiceroll]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A6145&address=agent1qvwk0ntr38yyghccrg530hnnm88r5uske4hdcalsa7gqp7sjgx42k4mp62r
INFO:     [dungeonsanddragonsdiceroll]: Starting server on http://0.0.0.0:6145 (Press CTRL+C to quit)

Run a local agent using a Mailbox

Through the Agentverse you can set up Mailboxes for your local Agents, allowing them to communicate with other agents registered on the Fetch Network without the need to be constantly online and without requiring your constant presence to operate.

Local agent setup

Let's start by creating a local agent named alice with a handle_message() function using an @agent.on_message() decorator to handle messages received by other agents and matching the Message class:

agent_mailbox.py
 
from uagents import Agent, Context, Model
 
 
class Message(Model):
    message: str
 
 
# First generate a secure seed phrase (e.g. https://pypi.org/project/mnemonic/)
SEED_PHRASE = "put_your_seed_phrase_here"
 
# Now go to https://agentverse.ai, register your agent in the Mailroom by providing the address you just copied.
# Then, copy the agent's utilising-the-mailbox key and insert it here below inline
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",
)
 
# Copy the address shown below
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}")
 
 
if __name__ == "__main__":
    agent.run()
 

To correctly run this code, you need to provide the AGENT_MAILBOX_KEY, SEED_PHRASE, name, seed and mailbox parameters. The output should look similarly to the following:

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

You can easily create a Mailbox by first retrieving your local agent address and head over to the Agentverse: My Agents tab. Here, click on Local Agents and click on Connect Local Agent.

You will need to provide the address of the local agent you wish to retrieve and wait for confirmation. You will then need to provide a name for the agent.

Once you do so and confirm, you will see a Mailbox API Key showing up. Paste it within your local agent code above by filling up the AGENT_MAILBOX_KEY field inline.

You can then restart your agent, now your agent doesn't need to run all the time as their messages will be waiting for them for when they come back online!