feat(docs): examples flow updates (#1040)

Co-authored-by: Joshua Croft <[email protected]>
Co-authored-by: Felix Nicolae Bucsa <[email protected]>

pages/examples/_meta.json

@@ -1,12 +1,15 @@
 {
-  "getting-started": {
-    "title": "Getting Started"
+  "easy": {
+    "title": "Easy Topics"
   },
   "intermediate": {
     "title": "Intermediate Topics"
   },
   "advanced": {
     "title": "Advanced Topics"
   },
-  "jupyter-agent": "Jupyter Notebook Agent"
+  "jupyter-agent": "Jupyter Notebook Agent",
+  "hugging-face-agent": "Hugging Face Agent",
+  "postgres-database-wigh-an-agent": "Postgres DB Integration",
+  "react_example": "React web app Agent"
 }

pages/examples/easy/_meta.json

@@ -0,0 +1,27 @@
+{
+  "first-agent": {
+    "title": "Create your first agent",
+    "tags": ["Agents", "Beginner", "Installation"],
+    "timestamp": true
+  },
+  "agents-interval-task": {
+    "title": "Interval task with Agents",
+    "tags": ["Intermediate", "Python", "Handlers", "Use Cases"],
+    "timestamp": true
+  },
+  "local-communication": {
+    "title": "Local Network communication",
+    "tags": ["Intermediate", "Python", "Communication", "Use Cases"],
+    "timestamp": true
+  },
+  "simple-agent-communication-with-bureau": {
+    "title": "Bureau Agents communication",
+    "tags": ["Intermediate", "Python", "Communication", "Use Cases"],
+    "timestamp": true
+  },
+  "storage": {
+    "title": "Agents storage",
+    "tags": ["Intermediate", "Python", "Storage", "Use Cases"],
+    "timestamp": true
+  }
+}

pages/examples/intermediate/hugging-face-agent.mdx → pages/examples/hugging-face-agent.mdx

@@ -1,4 +1,4 @@
-import { CodeGroup, DocsCode } from "../../../components/code"
+import { CodeGroup, DocsCode } from "../../components/code"
 
 # Hugging face API agent as a Function
 

pages/examples/intermediate/_meta.json

@@ -1,27 +1,54 @@
 {
-  "agents-interval-task": {
-    "title": "Interval task with Agents",
-    "tags": ["Intermediate", "Python", "Handlers", "Use Cases"],
+  "broadcast": {
+    "title": "Agents Broadcast",
+    "tags": ["Intermediate", "Python", "Communication", "Use Cases"],
     "timestamp": true
   },
   "multiple-agents": {
     "title": "Multiple agents communication",
     "tags": ["Intermediate", "Python", "Communication", "Use Cases"],
     "timestamp": true
   },
-  "local-communication": {
-    "title": "Local Network Interaction",
-    "tags": ["Intermediate", "Python", "Communication", "Use Cases"],
+  "mailbox-agents": {
+    "title": "Agents communication using Agentverse Mailbox service",
+    "tags": ["Intermediate", "Python", "Communication", "Mailbox"],
     "timestamp": true
   },
-  "simple-agent-communication": {
-    "title": "Agents communication",
-    "tags": ["Intermediate", "Python", "Communication", "Use Cases"],
+
+  "on-query-proxy": {
+    "title": "Query an agent using a proxy API",
+    "tags": ["Intermediate", "Python", "Communication", "FastAPI", "Proxy"],
     "timestamp": true
   },
-  "storage": {
-    "title": "Agents storage",
-    "tags": ["Intermediate", "Python", "Storage", "Use Cases"],
+  "dice-roll": {
+    "title": "Register a dice roll agent as a Function",
+    "tags": ["Intermediate", "Python", "Functions", "DeltaV"],
+    "timestamp": true
+  },
+  "coin-toss": {
+    "title": "Register a coin toss agent as a Function",
+    "tags": ["Intermediate", "Python", "Functions", "DeltaV"],
+    "timestamp": true
+  },
+
+  "on_query_example": {
+    "title": "Shopping Assistance Agent using on_query ",
+    "tags": ["Intermediate", "Python", "Functions", "OpenAI", "Use Cases"],
+    "timestamp": true
+  },
+  "agents-with-docker": {
+    "title": "Running an Agent with Docker",
+    "tags": ["Intermediate", "Python", "Docker", "Use Cases"],
+    "timestamp": true
+  },
+  "postgres-database-with-an-agent": {
+    "title": "Utilize the PostgreSQL database with the Agent.",
+    "tags": ["Intermediate", "Python", "Docker", "PostgreSQL", "Use Cases"],
+    "timestamp": true
+  },
+  "local-agent-registration": {
+    "title": "Register a local agent as a Function",
+    "tags": ["Intermediate", "Python", "Functions", "Agentverse"],
     "timestamp": true
   },
   "table-booking-demo": {
@@ -34,11 +61,13 @@
     "tags": ["Intermediate", "Python", "Use Cases"],
     "timestamp": true
   },
+
   "send-tokens-agents": {
     "title": "Send tokens with Agents",
     "tags": ["Intermediate", "Python", "Use Cases"],
     "timestamp": true
   },
+
   "verify-messages": {
     "title": "Verify messages with Agents",
     "tags": ["Intermediate", "Python", "Communication", "Use Cases"],
@@ -49,41 +78,13 @@
     "tags": ["Intermediate", "Python", "Communication", "Wallet"],
     "timestamp": true
   },
-  "mailbox-agents": {
-    "title": "Agents communication using Agentverse Mailbox service",
-    "tags": ["Intermediate", "Python", "Communication", "Mailbox"],
-    "timestamp": true
-  },
-  "broadcast": {
-    "title": "Agents Broadcast",
-    "tags": ["Intermediate", "Python", "Communication", "Use Cases"],
-    "timestamp": true
-  },
+
   "name-service": {
     "title": "Agents Name Service",
     "tags": ["Intermediate", "Python", "Name Service"],
     "timestamp": true
   },
-  "on-query-proxy": {
-    "title": "Query an agent using a proxy API",
-    "tags": ["Intermediate", "Python", "Communication", "FastAPI", "Proxy"],
-    "timestamp": true
-  },
-  "dice-roll": {
-    "title": "Register a dice roll agent as a Function",
-    "tags": ["Intermediate", "Python", "Functions", "DeltaV"],
-    "timestamp": true
-  },
-  "coin-toss": {
-    "title": "Register a coin toss agent as a Function",
-    "tags": ["Intermediate", "Python", "Functions", "DeltaV"],
-    "timestamp": true
-  },
-  "local-agent-registration": {
-    "title": "Register a local agent as a Function",
-    "tags": ["Intermediate", "Python", "Functions", "Agentverse"],
-    "timestamp": true
-  },
+
   "news-reading-system": {
     "title": "Using News API to build network of Primary and Secondary functions",
     "tags": ["Intermediate", "Python", "Functions", "AI Engine"],
@@ -129,21 +130,7 @@
     "tags": ["Intermediate", "Python", "Functions", "LangChain", "DeltaV"],
     "timestamp": true
   },
-  "on_query_example": {
-    "title": "Shopping Assistance Agent using on_query ",
-    "tags": ["Intermediate", "Python", "Functions", "OpenAI", "Use Cases"],
-    "timestamp": true
-  },
-  "agents-with-docker": {
-    "title": "Running an Agent with Docker",
-    "tags": ["Intermediate", "Python", "Docker", "Use Cases"],
-    "timestamp": true
-  },
-  "postgres-database-with-an-agent": {
-    "title": "Utilize the PostgreSQL database with the Agent.",
-    "tags": ["Intermediate", "Python", "Docker", "PostgreSQL", "Use Cases"],
-    "timestamp": true
-  },
+
   "sending-and-verifying-token-transactions-with-agent": {
     "title": "Sending and verifying token transactions with agent",
     "tags": [

pages/examples/jupyter-agent.mdx

@@ -2,7 +2,7 @@ import { CodeGroup, CodeSegment, DocsCode, GithubCodeSegment } from "../../compo
 
 # Using Jupyter notebook to build an Agent
 
-**Jupyter notebook** natively supports asyncio, and as Agents ↗️](/guides/agents/getting-started/whats-an-agent) are asynchronous by design, Jupyter and Agents work together with ease.
+**Jupyter notebook** natively supports asyncio, and as [Agents ↗️](/guides/agents/getting-started/whats-an-agent) are asynchronous by design, Jupyter and Agents work together with ease.
 
 Please check out the example code in our [examples repo ↗️](https://github.com/fetchai/uAgent-Examples/tree/main/5-documentation/jupyter-notebook) to run this locally.
 

pages/examples/intermediate/postgres-database-with-an-agent.mdx → pages/examples/postgres-database-with-an-agent.mdx

@@ -1,4 +1,4 @@
-import { CodeGroup, DocsCode } from "../../../components/code"
+import { CodeGroup, DocsCode } from "../../components/code"
 
 # Utilize the PostgreSQL database with the Agent
 

pages/examples/intermediate/react_example.mdx → pages/examples/react-example.mdx

@@ -1,5 +1,5 @@
 import { Callout } from 'nextra/components' 
-import { CodeGroup, DocsCode } from "../../../components/code"
+import { CodeGroup, DocsCode } from "../../components/code"
 
 # React app with agents 'on_query' decorator
 

pages/guides/agents/intermediate/_meta.json

@@ -4,6 +4,11 @@
     "tags": ["Intermediate", "Python", "Communication"],
     "timestamp": true
   },
+  "protocols": {
+    "title": "Protocols",
+    "tags": ["Intermediate", "Python", "Communication"],
+    "timestamp": true
+  },
   "handlers": {
     "title": "Agent Handlers (on_...)",
     "tags": ["Intermediate", "Python", "Handlers"],

pages/guides/agents/intermediate/protocols.mdx

@@ -0,0 +1,87 @@
+import { Callout } from 'nextra/components'
+import { CodeGroup, DocsCode } from "../../../../components/code";
+
+# Agents protocols
+
+Within the uAgents Framework, `protocols` support capturing related message types and handlers.
+
+Protocols are used to facilitate communication and interaction between agents in the Framework.
+
+    <Callout type="info" emoji="ℹ️">
+      Indeed, any agent including the same protocol will be able to communicate with each other.
+    </Callout>
+
+A `protocol` is built similar to an agent, but it has no identity and cannot be run. Protocols only contains the message types and handlers that define some components of an agent's functionality.
+
+Let's use a _simple restaurant table booking request_ as an example to better understand what a protocol means and how to build one:
+
+1. Let's start by creating a folder for our **protocols**. Then, let's create Python script within it, and name it:
+
+   `mkdir protocols`
+
+   and
+
+<CodeGroup hasCopy isOSFile>
+<DocsCode mac={true}>
+```py copy filename="mac"
+touch book.py
+```
+</DocsCode>
+
+<DocsCode windows={true}>
+    ```py copy filename="windows"
+    echo. > book.py
+    ```
+    </DocsCode>
+
+<DocsCode ubuntu={true}>
+    ```py copy filename="ubuntu"
+    touch book.py
+    ```
+    </DocsCode>
+</CodeGroup>
+
+2. We import from `uagents` library the necessary classes `Context`, `Model`, and `Protocol`. Then, need to define the type of messages that the handler will receive and send:
+
+   ```py copy
+   from uagents import Context, Model, Protocol
+
+   class BookTableRequest(Model):
+       table_number: int
+
+   class BookTableResponse(Model):
+       success: bool
+   ```
+
+   We use the `Model` class from `uagents` library to define `BookTableRequest` and `BookTableResponse` classes for setting up the structure of messages to be exchanged between your agents. The `BookTableRequest` class represents a request to book a table, containing the desired table number, while the `BookTableResponse` class represents the response to that request, indicating whether the booking was successful.
+
+3. Now, we would need to define the booking protocol as `book_proto` and also define the desired logic to determine if the `BookTableResponse` will be successful or not:
+
+   ```py copy
+   book_proto = Protocol()
+
+   @book_proto.on_message(model=BookTableRequest, replies={BookTableResponse})
+   async def handle_book_request(ctx: Context, sender: str, msg: BookTableRequest):
+       if ctx.storage.has(str(msg.table_number)):
+           success = False
+       else:
+           success = True
+           ctx.storage.set(str(msg.table_number), sender)
+
+       # send the response
+       await ctx.send(sender, BookTableResponse(success=success))
+   ```
+
+4. We can then import our booking protocol from into the script we create for our agent, in the following way:
+
+   ```py copy
+   from protocols.book import book_proto
+   ```
+
+5. If your agent is called `restaurant` you can include the protocol in this way:
+
+   ```py copy
+   restaurant.include(book_proto)
+   ```
+
+For a better understanding of these concepts, consider having a look at the [Agents storage ↗️](/references/uagents/uagents-protocols/storage) and [Exchange protocol ↗️](/references/uagents/uagents-protocols/exchange-protocol) resources and consider going through the extensive [How to book a table at a restaurant using agents ↗️](/examples/table-booking-demo) guide in the [Agents guides ↗️](/guides#ai-agents) section. Also, checkout the [Agents: broadcast ↗️](/examples/broadcast) for an additional implementation of protocols in agents communication.