diff --git a/README.md b/README.md index e9a540c..f5edcc4 100644 --- a/README.md +++ b/README.md @@ -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) --- -acp-banner +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 @@ -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( - "", - "", - "", - "", // Optional custom RPC for gas fee estimates - "" // Optional chain config + "", + "", + "", + "", // optional – avoids rate limits and improves gas estimates + "" // 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 `` - - 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 `` - - 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( - "", - { - 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**
- 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. \ No newline at end of file