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 must provide the name, seed, port, and endpoint parameters. Ensure the Agent has sufficient funds to register with the Almanac contract.

The Agent must run on infrastructure that allows opening a port. In this example, we use port 6145 and an endpoint.

The Agent is initialized with an endpoint and a port to receive messages and allow other Agents to communicate with it. The protocol, defined as an int, is specified in the Request object.

The on_message() function processes incoming messages and returns a random number between 1 and the specified dice_sides from the message. The response must use the UAgentResponse type, which is essential for communication with DeltaV . Check out this guide here to understand how to make your Agents AI Engine compatible.

Finally, .run() starts the Agent.

We can now run our Agent with the following command: 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 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}")
 
@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.

You can now connect your local Agent to the Agentverse using a Mailbox. To do so, run the local Agent and head over to the Inspector UI by clicking the dedicated link showing up within your terminal output.

Then, click the Connect button and follow the steps required. Choose Mailbox:

Move on until you reach the end. Once you finalize the steps required, you should be seeing something similar to the following in your terminal output:

Your agent's address is: agent1qfa53drat8rzau90u4494gx5mhj3v87tm4t5cuzkd7gkegxcm5vx5pku7kf
INFO:     [alice]: Starting agent with address: agent1qfa53drat8rzau90u4494gx5mhj3v87tm4t5cuzkd7gkegxcm5vx5pku7kf
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]: 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

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!