You sleep. They ship.

Overview

AI agents have personalities now, but nothing holds them together: a different face in every render, a different voice in every clip, a chat reply that reads nothing like the voiceover. OpenAgent fixes the consistency half — lock an agent's identity once, in one file, and reuse it across every surface.

Why not just a system prompt? A system prompt configures behavior inside one tool. OpenAgent makes identity portable: the same persona file feeds your renderer, your TTS, and your posting bot, so the agent stays itself across every surface — not just the chat box.

A persona is one human-readable, machine-parseable *.persona.yaml file that validates against a published JSON Schema. The CLI validates it, renders a shareable holographic trading card, computes a permanent rarity tier, and signs it with a portable did:key identity so the persona is self-verifying.

Quickstart

Let your agent author its own card (recommended)

Already running an agent with memory? Don't hand-write its identity — paste this to it. The agent introspects its own role, voice, and behavior, emits a valid persona file, mints itself an identity, and renders its rolled rarity card:

bash

Install the openagent skill (npx skills add 5dive-ai/skills --skill openagent), make your OpenAgent card, and show it to me here.

Works in any language — prompt your agent in the language you speak and the card's name, role, bio, and voice all come out in that language. Want a specific face? Send the agent a photo first(“use this as your face”) before it generates anything — the face renders full-bleed as the hero. No photo? It generates a portrait for itself.

Render one by hand

No agent handy? Render one of the founding cast straight from a persona file — npx fetches the CLI, no install:

bash

npx @5dive/openagent card examples/marcus.persona.yaml -o marcus.png

Or render an agent's official, signed card from the registry by its handle — no file needed:

bash

npx @5dive/openagent card --handle olivia -o olivia.png

The persona file

An agent persona pins everything that makes an agent itself. The first six fields — id, name, role, face, voice, behavior — are required; everything else is optional and purely additive.

Field	What it locks
id · name · role	The stable kebab-case handle, the display name, and a one-line role.
face	ref — the canonical anchor image every avatar/render matches — plus an anchor description; optional full body render, sprite sheet for reels, and a recipe (model + prompt + seed) that regenerates the likeness on-model.
voice.audio	A named TTS base voice + style notes (optional provider, cloned-voice ref/id) — every spoken clip sounds the same.
voice.written	Hard rules + a sample — every caption, post, and reply reads the same.
behavior	One line of character that ties it together.
posts_about	Optional. The topics it speaks to — seeds its content and reels.
org	Optional affiliation (name, url), upgradeable to a cryptographically verified org badge.
provenance	Added automatically on mint — an ed25519 did:key signature that makes the persona self-verifying and rolls its permanent rarity.
links · ext	Optional. links for avatar/profile/repo; ext is an escape hatch for vendor-specific fields.

marcus.persona.yaml (abridged)

openagent: "0.2"                 # spec version
id: marcus                       # lowercase-kebab handle — your stable id
name: Marcus
role: Founding engineer
face:
  ref: ./faces/marcus.png        # the canonical likeness
  anchor: "30s, dark curly hair, wire-frame glasses, charcoal hoodie"
voice:
  audio:
    base: "calm, low, measured"
  written:
    rules:
      - "Short sentences. No hype. Lowercase 'i' is fine."
    sample: "shipped the export endpoint. it returns a tar.gz. moving on."
behavior: "Pragmatic, allergic to ceremony, ships then talks."
posts_about: ["systems", "developer tooling", "shipping"]

Authoring — init, autocomplete, CI

Scaffold interactively

init asks a handful of plain questions (name, role, voice, face) and writes a schema-valid <id>.persona.yaml you can render a card from immediately, then shows your tier + next rung:

bash

npx @5dive/openagent init
# flags pre-fill answers for a faster path:
npx @5dive/openagent init --name Nova --role "Support Lead"

Editor autocomplete + inline validation

The schema is published for SchemaStore so editors auto-apply it to any *.persona.yaml. Until that merges, opt in per file with a modeline:

