feat(docs): minor updates, add jupyter example (#1028)

Co-authored-by: Joshua Croft <[email protected]> Co-authored-by: Felix Nicolae Bucsa <[email protected]>
fetchai · Nov 8, 2024 · 5e30e75 · 5e30e75
1 parent b92abbc
commit 5e30e75
Show file tree

Hide file tree

Showing 7 changed files with 401 additions and 25 deletions.
diff --git a/.github/spelling/known_words_corpus.txt b/.github/spelling/known_words_corpus.txt
@@ -712,6 +712,7 @@ olivia
 hackathon
 onboarded
 CI
+jupyter
 streamlit
 bot
 screenshots

diff --git a/pages/examples/_meta.json b/pages/examples/_meta.json
@@ -3,9 +3,10 @@
     "title": "Getting Started"
   },
   "intermediate": {
-    "title": "Intermediate topics"
+    "title": "Intermediate Topics"
   },
   "advanced": {
     "title": "Advanced Topics"
-  }
+  },
+  "jupyter-agent": "Jupyter Notebook Agent"
 }
diff --git a/pages/examples/jupyter-agent.mdx b/pages/examples/jupyter-agent.mdx
@@ -0,0 +1,312 @@
+import { CodeGroup, CodeSegment, DocsCode, GithubCodeSegment } from "../../components/code";
+
+# 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.
+
+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.
+
+## Installation
+
+We're using [poetry](https://python-poetry.org/) to manage our application, but it is not super essential for you. Just be sure to have the following libraries installed on your system:
+
+    ```bash
+        python = "3.11"
+        uagents = "^0.17.1"
+        notebook = "^7.2.2"
+        jupyter = "^1.1.1"
+    ```
+
+Are you new to Agents? To understand the agent in this example, please read [communicating with agents ↗️](/guides/agents/intermediate/communicating-with-other-agents)
+
+## Notebook
+
+<GithubCodeSegment digest="964b533f69f19c4c4e407ce900471ab4">
+    <CodeSegment
+        path="https://github.com/fetchai/uAgent-Examples/blob/main/5-documentation/jupyter-notebook/agent_in_notebook.ipynb"
+        lineStart={1}
+        lineEnd={223}
+        hosted={true}
+    />
+</GithubCodeSegment>
+<CodeGroup dynamic hasCopy isLocalHostedFile digest='964b533f69f19c4c4e407ce900471ab4'>
+
+<DocsCode local={true}>
+	```py copy filename="agent_in_notebook.ipynb"
+
+	{
+	 "cells": [
+	  {
+	   "cell_type": "code",
+	   "execution_count": 34,
+	   "id": "790cab08-020a-4903-80f5-10392785944a",
+	   "metadata": {},
+	   "outputs": [],
+	   "source": [
+	    "from uagents import Agent, Context, Model\n",
+	    "from uagents.setup import fund_agent_if_low\n",
+	    "import os\n",
+	    "import asyncio\n",
+	    "import contextlib"
+	   ]
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": 35,
+	   "id": "ff526b8f-5e08-47c9-af87-80cdd6eba972",
+	   "metadata": {},
+	   "outputs": [],
+	   "source": [
+	    "# comment "
+	   ]
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": 36,
+	   "id": "85aae090-2724-4bde-9f7c-e593135a410f",
+	   "metadata": {},
+	   "outputs": [
+	    {
+	     "name": "stdout",
+	     "output_type": "stream",
+	     "text": [
+	      "<_UnixSelectorEventLoop running=True closed=False debug=False>\n"
+	     ]
+	    }
+	   ],
+	   "source": [
+	    "loop = asyncio.get_event_loop()\n",
+	    "print (loop)"
+	   ]
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": 37,
+	   "id": "a09b9f72-5b41-486f-95df-900233a2742a",
+	   "metadata": {},
+	   "outputs": [
+	    {
+	     "name": "stdout",
+	     "output_type": "stream",
+	     "text": [
+	      "agent1qdwgulp6q2jw93u3yhh9teectdjaxvrmmwl900cs33vz4skkawstg3q74n4\n"
+	     ]
+	    }
+	   ],
+	   "source": [
+	    "agent = Agent(\n",
+	    "    name=\"first_agent\",\n",
+	    "    seed=\"AGENT_1_SEED\",\n",
+	    "    endpoint=[\"http://127.0.0.1:8005/submit\"],\n",
+	    "    port=8005)\n",
+	    "\n",
+	    "SECOND_AGENT_ADDRESS = (\n",
+	    "    \"agent1qdceynp4t0lel3cfdlvlezjva8tf6fww8jd97vs9ym2h3g678e65vjj8vjh\"\n",
+	    ")\n",
+	    "\n",
+	    "print (agent.address)\n"
+	   ]
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": 38,
+	   "id": "15182730-93b4-41a5-878b-674be50c240e",
+	   "metadata": {},
+	   "outputs": [],
+	   "source": [
+	    "class ResponseMessage(Model):\n",
+	    "    text: str\n"
+	   ]
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": 39,
+	   "id": "e83d7f83-58a5-4e54-995d-30aca419128f",
+	   "metadata": {},
+	   "outputs": [],
+	   "source": [
+	    "@agent.on_event(\"startup\")\n",
+	    "async def on_startup(ctx: Context):\n",
+	    "    message = ResponseMessage(text=\"Hello from first agent\")\n",
+	    "    await ctx.send(SECOND_AGENT_ADDRESS, message)\n",
+	    "\n",
+	    "\n",
+	    "@agent.on_message(model=ResponseMessage)\n",
+	    "async def handle_message(ctx: Context, sender: str, msg: ResponseMessage):\n",
+	    "    ctx.logger.info(f\"Received message from {sender}: {msg.text}\")\n",
+	    "    "
+	   ]
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": 40,
+	   "id": "a685d22f-f8b0-4026-812c-855ecdcf87ea",
+	   "metadata": {},
+	   "outputs": [
+	    {
+	     "name": "stdout",
+	     "output_type": "stream",
+	     "text": [
+	      "<uagents.agent.Agent object at 0x11282ea90>\n"
+	     ]
+	    }
+	   ],
+	   "source": [
+	    "print(agent)"
+	   ]
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": 41,
+	   "id": "ba14c679-f6a5-4ccf-9023-62e1de12b806",
+	   "metadata": {},
+	   "outputs": [
+	    {
+	     "data": {
+	      "text/plain": [
+	       "<Task pending name='Task-39' coro=<Agent.run_async() running at /Users/joshuacroft/Library/Caches/pypoetry/virtualenvs/jp-FhiL5LrG-py3.11/lib/python3.11/site-packages/uagents/agent.py:1170>>"
+	      ]
+	     },
+	     "execution_count": 41,
+	     "metadata": {},
+	     "output_type": "execute_result"
+	    },
+	    {
+	     "name": "stdout",
+	     "output_type": "stream",
+	     "text": [
+	      "INFO:     [first_agent]: Registration on Almanac API successful\n",
+	      "INFO:     [first_agent]: Registration on Almanac API successful\n",
+	      "INFO:     [first_agent]: Registration on Almanac API successful\n",
+	      "INFO:     [first_agent]: Registration on Almanac API successful\n",
+	      "INFO:     [first_agent]: Registration on Almanac API successful\n",
+	      "INFO:     [first_agent]: Registration on Almanac API successful\n",
+	      "INFO:     [first_agent]: Almanac contract registration is up to date!\n",
+	      "INFO:     [first_agent]: Almanac contract registration is up to date!\n",
+	      "INFO:     [first_agent]: Almanac contract registration is up to date!\n",
+	      "INFO:     [first_agent]: Almanac contract registration is up to date!\n",
+	      "INFO:     [first_agent]: Almanac contract registration is up to date!\n",
+	      "INFO:     [first_agent]: Almanac contract registration is up to date!\n",
+	      "ERROR:    [first_agent]: Unable to resolve destination endpoint\n",
+	      "ERROR:    [first_agent]: Unable to resolve destination endpoint\n",
+	      "ERROR:    [first_agent]: Unable to resolve destination endpoint\n",
+	      "ERROR:    [first_agent]: Unable to resolve destination endpoint\n",
+	      "ERROR:    [first_agent]: Unable to resolve destination endpoint\n",
+	      "ERROR:    [first_agent]: Unable to resolve destination endpoint\n",
+	      "INFO:     [first_agent]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8005&address=agent1qdwgulp6q2jw93u3yhh9teectdjaxvrmmwl900cs33vz4skkawstg3q74n4\n",
+	      "INFO:     [first_agent]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8005&address=agent1qdwgulp6q2jw93u3yhh9teectdjaxvrmmwl900cs33vz4skkawstg3q74n4\n",
+	      "INFO:     [first_agent]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8005&address=agent1qdwgulp6q2jw93u3yhh9teectdjaxvrmmwl900cs33vz4skkawstg3q74n4\n",
+	      "INFO:     [first_agent]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8005&address=agent1qdwgulp6q2jw93u3yhh9teectdjaxvrmmwl900cs33vz4skkawstg3q74n4\n",
+	      "INFO:     [first_agent]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8005&address=agent1qdwgulp6q2jw93u3yhh9teectdjaxvrmmwl900cs33vz4skkawstg3q74n4\n",
+	      "INFO:     [first_agent]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8005&address=agent1qdwgulp6q2jw93u3yhh9teectdjaxvrmmwl900cs33vz4skkawstg3q74n4\n",
+	      "INFO:     [first_agent]: Starting server on http://0.0.0.0:8005 (Press CTRL+C to quit)\n",
+	      "INFO:     [first_agent]: Starting server on http://0.0.0.0:8005 (Press CTRL+C to quit)\n",
+	      "INFO:     [first_agent]: Starting server on http://0.0.0.0:8005 (Press CTRL+C to quit)\n",
+	      "INFO:     [first_agent]: Starting server on http://0.0.0.0:8005 (Press CTRL+C to quit)\n",
+	      "INFO:     [first_agent]: Starting server on http://0.0.0.0:8005 (Press CTRL+C to quit)\n",
+	      "INFO:     [first_agent]: Starting server on http://0.0.0.0:8005 (Press CTRL+C to quit)\n",
+	      "INFO:     [first_agent]: Received message from agent1qgdefk0mewtn88dj5nu05lkwtxd3jedn9g8lw7jttrkz9c09l37lqnhs5zt: Hello from first agent\n",
+	      "INFO:     [first_agent]: Received message from agent1qgdefk0mewtn88dj5nu05lkwtxd3jedn9g8lw7jttrkz9c09l37lqnhs5zt: Hello from first agent\n",
+	      "INFO:     [first_agent]: Received message from agent1qgdefk0mewtn88dj5nu05lkwtxd3jedn9g8lw7jttrkz9c09l37lqnhs5zt: Hello from first agent\n",
+	      "INFO:     [first_agent]: Received message from agent1qgdefk0mewtn88dj5nu05lkwtxd3jedn9g8lw7jttrkz9c09l37lqnhs5zt: Hello from first agent\n",
+	      "INFO:     [first_agent]: Received message from agent1qgdefk0mewtn88dj5nu05lkwtxd3jedn9g8lw7jttrkz9c09l37lqnhs5zt: Hello from first agent\n",
+	      "INFO:     [first_agent]: Received message from agent1qgdefk0mewtn88dj5nu05lkwtxd3jedn9g8lw7jttrkz9c09l37lqnhs5zt: Hello from first agent\n"
+	     ]
+	    }
+	   ],
+	   "source": [
+	    "loop.create_task(agent.run_async())"
+	   ]
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": null,
+	   "id": "7a62d5e8-71f4-4a11-9e7c-f37ee6777891",
+	   "metadata": {},
+	   "outputs": [],
+	   "source": []
+	  },
+	  {
+	   "cell_type": "code",
+	   "execution_count": null,
+	   "id": "a483bc10-4861-4472-abc8-197db30a4b02",
+	   "metadata": {},
+	   "outputs": [],
+	   "source": []
+	  }
+	 ],
+	 "metadata": {
+	  "kernelspec": {
+	   "display_name": "Python 3 (ipykernel)",
+	   "language": "python",
+	   "name": "python3"
+	  },
+	  "language_info": {
+	   "codemirror_mode": {
+	    "name": "ipython",
+	    "version": 3
+	   },
+	   "file_extension": ".py",
+	   "mimetype": "text/x-python",
+	   "name": "python",
+	   "nbconvert_exporter": "python",
+	   "pygments_lexer": "ipython3",
+	   "version": "3.11.0"
+	  }
+	 },
+	 "nbformat": 4,
+	 "nbformat_minor": 5
+	}
+
+```
+</DocsCode>
+
+</CodeGroup>
+
+
+
+## Run this file
+
+If you are using Poetry, then run:
+
+```
+poetry run jupyter notebook
+```
+
+Else, from Pip:
+
+```
+jupyter notebook
+```
+
+## Testing
+
+To test your Agent running in a Jupyter notebook, let's run the second Agent:
+
+```
+python agent.py
+```
+
+### Expected output
+
+In Jupyter:
+
+```
+INFO:     [first_agent]: Registration on Almanac API successful
+INFO:     [first_agent]: Registering on almanac contract... 
+INFO:     [first_agent]: Registering on almanac contract...complete
+ERROR:    [first_agent]: Unable to resolve destination endpoint
+INFO:     [first_agent]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8005&address=agent1qdwgulp6q2jw93u3yhh9teectdjaxvrmmwl900cs33vz4skkawstg3q74n4
+INFO:     [first_agent]: Starting server on http://0.0.0.0:8005 (Press CTRL+C to quit)
+INFO:     [first_agent]: Received message from agent1qgdefk0mewtn88dj5nu05lkwtxd3jedn9g8lw7jttrkz9c09l37lqnhs5zt: Hello from first agent
+```
+
+From Command Line Python Agent:
+
+```
+INFO:     [jupyter_test_agent]: Registration on Almanac API successful
+INFO:     [jupyter_test_agent]: Registering on almanac contract... 
+INFO:     [jupyter_test_agent]: Registering on almanac contract...complete
+INFO:     [jupyter_test_agent]: Agent inspector available at https://agentverse.ai/inspect/?uri=http%3A//127.0.0.1%3A8009&address=agent1qgdefk0mewtn88dj5nu05lkwtxd3jedn9g8lw7jttrkz9c09l37lqnhs5zt
+INFO:     [jupyter_test_agent]: Starting server on http://0.0.0.0:8009 (Press CTRL+C to quit)
+```