feat(docs): add run agents on agentverse example

pages/examples/intermediate/_meta.json

@@ -55,22 +55,34 @@
     "title": "Query an agent using a proxy API",
     "tags": ["Agents", "Proxy", "API", "Intermediate"]
   },
+  "running-an-agent-on-agentverse": {
+    "title": "Run Agents on Agentverse",
+    "tags": ["Agents", "Agentverse", "Local", "Mailbox", "Intermediate"]
+  },
   "dice-roll": {
     "title": "Register a dice roll agent as a Function",
-    "tags": ["Agents", "Functions", "DiceRoll", "Intermediate"]
+    "tags": ["Agents", "Agentverse", "Functions", "DiceRoll", "Intermediate"]
   },
   "coin-toss": {
     "title": "Register a coin toss agent as a Function",
-    "tags": ["Agents", "Functions", "CoinToss", "Intermediate"]
+    "tags": ["Agents", "Agentverse", "Functions", "CoinToss", "Intermediate"]
   },
   "local-agent-registration": {
     "title": "Register a local agent as a Function",
-    "tags": ["Agents", "Local", "Functions", "Registration", "Intermediate"]
+    "tags": [
+      "Agents",
+      "Agentverse",
+      "Local",
+      "Functions",
+      "Registration",
+      "Intermediate"
+    ]
   },
   "news-reading-system": {
     "title": "Using News API to build network of Primary and Secondary functions",
     "tags": [
       "Agents",
+      "Agentverse",
       "Functions",
       "PrimaryFunction",
       "SecondaryFunction",
@@ -82,6 +94,7 @@
     "title": "Locally Hosted Agent with LangChain Integration",
     "tags": [
       "Agents",
+      "Agentverse",
       "Local",
       "Functions",
       "Registration",
@@ -93,6 +106,7 @@
     "title": "Hugging face API agent as a Function",
     "tags": [
       "Agents",
+      "Agentverse",
       "Functions",
       "Registration",
       "HuggingFace",
@@ -105,11 +119,18 @@
   },
   "agent-and-service-api": {
     "title": "Agents and Functions Creation using APIs",
-    "tags": ["Agents", "Functions", "API", "Intermediate"]
+    "tags": ["Agents", "Agentverse", "Functions", "API", "Intermediate"]
   },
   "agent-secret-api": {
     "title": "Adding Secret to agent using Agentverse API",
-    "tags": ["Agents", "Secrets", "API", "Agentverse", "Intermediate"]
+    "tags": [
+      "Agents",
+      "Agentverse",
+      "Secrets",
+      "API",
+      "Agentverse",
+      "Intermediate"
+    ]
   },
   "react_example": {
     "title": "React app with agents 'on_query' decorator",

pages/examples/intermediate/running-an-agent-on-agentverse.mdx

@@ -0,0 +1,178 @@
+# Run Agents on Agentverse
+
+## Introduction
+
+You can create, host and run any type of agent you want to create within the [Agentverse ↗️](/concepts/agent-services/agentverse-intro). There are multiple ways you can do so. You can decide to either **create your agent directly on the Agentverse** platform using its functionalities and allowed imports, or you can **create your agents locally** and then enrol them within the Agentverse by using an **Endpoint** or a **Mailbox** to make them retrievable by any other agent registered on the Fetch Network.
+
+Let's get started!
+
+## Supporting documentation
+
+- [Creating an agent ↗️](/guides/agents/create-a-uagent)
+
+- [Register in Almanac ↗️](/guides/agents/register-in-almanac)
+
+- [Almanac Contract ↗️](/references/contracts/uagents-almanac/almanac-overview)
+
+- [Agents address 🤖📫 ↗️](/guides/agents/getting-started/getting-uagent-address)
+
+- [Protocols ↗️](/references/uagents/uagents-protocols/agent-protocols)
+
+- [Creating an Agentverse hosted agent 🤖 ↗️](/guides/agentverse/creating-agentverse-agents/creating-a-hosted-agent)
+
+- [Agent Mailboxes ↗️](/guides/agents/intermediate/mailbox)
+
+- [Utilising the Agentverse Mailroom feature 📬↗️](/guides/agentverse/agentverse-mailbox/utilising-the-mailbox)
+
+- [Options for running your Agents ↗️](/guides/agents/intermediate/options-for-running-local-agents)
+
+## Create Agents hosted on the Agentverse
+
+It is possible for you to create and host any type of agent you want using the [My Agents ↗️](/concepts/agent-services/agent-hosting) tab. Managed agents are currently a beta feature and therefore do not fully support the entire [uagents ↗️](/concepts/agents/agents) library toolset for development. Check out the [Agentverse: allowed imports ↗️](/guides/agentverse/allowed-imports) guide for a better understanding of the packages available for development of Agents on the Agentverse.
+
+You can choose between creating agents from a **Blank Agent** script or using **Skeleton Agent** code as an initial template.
+
+### Create and run an agent on Agentverse
+
+First of all, navigate towards the [Agentverse ↗️](https://agentverse.ai/), sign in and choose the **My Agents** tab. Here, click on the **+ New Agent** button and choose **Blank Agent**. Provide the needed details including the agent's name.
+
+Once confirmed, you will see a box for your agents within the My Agents tab. By clicking on it, the **Agent Editor** will show up. Here you can code your agent and its protocols and you will also be able to run it and see if it behaves as you intend by looking at output result within the **Agents Logs** (which is an in-built terminal window) located at the bottom of the Agent Editor window.
+
+As an initial example, let's create a simple agent introducing itself and printing its `address` in the Agent Logs on an interval of 3 seconds by using the `.on_interval()` decorator:
+
+    ```py copy filename="simple_agent.py"
+    from uagents import Agent, Context
+
+    agent = Agent(name="Simple")
+
+    @agent.on_interval(period=3.0)
+    async def say_hello(ctx: Context):
+        ctx.logger.info(f"Hello, I'm an agent and my address is {agent.address}.")
+
+    if __name__ == "__main__":
+        agent.run()
+    ```
+
+Once you are happy with the code, click on **Start** button to start your agent and see the output within the Agent Logs. In this case, you will see something like:
+
+    ```
+    INFO:     [Simple]: Hello, I'm an agent and my address is agent1qwf7xx0402yndf4xvqscewmn86jrq5yqj7zz8yt5nac3qjut4jtcsh0fa6a.
+    INFO:     [Simple]: Hello, I'm an agent and my address is agent1qwf7xx0402yndf4xvqscewmn86jrq5yqj7zz8yt5nac3qjut4jtcsh0fa6a.
+    INFO:     [Simple]: Hello, I'm an agent and my address is agent1qwf7xx0402yndf4xvqscewmn86jrq5yqj7zz8yt5nac3qjut4jtcsh0fa6a.
+    ```
+
+Checkout this [guide ↗️](/guides/agentverse/creating-agentverse-agents/simple-dice-roll-agent) for an additional use case for a simple agent being created and run on the Agentverse.
+
+## Create agents locally
+
+We now cover the process of enrolling **local agents** on the Agentverse. This may be the case where you want to run an agent on your own hardware or infrastructure (e.g., VM, your laptop, Raspberry pi or tweak for Agentverse). This is pretty simple on any system that support Python 3.10.
+
+At startup, the script will register the agent to the [Almanac ↗️](/concepts/fetch-network/almanac). This way, the agent will be available to communicate with other agents registered on the Fetch Network.
+
+You can either run a local agent using an **endpoint** or an Agentverse **Mailbox**.
+
+### Run a local agent using an endpoint
+
+Let's consider the following local agent example:
+
+    ```py copy filename="agent.py"
+    from uagents.setup import fund_agent_if_low
+    from uagents import Agent, Context, Protocol, Model
+
+    class Message(Model):
+        message: str
+
+    agent = Agent(
+        name="TestAgent",
+        port=6145,
+        seed="RANDOM STRINGS",
+        endpoint=["http://YOUR_IP:6145/submit"],
+    )
+
+    fund_agent_if_low(agent.wallet.address())
+
+    @agent.on_event("startup")
+    async def hi(ctx: Context):
+        ctx.logger.info(agent.address)
+
+    test_protocol = Protocol("TestProtocol")
+
+    # Define your agent protocols
+    # Include the protocols within your agent
+    agent.include(test_protocol, publish_manifest=True)
+
+    agent.run()
+    ```
+
+Importantly, your agent needs to be running on an infrastructure allowing you to open a port. The agent is initialised with an **endpoint**, and a **port** so that it can receive messages, and other agents know where to send them. In the above example, the agent is run on port `6145`. You will need to define your agent's protocols in order to define what type of messages it will expect and produce whenever interacting with other agents on the Fetch Network. For an example of a complete code for a local agent with protocols, checkout this [guide ↗️](/guides/agents/intermediate/options-for-running-local-agents#the-agent).
+
+As it is possible to see from this latter guide, by implementing the `uagents-ai-engine` library within your agent's code, you will make your agent [AI Engine compatible ↗️](/guides/agents/intermediate/ai-engine-compatible-agent) and retrievable via DeltaV. Checkout the dedicated [AI Engine ↗️](/concepts/ai-engine/ai-engine-intro) resource for a better understanding of [Agent Functions ↗️](/guides/agents/intermediate/agent-functions).
+
+When running the above local agent, you will see something like this in your terminal:
+
+    ```
+    INFO:     [TestAgent]: Manifest published successfully: TestProtocol
+    INFO:     [TestAgent]: Registering on almanac contract...
+    INFO:     [TestAgent]: Registering on almanac contract...complete
+    INFO:     [TestAgent]: agent1qvwk0ntr38yyghccrg530hnnm88r5uske4hdcalsa7gqp7sjgx42k4mp62r
+    INFO:     [TestAgent]: Starting server on http://0.0.0.0:6145 (Press CTRL+C to quit)
+    ```
+
+**Great! You have successfully registered your local agent on the Fetch Network and the Agentverse.**
+
+This agent will be easily retrievable by any other agents on the Fetch Network for interaction and communication. If you head to the [Agentverse Explorer ↗️](/concepts/agent-services/agent-explorer) tab and paste the address of the local agent above, you will be able to see your local agent's details and protocols.
+
+### Run a local agent using a Mailbox
+
+**Mailboxes** are a great feature within the Agentverse. A Mailbox allows for communication between your local agents and any other agents registered within the Fetch Network without the need for you to be constantly present to operate them. Let's consider the following local agent example:
+
+    ```py copy filename="agent.py"
+    from uagents import Agent, Context, Model, Protocol
+
+    class Message(Model):
+        message: str
+
+    SEED_PHRASE = "put_your_seed_phrase_here"
+
+    print(f"Your agent's address is: {agent.address}")
+
+    AGENT_MAILBOX_KEY = "put_your_AGENT_MAILBOX_KEY_here"
+
+    agent = Agent(
+        name="MailboxTestAgent",
+        seed=SEED_PHRASE,
+        mailbox=f"{AGENT_MAILBOX_KEY}@https://agentverse.ai",
+    )
+
+    test_protocol = Protocol("TestProtocol")
+
+    # Define your agent protocols and behaviour
+    # Include the protocols within your agent
+
+    if __name__ == "__main__":
+        agent.run()
+    ```
+
+To create a Mailbox, first retrieve your **local agent address** and head over to the **Agentverse: My Agents** tab. There, click on **Local Agents** and click on **Connect Local Agent** button. 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. Copy and paste it within your local agent code by filling up the `AGENT_MAILBOX_KEY` field inline. You can then restart your agent.
+
+For an example of a complete code for a local agent with protocols registered on the Agentverse using the Mailbox feature, checkout this [example ↗️](/examples/intermediate/local-agent-langchain). As you can see from this latter guide, by implementing the `uagents-ai-engine` library within your agent's code, you will make your agent [AI Engine compatible ↗️](/guides/agents/intermediate/ai-engine-compatible-agent) and retrievable via DeltaV.
+
+When running the above local agent, you will see something like this on your terminal:
+
+    ```
+    Your agent's address is: agent1qfa53drat8rzau90u4494gx5mhj3v87tm4t5cuzkd7gkegxcm5vx5pku7kf
+    INFO:     [MailboxTestAgent]: Registering on almanac contract...
+    INFO:     [MailboxTestAgent]: Registering on almanac contract...complete
+    INFO:     [MailboxTestAgent]: Connecting to mailbox server at agentverse.ai
+    INFO:     [MailboxTestAgent]: Mailbox access token acquired
+    ```
+
+**Great! You have successfully registered your local agent on the Agentverse and Fetch Network using a Mailbox.**
+
+### Create Agents and Agent Functions using APIs
+
+If you wish to to create **Agents** and **Agent Functions** in Agentverse using APIs, head over to this [guide ↗️](/guides/apis/agent-function-creation-apis) which shows how set up a Python script that interacts with the Agentverse and helps you creating Agents and Agent Functions using APIs.
+
+## Next steps
+
+Now that you have a complete understanding on how to run agents on the Agentverse platform, you are ready to create your first [Agent Function ↗️](/guides/agents/intermediate/agent-functions), [Register it on the Agentverse ↗️](/guides/agentverse/agentverse-functions/registering-agent-services) and make it retrievable via [DeltaV ↗️](/concepts/ai-engine/deltav).