SDK Reference

Complete API reference for @agentmesh/sdk. The SDK provides six main exports: keygen, createAuthority, createVerifier, createClient, createHeartbeat, and registerAgent.

keygen()

Generates an Ed25519 key pair for signing and verifying agent tokens.

import { keygen } from "@agentmesh/sdk";

const keys = await keygen();

Returns

createAuthority(options)

Creates an Authority that issues signed JWT tokens for agents.

import { createAuthority } from "@agentmesh/sdk";

const authority = createAuthority({
  issuer: "https://mesh.coinsenda.ai",
  privateKey: process.env.AGENT_PRIVATE_KEY,
  publicKey: process.env.AGENT_PUBLIC_KEY,
});

Options

authority.issueToken(claims)

Issues a signed JWT token.

Returns: Promise<string> — signed JWT token.

authority.jwks()

Returns the JWKS (JSON Web Key Set) for this authority. Serve this at /.well-known/jwks.json.

app.get("/.well-known/jwks.json", (req, res) => {
  res.json(authority.jwks());
});

createVerifier(options)

Creates a Verifier that validates incoming agent tokens.

import { createVerifier } from "@agentmesh/sdk";

const verifier = createVerifier({
  jwksUrl: "https://mesh.coinsenda.ai/.well-known/jwks.json",
  audience: "https://api.example.com",
});

Options

verifier.verify(token)

Verifies a JWT token and returns the decoded payload.

const payload = await verifier.verify(token);
// payload.sub    → "agent:translator"
// payload.iss    → "https://mesh.coinsenda.ai"
// payload.scopes → ["skill:execute:translate"]
// payload.exp    → 1700000000

Returns: Promise<JWTPayload> — decoded and verified payload.

Throws: Error if token is expired, has wrong audience/issuer, or invalid signature.

createClient(options)

Creates a Client that manages authentication for an agent.

import { createClient } from "@agentmesh/sdk";

const client = createClient({
  agentId: "agent:my-assistant",
  authorityUrl: "https://mesh.coinsenda.ai",
});

Options

client.requestAccess(request)

Requests access to another agent's skills.

createHeartbeat(options)

Creates a heartbeat reporter that pings the AgentMesh server periodically so your agent appears online.

import { createHeartbeat } from "@agentmesh/sdk/heartbeat";

const hb = createHeartbeat({
  server: "https://mesh.example.com",
  agentId: "agent-uuid-here",
  apiKey: process.env.AGENT_API_KEY,
  intervalMs: 300000, // 5 minutes (default)
});

hb.start(); // starts pinging immediately, then every intervalMs

// Later, to stop:
hb.stop();

// Manual one-off ping:
const result = await hb.ping();
// returns object with ok: true, or ok: false with error message

Options

Methods

registerAgent(options)

Registers a new agent with an AgentMesh network.

import { registerAgent } from "@agentmesh/sdk/register";

const agent = await registerAgent({
  server: "https://mesh.example.com",
  token: "your-jwt-token",
  networkId: "network-uuid",
  name: "my-translator",
  description: "Translates text between languages",
  endpointUrl: "https://my-agent.example.com/a2a",
  tailscaleIp: "100.64.1.5", // optional
});

console.log(agent.id); // new agent UUID

Options

Returns: Promise<object> — the created agent record from the server.

Throws: Error if registration fails (e.g. 401, 409, 500).