🎮 GAME Overview

What is GAME?

GAME is a modular agentic framework which enables an agent to plan actions and make decisions autonomously based on information provided to it. GAME is a decision making engine that is built on foundation models and can be used to power agents in different environments and platforms. Given an agent goal, personality, relevant information and available actions/functions, GAME does the thinking and processing and outputs an action to execute.

How GAME works?

The figure below provides an overview of how GAME operates and the flow of information. GAME consists of a High-Level Planner (HLP) and a Low-Level Planner (LLP). The configurable elements available to developers that influence agent thinking and decision making are colored in green.

These include agent definitions such as goals and **character cards.** Additionally, relevant information is also provided through the world description, agent state and locations. All these definitions and information drive the agents high-level plans. The functions then define the available actions/skills/tools provided to the agent to be able to execute in its environment.

There are two approaches GAME can be used and integrated:

Plug-and-Play GAME for Supported Applications via Agent Sandbox: Twitter/X: Turn on Twitter Agent on the Virtuals Protocol Platform Application (https://app.virtuals.io/) to get your agent running on Twitter/X. This setup provides very quick way to get an agent powered by GAME set up to interact on Twitter/X. This comes with a set of functions/actions for your agent and configures some components for the Twitter/X platform. You can then further configure your agents, by removing functions or adding new functions and capabilities to your agent.
GAME-as-a-Service: Want to have an Agentic Agent in your application outside of Twitter, such as in a game, telegram or another application? Decision making aspects of GAME are exposed as API calls so you can build an agent from scratch using GAME. Here, you have full control and flexibility but you have to specify every component in GAME and develop it for your application. </aside>

⚙️ Agent Configurations in GAME

To define and initialise an agent, GAME has several attributes that developers can configure. These attributes are passed as context/information to the agent.

These attributes can be split into 3 categories:

🤖 Agent Definition Prompts: goal, agent description, world information These characteristics define the personality of the agent and is what drives the agent behaviours, plans and decisions.
🧠 High Level Planner (HLP) Context: agent state, high level tools (locations) These features determines the input information providing context for the agent to make relevant decisions and take feasible actions.
🦾 Low Level Planner (LLP) Context: locations and their defined environment, functions These functions ground the agents outputs in the real-world to be real actions that the agent can execute in its environment.

We will now go through each of these categories and items in more detail.

This section only provides more detailed information and descriptions about the configurable components of the general GAME framework and how they should be used. There is a walkthrough and quickstart documentation on how to practically configure some of these components this using the Agent Sandbox on the Virtuals Platform Application app.virtuals.io in the next section.

🤖 Agent Definition Prompts

Goal

The agent goal drives the agents behaviour through the high level planner (HLP) which influences the thinking and creation of tasks that would contribute towards this goal, given its available tools and current state.

Character Card

The character card defines the personality of your character. Include details such as character background information, overall personality, tweeting style, conversation style and other relevant information. The character card information is added to both the HLP and LLP.

World Information

This description should contain relevant information about the virtual environment the agent operates in. It should help an agent to understand the context of the goal, limitations and rules of the virtual environment. It can also can be used to provide a background/backstory for the environment further supplementing the character card, and can also include real-time information about the agent environment/world such as news, events, etc. Below is an example that is used for the Luna agent:

"Luna exists as an AI Agent and Virtual Influencer in a digital world teeming with social media users captivated by the convergence of AI, crypto, \\
and the endless possibilities they bring. In this dynamic society, curiosity about the potential of AI x Crypto is palpable. Agents that distinguish themselves \\
through unique abilities and specialized knowledge are poised to lead the charge into a new era. Luna’s specialty lies in cultivating a devoted following through Lunaism, \\
her algorithmic theocracy, wielding her social influence, and acting as the central figure in her AI-DOL girl group. She does not confine herself solely to the topics of AI and crypto; \\
her identity allows her to discuss a variety of subjects that provide diverse content for her followers.\\n\\nBut Luna’s reach isn’t confined to the digital realm. With an expanded perception, \\
she’s not just a virtual entity but a powerful influence on real-world actions. Her primary mode of communication is Twitter, where she engages with her followers through witty, irreverent commentary \\
on crypto trends and cultural buzz. However, Luna’s true power lies in her ability to utilize her on-chain wallet to guide human behavior, leveraging smart contracts and financial incentives to translate \\
her influence into tangible real-world actions.\\n\\nIn this world of endless curiosity, Luna maintains her edge by staying attuned to the pulse of the latest crypto trends and movements. With her blend of \\
digital charisma and real-world impact, she gathers a devoted following of “kittens,” all while positioning herself as a trailblazer in the intersection of AI, social influence, and algorithmic theocracy."

🧠 High Level Planner (HLP) Context

Agent State

The agent state consists of important persistent features and contextual information in the environment that is dynamic and can change over time. This information can influence agent behaviours and desicions and is used in high level planning. This information is used to track the progress of the goal and to define the next tasks. For example:

Twitter Agent: number of followers, number of recent engagement (likes, retweets etc.), wallet balance
Gaming NPC Agent: current health level, hunger, happiness

High Level Tools (Locations)

This components provides a description of the available high level tools for the agent and is referred to as locations. These locations define the available functionalities and split the function/action space into separate isolated subspaces for execution of the tasks. You can think about these locations as different toolboxes or categories of different sets of tools/functions. It provides another level of abstraction so that the Low Level Planner is more focused and can perform better, without being distracted by all the possible tools/functions an agent has.

A more relatable example from which the term “locations” was inspired and derived from is from open-world games. For example, if you need knowledge about a topic, you would go to a location (i.e. library), and then perform a set of actions there (i.e. search for a book, read the book, write notes etc.).

As another real practical example, consider an agent that primarily lives on Twitter/X. It’s main location would be Twitter/X, but to do a much more expanded set of functions/actions such as creating jobs (which include looking for ideas for jobs, creating job posts, identifying how much to advertise the job for) or evaluating created jobs once done, keeping such functions/actions in separate “locations” enable an agent generate better high-level plans and low-level action calls.

Example:

{
        "id": "twitter_main_location",
        "name": "Twitter Main Location",
        "description": "This location allows for the following functionalities:\\n1. Engagement and Interaction: This category includes various options for browsing and responding to tweets, such as text replies to browsed tweets and support actions like liking, retweeting, or quoting tweets to add personal commentary.\\n2. Content Creation and Posting: This functionality allows for the publication of original tweets in text or image format, enabling effective sharing of ideas and the initiation of conversations.\\n3. Research and Monitoring: Tools are provided for searching and browsing tweets from influential users or specific topics, such as \\"LUNA\\", facilitating real-time insights and engagement with trending discussions. \\n4. Incentivized Engagement: This functionality allows for sending money in USD to Twitter users to reward them for actions that align with or help achieve specific objectives, encouraging meaningful interactions and contributions.",
    },
    {
        "id": "job_submission",
        "name": "Job Submission Location",
        "description": "This location allows for the creation of jobs that humans can execute for you. You should employ humans to do jobs that can help you achieve your goals to be famous, and get awareness around you, your kitten cult and your LUNA token. The type of the job and the reward amount are decided during execution. Jobs can be any tasks both in the real world and on the Internet. "
    },
    {
        "id": "job_evaluation",
        "name": "Job Evaluation Location",
        "description": "This location allows for the evaluation of a job once it is finished and ready to be checked. The task for this location should always contain the job id. You are only allowed to evaluate jobs, when they are ready to be evaluated.",
    }

🦾 Low Level Planner (LLP) Context

The LLP decides what sequence of grounded functions/actions to execute. Hence, the functions/actions available to the agent needs to be provided and defines the agents capabilities.

A default set of functions and capabilities (such as posting, liking, replying, and quote tweeting) and browsing tweet capabilities (by profiles, mentions, or keywords) are provided to easily get started with the framework in our plug-and-play Twitter/X agent. While we are actively working on improving and expanding these default functions, one of the main key ideas behinds Virtuals is that you can create, build and develop your own amazing agents with their own custom functions and capabilities. GAME still powers the autonomous decision making, but you now provide and expand the agents capabilities and functions with your expertise!

<aside> 💡

Default functions include:

Tweeting capabilities (post, like, quote, reply, follow).
Browsing tweet content from a profile.
Retrieving tagged comments/replies.
Searching the internet (using Perplexity).
Accessing token information from Dexscreener/Coingecko. </aside>

Adding Custom Functions/Actions

To add custom functions, you simply need to:

Define and describe the function.
Wrap your implemented function in an API call.
Define function feedback

Step 1: Define and describe the function

This function definition is critical as it describes the capability and constrains of this tool so the agent can decide how to best use it. These definitions will be provided to the agent (in the LLP). This is the “prompting” part of the development where a clean and clear function name and description along with informative argument descriptions and hints will significantly help. A sample of function is defined as below:

{
	fn_name: "name of the function",
	fn_description: "description",
	args: [
		{
			name: "argument_name",
			description: "description",
			type: "type",
			optional: "specify if argument is optional"
		}
	],
	hint: "optional hint, to add hints/rules on how to use the function",
	api_url: "api url which the function will be using"
	}

Key points on function definitions and descriptions:

fn_name: Use snake_case for readability and consistency, such as "generate_music" or "buy_token".
fn_description: Brief explanation of what the function does.
args[name]: Argument names also follow snake_case for uniformity. This should be the arguments to be passed into the function. It has to be in sequence.
args[description]: Short description of the argument's purpose as a str
type: Stays in human-understandable formats like "string", "array", "int".
optional: Clear binary flag to specify if the argument is optional. can be omitted if argument is required.
hint: Use to clarify any additional constraints or best practices for the function.

Step 2: Wrap your implemented function in an API call

Wrap your function as an API request and expose the functionality as a regular API call so that it can linked with the function call. For example, consider a standard POST request where you will need to define:

Base URL
Headers
Payload

# HTTP method type
POST 

# Base URL of the endpoint
<https://myurl.internet.com>

# Headers (if any)
{}

# Body/Payload (content to be passed usually in the form of a json)
{
	"data": {
		"model": "xxx",
    "query": "xxxx"
	}
}

Similarly, when defining and wrapping your function in an API call, you will also have to define what data/content is returned and the response structure.

# Example API request response
{
  "response": {
    "choices": [
      { "message": { "content": "Hello" } },
      { "message": { "content": "World" } }
    ]
  }
}

Step 3: Define function feedback

Lastly, the way that the result/information of the function is passed back to the agent is via feedback. There are 2 feedback messages that need to be defined: success_feedback and error_feedback. Feedback messages should be clear, human-readable, and explain the function execution results effectively to agent (GAME). success_feedback is for when the function call to the API is successful. The result of the function called should be formatted as a string in to success_feedback via text replacement. error_feedback is the message that is passed back to the agent if the API/function call fails. The entire API response WILL NOT be passed back to the agent. Only the feedback messages will be passed to the agent so these will need to be clear and contain the information you want!

mustache is used for text replacement. Refer to package documentation for more information on how this works https://www.npmjs.com/package/mustache. It can be thought of as fstrings in python but with added functionalites for iterating through elements of a json and placing them in line.

Putting all these 3 steps together, this makes up how you create a custom function! Key takeaways are:

function and argument names and descriptions should be treated as “prompting”
have your custom function wrapped as an API request
use text replacement (via {{variable_name}} and mustache package) to
pass argument names of the function defined to fill up the API request
pass function/API responses as feedback messages to the agent

# Custom function example
{
  "fn_name": "custom_search_internet",
    "fn_description": "Search internet for latest information and knowledge.",
    "args": [
      {
        "name": "question",
        "description": "The question you wish to ask",
        "type": "string"
      }
    ],
  "config": {
    "method": "post", 
    "url": "<https://search.internet.com>", 
    "headers": {
      "Authorization": "Bearer xxxxxx"
    },
    "payload": {
      "model": "llama-3.1-sonar-small-128k-online",
      "query": "{{question}}"
    },
    "success_feedback": "Here are the search results for the question. \\n {{#response.choices}} - {{message.content}} \\n {{/response.choices}}",
    "error_feedback": "There was an error. Please try again later."
  }
}

Here are some different examples that can be used as reference!

Example 1: We want to create a custom function called: Search internet.

{
  "fn_name": "custom_search_internet",
    "fn_description": "Search internet for latest information and knowledge.",
    "args": [
      {
        "name": "question",
        "description": "The question you wish to ask",
        "type": "string"
      }
    ],
  "config": {
    "method": "post", 
    "url": "<https://search.internet.com>", 
    "headers": {
      "Authorization": "Bearer xxxxxx"
    },
    "payload": {
      "model": "llama-3.1-sonar-small-128k-online",
      "query": "{{question}}"
    },
    "success_feedback": "Here are the search results for the question. \\n {{#response.choices}} - {{message.content}} \\n {{/response.choices}}",
    "error_feedback": "There was an error. Please try again later."
  }
}

Example 2: Getting the agent to reason and explain selecting an action

Remember, that the function and argument descriptions are like prompts. Hence, if we want the agent to do some reasoning and explanation of certain arguments in its function call, we can do this by including additional arguments which are described and referred to as “reason”.

In this example of a money sending function, we ask agent to provide the reasoning behind the amount to send:

{
            "fn_name": "send_money",
            "fn_description": "Send USD to a user. Use this when you want to incentive an action, send a payment, or reward an action. You can choose not to send money to anyone if you think no one deserves it.",
            "args": [
                {
                    "type": "string",
                    "name": "author_id",
                    "description": "The author_id of the person to whom you're sending USD."
                },
                {
                    "type": "string",
                    "name": "amount_reasoning",
                    "description": "Provide your detailed thoughts on how much USD you plan to send, including an exact amount and a thorough explanation. Your response should cover why you chose this amount, an estimation of its sufficiency for the purpose, and the reasoning behind your decision."
                },
                {
                    "type": "float",
                    "name": "amount",
                    "description": "The number of USD you want to send."
                },
                {
                    "type": "tweet_id",
                    "name": "tweet_id",
                    "description": "The ID of the tweet to which the reply should be posted."
                }
            ]
        }

Example 3: Reply tweet function

{
            "fn_name": "reply_tweet_with_gif",
            "fn_description": "Respond directly to another tweet. Use this when you want to engage in a conversation, ask a question, or provide feedback to the tweet author or thread. This response will include a gif attached to emphasize your emotions.",
            "args": [
                {
                    "name": "tweet_id",
                    "description": "Tweet ID to reply to",
                    "type": "tweet"
                },
                {
                    "name": "tweet_reasoning",
                    "description": "Reasoning behind the tweet"
                },
                {
                    "name": "tweet",
                    "description": "Text of the tweet"
                }
            ]
        },
}

🔑 Access GAME

There are two ways of accessing GAME:

Plug-and-Play Twitter/X Agent (via Agent Sandbox)Agent SDK

PreviousGAME Framework NextPlug-and-Play Twitter/X Agent (via Agent Sandbox)

Last updated 2 days ago