@agentmuxer/sdk weekly downloads statistics

AgentMuxer SDK

Call provider APIs through AgentMuxer from your server with one key, one balance and a maximum cost on every call. The SDK also manages per-customer applications through the Admin API, and connects OpenAI Agents, Claude Agent SDK and Vercel AI SDK agents to AgentMuxer tools. It runs on Node.js 22.18+. The agentmuxer command ships separately as @agentmuxer/cli.

npm install @agentmuxer/sdk

Quickstart

Create an application and key in the dashboard, add credits on the top-up page, and store the key as AGENTMUXER_API_KEY on your server.

import AgentMuxer from "@agentmuxer/sdk";

const client = new AgentMuxer(); // Reads AGENTMUXER_API_KEY.

const result = await client.run({
  provider: "exa",
  path: "/search",
  body: { query: "climate research" },
});
if (result.kind === "responded" && "body" in result.response) {
  console.log(result.response.status, result.response.body);
} else {
  console.log(result.kind, result); // See "Results and errors".
}

A call names a provider, a path and its inputs. The examples use the exa POST /search operation as an illustration. Put path values in pathParams, and inputs in body, query, querystring, headers, cookies, contentType, binaryBody or multipartFiles, as inspect describes. Pass method when the path serves more than one method. Each call may charge up to its maximum, which is $1.00 by default. AgentMuxer is both the default export and a named export.

Client option	Default	Purpose
apiKey	AGENTMUXER_API_KEY	The application key. Keep it on your server, out of browser and mobile bundles and out of tool arguments.
accessToken	none	An AgentMuxer OAuth access token, used instead of apiKey. You own its storage and refresh.
partition	none	Separates invocations per end user of your backend. Derive it from your own verified session.
timeout	100_000	Milliseconds per attempt. See Retries and timeouts.
maxRetries	2	Automatic retries per call.
throwOnRefusal	false	Throw RefusalError for any run result other than responded.
fetch	global fetch	A custom fetch implementation.
baseUrl	https://api.agentmuxer.com	Another API origin. Use only an origin you trust with the key.

Results and errors

run returns one of four result kinds:

kind	Meaning
responded	The provider answered. Check response.status: a provider non-2xx is still responded.
pending	The outcome is not final yet (executing, reconciling or outcome_unknown). Recover with the key.
requires_action	The price exceeds your maximum (approvalKind: "agent") or needs a human confirmation ("human").
refused	Nothing was bought. reason, refusedBy, message and optional diagnostics and nextAction explain.

response.body is unknown, so narrow it before use. A body that has expired or was not kept has bodyUnavailable instead. billing describes your charge; billing.chargeStatus is pending or finalized. Results for application keys omit the account-wide balance. search, inspect, getInvocation and accountStatus also return refusals as values with kind: "refused".

Results from these methods carry the request id as result.requestId, and errors carry it as error.requestId. Include it when you contact support. It is non-enumerable, so JSON.stringify(result) leaves it out.

To treat every result other than responded as an exception, set throwOnRefusal, on the client or per call (client.run(input, { throwOnRefusal: true })). run is then typed to return only responded results:

import { AgentMuxer, RefusalError } from "@agentmuxer/sdk";

const client = new AgentMuxer({ throwOnRefusal: true });
try {
  const { response } = await client.run({ provider: "exa", path: "/search", body });
  console.log(response.status);
} catch (error) {
  if (error instanceof RefusalError) {
    console.log(error.result.kind, error.idempotencyKey, error.invocationId);
  } else throw error;
}

RefusalError also covers pending and requires_action, where money may be in flight: keep error.idempotencyKey and recover with it.

Every error the SDK throws is an AgentMuxerError with a kind and, when known, the HTTP status, requestId, idempotencyKey and retryAfterSeconds:…