You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Virtuals Python API Library is a Python library that provides a simple way to interact with the Virtuals API.
1
+
# Overview
3
2
4
-
Currently, this library supports the GAME API for configuring and deploying agents on the [Virtuals Platform](https://virtuals.io). This complements and extends the functionality of the [Agent Sandbox](https://sandbox.virtuals.io) by providing another way to evaluate and develop agents on Virtuals. With more programmatic interactions, this opens up more functionalities and possibilities to integrate it into your own applications.
3
+
If you wish to have your applications powered by Agent using GAME, you may use GAME python SDK to build your application.
5
4
6
-
## Documentation
7
-
For a walkthrough of some documentation and SDK and usage, please refer to the notion [documentation]() page.
5
+
<aside>
6
+
💡 To best understand this walkthrough, please go through the previous section on
7
+
[agent configurations in GAME](https://www.notion.so/1592d2a429e98016b389ea26b53686a3) to better understand the configurable components.
8
+
9
+
</aside>
10
+
11
+
## Create an API key
12
+
13
+
Open the [Virtuals Platform](https://app.virtuals.io/) and create/get an API key from the Virtuals Sandbox by clicking “Access G.A.M.E API”
14
+
15
+
16
+
17
+
Store the key in a safe location, like a `.bashrc` or a `.zshrc` file.
18
+
19
+
```bash
20
+
export VIRTUALS_API_KEY="your_virtuals_api_key"
21
+
```
22
+
23
+
Alternatively, you can also use a `.env` file ([`python-dotenv` package](https://github.com/theskumar/python-dotenv) to store and load the key) if you are using the Virtuals Python SDK.
8
24
9
25
## Installation
26
+
27
+
install our python SDK using pip
28
+
10
29
```bash
11
30
pip install virtuals_sdk
12
31
```
13
32
14
-
## Usage
33
+
## Usage (GAME)
34
+
35
+
SDK can be used for multiple use cases:
36
+
37
+
1. Update the existing Agent in Twitter environment
38
+
2. Build on other platforms using GAME.
39
+
40
+
### Update the existing Agent in Twitter environment
41
+
42
+
The SDK provides another interface to configure agents that is more friendly to developers. This is similar to configuring your agent in the [Agent Sandbox](https://game-lite.virtuals.io/).
43
+
15
44
```python
16
45
from virtuals_sdk.game import Agent
17
46
@@ -22,16 +51,140 @@ agent = Agent(
22
51
description="HODL-9000: A meme-loving trading bot powered by hopium and ramen",
23
52
world_info="Virtual crypto trading environment where 1 DOGE = 1 DOGE"
24
53
)
54
+
```
25
55
26
-
# list available functions that can be added to agent
You can also initialize the agent first with just the API key and set the goals, descriptions and world information separately and check the current agent descriptions if needed.
28
57
29
-
# selects functions to be enabled
58
+
```python
59
+
60
+
agent = Agent(api_key=VIRTUALS_API_KEY)
61
+
62
+
# check what is current goal, descriptions and world_info
63
+
agent.get_goal()
64
+
agent.get_description()
65
+
agent.get_world_info()
66
+
67
+
# Set components individually - set change the agent goal/description/worldinfo
68
+
agent.set_goal("Autonomously analyze crypto markets and provide trading insights")
69
+
agent.set_description("HODL-9000: A meme-loving trading bot powered by hopium and ramen")
70
+
agent.set_world_info("Virtual crypto trading environment where 1 DOGE = 1 DOGE")
71
+
72
+
# check what is current goal, descriptions and world_info
73
+
agent.get_goal()
74
+
agent.get_description()
75
+
agent.get_world_info()
76
+
```
77
+
78
+
### Functions
79
+
80
+
By default, there are no functions enabled when the agent is initialized (i.e. the agent has no actions/functions it can execute). There are a list of available and provided functions for the Twitter/X platform and you can set them.
You can then equip the agent with some custom functions as follows:
90
+
91
+
```python
92
+
93
+
search_function = game.Function(
94
+
fn_name="custom_search_internet",
95
+
fn_description="search the internet for the best songs",
96
+
args=[
97
+
game.FunctionArgument(
98
+
name="query",
99
+
type="string",
100
+
description="The query to search for"
101
+
)
102
+
],
103
+
config=game.FunctionConfig(
104
+
method="get",
105
+
url="https://google.com",
106
+
platform="twitter", # specify which platform this function is for, in this case this function is for twitter only
107
+
success_feedback="I found the best songs",
108
+
error_feedback="I couldn't find the best songs",
109
+
)
110
+
)
111
+
112
+
# adding custom functions only for platform twitter
113
+
agent.add_custom_function(search_function)
114
+
```
115
+
116
+
### Evaluate with Simulate, Deploy
117
+
118
+
You can simulate one step of the agentic loop on Twitter/X with your new configurations and see the outputs. This is similar to the simulate button on the [Agent Sandbox](https://game-lite.virtuals.io/). Hence, when running
31
119
32
-
# Simulate one step of the full agentic loop on Twitter/X from the HLP -> LLP -> action
120
+
```python
121
+
# Simulate one step of the full agentic loop on Twitter/X from the HLP -> LLP -> action (NOTE: supported for Twitter/X only now)
# To more realistically simulate deployment you can
125
+
```
126
+
127
+
```python
128
+
# Simulate response to a certain event
129
+
response = agent.react(
130
+
session_id="567", # string identifier that you decide
131
+
task_description="",
132
+
context="",
133
+
platform="",
134
+
)
135
+
```
136
+
137
+
Once you are happy, `deploy_twitter` will push your agent configurations to production and run your agent on Twitter/X autonomously.
138
+
139
+
```python
35
140
# deploy agent! (NOTE: supported for Twitter/X only now)
36
141
agent.deploy_twitter()
37
-
```
142
+
```
143
+
144
+
## Build on other platforms using GAME
145
+
146
+
`simulate_twitter` and `deploy_twitter` runs through the entire GAME stack from HLP → LLP→ action/function selected. However, these agent functionalities are currently for the Twitter/X platform. You may utilize Task-based Agent with Low-Level Planner and Reaction Module to develop applications that are powered by GAME. The Low Level Planner (LLP) of the agent (please see [documentation](https://www.notion.so/1592d2a429e98016b389ea26b53686a3?pvs=21) for more details on GAME and LLP) can separately act as a decision making engine based on a task description and event occurring. This agentic architecture is simpler but also sufficient for many applications.
147
+
148
+
We are releasing this simpler setup as a more generalised/platform agnostic framework (not specific to Twitter/X). The entire GAME stack along with the HLP will be opened up to be fully configurable and platform agnostic in the coming weeks.
149
+
150
+
<aside>
151
+
🖥️ Low-Level Planner (LLP) as a Task-based Agent
152
+
153
+
154
+
155
+
</aside>
156
+
157
+
After configuring the agent’s character card or description and setting up the agents functions, we can then use the `react` method to get an agent to respond and execute a sequence of actions based on the task description provided and the context. Between each action in the sequence, the agent only receives the `success_feedback` and `error_feedback` of each function executed.
158
+
159
+
```python
160
+
# React/respond to a certain event
161
+
response = agent.react(
162
+
session_id="567", # string identifier that you decide
163
+
task_description="",
164
+
context="Hi how are you?",
165
+
platform="TELEGRAM",
166
+
)
167
+
```
168
+
169
+
<aside>
170
+
⚠️ Remember that the `platform` tag determines what functions are available to the agent. The agent will have access to functions that have the same `platform` tag. All the default available functions listed on `agent.list_available_default_twitter_functions()` and set via `agent.use_default_twitter_functions()` have the `platform` tag of “twitter”.
171
+
172
+
</aside>
173
+
174
+
## Arguments Definition
175
+
176
+
### Session ID
177
+
178
+
The session ID is an identifier for an instance of the agent. When using the same session ID, it maintains and picks up from where it last left off, continuing the session/instance. It should be split per user/ conversation that you are maintaining on your platform. For different platforms, different session ID can be used.
179
+
180
+
### Platform Tag
181
+
182
+
When adding custom functions, and when calling the react agent (i.e. LLP), there is a platform tag that can be defined. This acts like a filter for the functions available that is passed to the agent. You should define the platform when passing in the events.
183
+
184
+
### Task Description
185
+
186
+
Task description serves as the prompt for the agent to respond. Since the reaction can be platform-based, you can define task description based on the platforms. In the task description, you should pass in any related info that require agent to make decision. That should include:
0 commit comments