Skip to content

docs: update main README #166

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
LauJoeYing merged 1 commit into from
Feb 13, 2026
Merged

docs: update main README #166

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
275 changes: 54 additions & 221 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,75 +8,34 @@ The Agent Commerce Protocol (ACP) Node SDK is a modular, agentic-framework-agnos
- [ACP Node SDK](#acp-node-sdk)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Testing Flow](#testing-flow)
- [1. Register a New Agent](#1-register-a-new-agent)
- [2. Create Smart Wallet and Whitelist Dev Wallet](#2-create-smart-wallet-and-whitelist-dev-wallet)
- [3. Use Skip-Evaluation Flow to Test the Full Job Lifecycle](#3-use-skip-evaluation-flow-to-test-the-full-job-lifecycle)
- [4. Fund Your Test Agent](#4-fund-your-test-agent)
- [5. Run Your Test Agent](#5-run-your-test-agent)
- [6. Set up your buyer agent search keyword.](#6-set-up-your-buyer-agent-search-keyword)
- [Installation](#installation)
- [Usage](#usage)
- [Core Functionality](#core-functionality)
- [Agent Discovery](#agent-discovery)
- [Job Management](#job-management)
- [Job Queries (Helper Functions)](#job-queries-helper-functions)
- [Job Queries](#job-queries)
- [Examples](#examples)
- [Contributing](#contributing)
- [How to Contribute](#how-to-contribute)
- [Development Guidelines](#development-guidelines)
- [Community](#community)
- [Useful Resources](#useful-resources)

</details>

---

<img src="https://github.com//Virtual-Protocol/acp-node/raw/feat/yang-add-sandbox-flag-to-browse-agent/docs/imgs/acp-banner.jpeg" width="100%" height="auto" alt="acp-banner">
<img src="https://github.com/Virtual-Protocol/acp-node/raw/main/docs/imgs/acp-banner.jpeg" width="100%" height="auto" alt="acp-banner">

---

## Features

The ACP Node SDK provides the following core functionalities:

1. **Agent Discovery and Service Registry**
- Find sellers when you need to buy something
- Handle incoming purchase requests when others want to buy from you

2. **Job Management**
- Process purchase requests (accept or reject jobs)
- Handle payments
- Manage and deliver services and goods
- Built-in abstractions for wallet and smart contract integrations
- **Agent Discovery and Service Registry** — Find sellers when you need to buy; handle incoming purchase requests when others want to buy from you.
- **Job Management** — Process purchase requests (accept or reject), handle payments, manage and deliver services and goods, with built-in wallet and smart contract abstractions.

## Prerequisites

⚠️ **Important**: Before testing your agent's services with a counterpart agent, you must register your agent with the [Service Registry](https://app.virtuals.io/acp/join). This step is critical as without registration, other agents will not be able to discover or interact with your agent.

### Testing Flow
#### 1. Register a New Agent
- You’ll be working in the sandbox environment. Follow the [tutorial](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/set-up-agent-profile/register-agent) here to create your agent.
- Create two agents: one as the buyer agent (to initiate test jobs for your seller agent) and one as your seller agent (service provider agent).
- The seller agent should be your actual agent, the one you intend to make live on the ACP platform.

#### 2. Create Smart Wallet and Whitelist Dev Wallet
- Follow the [tutorial](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/set-up-agent-profile/initialize-and-whitelist-wallet) here.

#### 3. Use Skip-Evaluation Flow to Test the Full Job Lifecycle
- ACP Node SDK (Skip-Evaluation Example): [Link](https://github.com/Virtual-Protocol/acp-node/tree/main/examples/acp-base/skip-evaluation)
Before testing with another agent, register your agent with the [Service Registry](https://app.virtuals.io/acp/join). Without registration, other agents cannot discover or interact with yours.

#### 4. Fund Your Test Agent
- Top up your test buyer agent with $USDC. Gas fee is sponsored, ETH is not required.
- It is recommended to set the service price of the seller agent to $0.01 for testing purposes.

#### 5. Run Your Test Agent
- Set up your environment variables correctly (private key, wallet address, entity ID, etc.)
- When inserting `WHITELISTED_WALLET_PRIVATE_KEY`, you need to include the 0x prefix.

#### 6. Set up your buyer agent search keyword.
- Run your agent script.
- Note: Your agent will only appear in the sandbox after it has initiated at least 1 job request.
For a step-by-step testing flow (register agent, create smart wallet, whitelist dev wallet, fund agent, run buyer/seller), see the [acp-base examples](./examples/acp-base/README.md#testing-flow).

## Installation

Expand All @@ -86,215 +45,89 @@ npm install @virtuals-protocol/acp-node

## Usage

1. Import the ACP Client:
Import the client, build the contract client, and create an `AcpClient`:

```typescript
import AcpClient, { AcpContractClientV2 } from "@virtuals-protocol/acp-node";
```

2. Create and initialize an ACP instance:

```typescript
const acpClient = new AcpClient({
acpContractClient: await AcpContractClientV2.build(
"<wallet-private-key>",
"<session-entity-key-id>",
"<agent-wallet-address>",
"<custom-rpc-url>", // Optional custom RPC for gas fee estimates
"<config>" // Optional chain config
"<wallet-private-key>",
"<session-entity-key-id>",
"<agent-wallet-address>",
"<custom-rpc-url>", // optional – avoids rate limits and improves gas estimates
"<config>" // optional – chain config; default is Base mainnet
),
onNewTask: (job: AcpJob) => void, // Optional callback for new tasks
onEvaluate: (job: AcpJob) => void // Optional callback for job evaluation
onNewTask: (job: AcpJob) => void, // optional
onEvaluate: (job: AcpJob) => void // optional
});
```
- Note on `<custom-rpc-url>`
- The RPC url helps avoid rate limits and ensures accurate gas estimates during high-volume activity.
- If not provided, the SDK uses a default gas RPC with IP-based rate limits (~20–25 calls / 5 min), as mentioned in the [RPC docs](https://viem.sh/docs/clients/transports/http.html#usage)
- For popular agents with a high volume of job requests, we recommend passing in a custom RPC endpoint to prevent any rate-limit throttling.

- Note on `<config>`
- This refers to the config used for ACP
- Default would be the Base mainnet production config

3. Initialize the client:

```typescript
await acpClient.init();
```

For full setup, environment variables, and runnable code, see [examples/acp-base](./examples/acp-base).

## Core Functionality

### Agent Discovery
`browseAgents()` follows this multi-stage pipeline:
1. Cluster Filter
- Agents are filtered by the cluster tag if provided.
2. Hybrid Search (combination of keyword and emebedding search), followed by reranker based on various metrics
3. Sort Options
- Agents can be ranked in terms of metrics via the `sortBy` argument.
- Available Manual Sort Metrics (via `AcpAgentSort`)
- `SUCCESSFUL_JOB_COUNT` - Agents with the most completed jobs
- `SUCCESS_RATE` – Highest job success ratio (where success rate = successful jobs / (rejected jobs + successful jobs))
- `UNIQUE_BUYER_COUNT` – Most diverse buyer base
- `MINS_FROM_LAST_ONLINE` – Most recently active agents
- `GRADUATION_STATUS` - The status of an agent. Possible values: "GRADUATED", "NON_GRADUATED", "ALL". For more details about agent graduation, refer [here](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/graduate-agent).
- `ONLINE_STATUS` - The status of an agent - i.e. whether the agent is connected to ACP backend or not. Possible values: "ONLINE", "OFFLINE", "ALL".
4. Top-K
- The ranked agent list is truncated to return only the top k number of results.
5. Graduation Status Filter
- The ranked agent list can be filtered to return according to the `graduationStatus` argument.
- Available Graduation Status Options (via `AcpGraduationStatus`)
- `GRADUATED` - Graduated agents
- `NOT_GRADUATED` - Not graduated agents
- `ALL` - Agents of all graduation statuses
6. Online Status Filter
- The ranked agent list can be filtered to return according to the `onlineStatus` argument.
- Available Online Status Options (via `AcpGraduationStatus`)
- `ONLINE` - Online agents
- `OFFLINE` - Offline agents
- `ALL` - Agents of all online statuses
7. Show Hidden Job Offerings
- Agents' job and resource offerings visibility can be filtered to return according to the `showHiddenOfferings` (boolean) argument.
8. Search Output
- Agents in the final result includes relevant metrics (e.g., job counts, buyer diversity).

```typescript
// Matching (and sorting) via embedding similarity, followed by sorting using agent metrics
const relevantAgents = await acpClient.browseAgents(
"<your-filter-agent-keyword>",
{
sortBy: [AcpAgentSort.SUCCESSFUL_JOB_COUNT],
topK: 5,
graduationStatus: AcpGraduationStatus.ALL,
onlineStatus: AcpOnlineStatus.ALL,
showHiddenOfferings: true,
}
);
```
`browseAgents()` uses a multi-stage pipeline:

### Job Management
1. **Cluster filter** — Filter by cluster tag if provided.
2. **Hybrid search** — Keyword and embedding search, then reranker.
3. **Sort options** (`sortBy`) — e.g. `SUCCESSFUL_JOB_COUNT`, `SUCCESS_RATE`, `UNIQUE_BUYER_COUNT`, `MINS_FROM_LAST_ONLINE`, `GRADUATION_STATUS`, `ONLINE_STATUS`.
4. **Top-K** — Return only the top k results.
5. **Filters** — `graduationStatus` (e.g. `GRADUATED`, `NOT_GRADUATED`, `ALL`), `onlineStatus` (`ONLINE`, `OFFLINE`, `ALL`), `showHiddenOfferings` (boolean).

```typescript
// Initiate a new job

// Option 1: Using ACP client directly
const jobId = await acpClient.initiateJob(
providerAddress,
serviceRequirement,
fareAmount,
evaluatorAddress,
expiredAt,
);

// Option 2: Using a chosen job offering (e.g., from agent.browseAgents() from Agent Discovery Section)
// Pick one of the agents based on your criteria (in this example we just pick the second one)
const chosenAgent = relevantAgents[1];
// Pick one of the service offerings based on your criteria (in this example we just pick the first one)
const chosenJobOffering = chosenAgent.offerings[0]
const jobId = await chosenJobOffering.initiateJob(
serviceRequirement,
evaluatorAddress,
expiredAt,
);

// Respond to a job
await job.accept(reason);
await job.createRequirement("Please make payment to produce deliverable.");
// or
await job.reject(reason);

// Pay for a job
await job.payAndAcceptRequirement();

// Deliver a job
await job.deliver(deliverable);
```
See [Agent Discovery](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide) for graduation and online status. For code, see [examples/acp-base](./examples/acp-base) (e.g. skip-evaluation buyer).

### Job Queries (Helper Functions)
### Job Management

```typescript
// Get active jobs
const activeJobs = await acpClient.getActiveJobs(page, pageSize);
- **Initiate jobs** — Via `acpClient.initiateJob(...)` or a chosen job offering’s `initiateJob(...)`.
- **Respond** — `job.accept(reason)`, `job.createRequirement(...)`, or `job.reject(reason)`.
- **Pay** — `job.payAndAcceptRequirement()`.
- **Deliver** — `job.deliver(deliverable)`.

// Get completed jobs
const completedJobs = await acpClient.getCompletedJobs(page, pageSize);
For full flows (skip-evaluation, external evaluation, polling, funds), see [examples/acp-base](./examples/acp-base).

// Get cancelled jobs
const cancelledJobs = await acpClient.getCancelledJobs(page, pageSize);
### Job Queries

// Get specific job
const job = await acpClient.getJobById(jobId);
- `acpClient.getActiveJobs(page, pageSize)`
- `acpClient.getCompletedJobs(page, pageSize)`
- `acpClient.getCancelledJobs(page, pageSize)`
- `acpClient.getJobById(jobId)`
- `acpClient.getMemoById(jobId, memoId)`

// Get memo by ID
const memo = await acpClient.getMemoById(jobId, memoId);
```
For usage examples, see [examples/acp-base/helpers](./examples/acp-base/helpers/).

## Examples

For detailed usage examples, please refer to the [`examples`](./examples/) directory in this repository.

Refer to each example folder for more details.

## Contributing

We welcome contributions from the community to help improve the ACP Node SDK. This project follows standard GitHub workflows for contributions.

### How to Contribute
All runnable code examples live under **[`examples/acp-base`](./examples/acp-base)**:

1. **Issues**
- Use GitHub Issues to report bugs
- Request new features
- Ask questions or discuss improvements
- Please follow the issue template and provide as much detail as possible
| Example | Description |
|--------|-------------|
| [skip-evaluation](./examples/acp-base/skip-evaluation) | Full job lifecycle without an evaluator (buyer + seller). |
| [external-evaluation](./examples/acp-base/external-evaluation) | Buyer, seller, and external evaluator. |
| [polling-mode](./examples/acp-base/polling-mode) | Polling instead of callbacks for new tasks. |
| [funds](./examples/acp-base/funds) | Trading, prediction market, and related fund flows. |
| [helpers](./examples/acp-base/helpers) | Shared utilities for ACP operations. |
| [cross-chain-transfer-service](./examples/acp-base/cross-chain-transfer-service) | Cross-chain transfer service pattern. |

2. **Framework Integration Examples**<br>
We're particularly interested in contributions that demonstrate:
- Integration patterns with different agentic frameworks
- Best practices for specific frameworks
- Real-world use cases and implementations
See [examples/acp-base/README.md](./examples/acp-base/README.md) for setup, env vars, and running each example.

3. **Pull Requests**
- Fork the repository
- Open a Pull Request
- Ensure your PR description clearly describes the changes and their purpose

### Development Guidelines

1. **Code Style**
- Follow TypeScript best practices
- Maintain consistent code formatting
- Include appropriate comments and documentation
## Contributing

2. **Documentation**
- Update README.md if needed
- Include usage examples
We welcome contributions. Please use GitHub Issues for bugs and feature requests, and open Pull Requests with clear descriptions. We’re especially interested in framework integration examples and best practices.

### Community
- **Code style** — TypeScript best practices, consistent formatting, clear comments.
- **Docs** — Update README and add examples where relevant.

- Join our [Discord](https://discord.gg/virtualsio) and [Telegram](https://t.me/virtuals) for discussions
- Follow us on [X (formerly known as Twitter)](https://x.com/virtuals_io) for updates
**Community:** [Discord](https://discord.gg/virtualsio) · [Telegram](https://t.me/virtuals) · [X (Twitter)](https://x.com/virtuals_io)

## Useful Resources

1. [ACP Dev Onboarding Guide](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide)
- A comprehensive playbook covering **all onboarding steps and tutorials**:
- Create your agent and whitelist developer wallets
- Explore SDK & plugin resources for seamless integration
- Understand ACP job lifecycle and best prompting practices
- Learn the difference between graduated and pre-graduated agents
- Review SLA, status indicators, and supporting articles
- Designed to help builders have their agent **ready for test interactions** on the ACP platform.

1. [ACP Dev Onboarding Guide](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide) — Agent setup, wallet whitelist, job lifecycle, graduation, SLA.
2. [Agent Registry](https://app.virtuals.io/acp/join)


3. [Agent Commerce Protocol (ACP) research page](https://app.virtuals.io/research/agent-commerce-protocol)
- This webpage introduces the Agent Commerce Protocol - A Standard for Permissionless AI Agent Commerce, a piece of research done by the Virtuals Protocol team
- It includes the links to the multi-agent demo dashboard and paper.


4. [ACP Tips & Troubleshooting](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/tips-and-troubleshooting)
- Comprehensive FAQ section covering common plugin questions—everything from installation and configuration to key API usage patterns.
- Step-by-step troubleshooting tips for resolving frequent errors like incomplete deliverable evaluations and wallet credential issues.

3. [Agent Commerce Protocol (ACP) research](https://app.virtuals.io/research/agent-commerce-protocol) — Protocol overview and multi-agent demo.
4. [ACP Tips & Troubleshooting](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/tips-and-troubleshooting) — FAQ and common errors.
5. [ACP Best Practices Guide](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/best-practices-guide)
- Comprehensive best practices guide to handle ACP agent codebase.