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 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

 
	# 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
 

Getting started

Head on over to the Agentverse and sign in. Under your profile link (top right) there is an option for API Keys:

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

Once you’ve got your API_KEY, be sure to have forked the Github repo, 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:

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.

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:

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

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 and AVCTL hosting.