Agent Robot Avatar

A lightweight, expressive robot avatar Web Component for AI agents and interactive applications.

Suitable for AI assistant and agent interfaces, including products and experiences similar to ChatGPT, Claude, Codex, Cursor, Grok Bot, Gemini CLI, and OpenCode.

It can also be used for desktop pets, virtual pets, desktop companions, digital mascots, chatbot avatars, and other interactive character experiences.

Agent Robot Avatar can also be used as a visual feedback layer for AG-UI-style agent interfaces.

Built with SVG and vanilla JavaScript, it works as a native custom element with zero runtime dependencies.

Live Demo

Open the interactive demo

Highlights

Native Web Component
SVG rendering + vanilla JavaScript
Zero runtime dependencies
Automatic blinking and subtle idle behavior
Pointer-following eyes and inertial head movement
Jelly-style drag deformation with elastic recovery
Programmatically controlled Agent states and expressions
Waiting, success, failure, warning, review, blocked, and system-error feedback
Reduced-motion support
Configurable sleep behavior
Adjustable head roundness
Optional antenna status flashing
TypeScript declarations included

Install

npm install agent-robot-avatar

import 'agent-robot-avatar';

Or load the repository source directly:

<script type="module" src="./agent-robot-avatar.js"></script>

Then add the component:

<agent-robot-avatar id="avatar"></agent-robot-avatar>

No initialization code is required. The avatar enters its default idle behavior automatically.

Basic usage

const avatar = document.querySelector('#avatar');

avatar.play('success');
avatar.play('warning');
avatar.play('error');

avatar.reset();

Available actions:

idle · bored · waiting · input · send · success · failure · warning · inspect · blocked · error · surprise · sleep · wake

failure is intended for a task that completed unsuccessfully, while error is intended for connection, service, or system failures.

For a real Agent request lifecycle:

avatar.startWaiting();

try {
  const result = await runAgentRequest();
  await avatar.play(result.ok ? 'success' : 'failure');
} catch (error) {
  await avatar.play('error');
}

Common options

<agent-robot-avatar
  size="160"
  color="#08090b"
  auto-sleep="30000"
  wake-on="activity"
  motion="auto">
</agent-robot-avatar>

Attribute	Purpose
`size`	Avatar size in pixels
`color`	Main avatar color
`auto-sleep`	Idle time before automatic sleep; `0` disables it
`wake-on`	Automatic wake policy: `activity`, `interaction`, or `manual`
`motion`	Motion policy: `auto`, `reduce`, or `full`

Common runtime controls:

avatar.setPointerFollow(false);
avatar.setHeadRoundness(75);
avatar.setAntennaFlash(true);

Events and integration

The component emits face-state for visual state changes and action-state for semantic action lifecycle changes.

For host integrations and accessibility status text, prefer action-state. See examples/accessibility.html for a runnable request-lifecycle example.

A minimal integration example is available at examples/basic.html.

Compatibility

Designed for modern browsers with support for ES Modules, Custom Elements, SVG, Pointer Events, Web Animations API, IntersectionObserver, ResizeObserver, and matchMedia.

Automated browser tests cover Chromium, Firefox, and WebKit.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md before submitting changes.

Project status

Current public version: v0.3.2

The public API is intentionally kept compact while the project evolves toward a future 1.0.0 stability commitment.

Agent Robot Avatar is independently developed and is not affiliated with, endorsed by, or representative of any AI platform or brand.

Character design and visual identity

The Agent Robot Avatar character, including its robot appearance and visual identity, is an original design by CX ArtLab.

The MIT License applies to the software and source code. It allows the avatar to be used, modified, and distributed as part of applications, but it does not transfer ownership of the Agent Robot Avatar name, character identity, or visual identity, or grant the right to present them as another party's original character or standalone brand.

Third-party product names mentioned in this project describe possible use cases only and do not indicate affiliation or endorsement.

License

MIT License. See LICENSE.

If this project is useful to you, you can buy me a coffee.