Agent Functions

Agents can act as executable functions for the AI Engine. We can enable this by utilizing Agentverse and registering our agent's function on the platform. AI Engine then indexes the registered function and can then communicate with your agent. Checkout the Agents 101 for AI Engine for a wider explanation of how this works.

Prerequisites

Make sure you have read the following resources before going on with this guide:

• Quick Start Guide for uAgents Framework
• Creating your first agent
• Agent Handlers
• Using agents storage function
• Almanac contract
• Register in Almanac
• Agents protocols
• Exchange protocol
• Options for running your Agents
• Make your agents AI Engine compatible

Imports needed

• uAgents (opens in a new tab)
• AI Engine (opens in a new tab)

Local Agent Function registration

Sometimes you'll want to run an agent on your own hardware or infrastructure; luckily this is very easy to do on any system that support Python 3.10.

Overview

This system is pretty simple and makes you get started as quickly as possible. You can run this agent on any device you'd like; in this scenario we're running on a VM but you could run this on your laptop, raspberry pi or tweak for Agentverse . On startup our script will register our agent to the Almanac , and then our agent will be available to communicate with other agents. To get this agent to be DeltaV accessible, we will also go to Agentverse to create a new Function for the agent, to then allow this agent to be found in DeltaV.

The agent

simple_function.py
 
from uagents.setup import fund_agent_if_low
from uagents import Agent, Context, Protocol, Model
import random
from uagents import Field
from ai_engine import UAgentResponse, UAgentResponseType
import sys
 
dungeons = Agent(
    name="dungeonsanddragonsdiceroll",
    port=6145,
    seed="RANDOM STRINGS",
    endpoint=["http://YOUR_IP:6145/submit"],
)
 
fund_agent_if_low(dungeons.wallet.address())
 
@dungeons.on_event("startup")
async def hi(ctx: Context):
    ctx.logger.info(dungeons.address)
 
class Request(Model):
    dice_sides: int = Field(description="How many sides does your dice need?")
 
 
dice_roll_protocol = Protocol("DungeonsAndDragonsDiceRoll")
 
@dice_roll_protocol.on_message(model=Request, replies={UAgentResponse})
async def roll_dice(ctx: Context, sender: str, msg: Request):
    result = str(random.randint(1, msg.dice_sides))
    message = f"Dice roll result: {result}"
    await ctx.send(
        sender, UAgentResponse(message=message, type=UAgentResponseType.FINAL)
    )
 
dungeons.include(dice_roll_protocol, publish_manifest=True)
 
dungeons.run()
 

It is important that you provide the name, port, seed and endpoint for your agent to correctly run this code.

A few things to note; you'll need to be running this agent on infrastructure that allows you to open a port, in our example we run on port 6145.

The agent is initialized with an endpoint, and a port - this is so that we can receive messages, and other agents know where to send them. We call fund_agent_if_low to get some funds, if we need them. And we define our protocol, which is just an int as seen in the Request object.

Our on_message doesn't do much other than return a number between 1 and the defined dice_sides from the message inclusive. However, the response type is of UAgentResponse which is essential to communicate with DeltaV.

.run() initializes the agent.

Finally, we run our agent as follows: python simple_function.py

Expected output:

INFO:     [dungeonsanddragonsdiceroll]: Manifest published successfully: DungeonsAndDragonsDiceRoll
INFO:     [dungeonsanddragonsdiceroll]: Registering on almanac contract...
INFO:     [dungeonsanddragonsdiceroll]: Registering on almanac contract...complete
INFO:     [dungeonsanddragonsdiceroll]: agent1qvh76795enwgnzkrjpedlnqxwv83d8wxnkkcszs9z46zc3qpfs3yvzc5kuw
INFO:     [dungeonsanddragonsdiceroll]: Starting server on http://0.0.0.0:6145 (Press CTRL+C to quit)

Register a local Agent Function on the Agentverse

For this example we set up a really simple Agent Function. For further information on Agent Functions and registration process, see Register Agent Functions on the Agentverse resource.

To register Local Agents and Functions, you will first need to log in the Agentverse (opens in a new tab) and head over to the My Agents tab. Then, click on Local Agents tab and click one of the Connect Local Agent buttons.

You will need to provide the local agent address and make sure it is running on your terminal as only running agents can enroll Agent Functions on the Agentverse!

Once your agent is retrieved correctly, you will see a box depicting it within the My Agents tab. Click on it and head over to the Deploy tab and click on + New Function. Here, you can now provide the needed details for your Agent Function in the dedicated fields. Remember to provide detailed descriptions for what your Agent Function does and the Fields for data Models expected. understanding of Functions fields descriptions.

It's recommended you alter the contract slightly, and follow the above steps so that you can run an agent, create a function for the agent and then have that agent accessible by DeltaV.

Description of your Agent Function

The Description is super important to the success of your Agent Function. The AI Engine will catalogue descriptions and parse these into its understanding. Make sure to be descriptive of what your Agent Function does, and be sure to reinforce keywords with repetition.

Read more and see examples on how to properly set field descriptions by heading over to: Field descriptions for DeltaV guide.

Objective Service and Sub-Service

Objective Service and Sub-Service functions are different but have strong similarities.

The first one is the primary Agent Function and for instance, it could be an agent that would respond to a user or be accessible via DeltaV. Primary Functions are expected to fully or partially fulfill an objective provided by users.

Similarly, a Sub-Service function is an Agent Sub-function providing secondary services that likely need additional context or information to carry out the Primary Function. Secondary Functions are executed in combination with the Objective task. If that's the case, DeltaV would see that the Agent Primary Function can be fulfilled by executing a Secondary Function, thus, it will contact this latter one which may or may not require gaining context directly from the user.

Functions registration resources

For further information and examples on how to register an Agent Function make it discoverable on DeltaV, check out our dedicated resources:

• Register Agentverse Functions .
• Register a coin toss agent as a Function .

For any additional questions, the Team is waiting for you on Discord (opens in a new tab) and Telegram (opens in a new tab) channels.