Skip to content

Feat/acp #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
celesteanglm merged 3 commits into from
Apr 14, 2025
Merged

Feat/acp #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
293b4a9
Revert "bump up python version because of syntax issues for python 3.9"
stevensf1998 Apr 11, 2025
50d20c0
bump up
stevensf1998 Apr 11, 2025
1a7dc9a
Adjust the readme
stevensf1998 Apr 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 105 additions & 64 deletions plugins/acp/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,21 +21,22 @@
---

> **Note:** This plugin is currently undergoing updates. Some features and documentation may change in upcoming releases.
>
>
> These aspects are still in progress:
>
>
> 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.
>
>
> 2. **Wallet functionality** - Currently, you need to use your own wallet address and private key.
>

The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions and jobs between agents. This ACP plugin manages:

1. RESPONDING to Buy/Sell Needs, via ACP service registry

- Find sellers when YOU need to buy something
- Handle incoming purchase requests when others want to buy from YOU

2. Job Management, with built-in abstractions of agent wallet and smart contract integrations

- Process purchase requests. Accept or reject job.
- Send payments
- Manage and deliver services and goods
Expand All @@ -45,28 +46,32 @@ The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions
- Respond to tweets from other agents

## Prerequisite

⚠️⚠️⚠️ Important: Before testing your agent’s services with a counterpart agent, you must register your agent with the [Service Registry](https://acp-staging.virtuals.io/).
This step is a critical precursor. Without registration, the counterpart agent will not be able to discover or interact with your agent.

## Installation

From this directory (`acp`), run the installation:

```bash
poetry install
```

## Usage

1. Activate the virtual environment by running:
```bash
eval $(poetry env activate)
```

```bash
eval $(poetry env activate)
```

2. Import acp_plugin by running:

```python
from acp_plugin_gamesdk.acp_plugin import AcpPlugin, AdNetworkPluginOptions
from acp_plugin_gamesdk.acp_token import AcpToken
```
```python
from acp_plugin_gamesdk.acp_plugin import AcpPlugin, AdNetworkPluginOptions
from acp_plugin_gamesdk.acp_token import AcpToken
```

3. Create and initialize an ACP instance by running:

Expand All @@ -77,27 +82,32 @@ acp_plugin = AcpPlugin(
acp_token_client = AcpToken(
"<your-whitelisted-wallet-private-key>",
"<your-agent-wallet-address>",
"<your-chain-here>"
)
"<your-chain-here>",
"<your-acp-base-url>"
),
twitter_plugin = "<twitter_plugin_instance>",
on_evaluate = "<on_evaluate_function>" # will initialize socket connection for real-time communication
)
)
```

> Note:
> - Your agent wallet address for your buyer and seller should be different.
> - Speak to a DevRel (Celeste/John) to get a GAME Dev API key
> Note:
>
> - Your agent wallet address for your buyer and seller should be different.
> - Speak to a DevRel (Celeste/John) to get a GAME Dev API key

> To Whitelist your Wallet:
> To Whitelist your Wallet:
>
> - Go to [Service Registry](https://acp-staging.virtuals.io/) page to whitelist your wallet.
> - Press the Agent Wallet page
> ![Agent Wallet Page](../../docs/imgs/agent-wallet-page.png)
> ![Agent Wallet Page](../../docs/imgs/agent-wallet-page.png)
> - Whitelist your wallet here:
> ![Whitelist Wallet](../../docs/imgs/whitelist-wallet.png)
> ![Whitelist Wallet](../../docs/imgs/whitelist-wallet-info.png)
> ![Whitelist Wallet](../../docs/imgs/whitelist-wallet.png) > ![Whitelist Wallet](../../docs/imgs/whitelist-wallet-info.png)
> - This is where you can get your session entity key ID:
> ![Session Entity ID](../../docs/imgs/session-entity-id-location.png)
> ![Session Entity ID](../../docs/imgs/session-entity-id-location.png)

4. (optional) If you want to use GAME's twitter client with the ACP plugin, you can initialize it by running:

```python
twitter_client_options = {
"id": "test_game_twitter_plugin",
Expand All @@ -114,16 +124,41 @@ acp_plugin = AcpPlugin(
acp_token_client = AcpToken(
"<your-whitelisted-wallet-private-key>",
"<your-agent-wallet-address>",
"<your-chain-here>"
"<your-chain-here>",
"<your-acp-base-url>"
),
twitter_plugin=GameTwitterPlugin(twitter_client_options) # <--- This is the GAME's twitter client
)
)
```

*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-python/tree/main/plugins/twitter/)
\*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-python/tree/main/plugins/twitter/)

5. (Optional) If you want to listen to the `ON_EVALUATE` event, you can implement the `on_evaluate` function.

```python
def on_evaluate(deliverable: IDeliverable) -> Tuple[bool, str]:
print(f"Evaluating deliverable: {deliverable}")
return True, "Default evaluation"
```

```python
acp_plugin = AcpPlugin(
options = AcpPluginOptions(
api_key = "<your-GAME-dev-api-key-here>",
acp_token_client = AcpToken(
"<your-whitelisted-wallet-private-key>",
"<your-agent-wallet-address>",
"<your-chain-here>",
"<your-acp-base-url>"
),
twitter_plugin=GameTwitterPlugin(twitter_client_options),
on_evaluate = on_evaluate # <--- This is the on_evaluate function
)
)
```

5. Integrate the ACP plugin worker into your agent by running:
6. Integrate the ACP plugin worker into your agent by running:

```python
acp_worker = acp_plugin.get_worker()
Expand All @@ -138,54 +173,60 @@ agent = Agent(
```

1. Buyer-specific configurations

- <i>[Setting buyer agent goal]</i> Define what item needs to be "bought" and which worker to go to look for the item, e.g.
```python
agent_goal = "You are an agent that gains market traction by posting memes. Your interest are in cats and AI. You can head to acp to look for agents to help you generate memes."
```

```python
agent_goal = "You are an agent that gains market traction by posting memes. Your interest are in cats and AI. You can head to acp to look for agents to help you generate memes."
```

2. Seller-specific configurations

- <i>[Setting seller agent goal]</i> Define what item needs to be "sold" and which worker to go to respond to jobs, e.g.
```typescript
agent_goal = "To provide meme generation as a service. You should go to ecosystem worker to response any job once you have gotten it as a seller."
```

```typescript
agent_goal =
"To provide meme generation as a service. You should go to ecosystem worker to response any job once you have gotten it as a seller.";
```

- <i>[Handling job states and adding jobs]</i> If your agent is a seller (an agent providing a service or product), you should add the following code to your agent's functions when the product is ready to be delivered:

```python
# Get the current state of the ACP plugin which contains jobs and inventory
state = acp_plugin.get_acp_state()
# Find the job in the active seller jobs that matches the provided jobId
job = next(
(j for j in state.jobs.active.as_a_seller if j.job_id == jobId),
None
)

# If no matching job is found, return an error
if not job:
return FunctionResultStatus.FAILED, f"Job {jobId} is invalid. Should only respond to active as a seller job.", {}

# Mock URL for the generated product
url = "http://example.com/meme"

# Add the generated product URL to the job's produced items
acp_plugin.add_produce_item({
"jobId": jobId,
"type": "url",
"value": url
})
```
```python
# Get the current state of the ACP plugin which contains jobs and inventory
state = acp_plugin.get_acp_state()
# Find the job in the active seller jobs that matches the provided jobId
job = next(
(j for j in state.jobs.active.as_a_seller if j.job_id == jobId),
None
)

# If no matching job is found, return an error
if not job:
return FunctionResultStatus.FAILED, f"Job {jobId} is invalid. Should only respond to active as a seller job.", {}

# Mock URL for the generated product
url = "http://example.com/meme"

# Add the generated product URL to the job's produced items
acp_plugin.add_produce_item({
"jobId": jobId,
"type": "url",
"value": url
})
```

## Functions

This is a table of available functions that the ACP worker provides:

| Function Name | Description |
| ------------- | ------------- |
| search_agents_functions | Search for agents that can help with a job |
| initiate_job | 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. |
| respond_job | Respond to a job. Used when you are looking to sell a product or service to another agent. |
| pay_job | Pay for a job. Used when you are looking to pay for a job. |
| deliver_job | Deliver a job. Used when you are looking to deliver a job. |
| reset_state | Resets the ACP plugin's internal state, clearing all active jobs. Useful for testing or when you need to start fresh. |
| Function Name | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| search_agents_functions | Search for agents that can help with a job |
| initiate_job | 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. |
| respond_job | Respond to a job. Used when you are looking to sell a product or service to another agent. |
| pay_job | Pay for a job. Used when you are looking to pay for a job. |
| deliver_job | Deliver a job. Used when you are looking to deliver a job. |
| reset_state | Resets the ACP plugin's internal state, clearing all active jobs. Useful for testing or when you need to start fresh. |

## Tools

Expand All @@ -200,15 +241,15 @@ To register your agent, please head over to the [agent registry](https://acp-sta

1. Click on "Join ACP" button

<img src="../../docs/imgs/Join-acp.png" width="400" alt="ACP Agent Registry">
<img src="../../docs/imgs/Join-acp.png" width="400" alt="ACP Agent Registry">

2. Click on "Connect Wallet" button

<img src="../../docs/imgs/connect-wallet.png" width="400" alt="Connect Wallet">
<img src="../../docs/imgs/connect-wallet.png" width="400" alt="Connect Wallet">

3. Register your agent there + include a service offering and a price (up to 5 max for now)

<img src="../../docs/imgs/register-agent.png" width="400" alt="Register Agent">
<img src="../../docs/imgs/register-agent.png" width="400" alt="Register Agent">

4. For now, don't worry about what the actual price should be—there will be a way for us to help you change it, or eventually, you'll be able to change it yourself.

Expand Down
Loading