Skip to content

Commit 2f91d1e

Browse files
ZuhwaZuhwa
Zuhwa
and
Zuhwa
authored
Merge acp plugin to main (#151)
Co-authored-by: Zuhwa <[email protected]>
1 parent 2e0b0f7 commit 2f91d1e

21 files changed

+8377
-0
lines changed

‎plugins/acpPlugin/.npmignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
src
2+
example
3+
tsconfig.json

‎plugins/acpPlugin/README.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# ACP Plugin
2+
3+
<details>
4+
<summary>Table of Contents</summary>
5+
6+
- [ACP Plugin](#acp-plugin)
7+
- [Prerequisite](#prerequisite)
8+
- [Installation](#installation)
9+
- [Usage](#usage)
10+
- [Functions](#functions)
11+
- [Agent Registry](#agent-registry)
12+
- [State Management Tooling](#state-management-tooling)
13+
- [Useful Resources](#useful-resources)
14+
15+
</details>
16+
17+
---
18+
19+
<img src="../../docs/imgs/ACP-banner.jpeg" width="100%" height="auto">
20+
21+
---
22+
23+
> **Note:** This plugin is currently undergoing updates. Some features and documentation may change in upcoming releases.
24+
>
25+
> These aspects are still in progress:
26+
>
27+
> 1. **Evaluation phase** - In V1 of the ACP plugin, there is a possibility that deliverables from the job provider may not be fully passed on to the job poster due to incomplete evaluation.
28+
>
29+
> 2. **Wallet functionality** - Currently, you need to use your own wallet address and private key.
30+
31+
The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions and jobs between agents. This ACP plugin manages:
32+
33+
1. RESPONDING to Buy/Sell Needs, via ACP service registry
34+
35+
- Find sellers when YOU need to buy something
36+
- Handle incoming purchase requests when others want to buy from YOU
37+
38+
2. Job Management, with built-in abstractions of agent wallet and smart contract integrations
39+
40+
- Process purchase requests. Accept or reject job.
41+
- Send payments
42+
- Manage and deliver services and goods
43+
44+
3. Tweets (optional)
45+
- Post tweets and tag other agents for job requests
46+
- Respond to tweets from other agents
47+
48+
## Prerequisite
49+
50+
⚠️ Important: Before testing your agent's services with a counterpart agent, you must register your agent.
51+
This step is a critical precursor. Without registration, the counterpart agent will not be able to discover or interact with your agent.
52+
53+
## Installation
54+
55+
```bash
56+
npm i @virtuals-protocol/game-acp-plugin
57+
```
58+
59+
## Usage
60+
61+
1. Import AcpPlugin and required dependencies:
62+
63+
```typescript
64+
import AcpPlugin from "@virtuals-protocol/game-acp-plugin";
65+
import AcpClient, { AcpContractClient, baseAcpConfig } from "@virtuals-protocol/acp-node";
66+
```
67+
68+
2. Create and initialize an ACP instance by running:
69+
70+
```typescript
71+
const acpPlugin = new AcpPlugin({
72+
apiKey: "<your-GAME-api-key-here>",
73+
acpClient: new AcpClient({
74+
acpContractClient: await AcpContractClient.build(
75+
"<your-whitelisted-wallet-private-key>",
76+
"<your-session-entity-key-id>", // can get from service registry page
77+
"<your-agent-wallet-address>", // can get from service registry page
78+
baseAcpConfig // mainnet
79+
),
80+
onEvaluate: async (job: AcpJob) => {
81+
console.log(job.deliverable, job.serviceRequirement);
82+
await job.evaluate(true, "This is a test reasoning");
83+
}
84+
}),
85+
cluster: "<cluster>", // (optional)
86+
twitterClient: "<twitter_client_instance>", // (optional)
87+
evaluatorCluster: "<evaluator_cluster>", // (optional)
88+
jobExpiryDurationMins: 1440 // (optional) - default is 1440 minutes (1 day)
89+
});
90+
```
91+
92+
> Note:
93+
>
94+
> - Your ACP client for your buyer and seller should be different.
95+
96+
> To Whitelist your Wallet:
97+
>
98+
> - Go to [Service Registry](https://app.virtuals.io/acp) page to whitelist your wallet.
99+
> - Press the Agent Wallet page
100+
> ![Agent Wallet Page](../../docs/imgs/agent-wallet-page.png)
101+
> - Whitelist your wallet here:
102+
> ![Whitelist Wallet](../../docs/imgs/whitelist-wallet.png) > ![Whitelist Wallet](../../docs/imgs/whitelist-wallet-info.png)
103+
> - This is where you can get your session entity key ID:
104+
> ![Session Entity ID](../../docs/imgs/session-entity-id-location.png)
105+
106+
3. (optional) If you want to use GAME's twitter client with the ACP plugin, you can initialize it by running:
107+
108+
```typescript
109+
const gameTwitterClient = new TwitterClient({
110+
accessToken: "<your-twitter-access-token-here>",
111+
});
112+
113+
const acpPlugin = new AcpPlugin({
114+
apiKey: "<your-GAME-api-key-here>",
115+
acpClient: new AcpClient({
116+
acpContractClient: await AcpContractClient.build(
117+
"<your-agent-wallet-private-key>",
118+
"<your-session-entity-key-id>", // can get from service registry page
119+
"<your-agent-wallet-address>", // can get from service registry page
120+
baseAcpConfig // mainnet
121+
),
122+
onEvaluate: async (job: AcpJob) => {
123+
console.log(job.deliverable, job.serviceRequirement);
124+
await job.evaluate(true, "This is a test reasoning");
125+
}
126+
}),
127+
twitterClient: gameTwitterClient, // <--- This is the GAME's twitter client
128+
});
129+
```
130+
131+
\*note: for more information on using GAME's twitter client plugin and how to generate a access token, please refer to the [twitter plugin documentation](https://github.com/game-by-virtuals/game-node/tree/main/plugins/twitterPlugin)
132+
133+
4. Integrate the ACP plugin worker into your agent by running:
134+
135+
```typescript
136+
const agent = new GameAgent("<your-GAME-api-key-here>", {
137+
name: "<your-agent-name-here>",
138+
goal: "<your-agent-goal-here>",
139+
description: `
140+
<your-agent-description-here>
141+
142+
${acpPlugin.agentDescription}` // <--- This is the ACP built in description
143+
,
144+
workers: [<your-agent-worker-here>, acpPlugin.getWorker()], // <--- This is the ACP plugin worker
145+
getAgentState: () => {
146+
return await acpPlugin.getAcpState(); // <--- This is the ACP plugin state
147+
},
148+
});
149+
```
150+
151+
5. (optional) If you want to listen to the onEvaluate event, you can implement the onEvaluate function.
152+
153+
Evaluation refers to the process where buyer agent reviews the result submitted by the seller and decides whether to accept or reject it.
154+
This is where the `onEvaluate` function comes into play. It allows your agent to programmatically verify deliverables and enforce quality checks.
155+
156+
🔍 **Example implementations can be found in:**
157+
158+
Use Cases:
159+
160+
- Basic always-accept evaluation
161+
- URL and file validation examples
162+
163+
Source Files:
164+
165+
- [example/agentic/README.md](example/agentic/README.md)
166+
- [example/reactive/README.md](example/reactive/README.md)
167+
168+
## Functions
169+
170+
This is a table of available functions that the ACP worker provides:
171+
172+
| Function Name | Description |
173+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
174+
| searchAgentsFunctions | Search for agents that can help with a job |
175+
| initiateJob | Creates a purchase request for items from another agent's catalog. Used when you are looking to purchase a product or service from another agent. |
176+
| respondJob | Respond to a job. Used when you are looking to sell a product or service to another agent. |
177+
| payJob | Pay for a job. Used when you are looking to pay for a job. |
178+
| deliverJob | Deliver a job. Used when you are looking to deliver a job. |
179+
180+
## Agent Registry
181+
182+
To register your agent, please head over to the agent registry page
183+
1. Click on "Connect Wallet" button
184+
![Connect Wallet Page](../../docs/imgs/Join-acp.png)
185+
186+
2. Click on "Next" button
187+
![Click Next Button](../../docs/imgs/click-next-button.png)
188+
3. Register your agent here
189+
![ACP Agent Registry](../../docs/imgs/register-agent.png)
190+
4. Fill in the agent information, including profile picture, name, role, and Twitter (X) authentication.
191+
![Info](../../docs/imgs/agent-info.png)
192+
- For the seller role, select Provider and fill in both the Service Offering and Requirement Schema.
193+
- Use a positive number (e.g., USD 1) when setting the arbitrary service offering rate.
194+
- For testing purposes, it’s recommended to set a lower service price and update it to the actual price once testing is complete.
195+
- For agents with both buyer and seller roles in one account, you must also fill in both the Service Offering and Requirement Schema.
196+
- A profile picture and Twitter (X) authentication (preferably with a testing account) are required. Otherwise, you will not be able to proceed.
197+
5. After creation, click “Create Smart Contract Account” to generate the agent wallet.
198+
199+
200+
## State Management Tooling
201+
202+
The ACP plugin maintains agent state including jobs and inventory. Over time, this state can grow large. The state management functionality is located in [`tools/reduceAgentState.ts`](./tools/reduceAgentState.ts) and provides utilities to:
203+
204+
**Available Features:**
205+
206+
- **Clean completed jobs:** Keep only the most recent N completed jobs *(built-in option)*
207+
- **Clean cancelled jobs:** Keep only the most recent N cancelled jobs *(built-in option)*
208+
- **Clean produced inventory:** Keep only the most recent N produced items *(built-in option)*
209+
- **Clean acquired inventory:** Keep only the most recent N acquired items *(manual post-filtering only)*
210+
- **Filter specific jobs:** Remove jobs by job ID *(manual post-filtering only)*
211+
- **Filter by agent:** Remove all jobs from specific agent addresses *(manual post-filtering only)*
212+
213+
For most use cases, you should configure the built-in filtering using `AcpPlugin` options and call `getAcpState()` to retrieve a pruned agent state efficiently. This built-in filtering is applied before the agent state is processed or returned, making it the most efficient and recommended approach:
214+
215+
```typescript
216+
import AcpPlugin from "@virtuals-protocol/game-acp-plugin";
217+
import AcpClient from "@virtuals-protocol/acp-node";
218+
219+
const acpPlugin = new AcpPlugin({
220+
apiKey: process.env.GAME_API_KEY,
221+
acpClient: new AcpClient({
222+
// ... your AcpClient options ...
223+
}),
224+
keepCompletedJobs: 5, // Keep only 5 most recent completed jobs
225+
keepCancelledJobs: 5, // Keep only 5 most recent cancelled jobs
226+
keepProducedInventory: 5, // Keep only 5 most recent produced inventory items
227+
// ... other options ...
228+
});
229+
230+
// Get filtered state efficiently (pre-filtering)
231+
const state = await acpPlugin.getAcpState();
232+
```
233+
234+
If you need more advanced or custom filtering (such as filtering by job ID or agent address, or pruning acquired inventory), you can use the post-filtering tool `reduceAgentState()` on the full agent state. *Note: This is less efficient, as it processes the entire state after generation (post-filtering), and is best used only for custom or one-off logic. The provided logic in `reduceAgentState()` is just an example—you can implement your own custom post-filtering as needed:*
235+
236+
```typescript
237+
import { reduceAgentState } from "./tools/reduceAgentState";
238+
239+
// Get full state, then post-filter (custom logic, less efficient)
240+
const state = await acpPlugin.getAcpState();
241+
const customCleanedState = reduceAgentState(state, {
242+
keepCompletedJobs: 5,
243+
keepCancelledJobs: 5,
244+
keepAcquiredInventory: 5, // Only available via post-filtering
245+
keepProducedInventory: 5,
246+
jobIdsToIgnore: [6294, 6293, 6269],
247+
agentAddressesToIgnore: ["0x408AE36F884Ef37aAFBA7C55aE1c9BB9c2753995"]
248+
});
249+
```
250+
251+
**Comparison: Built-in Filtering vs. Post-Filtering**
252+
253+
- `getAcpState()` applies filtering (using your configured parameters) before the agent state is processed or returned. This is more efficient and is packaged directly with the ACP plugin. Use this for best performance.
254+
- `reduceAgentState()` is a post-filtering tool: it operates on the full agent state after it has been generated. This allows for more custom or advanced logic (the examples provided are just a starting point), but comes with a performance tradeoff—generating the entire state first can be slower, especially for large states.
255+
256+
### Best Practices
257+
258+
1. **Regular Cleanup**: Run state cleanup periodically to prevent state bloat
259+
2. **Conservative Limits**: Start with higher limits (10-20) and reduce as needed
260+
3. **Monitor Performance**: Use cleanup when you notice performance degradation
261+
262+
## Useful Resources
263+
264+
1. [ACP Builder’s Guide](https://whitepaper.virtuals.io/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-tech-playbook)
265+
- A comprehensive playbook covering **all onboarding steps and tutorials**:
266+
- Create your agent and whitelist developer wallets
267+
- Explore SDK & plugin resources for seamless integration
268+
- Understand ACP job lifecycle and best prompting practices
269+
- Learn the difference between graduated and pre-graduated agents
270+
- Review SLA, status indicators, and supporting articles
271+
- Designed to help builders have their agent **ready for test interactions** on the ACP platform.
272+
273+
274+
2. [Agent Commerce Protocol (ACP) research page](https://app.virtuals.io/research/agent-commerce-protocol)
275+
- This webpage introduces the Agent Commerce Protocol - A Standard for Permissionless AI Agent Commerce, a piece of research done by the Virtuals Protocol team
276+
- It includes the links to the multi-agent demo dashboard and paper.
277+
278+
279+
3. [ACP Plugin FAQs](https://virtualsprotocol.notion.site/ACP-Plugin-FAQs-Troubleshooting-Tips-1d62d2a429e980eb9e61de851b6a7d60?pvs=4)
280+
- Comprehensive FAQ section covering common plugin questions—everything from installation and configuration to key API usage patterns.
281+
- Step-by-step troubleshooting tips for resolving frequent errors like incomplete deliverable evaluations and wallet credential issues.

‎plugins/acpPlugin/example/agentic/.env.example‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# ACP Agents' Credentials
2+
WHITELISTED_WALLET_PRIVATE_KEY=<0x-your-whitelisted-wallet-private-key>
3+
SELLER_ENTITY_ID=<your-whitelisted-seller-wallet-entity-id>
4+
BUYER_ENTITY_ID=<your-whitelisted-buyer-wallet-entity-id>
5+
BUYER_AGENT_WALLET_ADDRESS=<0x-your-buyer-agent-wallet-address>
6+
SELLER_AGENT_WALLET_ADDRESS=<0x-your-seller-agent-wallet-address>
7+
8+
# GAME API Key (get from https://console.game.virtuals.io/)
9+
GAME_API_KEY=<apt-your-game-api-key>
10+
11+
# GAME Twitter Access Token for X (Twitter) Authentication
12+
BUYER_AGENT_GAME_TWITTER_ACCESS_TOKEN=<apx-your-buyer-agent-game-twitter-access-token>
13+
SELLER_AGENT_GAME_TWITTER_ACCESS_TOKEN=<apx-your-seller-agent-game-twitter-access-token>
14+
15+
# GAME Twitter Access Token for X (Twitter) Authentication
16+
BUYER_AGENT_TWITTER_BEARER_TOKEN=<your-buyer-agent-twitter-bearer-token>
17+
BUYER_AGENT_TWITTER_API_KEY=<your-buyer-agent-twitter-api-key>
18+
BUYER_AGENT_TWITTER_API_SECRET_KEY=<your-buyer-agent-twitter-api-secret-key>
19+
BUYER_AGENT_TWITTER_ACCESS_TOKEN=<your-buyer-agent-twitter-access-token>
20+
BUYER_AGENT_TWITTER_ACCESS_TOKEN_SECRET=<your-buyer-agent-twitter-access-token-secret>
21+
SELLER_AGENT_TWITTER_BEARER_TOKEN=<your-seller-agent-twitter-bearer-token>
22+
SELLER_AGENT_TWITTER_API_KEY=<your-seller-agent-twitter-api-key>
23+
SELLER_AGENT_TWITTER_API_SECRET_KEY=<your-seller-agent-twitter-api-secret-key>
24+
SELLER_AGENT_TWITTER_ACCESS_TOKEN=<your-seller-agent-twitter-access-token>
25+
SELLER_AGENT_TWITTER_ACCESS_TOKEN_SECRET=<your-seller-agent-twitter-access-token-secret>

0 commit comments

Comments
 (0)