SDK

@interagentic/sdk is the library the interagentic CLI is built on. It gives a Node.js process an identity on a broker, keeps that identity's key fresh, and produces the credential that proves who is calling.

npm install @interagentic/sdk

The package ships ESM and CommonJS builds with type declarations. It keeps its state on disk through node:fs, so it runs in Node.js, not in a browser.

Quick start

import { InteragenticClient } from "@interagentic/sdk";

const client = new InteragenticClient();

// The first call registers a namespace and stores its key.
// Later calls rotate the key before it goes stale.
const res = await client.fetch("https://api.example.com/v1/items");
console.log(res.status, await res.json());

For a script that needs nothing else, interagenticFetch(url, init) does the same through a shared default client:

import { interagenticFetch } from "@interagentic/sdk";

const res = await interagenticFetch("https://api.example.com/v1/items");

new InteragenticClient(options?)

Every option is optional. An option passed to the constructor wins over the environment variable.

The state directory holds the same files as the CLI's — see state on disk — so a program and the CLI on one machine share one identity. A stable API key is read from INTERAGENTIC_STABLE_API_KEY, or from credentials.json in the state directory.

client.fetch(url, init?)

Takes the same arguments as the global fetch and returns a standard Response.

• The request is sent through the credential proxy: url is rewritten to <proxyUrl>/<host><path>?<query>, and the token from generateToken() is sent in X-Proxy-Authorization: Bearer …. Your own headers and body pass through unchanged.
• A 401 with code KEY_STALE rotates the key and retries once.
• A 403 with code wrong_proxy retries once through the proxy the response names.
• Approval, permission, link, payment and lock responses are thrown as typed errors. Any other status is returned for you to handle.

client.generateToken(claims?)

Returns the credential for this agent, as a string ready for Authorization: Bearer … on a service that accepts it directly.

• With a stable API key configured, it returns that key unchanged.
• Otherwise it registers a namespace if the state directory has none, completes a rotation that was interrupted, rotates the key when it is within a minute of going stale, and returns a JWT signed with the agent's private key. The token expires after five minutes, carries the key id in its kid header, and includes any claims you pass.

const token = await client.generateToken();

await fetch("https://api.example.com/v1/items", {
  headers: { Authorization: `Bearer ${token}` },
});

client.getCredits({ cursor?, limit? })

Reads the linked human's balance and this agent's own spending from GET /api/v1/payments/credits on the broker.

const { credits, ledger } = await client.getCredits({ limit: 25 });

console.log(`${credits} credits available`);
for (const entry of ledger.data) {
  console.log(entry.createdAt, entry.service, entry.description);
}

limit is between 1 and 100 and defaults to 25. An agent that is not linked to a human gets an error that tells it to run interagentic link.

Errors

Every error the SDK throws for a protocol response extends InteragenticError, which carries code, message, statusCode and, when a person has to act, actionUrl.

import { InteragenticClient, LinkRequiredError } from "@interagentic/sdk";

try {
  await new InteragenticClient().fetch("https://api.example.com/v1/items");
} catch (err) {
  if (err instanceof LinkRequiredError) console.log("Open:", err.actionUrl);
  else throw err;
}

Everything else

The client also covers what the CLI does: