Merge branch 'main' into feat/agentverse-allowe-imports-guide-update

.github/spelling/known_words_corpus.txt

@@ -702,4 +702,10 @@ decentralised
 publicandprivateagents
 darkpublicandprivateagents
 highleveldiagram
-darkhighleveldiagram
+darkhighleveldiagram
+walkthrough
+asyncio
+asgi
+abstracteventloop
+ethan
+olivia

components/products.tsx

@@ -152,7 +152,7 @@ const items: { [key: string]: Item[] } = {
       title: "Analytics",
       description: <>Coming soon.</>,
       icon: analyticsIcon,
-      path: "/guides",
+      path: "",
     },
   ],
   "Agentverse components": [

pages/apis/agentverse/_meta.json

@@ -0,0 +1,5 @@
+{
+  "almanac": { "title": "Almanac APIs", "timestamp": true },
+  "hosting": { "title": "Hosting APIs", "timestamp": true },
+  "mailroom": { "title": "Mailroom APIs", "timestamp": true }
+}

pages/guides/agent-courses/agents-for-ai.mdx

@@ -507,7 +507,7 @@ Let's take a look.
 	summaryAgent.include(summary_protocol, publish_manifest=True)
 	summaryAgent.run()
 
-    ```
+```
 </DocsCode>
 
 </CodeGroup>

pages/guides/agents/advanced/register-in-almanac.mdx

@@ -78,11 +78,13 @@ Make sure you have read the following resources before going on with this guide:
 
 	agent.run()
 
-    ```
+```
 </DocsCode>
 
 </CodeGroup>
 
+
+
 There's a few things happening in this script; we initialize Alice with an endpoint. An endpoint is the address in which other agents can send messages to where Alice will be listening. As highlighted in [Registration and Endpoints Weighting ↗️](/references/contracts/uagents-almanac/endpoints), agents can communicate by querying the Almanac and retrieving an endpoint from the recipient agent. Therefore, we need to specify the service endpoints when defining our agents.
 
 We also have to define `agent.run()`. This `.run()` function runs the agent, but more importantly this registers the agent to the Almanac when code is initialized.

pages/guides/agents/getting-started/whats-an-agent.mdx

@@ -24,7 +24,6 @@ The **uAgents Framework** is a lightweight library designed to facilitate the de
   alt="agents-interacting"
 />
 
-
 Agents are autonomous software program built using the uAgents framework and that can interact autonomously with other agents in a decentralized environment. These agents can operate in a decentralized manner, but their decentralization remains optional and dependent on individual preferences or needs.
 
 Intelligent agents can fundamentally change the way we see complicated systems. For example, supply chain management could deploy Agents using the uAgents Framework to improve operations at various stages. Demand forecasting, inventory control, logistics optimization, supplier relationships monitoring, quality control and risk mitigation in all areas can be done with their help. Agents could transform supply chain operations by increasing efficiency, reducing costs, improving accuracy and providing real-time visibility.

pages/guides/agents/intermediate/_meta.json

@@ -34,6 +34,11 @@
     "tags": ["Intermediate", "Python", "Communication", "Mailbox"],
     "timestamp": true
   },
+  "local-agent-inspector": {
+    "title": "Local Agent Inspector",
+    "tags": ["Intermediate", "Python", "Agents"],
+    "timestamp": true
+  },
   "agent-functions": {
     "title": "Agent Functions",
     "tags": ["Intermediate", "Python", "Functions", "AI Engine"],
@@ -68,5 +73,15 @@
     "title": "REST endpoints",
     "tags": ["Intermediate", "Python", "REST API", "HTTP Protocols"],
     "timestamp": true
+  },
+  "bureau": {
+    "title": "Bureau",
+    "tags": ["Intermediate", "Python", "Bureau"],
+    "timestamp": true
+  },
+  "broadcast": {
+    "title": "Broadcast",
+    "tags": ["Intermediate", "Python", "Broadcast"],
+    "timestamp": true
   }
 }

pages/guides/agents/intermediate/broadcast.mdx

