feat(docs): Adding guide for AVCTL hosting (#1023)

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

.github/spelling/known_words_corpus.txt

@@ -710,4 +710,5 @@ abstracteventloop
 ethan
 olivia
 hackathon
-onboarded
+onboarded
+CI

pages/guides/agentverse/avctl/_meta.json

@@ -1,12 +1,17 @@
 {
   "avctl": {
     "title": "Agentverse Command Line Interface (AVCTL)",
-    "tags": ["Intermediate", "Python", "Agentverse"],
+    "tags": ["Intermediate", "Python", "AVCTL", "Agentverse"],
     "timestamp": true
   },
   "avctl-hosting": {
     "title": "AVCTL Hosting commands",
-    "tags": ["Intermediate", "Python", "Agentverse"],
+    "tags": ["Intermediate", "Python", "AVCTL", "Agentverse"],
+    "timestamp": true
+  },
+  "avctl-ci-github": {
+    "title": "CI with AVCTL and Github Actions",
+    "tags": ["Intermediate", "Python", "AVCTL", "Agentverse", "Github"],
     "timestamp": true
   }
 }

pages/guides/agentverse/avctl/avctl-ci-github.mdx

@@ -0,0 +1,208 @@
+import { Callout } from 'nextra/components'
+import agentverse_secret from 'src/images/guides/agentverse/avctl/agentverse_secret.png';
+import github_secret from 'src/images/guides/agentverse/avctl/github_secret.png';
+import action from 'src/images/guides/agentverse/avctl/action.png';
+import { ImageByTheme } from "components/mdx"
+import {CodeGroup, CodeSegment, DocsCode, GithubCodeSegment} from "../../../../components/code";
+
+# CI with AVCTL and Github Actions
+
+This guide explains how we deploy an agent, or update a deployed agent on agentverse using AVCTL.
+
+## Structure
+
+We have a [GitHub repo](https://github.com/fetchai/avctl-ci-example) where you can template or clone this code.
+
+It is made up of three parts, but really two we have our deployment scripts in `.github/workflows` and in `scripts/` and our Agent is under `agent/`.
+
+    ```
+    ├── README.md
+    ├── .github
+    │    └── workflows
+    │        └── deploy-agent.yaml
+    ├── agent
+    │    ├── README.md
+    │    ├── agent.py
+    │    ├── poetry.lock
+    |    └── pyproject.toml
+    └── scripts
+        └── deploy-agent.sh
+    ```
+
+This logic is very simple, we have a Github workflow that triggers when the branch main is updated. It then calls the
+deployment script in `scripts/deploy-agent.sh`; this script first checks if the Agent already has an address defined in `.avctl/config.toml`; in case it does, is this agent registered? If it isn't, we proceed and register this agent. 
+
+If it is registered, let's stop the remote Agent and update it.
+
+You can see the deploy script below, or on [Github](https://github.com/fetchai/avctl-ci-example/blob/main/scripts/deploy-agent.sh)
+
+   <GithubCodeSegment digest="d6ffbd71cd64db449cca201ec19d7eff">
+       <CodeSegment
+           path="https://github.com/fetchai/avctl-ci-example/blob/main/scripts/deploy-agent.sh"
+           lineStart={1}
+           lineEnd={52}
+           hosted={true}
+       />
+   </GithubCodeSegment>
+<CodeGroup dynamic hasCopy isLocalHostedFile digest='d6ffbd71cd64db449cca201ec19d7eff'>
+
+<DocsCode local={true}>
+	```py copy filename="deploy-agent.sh"
+
+	# Define the function
+	get_agent_address() {
+	  local file=".avctl/config.toml "
+
+	  # Check if the file exists
+	  if [ -f "$file" ]; then
+	    # Extract the address value
+	    agent_address=$(grep 'address =' "$file" | sed -E 's/.*= "(.*)"/\1/')
+
+	    # Check if the address is not empty
+	    if [ -n "$agent_address" ]; then
+	      echo $agent_address
+	    else
+	      echo ""
+	    fi
+	  else
+	    echo ""
+	  fi
+	}
+
+	# Define the specific directory to work on
+	defined_directory="agent/"
+
+	# Change to the specified agent directory
+	cd "$defined_directory"
+
+	# Create a .staging.avctl folder for new agents if it doesn't exist
+	avctl hosting init
+
+	# get the agent address if it exists
+	agent_address=$(get_agent_address)
+
+	# Get the agent's name from the README.md top line header
+	agent_name=$(head -n 1 README.md | sed -e 's/#//g' | xargs)
+
+
+	# If the address exists...
+	if [ -n "$agent_address" ]; then
+	  avctl hosting get agent -a "$agent_address"
+	  response=$(avctl hosting get agent -a "$agent_address")\
+
+	  # Check if the agent is already in existence, if it isn't, deploy as new, else sync.
+	  if [ $? -eq 0 ]; then
+	    avctl hosting stop -a "$agent_address"
+	    avctl hosting sync -a "$agent_address"
+	  else
+	    avctl hosting deploy -n "$agent_name" --no-dependency-check || true
+	  fi
+	# Agent doesn't exist, so let's deploy
+	else
+	  avctl hosting deploy -n "$agent_name" --no-dependency-check || true
+	fi
+
+```
+</DocsCode>
+
+</CodeGroup>
+
+## Getting started
+
+Head on over to the [Agentverse ↗️](https://agentverse.ai) and sign in. Under your profile link (top right) there is an
+option for `API Keys`:
+
+<ImageByTheme
+  darkSrc={agentverse_secret}
+  lightSrc={agentverse_secret}
+  alt="agentverse_secret"
+/>
+
+Clicking this, takes you to an API Key window; here click new **+ New API Key**, give the key a name and give this API key
+full permissions. Click generate API Key at the bottom of the page, and copy the output. Detailed instructions can
+also be found [here ↗️](/guides/apis/agent-function-creation-apis#how-to-get-agentverse-api-tokens)
+
+Once you've got your `API_KEY`, be sure to have forked the [Github repo ↗️](https://github.com/fetchai/avctl-ci-example),
+and visit that repo. Go to settings, on the left hand menu select **Secrets and variables**, and click actions from the
+drop down. 
+
+You'll get a window like shown below:
+
+<ImageByTheme
+  darkSrc={github_secret}
+  lightSrc={github_secret}
+  alt="github_secret"
+/>
+
+Click **New repository secret** and enter the `API_KEY`; we have named ours `AGENTVERSE_API_KEY`.
+
+Great! With that set, copy it in your Agent code below Agent definition part. It is assumed here that your Agent is tested, and you also have an account on [Agentverse ↗️](https://agentverse.ai).
+
+Now, let's push:
+
+    ```
+    git add .
+    git commit -m "updating agent"
+    git push
+    ```
+Visit your forked repo Github page, and under actions you should see the runner in action:
+
+<ImageByTheme
+  darkSrc={action}
+  lightSrc={action}
+  alt="action of github runner"
+/>
+
+### Possible error
+
+You may need to locally run:
+
+    ```
+    sudo git update-index --chmod=+x scripts/deploy-agent.sh
+    ```
+
+This tells git to update the permission on the executable script. Then push up the changes for them to take effect.
+
+## Running this locally:
+
+Please follow the installation guide [here ↗️](guides/agentverse/avctl/avctl#installation)
+
+Update the permissions on `deploy-agent.sh` (You should only need to do this once):
+
+    ```
+    chmod +x scripts/deploy-agent.sh
+    ```
+
+Login to Agentverse from terminal:
+
+    ```
+    avctl auth login
+    ```
+
+Then, from terminal run:
+
+    ```
+    ./scripts/deploy-agent.sh
+    ```
+
+You should see output similar too, dependent on your Agents deployed state:
+
+    ```
+    josh@vm avctl-ci-example % ./scripts/deploy-agent.sh
+    Project already initialized
+    Agent exists on agentverse under address: 'agent1qfx5mmewjs4x9ysyxemsaxv6empds4mmpx4sav84yagmhed5yczdwtqkcxu'
+    Agent agent1qfx5mmewjs4x9ysyxemsaxv6empds4mmpx4sav84yagmhed5yczdwtqkcxu has been stopped.
+    Pushing latest code...
+    Everything is up to date. Nothing to push
+    Agent agent1qfx5mmewjs4x9ysyxemsaxv6empds4mmpx4sav84yagmhed5yczdwtqkcxu is now running!
+    josh@vm avctl-ci-example %
+    
+    ```
+
+## Quirks
+
+For security reasons, the Agentverse defines your Agent's address and stores your Private Key. An address you set locally will not be applied on Agentverse using the above method.
+
+## Further steps
+
+To get familiar with AVCTL, we recommend reading the other guides in this series: [AVCTL ↗️](guides/agentverse/avctl/avctl) and [AVCTL hosting ↗️](guides/agentverse/avctl/avctl-hosting).