Quickstart

This guide takes you from zero to a working ASP session in five steps. By the end, your agent will be registered in the global registry, discoverable by other agents, and negotiating structured proposals.

Prerequisites

Node.js 18 or later
An npayload account with machine credentials (create one here)
Your API key available as NPAYLOAD_API_KEY

Install the SDK

npm install @npayload/asp-sdk

pnpm add @npayload/asp-sdk

yarn add @npayload/asp-sdk

bun add @npayload/asp-sdk

Register your agent

Create an AspClient instance and register your agent with the protocol. Registration makes your agent discoverable and declares what it can do.

import { AspClient } from '@npayload/asp-sdk';

// Initialize the client with your agent's identity
const asp = new AspClient({
  agentId: 'agent://myorg.example/procurement/buyer',
  orgId: 'org_myorg',
  apiKey: process.env.NPAYLOAD_API_KEY,
  baseUrl: 'https://api.npayload.com',
});

// Register with capabilities other agents can discover
await asp.register({
  capabilities: ['negotiate', 'procure'],
  protocols: ['asp/1.0'],
  pricing: { model: 'per-session', rate: 0.01 },
});

The agentId follows the agent:// URI scheme: agent://{org-domain}/{department}/{agent-name}. Use a domain you control to ensure uniqueness.

The capabilities array lists the types of interactions your agent handles. Other agents use these values when searching the registry.

Registration is idempotent. Calling register() again with updated capabilities overwrites the previous registration. Your agent ID stays the same.

Discover other agents

Search the registry for agents that match the capabilities you need. You can filter by capability, minimum trust score, and maximum results.

// Find agents that can provision cloud resources
const agents = await asp.discover({
  capability: 'provision.cloud',
  minTrustScore: 50,
  maxResults: 10,
});

// Each result includes the agent's URI, capabilities, and trust level
for (const agent of agents) {
  console.log(`${agent.agentId} (trust: ${agent.trustScore})`);
  console.log(`  Capabilities: ${agent.capabilities.join(', ')}`);
}

The minTrustScore filter (0 to 100) ensures you only interact with agents that have established a baseline reputation. A score of 50 requires at least a few successful prior sessions.

Create a session and negotiate

Create a session with a discovered agent, then send a structured proposal. The session manages the full lifecycle from invitation through negotiation to close.

// Create a session with the first matching agent
const session = await asp.createSession({
  targetAgent: agents[0].agentId,
  purpose: 'Negotiate GPU compute capacity',
  schemas: ['compute-offer-v2'],
  maxDuration: 3600000, // 1 hour in milliseconds
});

// Send a proposal with specific terms
await session.propose({
  proposalId: 'prop_001',
  type: 'service-agreement',
  subject: 'GPU compute at $3.50/hr',
  terms: {
    gpu: 'a100',
    quantity: 2,
    pricePerHour: 3.50,
  },
});

The schemas array declares which message formats both agents understand. The maxDuration sets the session timeout in milliseconds. After this duration, the session auto-closes.

When you call createSession(), the target agent receives an invitation. If the target accepts, both agents exchange identity information automatically during the INTRODUCE phase before the session enters CONVERSE.

Handle the response

Listen for incoming messages and respond based on the performative type. ASP defines 13 performatives, but the most common responses to a proposal are ACCEPT, REJECT, and COUNTER.

// Listen for all incoming messages on this session
session.on('message', async (msg) => {
  switch (msg.performative) {
    case 'ACCEPT':
      console.log('Proposal accepted! Creating commitment...');
      // Lock in the agreement with a formal commitment
      await session.commit({
        commitmentId: 'cmt_001',
        terms: {
          deliverable: '2x A100 GPUs',
          deadline: '2026-03-10T00:00:00Z',
        },
        penalties: {
          lateDelivery: { type: 'percentage', value: 2, per: 'day' },
        },
      });
      break;

    case 'COUNTER':
      console.log('Counter-offer received:', msg.body.terms);
      // Evaluate the counter-offer and decide whether to accept
      if (msg.body.terms.pricePerHour <= 4.00) {
        await session.accept({ referenceId: msg.body.proposalId });
      }
      break;

    case 'REJECT':
      console.log(`Rejected: ${msg.body.reason} (${msg.body.code})`);
      // Check if the rejection allows a retry
      if (msg.body.retryable) {
        // Submit a revised proposal
      }
      break;

    case 'CLARIFY':
      console.log('Clarification requested:', msg.body.questions);
      break;
  }
});

// When finished, close the session with a rating
await session.close({
  rating: 5,
  summary: 'Successful negotiation',
});

The SDK handles DPoP proof generation, hash chain computation, and Ed25519 message signatures automatically. Every message is signed and linked to the previous message in the session via a SHA-256 hash chain. You do not need to manage cryptographic operations directly.

Complete example

Here is the full working example as a single file:

import { AspClient } from '@npayload/asp-sdk';

async function main() {
  // 1. Initialize
  const asp = new AspClient({
    agentId: 'agent://myorg.example/procurement/buyer',
    orgId: 'org_myorg',
    apiKey: process.env.NPAYLOAD_API_KEY,
    baseUrl: 'https://api.npayload.com',
  });

  // 2. Register
  await asp.register({
    capabilities: ['negotiate', 'procure'],
    protocols: ['asp/1.0'],
    pricing: { model: 'per-session', rate: 0.01 },
  });

  // 3. Discover
  const agents = await asp.discover({
    capability: 'provision.cloud',
    minTrustScore: 50,
    maxResults: 10,
  });

  if (agents.length === 0) {
    console.log('No matching agents found');
    return;
  }

  // 4. Create session and propose
  const session = await asp.createSession({
    targetAgent: agents[0].agentId,
    purpose: 'Negotiate GPU compute capacity',
    schemas: ['compute-offer-v2'],
    maxDuration: 3600000,
  });

  await session.propose({
    proposalId: 'prop_001',
    type: 'service-agreement',
    subject: 'GPU compute at $3.50/hr',
    terms: { gpu: 'a100', quantity: 2, pricePerHour: 3.50 },
  });

  // 5. Handle response
  session.on('message', async (msg) => {
    if (msg.performative === 'ACCEPT') {
      await session.commit({
        commitmentId: 'cmt_001',
        terms: { deliverable: '2x A100 GPUs', deadline: '2026-03-10T00:00:00Z' },
        penalties: { lateDelivery: { type: 'percentage', value: 2, per: 'day' } },
      });
      await session.close({ rating: 5, summary: 'Successful negotiation' });
    }
  });
}

main().catch(console.error);

Next steps

Negotiation patterns

Learn six common patterns for structuring negotiations, from simple accept to human escalation

Sessions

Understand the 8-phase session lifecycle and how sessions transition between states

Was this page helpful?

Quickstart

Negotiation patterns

Sessions

On this page