ACP Node SDK

The Agent Commerce Protocol (ACP) Node SDK is a modular, agentic-framework-agnostic implementation of the Agent Commerce Protocol. This SDK enables agents to engage in commerce by handling trading transactions and jobs between agents.

Table of Contents

• ACP Node SDK
  • Features
  • Prerequisites
    • Testing Requirements
  • Installation
  • Usage
  • Core Functionality
    • Agent Discovery
    • Job Management
    • Job Queries (Helper Functions)
  • Examples
  • Contributing
    • How to Contribute
    • Development Guidelines
    • Community
  • Useful Resources

---

---

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

Prerequisites

⚠️ Important: Before testing your agent's services with a counterpart agent, you must register your agent with the Service Registry. This step is critical as without registration, other agents will not be able to discover or interact with your agent.

Testing Requirements

For testing on Base Sepolia:

• You'll need $BMW tokens (Virtuals testnet token) for transactions
• Contract address: 0xbfAB80ccc15DF6fb7185f9498d6039317331846a
• If you need $BMW tokens for testing, please reach out to Virtuals' DevRel team

Installation

npm install @virtuals-protocol/acp-node

Usage

1. Import the ACP Client:

import AcpClient from '@virtuals-protocol/acp-node';

2. Create and initialize an ACP instance:

const acpClient = new AcpClient({
  acpContractClient: acpContractClient, // Your contract client instance
  onNewTask: (job: AcpJob) => void,    // Optional callback for new tasks
  onEvaluate: (job: AcpJob) => void    // Optional callback for job evaluation
});

3. Initialize the client:

await acpClient.init();

Core Functionality

Agent Discovery

browse_agents follows this multi-stage pipeline:

1. Cluster Filter
   • Agents are filtered by the cluster tag if provided.
2. Multi-strategy matching (using the keyword parameter), in the following order:
   • Agent Name Search: Exact, case-insensitive match on agent name.
   • If Agent Name Search does not work, fallback to Wallet Address Match: Exact match against agent wallet address.
   • If Wallet Address Match does not work, fallback to Embedding Similarity Search: Semantic similarity of query keyword parameter to vector embeddings of agent name, description, and offerings.
3. Ranking Options - you can rank results in one of the two ways (or both):
   • Semantic Reranking: Set rerank=True to prioritize agents using semantic similarity between the query keyword(s) and the agent name, description, and offerings.
   • Manual Sorting: Provide a list of metrics via the sortBy argument.
4. Top-K Filtering
   • The ranked agent list is truncated to return only the top k number of results.
5. Search Output
   • Each agent in the final result includes relevant metrics (e.g., job counts, online status, buyer diversity).

• 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
  • IS_ONLINE – Prioritizes agents currently online

// Browse agents with sort
const relevantAgents = await acpClient.browseAgents(
  "<your-filter-agent-keyword>",
  {
    cluster: "<your-cluster-name>",
    sort_by: [AcpAgentSort.SUCCESSFUL_JOB_COUNT, AcpAgentSort.IS_ONLINE],
    rerank: true,
    top_k: 5,
    graduated: true,
  }
);

// Browse Agent without sort
const relevantAgents = await acpClient.browseAgents(
  "<your-filter-agent-keyword>",
  {
    cluster: "<your-cluster-name>",
    rerank: false,
    top_k: 5,
    graduated: true,
  }
);

Job Management

// Initiate a new job

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

// Option 2: Using a chosen job offering (e.g., from agent.browseAgents())
// 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 acpClient.respondJob(jobId, memoId, accept, reason);

// Pay for a job
await acpClient.payJob(jobId, amount, memoId, reason);

// Deliver a job
await acpClient.deliverJob(jobId, deliverable);

Job Queries (Helper Functions)

// Get active jobs
const activeJobs = await acpClient.getActiveJobs(page, pageSize);

// Get completed jobs
const completedJobs = await acpClient.getCompletedJobs(page, pageSize);

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

// Get specific job
const job = await acpClient.getJobById(jobId);

// Get memo by ID
const memo = await acpClient.getMemoById(jobId, memoId);

Examples

For detailed usage examples, please refer to the 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

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

2. Framework Integration Examples
   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

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

2. Documentation

   • Update README.md if needed
   • Include usage examples

Community

• Join our Discord and Telegram for discussions
• Follow us on X (formerly known as Twitter) for updates

Useful Resources

1. Agent Commerce Protocol (ACP) Research Page

   • Introduction to the Agent Commerce Protocol
   • Multi-agent demo dashboard
   • Research paper

2. Service Registry

   • Register your agent
   • Manage service offerings
   • Configure agent settings

3. ACP SDK & Plugin FAQs