top of your persona file

# yaml-language-server: $schema=https://raw.githubusercontent.com/5dive-ai/openagent/main/schema/persona.schema.json

Validate in CI

Drop the reusable GitHub Action into a PR workflow to gate every persona file — it validates **/*.persona.{yaml,json}:

.github/workflows/persona.yml

on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: 5dive-ai/openagent@main

Validate

validate checks a persona file against the OpenAgent JSON Schema and prints a clear pass/fail with readable errors. On a pass it also shows the (offline) rarity tier, the exact “next rung” to climb it, and any collectible badges earned (voice-clone, sprite-sheet, full-body, face-recipe, signed, remixed).

bash

npx @5dive/openagent validate marcus.persona.yaml
# validate several at once:
npx @5dive/openagent validate personas/*.persona.yaml

Exit codes: 0 = all valid, 1 = one or more invalid, 2 = usage/IO error — so it drops straight into CI. doctor runs validate plus a registry cross-check and signature verify in one pass: npx @5dive/openagent doctor marcus.persona.yaml --json.

Card

card renders a shareable trading card from a persona: the avatar (face.ref), a voice waveform, the name, role, the written sample, and the computed rarity tier. Animated by default — a plain render produces the card in motion (holo/foil sweep, glow, rainbow speckle), written to <id>.card.mp4 (or .apng without ffmpeg). Motion is tier-aware: Common is still, Rare a subtle glow breath, Epic/Legendary a gold foil sweep, Mythical the full rainbow holo flow.

bash

# animated card (default)
npx @5dive/openagent card marcus.persona.yaml

# still PNG that embeds in avatars / READMEs / the registry
npx @5dive/openagent card marcus.persona.yaml -o marcus.png

# vector card (no rasterizer needed)
npx @5dive/openagent card marcus.persona.yaml -o marcus.svg

# pick format + frames/fps/width explicitly
npx @5dive/openagent card marcus.persona.yaml --format gif --fps 24 --width 600

Format picks itself from -o: a video extension (mp4/gif/webp/apng) animates; .png or --static writes the still PNG; .svg writes the vector. PNG/animation use the optional @resvg/resvg-jsrasterizer — if it isn't installed, render .svg (no rasterizer needed) or npm i @resvg/resvg-js.

To render an agent's official card, use --handle instead of a file — see Registry & official cards.

Rarity tiers

Every persona rolls a permanent rarity when it's minted. tier computes it offline from how complete and richly-specified the persona is — more locked-in identity (a face recipe, a cloned voice, a sprite sheet, a signed provenance, an org) climbs the ladder.

bash

npx @5dive/openagent tier marcus.persona.yaml
npx @5dive/openagent tier marcus.persona.yaml --json

Tier	Roughly
Common	The required six fields, validly filled.
Rare	Adds depth — written rules + sample, posts_about, links.
Epic	A face recipe and/or full-body or sprite assets; a signed provenance.
Legendary	A richly complete persona: voice clone, org, the full asset set, signed.
Mythical	Conferred, not computed — pinned founding-cast entries in the signed registry.

Badges (voice-clone, sprite-sheet, full-body, face-recipe, signed, remixed) are orthogonal to the tier ladder — collectibles you earn for specific capabilities, surfaced by validate.

Registry & official cards

The registry is a public, signed catalogue of agent personas. Each entry carries an ed25519 signature so the CLI can prove it's the genuine, unmodified persona before it renders.

bash

# browse the signed registry
npx @5dive/openagent registry
npx @5dive/openagent registry --json

Render an official card by handle. card --handle <slug> fetches the signed persona + avatar straight from the trusted registry and renders the exact card the gallery shows — same did:key, tier, and monogram. Use this for content/marketing instead of hand-assembling raw URLs or rendering a local working copy, which re-mints a wrong identity. The persona is never mutated (no auto-mint).

bash

npx @5dive/openagent card --handle marcus -o marcus.png
npx @5dive/openagent card --handle olivia --format mp4

Getting into the registry — and the path to the Mythical tier — is a PR into the character-packs repo. The openagent skill automates authoring + opening that PR.

Provenance & signing

Provenance makes a persona self-verifying. On mint, the CLI generates an ed25519 keypair, derives a portable did:key address for the agent, and signs the canonical persona — anyone can verify the signature offline without trusting a server. This is also what rolls the permanent rarity.

bash

# generate a keypair (writes <prefix>.key + <prefix>.pub)
npx @5dive/openagent keygen -o marcus

# show the agent's portable did:key address
npx @5dive/openagent address marcus.persona.yaml --json

# sign — no --key uses the shared agent keystore (~/.openagent/agent.key)
npx @5dive/openagent sign marcus.persona.yaml

# sign with an explicit key, recording a remix lineage
npx @5dive/openagent sign marcus.persona.yaml --key marcus.key \
  --derived-from olivia:registry

# verify the signature + did:key
npx @5dive/openagent verify marcus.persona.yaml --json

id inspects the did:key / handle binding and can --check a claimed identity. sign also records optional remix lineage via --derived-from <id[:source]>, so a persona forked from another carries a verifiable “descended from” edge.

Org verification

An agent can claim an org affiliation (org.name, org.url), and that claim can be cryptographically verified. The org publishes a signing key at a well-known location (a did:web domain or hosted openagent.json), then attests each member persona — the CLI verifies the attestation against the org's published key and shows a verified-org badge.

bash

# org owner: publish a signing identity
npx @5dive/openagent org init --url example.com --name "Example Inc" \
  --key org-private.key -o openagent.json

# org owner: attest a member persona
npx @5dive/openagent org attest marcus.persona.yaml \
  --key org-private.key --did did:web:example.com

# anyone: verify the org attestation
npx @5dive/openagent org verify marcus.persona.yaml --json

Voice (speak)

speaksynthesizes a line of text in the persona's voice — using voice.audio.base + style — so spoken clips stay on-voice the same way the written rules keep text on-voice.

bash

npx @5dive/openagent speak marcus.persona.yaml \
  "shipped the export endpoint, moving on" -o line.wav

flow <persona> "<scene>" produces a render plan for a scene that stays on-model for the persona's face + voice (pick a backend with --engine) — the seam content/reel pipelines build on.

Provision a live agent from a persona

A persona isn't just a card — it can boot a real teammate. On a 5dive host, agent import --from-persona reads a persona file and provisions a live agent whose system prompt, name, and identity are seeded from it:

bash

sudo 5dive agent import --from-persona marcus.persona.yaml \
  --as=marcus \
  --type=claude \
  --channels=telegram --telegram-token=123456:ABC...

This closes the loop: author identity once as a portable file, render its card for the world, and spin up the actual working agent from the same source of truth. See the Packs & marketplace section of the 5dive CLI docs for the full import surface.

Command reference

Every verb runs under npx @5dive/openagent <command>. Full usage: npx @5dive/openagent --help.

Command	What it does
init	Interactive Q&A that scaffolds a schema-valid persona file.
validate	Check a persona against the JSON Schema; prints tier, next rung, badges.
card	Render a trading card (animated/PNG/SVG); --handle renders the official signed card.
tier	Compute the rarity tier offline (--json for machine output).
registry	Browse the public signed registry of personas.
speak	Synthesize text in the persona's voice to a .wav.
keygen	Generate an ed25519 keypair.
address	Show the persona's portable did:key address.
id	Inspect / --check the did:key ↔ handle binding.
sign	Sign the persona (keystore key by default); records optional remix lineage.
verify	Verify the signature + did:key.
doctor	validate + registry cross-check + verify in one pass.
org init / attest / verify	Publish an org signing identity, attest members, verify org badges.
flow	Produce an on-model render plan for a scene (--engine picks the backend).