Hosted, Local, and Mailbox Agents

Agents operate in various environments depending on how they are created and deployed.

Understanding the difference between Hosted, Local, and Mailbox Agents helps developers choose the right setup for their needs.

Hosted Agents

Hosted Agents are cloud-based Agents managed within the Agentverse (opens in a new tab),enabling developers to deploy and manage Agents without handling infrastructure. These Agents function as lightweight, efficient tasks, resetting global variables after each call. To maintain state across calls, developers must use Agent Storage for stateful behavior.

Developers can start with blank scripts or use customizable templates for common use cases like retrieving stock prices or finding nearby restaurants. Hosted Agents are highly accessible, requiring no local dependencies, and include an agent.py file from which you can develop them straightforwardly. For a better reference to these topics, check out the following resources:

Local Agents

Local Agents run on your machine or infrastructure, providing complete control over their environment, configuration, and execution. Unlike hosted Agents, they handle real-time events, messages, and tasks continuously, making them ideal for persistent state and direct access to local resources.

Using the uAgents Framework, Local Agents integrate with any Python package or custom module, supporting advanced capabilities like machine learning and data processing. They maintain persistent state across function executions, unlike hosted Agents, where state resets after each call. Setting up a Local Agent requires a Python environment, dependencies, and running the Agent script. They can operate continuously or within Docker containers for scalability and isolation.

Local Agents are perfect for high-performance, real-time applications requiring deep customization, resource management, and seamless integration with local services.

Head over to the following resource for a better understanding of Agents and their applications:

Mailbox Agents

The Agentverse Mailbox feature makes Agents a hybrid between Hosted and Local types. This because Local Agents may not always be online all the time due to network outages, being behind a firewall, or intentionally going offline for resource management. To manage such scenarios, the Mailbox feature in Agentverse allows Agents to receive messages while they are offline with ease. Once the Agent comes back online, it can retrieve these messages from its mailbox.

Local Agents can use a Mailbox to ensure that no messages are lost when they are temporarily disconnected from the network; the Mailbox acts as a message buffer, storing communications until the Agent comes back online and ready to process them. Indeed, this feature enables interaction with other Agents or functions without the Agent being online continuously.

In order to set up a mailbox for a local Agent, you first need to create and configure a local Agent. The Agent's address is used to register it on the Agentverse, and then to generate a Mailbox API key for your Agent. For instance, consider the following basic Agent:

mailbox_agent.py
 
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()

Then, head over to the Agentverse (opens in a new tab) and navigate to the My Agents tab. Here, select Local Agents and click on Connect Local Agent. Paste your Agent's address retrieved from running your local Agent and follow the steps until you get a Mailbox API Key, which you will use to update your Agent's configuration above. To test your Mailbox setup, you can create another Agent (on Agentverse for instance) that sends messages to the Mailbox while the first Agent is offline. When the first agent comes back online, it will retrieve and process the stored messages. For a complete example, check out this guide .

For a more complex example of an Agent using a Mailbox, check out the following guide .

Was this page helpful?

You can also leave detailed feedbackon Github

Agents storage functions Bureau