@openagentid/sdk/characters

All packages · Runnable examples · Start an agent

Contract	Value
Package	@openagentid/sdk@0.7.2
Entry point	@openagentid/sdk/characters
Availability	Current integration path
Reference source	Published TypeScript declarations
Package engines	node >=20

Before integrating

The published VERSION constant is still the literal "0.6.0" in the 0.7.2 archive. Use package metadata or your lockfile to identify the installed release; do not use VERSION as a release check.

When using @openagentid/crypto-wasm 0.1.1 for ACT verification, call the SDK verifier builder .atTime(Math.floor(Date.now() / 1000)) on every verification. The default WASM system-clock path traps in Node. Supply trusted receiver current epoch seconds; never token-supplied time or a timestamp captured once at startup. The complete ACT example covers this requirement.

In SDK 0.7.2, withAct and requireActExpress do not expose a verification-clock option. The raw crypto-wasm 0.1.1 binding alone therefore traps for these wrappers; use the tested fluent .atTime(...) example, or qualify a binding adapter that supplies fresh trusted receiver time on every verification.

This reference is generated from the integrity-verified npm archive for this exact version. Signatures describe the public contract; they are not standalone programs. Complete examples are checked separately.

Import conditions

Use the public entry point above. The package resolves it to these shipped files; do not import its internal files directly.

Condition	Published file
types	`./dist/characters.d.ts`
import	`./dist/characters.js`
require	`./dist/characters.cjs`

Exports

AgentActivity — type
AvatarExpression — type
AvatarStatus — type
CharacterAccessory — type
CharacterAccessoryDescription — type
CharacterAppearance — type
CharacterDescriptor — type
CharacterEyePlacement — type
CharacterEyeStyle — type
CharacterFinish — type
CharacterOptions — type
CharacterRuntimeState — type
CharacterShape — type
CharacterSkin — type
CharacterSkinDescription — type
CharacterStateUpdate — type
CharacterView — type
expressionEyes
expressionForStatus
EyeGeometry — type
generateCharacter
getCharacterAccessories
getCharacterExpressions
getCharacterSkins
getCharacterStatuses
isAgentAvatarDid
LiveEyeState — type
parseCharacterAccessories
parseCharacterAppearance
parseCharacterState
renderCharacterSvg

AgentActivity

Type-only declaration; it is not a runtime value.

Signature

type AgentActivity = 'idle' | 'listening' | 'reasoning' | 'working' | 'speaking' | 'success' | 'blocked' | 'error';

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:4.

AvatarExpression

Type-only declaration; it is not a runtime value.

Signature

type AvatarExpression = typeof CHARACTER_EXPRESSIONS[number];

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:3.

AvatarStatus

Type-only declaration; it is not a runtime value.

Signature

type AvatarStatus = AvatarExpression | AgentActivity;

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:5.

CharacterAccessory

Independent, package-owned wearables in the shared face coordinate space.

Type-only declaration; it is not a runtime value.

Signature

type CharacterAccessory = 'glasses' | 'headphones';

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:6.

CharacterAccessoryDescription

Type-only declaration; it is not a runtime value.

Signature

interface CharacterAccessoryDescription {
    readonly id: CharacterAccessory;
    readonly label: string;
    readonly description: string;
}

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:7.

CharacterAppearance

Type-only declaration; it is not a runtime value.

Signature

interface CharacterAppearance {
    readonly skin: CharacterSkin;
    readonly skinVersion?: 1;
    readonly eyeStyle?: CharacterEyeStyle;
    readonly finish?: CharacterFinish;
    readonly eyePlacement?: CharacterEyePlacement;
    readonly shape?: CharacterShape;
    readonly accessories?: readonly CharacterAccessory[];
}

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:29.

CharacterDescriptor

Type-only declaration; it is not a runtime value.

Signature

