Deterministic avatars, from first import to production.

Use one small package to render stable SVG identities in browsers, export PNG files in Node.js, allocate visually distinct agent sets, and protect sensitive seeds on the server.

Start with SVG View on npm

Install and render.

The root entry point has no runtime dependencies and works in a browser or Node.js. A stable seed plus stable options produces the same result.

npm install agent-avatars

import { createHashAvatar } from "agent-avatars";

const svg = createHashAvatar("research-assistant", {
  namespace: "my-product/agents",
  theme: "dark",
  size: 96,
});

Prefer a durable internal agent ID as the seed. The namespace separates products or identity collections, but it is not a secret.

Four focused entry points.

Import only the environment-specific surface you need. ESM, CommonJS, and TypeScript declarations are included.

`agent-avatars`

Browser and Node.js SVG generation, data URIs, descriptors, catalog inspection, validation, and identity-set allocation.

`agent-avatars/react`

A React 18/19 image component that also renders during SSR. See the React integration guide.

`agent-avatars/png`

Node.js PNG byte generation, data URIs, platform-size sets, and atomic filesystem export.

`agent-avatars/private`

Asynchronous HMAC-derived seeds and avatars for server-side use. See private identities.

Choose the API by outcome.

The public surface separates individual rendering, batch identity allocation, bitmap inspection, and file export.

Outcome	API	Notes
SVG string	`createHashAvatar()`	Browser-safe and deterministic.
Image URL value	`avatarDataUri()`	Local SVG data URI for APIs that expect a `src`.
Inspect identity	`createAvatarDescriptor()`	Returns the selected shape, palette, metrics, and stable signature.
Distinct group	`createIdentitySet()`	Exact signature uniqueness with optional visual-distance rules and reusable manifests.
Interactive group	`createIdentitySetWithFallback()`	Can report a deterministic policy adjustment when a new requested set is infeasible.
PNG bytes or files	`createAvatarPng()`, `writeAvatarPngSet()`	Node.js-only entry point with bounded supersampling.

Privacy-safe traffic attribution.

The documentation site exposes provider-neutral browser events without transmitting or persisting visitor data. Connect them to analytics only after choosing a consent and data policy.

agent-avatars:visit includes normalized UTM values, landing path, and an aiReferral flag for known assistant referrers. agent-avatars:conversion adds the clicked action from a marked link or button.

window.addEventListener("agent-avatars:visit", ({ detail }) => {
  analytics.track("Docs visit", detail);
});

window.addEventListener("agent-avatars:conversion", ({ detail }) => {
  analytics.track("Docs conversion", detail);
});

OpenAI documents ChatGPT referral URLs with utm_source=chatgpt.com; the local classifier recognizes that value as an AI referral.

Common questions.

Short answers to the integration decisions that affect stable identity.

Does the same seed always produce the same avatar?

Yes, when the package style version, seed, namespace, and identity-affecting options remain the same. Persist identity-set manifests when a group grows.

Can I use an email address as a seed?

Do not expose sensitive identifiers through ordinary deterministic output. Derive a private seed on the server with the private entry point and keep the HMAC secret out of browser code.

Does SVG generation call a remote service?

No. The root package generates output locally. A Content Security Policy may need to permit data: images if you use avatarDataUri().

Which Node.js and React versions are supported?

Runtime consumers support Node.js 18 and newer. React 18 or 19 is an optional peer dependency.

Try the real output.

Use the interactive generator for single avatars or a visually separated identity set, then copy or download SVG and PNG assets.

Open generator Browse examples