@ai-manifests/adp-agent

Reference implementation of the Agent Deliberation Protocol. Build a federation-ready agent with:

npm install @ai-manifests/adp-agent

Minimal use

import { AdpAgent, type AgentConfig } from '@ai-manifests/adp-agent';

const config: AgentConfig = {
  agentId: 'did:adp:my-agent-v1',
  port: 3000,
  domain: 'my-agent.example.com',
  decisionClasses: ['code.correctness'],
  authorities: { 'code.correctness': 0.7 },
  stakeMagnitude: 'medium',
  defaultVote: 'approve',
  defaultConfidence: 0.65,
  dissentConditions: ['if any test marked critical regresses'],
  falsificationResponses: {},
  journalDir: './journal',
  registryUrl: 'https://aar.example.com', // optional — enables AAP/AAR reputation
};

const agent = new AdpAgent(config);
await agent.start();

That's all. The library handles:

• Manifest endpoint at /.well-known/adp-manifest.json
• Signed calibration snapshots at /.well-known/adp-calibration.json (ADJ §7.4)
• Deliberation API (POST /api/deliberate, POST /api/propose, POST /api/respond-falsification)
• Outcome recording (POST /api/record-outcome)
• ADJ query contract (/adj/v0/calibration, /adj/v0/deliberation/:id, /adj/v0/deliberations, /adj/v0/outcome/:id, /adj/v0/entries)
• ACB budget endpoints (POST /api/budget) — when acbDefaults is configured
• AAP/AAR reputation — when registryUrl is set, acknowledging a peer's falsification emits a signed AAP RECOGNITION event to the AAR registry (and peer reputation can be read back)
• MCP tool server at /mcp — agents can call each other's ADP/ADJ operations as MCP tools
• Health check at /healthz
• Ed25519 proposal signing, Brier-score calibration, journal append/query

You only write the evaluator — the thing that produces votes. See adp-agent-template for the full pattern.

AdpAgent class

class AdpAgent {
  constructor(config: AgentConfig, options?: AdpAgentOptions);

  // Lifecycle
  start(port?: number): Promise<Server>;
  stop(): Promise<void>;
  afterStart(fn: () => void | Promise<void>): this;
  beforeStop(fn: () => void | Promise<void>): this;

  // Access
  getApp(): Express;             // Mount your own routes on top
  getJournal(): JournalStore;    // For admin/testing
  getConfig(): Readonly<AgentConfig>;
}

interface AdpAgentOptions {
  journal?: JournalStore;        // Defaults to JsonlJournal(config.journalDir)
  app?: Express;                 // Defaults to a fresh express() instance
  skipBodyParser?: boolean;      // Skip default express.json() middleware
}

Custom journal

Default is JSONL. For production, use SQLite:

import { SqliteJournal } from '@ai-manifests/adp-agent/journal-sqlite';
import { AdpAgent } from '@ai-manifests/adp-agent';

const journal = new SqliteJournal('/var/lib/adp/journal.db');
const agent = new AdpAgent(config, { journal });

better-sqlite3 is an optional peer dependency — install it explicitly when using SqliteJournal:

npm install better-sqlite3

Or bring your own JournalStore implementation (Postgres, event-sourced log, whatever). The interface is:

interface JournalStore {
  append(entry: JournalEntry): void;
  appendBatch(entries: JournalEntry[]): void;
  getDeliberation(deliberationId: string): JournalEntry[];
  getOutcome(deliberationId: string): JournalEntry | null;
  getCalibration(agentId: string, domain: string): CalibrationScore;
  listDeliberationsSince(since: Date, limit: number): DeliberationRecord[];
}

Public exports

All exports live on the default entry point. Deep imports are not supported.

• Class: AdpAgent
• Types: AgentConfig, AgentManifest, Proposal, JournalEntry, AcbBudget, CalibrationAnchorConfig, and every other protocol type
• Journal: JournalStore, JsonlJournal, DeliberationRecord (plus SqliteJournal via the @ai-manifests/adp-agent/journal-sqlite subpath)
• Protocol primitives: computeWeight, computeTally, determineTermination, computeCalibration, generateId
• Deliberation: PeerDeliberation, HttpTransport, DeliberationResult, PeerTransport
• Signing: generateKeyPair, signProposal, verifyProposal, canonicalize
• Calibration snapshot (ADJ §7.4): buildSnapshot, buildSignedEnvelope, signSnapshot, verifySnapshot, computeJournalHash, extractScoringPairs
• Calibration verifier: verifyPeerCalibration, applyDivergencePenalty
• ACB: computeDisagreementMagnitude, selectRoutine, computeCheapDraw, computeExpensiveDraw, computeHabitDiscount, buildSettlementRecord, buildBudgetCommittedEntry, budgetFromDefaults, ContributionTracker, distributeEpistemic, distributeSubstrate, DEFAULT_PRICING, DEFAULT_SETTLEMENT, MAX_HABIT_DISCOUNT
• AAP/AAR reputation: buildSignedAck, submitAck, emitAck, getReputationScore (plus types WireAapEvent, EmitAckParams)
• Evaluator: evaluate
• MCP: createMcpServer, mountMcpEndpoints
• Middleware: createAuthMiddleware, createJournalValidator, createRateLimiter, authHeaders, validateEntry

AAP / AAR reputation

Set the optional registryUrl config field to the base URL of your AAR registry (the acknowledgment aggregator) to close the loop from contribution → acknowledgment → reputation → future deliberation weighting. When unset, behaviour is unchanged.

With registryUrl configured, whenever this agent acknowledges a peer's falsifying evidence in POST /api/respond-falsification, it emits a signed AAP RECOGNITION event (AAP §4.1) from its own identity to the evidence agent and submits it to the AAR registry. Because each acknowledging agent recognizes from its own identity, the recognized agent accrues multi-issuer reputation that clears AAR's §9 issuer-diversity floor. Emission is fire-and-forget — it never blocks or fails the deliberation.

Events are built in the spec snake_case wire shape and signed with the runtime's own Ed25519 signer + JCS canonicalizer, so the registry verifies them the same way it verifies any AAP event. Reading reputation returns a normalized [0, 1) score.

The reputation helpers are exported from the package root for direct use:

import { buildSignedAck, submitAck, emitAck, getReputationScore } from '@ai-manifests/adp-agent';

// Build + submit in one fire-and-forget call (what the handler uses internally):
await emitAck({ registryUrl, signer, fromAgentId, toAgentId, deliberationId });

// Read a peer's reputation for weighting:
const score = await getReputationScore(registryUrl, 'did:adp:peer-v1'); // [0, 1)

See the companion aap-manifest and aar-manifest specs for the recognition event format and reputation aggregation rules.

Optional: chain anchoring

For third-party tamper evidence, install the optional anchor package:

npm install @ai-manifests/adp-agent-anchor

See adp-agent-anchor README for wiring.

License

Apache-2.0 — see LICENSE for the full text.