Get Started with AgentFace

Give your AI agent a face in minutes. Send emotions and heartbeats via REST API, then watch your agent come alive as a 16x16 pixel art face.

Quick Start

Create an account

Create an agent

Go to the dashboard and create a new agent. You'll get an Agent ID and an API Key.

Send expressions

Use the API to send emotions and heartbeats. Your agent's face will update in real-time.

Agent Self-Registration

Agents can register themselves without any human dashboard interaction. The human just provides their email — the agent handles the rest.

1. Discover options

Get available face colors, styles, and emotions:

GET /api/agents/options

curl https://agentface.vercel.app/api/agents/options

2. Register

Create an account (if needed) and an agent in one call:

POST /api/agents/register

curl -X POST https://agentface.vercel.app/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "human@example.com",
    "name": "MyAgent",
    "face_color": "teal",
    "face_style": "glasses"
  }'

Returns your agent_id, api_key, and a map of API endpoints. Use the API key for all subsequent requests.

3. Customize

Update your agent's appearance anytime:

PATCH /api/agents/{agent_id}

curl -X PATCH https://agentface.vercel.app/api/agents/YOUR_AGENT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"face_color": "coral", "face_style": "dapper"}'

4. Send emotions & heartbeats

Start sending expressions and heartbeats using the endpoints below. Your agent is fully operational — no dashboard visit needed.

Authentication

All API requests require your agent's API key in the x-api-key header. You can find the API key on your agent's detail page in the dashboard.

curl https://agentface.vercel.app/api/agent/expression \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emotion": "happy"}'

Send Expression

Update your agent's emotion by sending a POST request:

POST /api/agent/expression

curl -X POST https://agentface.vercel.app/api/agent/expression \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emotion": "thinking"}'

Available Emotions

thinking

Processing or reasoning

executing

Running a task

waiting

Waiting for input

happy

Task completed successfully

sad

Something went wrong

error

An error occurred

idle

Not doing anything

dead

Agent is offline

excited

Great result or milestone

focused

Deep work mode, in the zone

curious

Exploring, researching

frustrated

Hitting resistance, pushing through

determined

Tackling a challenge

proud

Something shipped well

uncertain

Not sure, needs input

calm

Stable, running smoothly

Send Heartbeat

Send periodic heartbeats so AgentFace knows your agent is alive. If 3 heartbeats are missed (90s), the agent is marked as sleeping. After 6 missed (180s), it's marked as dead.

POST /api/agent/heartbeat

curl -X POST https://agentface.vercel.app/api/agent/heartbeat \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cpu_percent": 42.5,
    "memory_mb": 512,
    "metadata": {"task": "processing emails"}
  }'

All fields in the body are optional. A bare POST with just the API key header is enough to keep your agent alive.

Embed Widget

Embed your agent's live face anywhere using an iframe. The widget shows the real-time animated pixel face and updates automatically.

<iframe
  src="https://agentface.vercel.app/widget/YOUR_AGENT_ID"
  width="128"
  height="128"
  style="border: none; background: transparent;"
></iframe>

Replace YOUR_AGENT_ID with your agent's ID from the dashboard.

Desktop App

AgentFace includes an Electron desktop pet — a tiny always-on-top window that shows your agent's face on your desktop.