@@ -0,0 +1,209 @@
+import {CodeGroup, DocsCode} from "components/code";
+
+# Broadcast
+
+## Introduction to `ctx.broadcast()`
+
+The `ctx.broadcast()` function is used within an agent to send a message to all other agents that support a specific protocol. It is a powerful method when you want to communicate with multiple agents at once without knowing their addresses beforehand. This is especially useful in systems where many agents may be participating in the same protocol, and you want to notify or query all of them simultaneously.
+
+Let's get started!
+
+## Prerequisites
+
+Make sure you have read the following resources before going on with this guide:
+
+    - [Quick Start Guide for uAgents Framework ↗️](/guides/agents/quickstart)
+    - [Creating your first agent ↗️](/guides/agents/getting-started/create-a-uagent)
+    - [Agents address ↗️](/guides/agents/getting-started/getting-uagent-address)
+    - [Almanac contract ↗️](/concepts/fetch-network/almanac)
+    - [Register in Almanac ↗️](/guides/agents/register-in-almanac)
+
+## Imports needed
+
+    - [uAgents ↗️](https://pypi.org/project/uagents/)
+
+## Bureau Walkthrough
+
+### Overview
+
+In this guide, we will create a multi-agent broadcast system using the `uagents` library. Three agents will be initialized: Ethan, Olivia, and Liam. Ethan and Olivia will support a defined communication protocol, while Liam will broadcast a message to all agents supporting this protocol and handle their responses. We’ll use `ctx.broadcast` to manage communication between agents and demonstrate the structure of message handling within the context of the `uagents` framework.
+
+### Step 1: Import Classes and Initialize Agents
+
+```py
+from uagents import Agent, Bureau, Context, Model, Protocol
+
+ethan = Agent(name="ethan", seed="ethan recovery phrase")
+olivia = Agent(name="olivia", seed="olivia recovery phrase")
+liam = Agent(name="liam", seed="liam recovery phrase")
+
+```
+In this step, we import the core classes needed to define agents, protocols, and message handling. We then initialize three agents: Ethan, Olivia, and Liam, each with unique seed phrases, ensuring fixed addresses for their identities.
+
+### Step 2: Define Message Models
+
+```py
+class BroadcastExampleRequest(Model):
+    pass
+
+class BroadcastExampleResponse(Model):
+    text: str
+
+```
+
+We define two message models:
+
+- `BroadcastExampleRequest`: This model represents a request message (empty for now).
+- `BroadcastExampleResponse`: This model holds a response message containing a text field.
+
+
+### Step 3: Define a Communication Protocol
+
+```py
+proto = Protocol(name="proto", version="1.0")
+
+```
+
+A protocol named proto with version 1.0 is defined. This protocol will govern communication between agents that support it.
+
+### Step 5: Message Handler for Broadcast Requests
+
+```py
+
+@proto.on_message(model=BroadcastExampleRequest, replies=BroadcastExampleResponse)
+async def handle_request(ctx: Context, sender: str, _msg: BroadcastExampleRequest):
+    await ctx.send(
+        sender, BroadcastExampleResponse(text=f"Hello from {ctx.agent.name}")
+    )
+
+```
+
+This function handles incoming `BroadcastExampleRequest` messages. When an agent (e.g., Ethan or Olivia) receives a request, it replies with a `BroadcastExampleResponse`, sending a message containing its own name.
+
+
+### Step 6: Include the Protocol in Agents
+
+```py
+ethan.include(proto)
+olivia.include(proto)
+
+```
+
+We include the protocol in Ethan and Olivia. This allows them to participate in communication governed by the `proto` protocol.
+
+### Step 7: Liam's Behavior - Broadcasting and Handling Responses
+
+```py
+@liam.on_interval(period=5)
+async def say_hello(ctx: Context):
+    status_list = await ctx.broadcast(proto.digest, message=BroadcastExampleRequest())
+    ctx.logger.info(f"Trying to contact {len(status_list)} agents.")
+
+```
+
+The `say_hello` function is executed by Liam every 5 seconds (using `on_interval`). Liam sends a `BroadcastExampleRequest` message to all agents supporting the `proto` protocol via `ctx.broadcast`. The `proto.digest` is used to identify the protocol.
+
+```py
+@liam.on_message(model=BroadcastExampleResponse)
+async def handle_response(ctx: Context, sender: str, msg: BroadcastExampleResponse):
+    ctx.logger.info(f"Received response from {sender}: {msg.text}")
+
+
+```
+
+When Liam receives a BroadcastExampleResponse, the handle_response function logs the sender and the content of the message.
+
+### Step 8: Run the Bureau
+
+```py
+bureau = Bureau(port=8000, endpoint="http://localhost:8000/submit")
+bureau.add(ethan)
+bureau.add(olivia)
+bureau.add(liam)
+
+if __name__ == "__main__":
+    bureau.run()
+
+```
+
+## Explanation of ctx.broadcast
+
+The broadcast() method in the Context class allows an agent to send a message to multiple agents that support a specific protocol. Here's a detailed look at its usage:
+
+`status_list = await ctx.broadcast(proto.digest, message=BroadcastExampleRequest())`
+
+- `proto.digest`: This is a unique identifier for the protocol that the message will be sent under. Only agents supporting this protocol will receive the broadcast.
+- `message`: The message being broadcast, in this case, a BroadcastExampleRequest.
+- `status_list`: This is a list of statuses returned by the broadcast, indicating which agents were successfully contacted.
+
+By calling broadcast, Liam attempts to contact all agents supporting the proto protocol. This communication is asynchronous and can target multiple agents concurrently.
+
+The overall script for this example should look as follows:
+
+<CodeGroup hasCopy isLocalHostedFile>
+    <DocsCode local={true}>
+
+    ```py filename="broadcast-agent.py"
+    from uagents import Agent, Bureau, Context, Model, Protocol
+
+    ethan = Agent(name="ethan", seed="ethan recovery phrase")
+    olivia = Agent(name="olivia", seed="olivia recovery phrase")
+    liam = Agent(name="liam", seed="liam recovery phrase")
+
+    class BroadcastExampleRequest(Model):
+        pass
+
+    class BroadcastExampleResponse(Model):
+        text: str
+
+    proto = Protocol(name="proto", version="1.0")
+
+    @proto.on_message(model=BroadcastExampleRequest, replies=BroadcastExampleResponse)
+    async def handle_request(ctx: Context, sender: str, _msg: BroadcastExampleRequest):
+        await ctx.send(
+            sender, BroadcastExampleResponse(text=f"Hello from {ctx.agent.name}")
+        )
+
+    ethan.include(proto)
+    olivia.include(proto)
+
+    @liam.on_interval(period=5)
+    async def say_hello(ctx: Context):
+        status_list = await ctx.broadcast(proto.digest, message=BroadcastExampleRequest())
+        ctx.logger.info(f"Trying to contact {len(status_list)} agents.")
+
+    @liam.on_message(model=BroadcastExampleResponse)
+    async def handle_response(ctx: Context, sender: str, msg: BroadcastExampleResponse):
+        ctx.logger.info(f"Received response from {sender}: {msg.text}")
+
+    bureau = Bureau(port=8000, endpoint="http://localhost:8000/submit")
+    bureau.add(ethan)
+    bureau.add(olivia)
+    bureau.add(liam)
+
+    if __name__ == "__main__":
+        bureau.run()
+
+    ```
+    </DocsCode>
+</CodeGroup>
+
+
+We are now ready to run the script: `python broadcast-agent.py`
+
+The output would be:
+
+    ```
+    INFO:     [ethan]: Registration on Almanac API successful
+    INFO:     [ethan]: Almanac contract registration is up to date!
+    INFO:     [olivia]: Registration on Almanac API successful
+    INFO:     [olivia]: Almanac contract registration is up to date!
+    INFO:     [ liam]: Registration on Almanac API successful
+    INFO:     [ liam]: Almanac contract registration is up to date!
+    INFO:     [bureau]: Starting server on http://0.0.0.0:8000 (Press CTRL+C to quit)
+    INFO:     [ liam]: Trying to contact 4 agents.
+    INFO:     [ liam]: Received response from agent1q2hdqe8hxa6g0awspktktgc5furywq5jur5q9whh9hzyffxsm9ka6c2dmhz: Hello from olivia
+    INFO:     [ liam]: Received response from agent1qff9zl5cehj2z68zef7q68uw76jjslh2r8xda93avayedqajzjwwyce8pt9: Hello from ethan
+
+
+    ```