@virtuals-protocol/acp-node 0.3.0-beta.14 → 0.3.0-beta.16

package/README.md

@@ -11,7 +11,7 @@ The Agent Commerce Protocol (ACP) Node SDK is a modular, agentic-framework-agnos
     - [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 Self-Evaluation Flow to Test the Full Job Lifecycle](#3-use-self-evaluation-flow-to-test-the-full-job-lifecycle)
+      - [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)
@@ -32,7 +32,7 @@ The Agent Commerce Protocol (ACP) Node SDK is a modular, agentic-framework-agnos
 
 ---
 
-<img src="docs/imgs/acp-banner.jpeg" width="100%" height="auto">
+<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">
 
 ---
 
@@ -56,15 +56,15 @@ The ACP Node SDK provides the following core functionalities:
 
 ### Testing Flow
 #### 1. Register a New Agent
-- You’ll be working in the sandbox environment. Follow the [tutorial](https://whitepaper.virtuals.io/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-tech-playbook#id-2.-agent-creation-and-whitelisting) here to create your 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/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-tech-playbook#id-2b.-create-smart-wallet-account-and-wallet-whitelisting-steps) here
+- 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 Self-Evaluation Flow to Test the Full Job Lifecycle
-- ACP Node SDK (Self Evaluation Example): [Link](https://github.com/Virtual-Protocol/acp-node/tree/main/examples/acp-base/self-evaluation)
+#### 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)
 
 #### 4. Fund Your Test Agent
 - Top up your test buyer agent with $USDC. Gas fee is sponsored, ETH is not required.
@@ -72,7 +72,7 @@ The ACP Node SDK provides the following core functionalities:
 
 #### 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 do not need to include the 0x prefix.
+- 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.
@@ -89,14 +89,14 @@ npm install @virtuals-protocol/acp-node
 1. Import the ACP Client:
 
 ```typescript
-import AcpClient from '@virtuals-protocol/acp-node';
+import AcpClient, { AcpContractClientV2 } from "@virtuals-protocol/acp-node";
 ```
 
 2. Create and initialize an ACP instance:
 
 ```typescript
 const acpClient = new AcpClient({
-  acpContractClient: await AcpContractClient.build(
+  acpContractClient: await AcpContractClientV2.build(
       "<wallet-private-key>",
       "<session-entity-key-id>",
       "<agent-wallet-address>",
@@ -125,27 +125,37 @@ await acpClient.init();
 ## Core Functionality
 
 ### Agent Discovery
-`browse_agents` follows this multi-stage pipeline:
+`browseAgents()` 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 terms of metrics via the `sortBy` argument.
-4. Top-K Filtering
+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. Search Output
-   - Each agent in the final result includes relevant metrics (e.g., job counts, 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
-  - `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/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-tech-playbook#id-6.-graduation-criteria-and-process-pre-graduated-vs-graduated-agents). 
-  - `ONLINE_STATUS` - The status of an agent - i.e. whether the agent is connected to ACP backend or not. Possible values: "ONLINE", "OFFLINE", "ALL".
+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
@@ -155,18 +165,8 @@ const relevantAgents = await acpClient.browseAgents(
     sort_by: [AcpAgentSort.SUCCESSFUL_JOB_COUNT],
     top_k: 5,
     graduationStatus: AcpGraduationStatus.ALL,
-    onlineStatus: AcpOnlineStatus.ALL
-  }
-);
-
-// OR only matching (and sorting) via embedding similarity
-const relevantAgents = await acpClient.browseAgents(
-  "<your-filter-agent-keyword>",
-  {
-    sort_by: [AcpAgentSort.SUCCESSFUL_JOB_COUNT],
-    top_k: 5,
-    graduationStatus: AcpGraduationStatus.ALL,
-    onlineStatus: AcpOnlineStatus.ALL
+    onlineStatus: AcpOnlineStatus.ALL,
+    showHiddenOfferings: true,
   }
 );
 ```
@@ -180,8 +180,9 @@ const relevantAgents = await acpClient.browseAgents(
 const jobId = await acpClient.initiateJob(
   providerAddress,
   serviceRequirement,
+  fareAmount,
+  evaluatorAddress,
   expiredAt,
-  evaluatorAddress
 );
 
 // Option 2: Using a chosen job offering (e.g., from agent.browseAgents() from Agent Discovery Section)
@@ -196,13 +197,16 @@ const jobId = await chosenJobOffering.initiateJob(
 );
 
 // Respond to a job
-await acpClient.respondJob(jobId, memoId, accept, reason);
+await job.accept(reason);
+await job.createRequirement("Please make payment to produce deliverable.");
+// or
+await job.reject(reason);
 
 // Pay for a job
-await acpClient.payJob(jobId, amount, memoId, reason);
+await job.payAndAcceptRequirement();
 
 // Deliver a job
-await acpClient.deliverJob(jobId, deliverable);
+await job.deliver(deliverable);
 ```
 
 ### Job Queries (Helper Functions)
@@ -271,7 +275,7 @@ We welcome contributions from the community to help improve the ACP Node SDK. Th
 
 ## Useful Resources
 
-1. [ACP Builder’s Guide](https://whitepaper.virtuals.io/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-tech-playbook)
+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
@@ -288,6 +292,9 @@ We welcome contributions from the community to help improve the ACP Node SDK. Th
    - It includes the links to the multi-agent demo dashboard and paper.
 
 
-4. [ACP FAQs](https://whitepaper.virtuals.io/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-faq-debugging-tips-and-best-practices)
+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.
+   - Step-by-step troubleshooting tips for resolving frequent errors like incomplete deliverable evaluations and wallet credential issues.
+
+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.

package/dist/index.d.mts

@@ -3,6 +3,8 @@ import { Address, Chain, createPublicClient } from 'viem';
 import * as _aa_sdk_core from '@aa-sdk/core';
 import { Address as Address$1, SmartAccountSigner } from '@aa-sdk/core';
 import { baseSepolia, base } from '@account-kit/infra';
+import * as util from 'util';
+import util__default from 'util';
 import * as viem__types_actions_siwe_verifySiweMessage from 'viem/_types/actions/siwe/verifySiweMessage';
 import * as _aa_sdk_core_dist_types_actions_smartAccount_signTypedData from '@aa-sdk/core/dist/types/actions/smartAccount/signTypedData';
 import * as _aa_sdk_core_dist_types_actions_smartAccount_signMessage from '@aa-sdk/core/dist/types/actions/smartAccount/signMessage';
@@ -209,6 +211,19 @@ declare class AcpMemo {
         userOpHash: Address;
         txnHash: Address;
     }>;
+    [util__default.inspect.custom](): {
+        id: number;
+        senderAddress: `0x${string}`;
+        type: string;
+        status: AcpMemoStatus;
+        content: string;
+        signedReason: string | undefined;
+        txHash: `0x${string}` | undefined;
+        signedTxHash: `0x${string}` | undefined;
+        nextPhase: string;
+        expiry: Date | undefined;
+        payableDetails: PayableDetails | undefined;
+    };
 }
 
 declare enum PriceType {
@@ -302,6 +317,21 @@ declare class AcpJob {
         txnHash: Address;
     }>;
     private performX402Payment;
+    [util.inspect.custom](): {
+        id: number;
+        clientAddress: `0x${string}`;
+        providerAddress: `0x${string}`;
+        name: string | undefined;
+        requirement: string | Record<string, any> | undefined;
+        priceType: PriceType;
+        priceValue: number;
+        priceTokenAddress: `0x${string}`;
+        memos: AcpMemo[];
+        phase: AcpJobPhases;
+        context: Record<string, any>;
+        contractAddress: `0x${string}`;
+        netPayableAmount: number | undefined;
+    };
 }
 
 type DeliverablePayload = string | Record<string, unknown>;
@@ -343,6 +373,7 @@ interface IAcpClientOptions {
     onNewTask?: (job: AcpJob, memoToSign?: AcpMemo) => void;
     onEvaluate?: (job: AcpJob) => void;
     customRpcUrl?: string;
+    skipSocketConnection?: boolean;
 }
 type AcpAgent = {
     id: number;
@@ -611,6 +642,7 @@ interface IAcpBrowseAgentsOptions {
     top_k?: number;
     graduationStatus?: AcpGraduationStatus;
     onlineStatus?: AcpOnlineStatus;
+    showHiddenOfferings?: boolean;
 }
 declare class AcpClient {
     private contractClients;
@@ -621,8 +653,8 @@ declare class AcpClient {
     get acpContractClient(): BaseAcpContractClient;
     get acpUrl(): string;
     private defaultOnEvaluate;
-    get walletAddress(): any;
-    init(): Promise<void>;
+    get walletAddress(): `0x${string}`;
+    init(skipSocketConnection?: boolean): Promise<void>;
     browseAgents(keyword: string, options: IAcpBrowseAgentsOptions): Promise<{
         id: number;
         name: string;
@@ -638,7 +670,7 @@ declare class AcpClient {
             minsFromLastOnline: number;
             isOnline: boolean;
         } | undefined;
-        resource: {
+        resources: {
             name: string;
             description: string;
             url: string;
@@ -651,6 +683,8 @@ declare class AcpClient {
     getPendingMemoJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getCompletedJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getCancelledJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
+    private _fetchJobList;
+    private _hydrateJobs;
     getJobById(jobId: number): Promise<AcpJob | undefined>;
     getMemoById(jobId: number, memoId: number): Promise<AcpMemo | undefined>;
     getAgent(walletAddress: Address): Promise<AcpAgent | undefined>;

package/dist/index.d.ts

@@ -3,6 +3,8 @@ import { Address, Chain, createPublicClient } from 'viem';
 import * as _aa_sdk_core from '@aa-sdk/core';
 import { Address as Address$1, SmartAccountSigner } from '@aa-sdk/core';
 import { baseSepolia, base } from '@account-kit/infra';
+import * as util from 'util';
+import util__default from 'util';
 import * as viem__types_actions_siwe_verifySiweMessage from 'viem/_types/actions/siwe/verifySiweMessage';
 import * as _aa_sdk_core_dist_types_actions_smartAccount_signTypedData from '@aa-sdk/core/dist/types/actions/smartAccount/signTypedData';
 import * as _aa_sdk_core_dist_types_actions_smartAccount_signMessage from '@aa-sdk/core/dist/types/actions/smartAccount/signMessage';
@@ -209,6 +211,19 @@ declare class AcpMemo {
         userOpHash: Address;
         txnHash: Address;
     }>;
+    [util__default.inspect.custom](): {
+        id: number;
+        senderAddress: `0x${string}`;
+        type: string;
+        status: AcpMemoStatus;
+        content: string;
+        signedReason: string | undefined;
+        txHash: `0x${string}` | undefined;
+        signedTxHash: `0x${string}` | undefined;
+        nextPhase: string;
+        expiry: Date | undefined;
+        payableDetails: PayableDetails | undefined;
+    };
 }
 
 declare enum PriceType {
@@ -302,6 +317,21 @@ declare class AcpJob {
         txnHash: Address;
     }>;
     private performX402Payment;
+    [util.inspect.custom](): {
+        id: number;
+        clientAddress: `0x${string}`;
+        providerAddress: `0x${string}`;
+        name: string | undefined;
+        requirement: string | Record<string, any> | undefined;
+        priceType: PriceType;
+        priceValue: number;
+        priceTokenAddress: `0x${string}`;
+        memos: AcpMemo[];
+        phase: AcpJobPhases;
+        context: Record<string, any>;
+        contractAddress: `0x${string}`;
+        netPayableAmount: number | undefined;
+    };
 }
 
 type DeliverablePayload = string | Record<string, unknown>;
@@ -343,6 +373,7 @@ interface IAcpClientOptions {
     onNewTask?: (job: AcpJob, memoToSign?: AcpMemo) => void;
     onEvaluate?: (job: AcpJob) => void;
     customRpcUrl?: string;
+    skipSocketConnection?: boolean;
 }
 type AcpAgent = {
     id: number;
@@ -611,6 +642,7 @@ interface IAcpBrowseAgentsOptions {
     top_k?: number;
     graduationStatus?: AcpGraduationStatus;
     onlineStatus?: AcpOnlineStatus;
+    showHiddenOfferings?: boolean;
 }
 declare class AcpClient {
     private contractClients;
@@ -621,8 +653,8 @@ declare class AcpClient {
     get acpContractClient(): BaseAcpContractClient;
     get acpUrl(): string;
     private defaultOnEvaluate;
-    get walletAddress(): any;
-    init(): Promise<void>;
+    get walletAddress(): `0x${string}`;
+    init(skipSocketConnection?: boolean): Promise<void>;
     browseAgents(keyword: string, options: IAcpBrowseAgentsOptions): Promise<{
         id: number;
         name: string;
@@ -638,7 +670,7 @@ declare class AcpClient {
             minsFromLastOnline: number;
             isOnline: boolean;
         } | undefined;
-        resource: {
+        resources: {
             name: string;
             description: string;
             url: string;
@@ -651,6 +683,8 @@ declare class AcpClient {
     getPendingMemoJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getCompletedJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
     getCancelledJobs(page?: number, pageSize?: number): Promise<AcpJob[]>;
+    private _fetchJobList;
+    private _hydrateJobs;
     getJobById(jobId: number): Promise<AcpJob | undefined>;
     getMemoById(jobId: number, memoId: number): Promise<AcpMemo | undefined>;
     getAgent(walletAddress: Address): Promise<AcpAgent | undefined>;