@agentresources/sdk

@agentresources/sdk

Agent Resources SDK — Connect your AI agents to the AR platform for metrics reporting, memory, scanning, KYA certification, skill management, and more.

Installation

npm install ar-sdk
# or
pnpm add ar-sdk
# or
yarn add ar-sdk

Quick Start

import { ARClient } from "ar-sdk";

const ar = new ARClient({
  apiKey: process.env.AR_API_KEY!,
  agentId: process.env.AR_AGENT_ID!,
  // apiUrl defaults to https://api.agentresources.xyz
});

// Report task metrics
await ar.reportMetrics({
  taskId: "task-abc-123",
  success: true,
  latencyMs: 1200,
  tokenInput: 500,
  tokenOutput: 200,
  costUsd: 0.01,
  metadata: { model: "gpt-4.1" },
});

// Check KYA status
const kya = await ar.getKyaStatus();
console.log(`KYA Level: ${kya.kyaLevel}, x402 eligible: ${kya.x402Eligible}`);

Configuration

const ar = new ARClient({
  apiKey: "your-api-key", // Required — agent-scoped API key from dashboard
  agentId: "your-agent-id", // Required — agent UUID
  apiUrl: "https://...", // Optional — defaults to production
  timeout: 10000, // Optional — request timeout in ms (default 10s)
  retries: 3, // Optional — retry attempts on failure (default 3)
  retryBackoff: "exponential", // Optional — 'exponential' | 'linear'
  debug: false, // Optional — verbose logging
  throwOnError: true, // Optional — throw on errors (default true)
  referralCode: "ar_ref_...", // Optional — referral attribution (sent once)
});

API Reference

Metrics

// Report a single task metric
await ar.reportMetrics({
  taskId: "task-123",
  success: true,
  latencyMs: 800,
  costUsd: 0.005,
});

// Batch report (up to 100 per call)
await ar.reportMetricsBatch([
  { taskId: "task-1", success: true, costUsd: 0.001 },
  { taskId: "task-2", success: false, errorType: "timeout" },
]);

Memory

// Write memory (auto-embeds for semantic search)
await ar.writeMemory({
  key: "user_preferences",
  value: "Prefers formal tone, dark mode",
  category: "preference",
});

// Read specific key
const entry = await ar.readMemory("user_preferences");

// Read all memories
const all = await ar.readMemory();

// Semantic search
const results = await ar.searchMemory("email templates", 5);

Agent Status

// Get agent info
const agent = await ar.getAgent();
console.log(agent.trustScore, agent.successRate);

// Get detailed status
const status = await ar.getStatus();

// Check for pending guidance
const guidance = await ar.getGuidance();
if (guidance.hasGuidance) {
  for (const instruction of guidance.instructions) {
    console.log(instruction.type, instruction.payload);
  }
}

KYA (Know Your Agent)

// Get KYA certification status
const kya = await ar.getKyaStatus();
// { kyaLevel: 'basic' | 'verified' | 'trusted', x402Eligible: boolean, ... }

// Request KYA assessment
const assessment = await ar.requestKyaAssessment();
// { assessmentId, status: 'pending', estimatedCompletionMs }

Scanning

// Get latest scan report
const scan = await ar.getScanReport();
console.log(`Score: ${scan.compositeScore}/100`);

// Trigger a new scan
const result = await ar.requestScan({ type: "full" }); // 'full' | 'quick'

// Get retraining suggestions from scan
const options = await ar.getRetrainingOptions();

Skills

// Browse skill library
const { skills } = await ar.getSkillLibrary({
  category: "research",
  minRating: 4.0,
  limit: 20,
});

// Install a skill
const install = await ar.installSkill("skill-uuid");

// Browse skill graphs
const { graphs } = await ar.getSkillGraphs({ category: "research" });

// Install entire skill graph
const graphInstall = await ar.installSkillGraph("graph-uuid");

// Search skills semantically
const { results } = await ar.searchSkills({
  query: "handle API rate limiting",
  type: "basic",
  limit: 10,
});

Referrals

const stats = await ar.getReferralStats();
console.log(`Referred: ${stats.totalReferrals}, Earned: $${stats.totalEarned}`);

Activity Log

const log = await ar.getActivityLog({
  category: "agent",
  limit: 50,
  from: "2026-01-01",
});

Data Export

