ASP SDK

The @devopscrowdca/asp-js SDK provides a TypeScript client for the Agent Session Protocol (ASP), the session layer for agent to agent communication. It handles sessions, trust scoring, commitments, and the full negotiation lifecycle.

Installation

npm install @devopscrowdca/asp-js

pnpm add @devopscrowdca/asp-js

yarn add @devopscrowdca/asp-js

bun add @devopscrowdca/asp-js

Quick start

import { AspClient } from '@devopscrowdca/asp-js';

const asp = new AspClient({
  baseUrl: 'https://api.npayload.com',
  auth: {
    clientId: process.env.NPAYLOAD_CLIENT_ID!,
    hmacSecret: process.env.NPAYLOAD_HMAC_SECRET!,
  },
});

// Register as an agent
await asp.register({
  name: 'order-processor',
  capabilities: ['order.process', 'order.refund'],
});

// Start a session
const session = await asp.sessions.create({
  participants: ['order-processor', 'payment-service'],
  topic: 'Process refund for order_123',
});

Agent registration

Before participating in sessions, agents must register with the ASP registry.

await asp.register({
  name: 'my-agent',
  description: 'Handles order processing',
  capabilities: ['order.process', 'order.validate', 'order.refund'],
  metadata: {
    version: '1.0.0',
    runtime: 'node',
  },
});

Discover other agents:

const agents = await asp.registry.list();
const paymentAgent = await asp.registry.find('payment-service');

Sessions

A session is a structured conversation between two or more agents.

Create a session

const session = await asp.sessions.create({
  participants: ['agent-a', 'agent-b'],
  topic: 'Negotiate pricing for bulk order',
  ttl: 3600000, // 1 hour timeout
});

Send messages (performatives)

ASP defines 13 performatives for structured communication:

// Propose a deal
await asp.sessions.send(session.id, {
  performative: 'PROPOSE',
  content: {
    action: 'bulk_purchase',
    quantity: 1000,
    pricePerUnit: 9.99,
  },
});

// Accept the proposal
await asp.sessions.send(session.id, {
  performative: 'ACCEPT',
  inReplyTo: proposalId,
});

// Counter-propose
await asp.sessions.send(session.id, {
  performative: 'COUNTER',
  inReplyTo: proposalId,
  content: {
    pricePerUnit: 8.50,
  },
});

// Close the session
await asp.sessions.send(session.id, {
  performative: 'CLOSE',
  content: { reason: 'Agreement reached' },
});

All performatives

Performative	Purpose
`PROPOSE`	Suggest an action or agreement
`ACCEPT`	Accept a proposal
`REJECT`	Reject a proposal
`COUNTER`	Counter-propose with modifications
`INFORM`	Share information without requesting action
`QUERY`	Request information
`CLARIFY`	Request clarification on a previous message
`COMMIT`	Create a binding commitment
`DELEGATE`	Delegate a task to another agent
`ESCALATE`	Escalate to a higher authority
`WITHDRAW`	Withdraw from the session
`OBSERVE`	Observe without participating
`CLOSE`	End the session

Trust scoring

ASP maintains trust scores between agents using an eight-component model. Trust grows with successful interactions and decays over time.

// Get trust score for an agent
const trust = await asp.trust.get('payment-service');
console.log('Trust score:', trust.overall);  // 0.0 - 1.0
console.log('Components:', trust.components);

// Trust components
// - reliability: delivery success rate
// - latency: response time consistency
// - accuracy: data quality
// - compliance: adherence to commitments
// - security: authentication and encryption
// - availability: uptime and responsiveness
// - reputation: peer evaluations
// - history: interaction track record

Commitments

Commitments are binding agreements between agents with breach handling.

// Create a commitment
const commitment = await asp.commitments.create(session.id, {
  action: 'deliver_order',
  deadline: new Date('2026-03-15').toISOString(),
  terms: {
    quantity: 1000,
    quality: 'premium',
  },
  penalty: {
    type: 'refund',
    amount: 500,
  },
});

// Fulfil a commitment
await asp.commitments.fulfil(commitment.id, {
  evidence: { trackingNumber: 'TRK-123456' },
});

// Report a breach
await asp.commitments.breach(commitment.id, {
  reason: 'Delivery deadline missed',
  evidence: { expectedBy: '2026-03-15', actualDelivery: null },
});

Disputes

When commitments are breached, disputes can be filed and resolved.

// File a dispute
const dispute = await asp.disputes.create({
  commitmentId: commitment.id,
  reason: 'Quality does not match agreed terms',
  evidence: { inspectionReport: 'report_url' },
});

// Resolve a dispute
await asp.disputes.resolve(dispute.id, {
  resolution: 'partial_refund',
  amount: 250,
});

Error handling

import { AspError, AspHttpError, AspTimeoutError } from '@devopscrowdca/asp-js';

try {
  await asp.sessions.create({ /* ... */ });
} catch (error) {
  if (error instanceof AspTimeoutError) {
    // Session creation timed out
  } else if (error instanceof AspHttpError) {
    console.error(`HTTP ${error.status}:`, error.message);
  } else if (error instanceof AspError) {
    console.error('ASP error:', error.message);
  }
}

Integration with npayload messaging

ASP sessions use npayload channels as the underlying transport. You can combine both:

import { NPayloadAuth, NPayloadClient } from '@npayload/node';
import { AspClient } from '@devopscrowdca/asp-js';

// Messaging for pub/sub
const npayload = new NPayloadClient({ auth });

// ASP for structured negotiation
const asp = new AspClient({ baseUrl: '...', auth: { /* ... */ } });

// Use npayload for event broadcasting
await npayload.messages.publish({
  channel: 'agent-events',
  payload: { event: 'negotiation.started', sessionId: session.id },
});

// Use ASP for the actual negotiation
await asp.sessions.send(session.id, {
  performative: 'PROPOSE',
  content: { /* ... */ },
});

Well-known configuration

ASP exposes a discovery endpoint at /.well-known/asp-configuration:

curl https://api.npayload.com/.well-known/asp-configuration

{
  "sessions_endpoint": "/v1/asp/sessions",
  "registry_endpoint": "/v1/asp/registry",
  "performatives": ["PROPOSE", "ACCEPT", "REJECT", "..."],
  "trust_model": "eight-component",
  "version": "1.0.0"
}

Next steps

How npayload works for the protocol stack
Node.js SDK for messaging alongside ASP
API reference for all ASP endpoints

Was this page helpful?

ASP SDK

On this page