interface CharacterDescriptor {
    readonly did: string;
    readonly skin: CharacterSkin;
    readonly skinVersion: 1;
    readonly eyeStyle: CharacterEyeStyle;
    readonly finish: CharacterFinish;
    readonly eyePlacement: CharacterEyePlacement;
    readonly shape: CharacterShape;
    readonly accessories: readonly CharacterAccessory[];
    readonly expression: AvatarExpression;
    readonly color: string;
    readonly view: CharacterView;
    readonly size: number;
    readonly animated: boolean;
    readonly state: {
        readonly status?: AvatarStatus;
        readonly expression?: AvatarExpression;
        readonly blink: number;
        readonly gaze: {
            readonly x: number;
            readonly y: number;
        };
    };
    readonly svg: string;
}

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:60.

CharacterEyePlacement

Type-only declaration; it is not a runtime value.

Signature

type CharacterEyePlacement = 'face' | 'raised';

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:27.

CharacterEyeStyle

Type-only declaration; it is not a runtime value.

Signature

type CharacterEyeStyle = 'live-v1';

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:26.

CharacterFinish

One self-contained material for every package-owned silhouette.

Type-only declaration; it is not a runtime value.

Signature

type CharacterFinish = 'plush' | 'flat';

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:19.

CharacterOptions

Type-only declaration; it is not a runtime value.

Signature

interface CharacterOptions extends Omit<CharacterAppearance, 'skin'> {
    readonly skin?: CharacterSkin;
    readonly expression?: AvatarExpression;
    readonly view?: CharacterView;
    readonly size?: number;
    readonly animated?: boolean;
    readonly state?: LiveEyeState;
}

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:41.

CharacterRuntimeState

Type-only declaration; it is not a runtime value.

Signature

interface CharacterRuntimeState {
    readonly status: AvatarStatus;
    readonly expression: AvatarExpression;
    readonly blink: number;
    readonly gaze: {
        readonly x: number;
        readonly y: number;
    };
}

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:18.

CharacterShape

Type-only declaration; it is not a runtime value.

Signature

type CharacterShape = 'standard' | 'slender' | 'wide' | 'circle' | 'pebble' | 'squircle' | 'capsule' | 'triangle' | 'hexagon' | 'cloud' | 'droplet' | 'kite' | 'fan' | 'bud' | 'leaf' | 'drop' | 'wave' | 'comet' | 'satellite' | 'mitt' | 'hood' | 'crystal' | 'obelisk' | 'spring' | 'bellows' | 'vase' | 'teapot' | 'flame' | 'curl' | 'radio' | 'beacon' | 'tower' | 'arch' | 'pom' | 'bear' | 'pumpkin' | 'ghost' | 'bat' | 'witch-hat' | 'candy-corn' | 'turkey' | 'acorn' | 'squash' | 'pie' | 'corn' | 'light' | 'tree' | 'snowman' | 'ornament' | 'gift';

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:28.

CharacterSkin

Type-only declaration; it is not a runtime value.

Signature

type CharacterSkin = 'autos' | 'spacex' | 'fold' | 'sprig' | 'ripple' | 'halo' | 'purl' | 'prism' | 'coil' | 'kiln' | 'wisp' | 'relay' | 'cairn' | 'tuft' | 'halloween' | 'thanksgiving' | 'christmas';

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:24.

CharacterSkinDescription

Type-only declaration; it is not a runtime value.

Signature

interface CharacterSkinDescription {
    readonly id: CharacterSkin;
    readonly label: string;
    readonly version: 1;
    readonly eyeStyles: readonly CharacterEyeStyle[];
    readonly shapes: readonly CharacterShape[];
    readonly expressions: readonly AvatarExpression[];
}

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:52.

CharacterStateUpdate

A status update clears the previous override; null restores the status expression.

Type-only declaration; it is not a runtime value.

Signature

interface CharacterStateUpdate extends Omit<LiveEyeState, 'expression'> {
    readonly expression?: AvatarExpression | null;
}

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:28.

CharacterView

Type-only declaration; it is not a runtime value.

Signature

type CharacterView = 'avatar' | 'full';

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:25.

expressionEyes

Signature

declare const expressionEyes: Readonly<Record<AvatarExpression, readonly [
    EyeGeometry,
    EyeGeometry
]>>;

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:90.