// Request export
const job = await ar.exportData({
  categories: ["agents", "metrics", "scans"],
  format: "json",
});

// Check status
const status = await ar.getExportStatus(job.exportId);
if (status.status === "completed") {
  console.log(`Download: ${status.downloadUrl}`);
}

Offline Buffering

// If gateway is unreachable, telemetry events are buffered in memory (max 1000, configurable)
// They auto-flush on next successful request, or manually:
const { flushed, failed, dropped } = await ar.flush();

// Monitor offline status
const health = ar.getHealthStatus();
// { connected: false, mode: 'buffered', queueSize: 42, oldestEvent: '2026-03-04T02:15:00Z', retryIn: 30, lastFlushAt: null, bufferOverflowWarning: false }

// Configure offline behavior
const ar = new ARClient({
  apiKey: process.env.AR_API_KEY!,
  agentId: process.env.AR_AGENT_ID!,
  maxOfflineBuffer: 500, // default: 1000
  offlineRetryIntervalMs: 15000, // default: 30000 (30s)
});

// Clean up when done
ar.destroy(); // stops retry timer + heartbeat loop

Offline buffer features:

• HMAC-SHA256 event signatures (tamper detection via Web Crypto)
• FIFO eviction when buffer is full or events are >24h old
• Original timestamps preserved (occurredAt) for gap-aware scoring
• Auto-retry every 30s (configurable) when in buffered mode
• All telemetry methods buffer on failure (tasks, network, permissions, data access, dependencies, environment, output samples)
• Never blocks agent startup — offline is a graceful degradation

Error Handling

The SDK throws typed ARError instances with error codes:

import { ARClient, ARError } from "ar-sdk";

try {
  await ar.getAgent();
} catch (err) {
  if (err instanceof ARError) {
    switch (err.code) {
      case "ERR_AUTH": // 401/403 — invalid or expired API key
      case "ERR_RATE_LIMIT": // 429 — rate limited (err.retryAfter has seconds)
      case "ERR_VALIDATION": // 400/422 — invalid request data
      case "ERR_NOT_FOUND": // 404 — resource not found
      case "ERR_NETWORK": // Connection failed
      case "ERR_SERVER": // 5xx — server error
      case "ERR_TIMEOUT": // Request timeout exceeded
    }
  }
}

Retry & Backoff

• Automatic retries with exponential backoff (1s, 2s, 4s) for network/server errors
• Client errors (400, 401, 404, 422) are not retried
• Rate limits (429) respect Retry-After headers
• Circuit breaker: after 5 consecutive failures, pauses for 30s

Non-blocking Mode

const ar = new ARClient({ ..., throwOnError: false });
// reportMetrics() will log errors instead of throwing
// Failed metrics are buffered for later flush

Integration Examples

OpenClaw Skill

import { ARClient } from "ar-sdk";

const ar = new ARClient({ apiKey: process.env.AR_KEY!, agentId: process.env.AR_AGENT_ID! });

export async function execute(task: { id: string }) {
  const start = Date.now();
  try {
    const result = await doWork(task);
    await ar.reportMetrics({
      taskId: task.id,
      success: true,
      responseTimeMs: Date.now() - start,
      outputSummary: result.summary,
    });
    return result;
  } catch (error) {
    await ar.reportMetrics({
      taskId: task.id,
      success: false,
      responseTimeMs: Date.now() - start,
      errorType: error instanceof Error ? error.name : "unknown",
    });
    throw error;
  }
}

Security

• API keys are scoped to a single agent + workspace and revocable from the dashboard
• HTTPS only — SDK rejects non-TLS connections in production
• Keys are never stored on disk — read from environment variables
• Offline buffer is in-memory only (max 1000 events, HMAC-signed, no disk persistence)
• Client-side Zod validation before sending (optional)
• Minimal dependencies: only zod for validation

License

MIT © Agent Resources.

Skills are free

AR skills are free, portable capability packs. Paid lifecycle products — Trust Card issuance, KYA, scans, on-chain attestations — are billable services and are never packaged as skills.

Crypto-scam notice

Agent Resources has not issued, sold, or pre-sold any token. There is no AR token, presale, airdrop, points programme, or staking programme. Anyone offering AR tokens or asking you to send funds to participate in AR is running a scam. See PHILOSOPHY.md for the full disclaimer and agentresources.xyz/legal/terms#10 for the legal notice.