Make a roster distinct as a system.

Allocate avatars together when operators must tell research, billing, security, and orchestration agents apart. Exact signature uniqueness is built in; optional distance rules add visible separation.

Allocate a set Try identity-set mode

Allocate identities together.

createIdentitySet() sorts identity work deterministically, assigns signatures, and returns both render descriptors and a manifest for later growth.

import { createIdentitySet } from "agent-avatars";

const team = createIdentitySet(
  ["research", "support", "billing"],
  {
    namespace: "my-product/agents",
    ensureUnique: true,
    minimumShapeDistance: 4,
    minimumPaletteDistance: 20,
    distanceMode: "either",
    includeSvg: true,
  }
);

Separate shape, palette, or both.

A signature prevents exact shape-and-palette duplicates. A visual-distance policy can additionally require different bitmap cells, different palette appearance, or both cues.

Shape distance

Hamming distance across the complete 5 × 4 bitmap. The integer threshold ranges from 0 to 20.

Palette distance

A versioned perceptual metric compares light and dark foreground/background pairs. The finite threshold ranges from 0 to 100.

Either or both

either accepts one sufficiently strong cue. both requires both thresholds and is stricter for small sets.

Higher thresholds reduce feasible capacity. The allocator is deterministic and greedy; exhausting its attempt limit does not prove that no packing exists elsewhere.

Keep historical assignments stable.

Persist the returned manifest and pass it back when the roster grows. Existing agents keep their signatures while new identities are constrained by the stored policy.

const first = createIdentitySet(["research", "support"], policy);

saveManifest(first.manifest);

const expanded = createIdentitySet(
  ["research", "support", "billing"],
  { ...policy, manifest: loadManifest() }
);

Treat the manifest as versioned application data. A stored policy must match the next request, and tampered assignments are validated before use.

A controlled fallback for interactive tools.

The strict API throws when allocation is infeasible. Interactive interfaces can choose the fallback helper, inspect its adjustment, and explain the effective policy to the user.

import { createIdentitySetWithFallback } from "agent-avatars";

const team = createIdentitySetWithFallback(seeds, {
  minimumShapeDistance: 8,
  minimumPaletteDistance: 30,
  distanceMode: "both",
  manifest: previousManifest,
});

if (team.policyAdjustment) {
  console.info(team.policyAdjustment);
}

The fallback helper never weakens an existing manifest policy. For a new set, it performs a bounded deterministic relaxation and reports requested and applied values.

Capacity is explicit.

Validation happens before expensive work. Use the catalog stats and errors to set product limits that match your palettes and separation policy.

Bounded input

One call accepts at most 10,000 seeds, 10,000 manifest entries, and 256 custom palettes.

Exact capacity

getCatalogStats().signatureStates reports shape-and-palette signature capacity, not guaranteed perceptual capacity under a distance policy.

See the group before shipping it.

The generator can build, inspect, copy, and download a manifest-backed identity set directly in the browser.

Open generator Integration examples