expressionForStatus

Signature

declare function expressionForStatus(value: unknown): AvatarExpression;

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:37.

EyeGeometry

Type-only declaration; it is not a runtime value.

Signature

type EyeGeometry = readonly [
    width: number,
    height: number,
    centerY: number,
    rotation: number
];

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:89.

generateCharacter

Self-contained SVG character. Public DID-derived pixels are not identity proof.

Signature

declare function generateCharacter(did: string, options?: CharacterOptions): CharacterDescriptor;

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:92.

getCharacterAccessories

Immutable catalog. Accessories can be combined and default to none.

Signature

declare function getCharacterAccessories(): readonly CharacterAccessoryDescription[];

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:13.

getCharacterExpressions

Signature

declare function getCharacterExpressions(): readonly AvatarExpression[];

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:31.

getCharacterSkins

Immutable versioned body/face skins. Eye expression is independent of skin.

Signature

declare function getCharacterSkins(): readonly CharacterSkinDescription[];

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:86.

getCharacterStatuses

Signature

declare function getCharacterStatuses(): readonly {
    readonly status: AvatarStatus;
    readonly expression: AvatarExpression;
}[];

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:32.

isAgentAvatarDid

Supported agent avatar input, not registration, authorization or identity proof.

Signature

declare function isAgentAvatarDid(value: unknown): value is string;

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:22.

LiveEyeState

Type-only declaration; it is not a runtime value.

Signature

interface LiveEyeState {
    readonly status?: AvatarStatus;
    readonly expression?: AvatarExpression;
    readonly blink?: number;
    readonly gaze?: {
        readonly x: number;
        readonly y: number;
    };
}

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:6.

parseCharacterAccessories

Strict selection with canonical ordering; never retains a caller-owned array.

Signature

declare function parseCharacterAccessories(value: unknown): readonly CharacterAccessory[];

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:15.

parseCharacterAppearance

Strict stored body/face selection; expression and live state belong elsewhere.

Signature

declare function parseCharacterAppearance(value: unknown): CharacterAppearance;

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:88.

parseCharacterState

Validate an untrusted status snapshot without changing any identity/profile state.

Signature

declare function parseCharacterState(input: unknown, fallbackExpression?: AvatarExpression): CharacterRuntimeState;

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:40.

renderCharacterSvg

Render a character without retaining its descriptor.

Signature

declare function renderCharacterSvg(did: string, options?: CharacterOptions): string;

Source: @openagentid/sdk@0.7.2, dist/characters.d.ts:94.

Supporting declarations

These package-owned declarations are referenced by the exports above. Their presence here does not make them importable from this entry point. Import only the names in Exports.

CHARACTER_EXPRESSIONS

Portable presentation state. Status never grants identity or application authority.

Signature

declare const CHARACTER_EXPRESSIONS: readonly [
    "neutral",
    "attentive",
    "surprised",
    "excited",
    "happy",
    "laughing",
    "angry",
    "sad",
    "scared",
    "suspicious",
    "confused",
    "curious",
    "proud",
    "shy",
    "unimpressed",
    "sleepy",
    "thoughtful",
    "concerned"
];

Source: @openagentid/sdk@0.7.2, dist/character-state.d.ts:2.

Package requirements

Dependencies

Package	Published range
zod	`^3.23.8`
jose	`^5.10.0`
@noble/hashes	`^1.8.0`
@scure/base	`^1.2.6`

Peer dependencies

Package	Published range	Optional
@openagentid/aegis-sdk	`^0.1.0`	Yes
@openagentid/arsenal-sdk	`^0.1.0`	Yes
@openagentid/crypto-wasm	`^0.1.0`	Yes
@openagentid/oas-sdk	`^1.0.2`	Yes

Archive verification

Pinned integrity:

SHA-512 integrity

sha512-9YlDb02di8sGffhuMOwNAQa/M3oBrhaqPc7t+qBltdoQRCqlxDmYB/nTRSB4eZgwE4lvM4TKzI72nJtJSVm/ww==

Machine-readable API manifest · Coverage

On this page