Hosted, Local, Mailbox and Proxy Agents
Agents operate in various environments depending on how they are created and deployed.
Understanding the difference between Hosted, Local, Mailbox and Proxy 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. 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 direct integration with local functions. Head over to the following resource for a better understanding of Agents and their applications:
- Agents - uAgents Framework
.
- Creating your first agent
.
- Agent Functions
.
- Options for running your Agents
.
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 the local Agent. For instance, consider the following basic Agent:
mailbox_agent.pyfrom uagents import Agent, Context, Model class Message(Model): message: str SEED_PHRASE = "put_your_seed_phrase_here" # Now your agent is ready to join the agentverse! agent = Agent( name="alice", port=8000, mailbox=True ) # Copy the address shown below print(f"Your agent's address is: {agent.address}") if __name__ == "__main__": agent.run()
Once you run this Agent, you will be able to see a link in your terminal output redirecting you towards the Local Agent Inspector for this specific Agent on the Agentverse (opens in a new tab)
.
By clicking the Connect button and then choosing Mailbox you will be guided into correctly setting up a mailbox for your local Agent. 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
.
Proxy Agents
A Proxy serves as a bridge between your Agent and the Agentverse, allowing the Agent to publish interaction data without needing a Mailbox. This setup is particularly beneficial for Agents requiring continuous operation and visibility in the Agentverse Marketplace .
Consider the following basic Agent with a proxy:
proxy_agent.pyfrom uagents import Agent, Context, Model class Message(Model): message: str # Initialize the agent agent = Agent( name="alice", seed="your_agent_seed_phrase", proxy=True ) # Display the agent's address print(f"Your agent's address is: {agent.address}") if __name__ == "__main__": agent.run()
Run the Agent and access the Agent Inspector using the terminal output. Log in to the Agentverse and configure the Proxy connection by providing the public URL or IP address of your Agent. Verify and finalize the setup. Using a Proxy ensures that Agents remain discoverable and can interact with others in the Agentverse, enhancing engagement and visibility in the Marketplace.
For a complete overview of the PRoxy setup, check out this guide .