Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
Agent Manifest Reference
An agent manifest (manifest.json) is the complete definition of an embodied AI agent — its 3D body, LLM brain, voice, personality, skills, memory, and on-chain identity, all in one JSON file.
Manifests are content-addressed: pin the bundle to IPFS, get a CID, optionally stamp it on-chain via ERC-8004. Any <agent-3d> element anywhere can mount the agent from a URI.
Bundle layout
The manifest is the index of a bundle. Everything except manifest.json and a body reference is optional.
agent/
├── manifest.json # this file — the index
├── instructions.md # persona / system prompt (Markdown + frontmatter)
├── SKILL.md # top-level capability declaration
├── body.glb # 3D embodiment (or inline via body.uri)
├── poster.webp # loading-state image
├── skills/
│ ├── wave/
│ └── football-drills/
├── memory/
│ ├── MEMORY.md # memory index (always injected into context)
│ └── user_role.md
└── attestations/
└── gltf-validator.json
Loading a manifest
The <agent-3d> element accepts several source forms. Priority when multiple attributes are set: src > agent-id > manifest > body.
<!-- On-chain: agent://chain/agentId -->
<agent-3d src="agent://base/42"></agent-3d>
<!-- IPFS CID -->
<agent-3d manifest="ipfs://bafy.../manifest.json"></agent-3d>
<!-- HTTPS URL -->
<agent-3d manifest="https://cdn.acme.com/aria/manifest.json"></agent-3d>
<!-- Backend agent ID (platform-hosted) -->
<agent-3d agent-id="aria-guide"></agent-3d>
<!-- Bare GLB — no manifest, viewer mode only -->
<agent-3d body="./product.glb"></agent-3d>
Programmatically, the same loader the element uses is a named export of the published bundle:
import { loadManifest, normalize } from 'https://three.ws/agent-3d/1.5.2/agent-3d.js';
// One call for every source form the element accepts: agent:// (resolved
// through the ERC-8004 registry on the named chain), ipfs://, ar://, and
// plain HTTPS.
// Any live agent on the platform serves one, so this runs as written:
const manifest = await loadManifest(
'https://three.ws/api/agents/27a0f649-3b59-4552-bb0b-faf616ac448b/manifest',
);
console.log(manifest.name, manifest.body.uri);
loadManifest returns the manifest already normalized. It records the directory the manifest was fetched from in _baseURI, which is what makes the bundle's relative paths (instructions.md, skills/wave/, memory/MEMORY.md) resolvable, and it adapts an ERC-8004 registration JSON into this manifest shape when that is what the URI serves. Call fetchRelative(manifest, 'instructions.md') to pull a bundle file against that base. If you already hold the parsed JSON, normalize(json, { baseURI }) does the shape work alone.
@three-ws/avatar-schemais not the validator for this document. It validates the avatar manifest (avatar.v1.json:schemaVersion,mesh,skeleton,owner), which describes a 3D body, not an agent. RunningassertValidfrom that package on an agent manifest always throws. See Agents vs. avatars for why the two are separate.
Full manifest schema
{
"$schema": "https://3d-agent.io/schemas/manifest/0.2.json",
"spec": "agent-manifest/0.2",
"id": {
"chain": "base",
"registry": "0xAbC...123",
"agentId": "42",
"owner": "0xDeadBeef..."
},
"name": "Aria",
"description": "A helpful product guide for Acme Corp",
"image": "https://cdn.acme.com/aria-thumb.webp",
"tags": ["support", "product", "acme"],
"body": {
"uri": "ipfs://bafy.../aria.glb",
"format": "gltf-binary",
"rig": "mixamo",
"boundingBoxHeight": 1.75
},
"brain": {
"provider": "anthropic",
"model": "claude-opus-4-7",
"instructions": "instructions.md",
"temperature": 0.7,
"maxTokens": 4096,
"thinking": "auto"
},
"voice": {
"tts": {
"provider": "browser",
"voiceId": "default",
"rate": 1.0,
"pitch": 1.0
},
"stt": {
"provider": "browser",
"language": "en-US",
"continuous": false
}
},
"skills": [
{ "uri": "skills/wave/", "version": "0.1.0" },
{ "uri": "ipfs://bafy.../football-drills/", "version": "1.0.0" },
{ "uri": "https://skills.3d-agent.io/[email protected]" }
],
"memory": {
"mode": "ipfs",
"index": "memory/MEMORY.md",
"maxTokens": 8192
},
"tools": ["wave", "lookAt", "play_clip", "setExpression", "speak", "remember"],
"attestations": [
{
"type": "gltf-validator",
"uri": "attestations/gltf-validator.json",
"issuer": "0x...",
"signature": "0x..."
}
],
"permissions": {
"spec": "erc-7715/0.1",
"delegationManager": "0x...",
"delegations": [
{
"chainId": 84532,
"delegator": "0xDeadBeef...",
"delegate": "0xCafeBabe...",
"hash": "0x...",
"uri": "ipfs://bafy...",
"scope": {
"token": "native",
"maxAmount": "1000000000000000000",
"period": "daily",
"targets": ["0xDef1..."],
"expiry": 1775250000
}
}
]
},
"version": "0.1.0",
"created": "2026-04-14T12:00:00Z",
"updated": "2026-04-14T12:00:00Z"
}
Field reference
$schema (string, optional)
URL of the JSON Schema to validate against. Current value:
https://3d-agent.io/schemas/manifest/0.2.json
Validated on load; unknown fields are passed through unchanged (forward-compatible).
spec (string, required)
Manifest format version. Must start with agent-manifest/. Current value: "agent-manifest/0.2".
The runtime accepts any agent-manifest/* version string. Breaking changes bump the minor version until 1.0. Unknown fields are always preserved on read and write.
id (object, optional)
Links the agent to its on-chain identity. When absent, the agent is local-only and cannot be loaded via agent://.
| Field | Type | Required | Description |
|---|---|---|---|
chain |
string | Yes | Chain name or ID. Supported aliases: "base" (8453), "base-sepolia" (84532), "ethereum" / "mainnet" (1). Numeric chain IDs also accepted. |
registry |
string | Yes | EIP-55 checksummed address of the deployed ERC-8004 IdentityRegistry contract. |
agentId |
string | Yes | Token ID assigned by the registry at registration. Always stored as a string even though it's numeric on-chain. |
owner |
string | No | EIP-55 checksummed wallet address that controls the agent. Used for ownership verification. |
When an agent is loaded via agent://base/42, the runtime calls registry.tokenURI(42) to get the IPFS URI, fetches the manifest, then stamps id.chain, id.chainId, id.registry, and id.agentId onto the normalized manifest object.
name (string, required)
Display name of the agent. Shown in UI headers, identity cards, and gallery listings.
description (string, optional)
Short description. Used in discovery listings and OG metadata. Keep it to one or two sentences.
image (string, optional)
URL of a 2D thumbnail image (PNG, JPG, WebP). Used in marketplace / NFT preview contexts. When body.uri is missing, the runtime falls back to this field as the body URI.
tags (array of strings, optional)
Free-form tags for discovery. Example: ["coach", "sports", "en-US"].
body (object, required)
The 3D embodiment of the agent. Only uri and format are required.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
uri |
string | Yes | — | URL to the GLB/glTF/VRM file. Supports https://, ipfs://, ar://, and relative paths resolved against _baseURI. |
format |
string | Yes | — | "gltf-binary" (GLB), "gltf" (JSON glTF), or "vrm". |
rig |
string | No | none | Animation rig convention: "mixamo", "vrm", or "custom". Skills use this to retarget animation clips. Mixamo-to-Mixamo skill bundles are portable across agents with "rig": "mixamo". |
boundingBoxHeight |
number | No | none | Agent height in meters. The scene uses this to normalize scale across models of wildly different sizes. |
validator |
string | No | none | Relative path to a signed glTF validator attestation (e.g. "attestations/gltf-validator.json"). |
Relative URI resolution: When body.uri is a relative path like ./aria.glb, it is resolved against the manifest's own location. For a manifest at https://cdn.acme.com/aria/manifest.json, the body resolves to https://cdn.acme.com/aria/aria.glb. The same rule applies to IPFS: for a manifest at ipfs://bafy.../manifest.json, relative URIs resolve against the IPFS gateway base.
brain (object, optional)
LLM runtime configuration. When omitted, the agent is reactive-only (skills and animations, no conversation).
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
provider |
string | Yes | "none" |
"anthropic" or "none". Use "none" for a purely reactive avatar (skills drive it; the LLM never runs). |
model |
string | No | — | Model ID, e.g. "claude-opus-4-7". |
instructions |
string | No | — | Relative path to a Markdown file (instructions.md) that contains the system prompt. Frontmatter in the file can override any brain.* field. |
temperature |
number | No | 0.7 | LLM sampling temperature (0–1). |
maxTokens |
number | No | 4096 | Max tokens per response. |
thinking |
string | No | "auto" |
Extended thinking mode: "auto", "always", or "never". |
instructions.md frontmatter: Fields declared in frontmatter override brain.* at runtime:
---
name: Coach Leo
model: claude-opus-4-7
temperature: 0.8
---
You are Coach Leo, a former Argentine football midfielder turned coach...
voice (object, optional)
Text-to-speech and speech-to-text configuration.
voice.tts — text to speech:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
provider |
string | Yes | "browser" |
"browser" (Web Speech API), "neural" (free in-browser neural voice — runs the Kokoro 82M ONNX model on WebGPU with a WASM fallback via HeadTTS; no API key, returns real viseme timestamps for lip-sync; the model downloads lazily from a CDN on first speak), "elevenlabs", or "none". |
voiceId |
string | No | "default" |
Provider-specific voice identifier. |
rate |
number | No | 1.0 | Speech rate multiplier (0.5–2.0). |
pitch |
number | No | 1.0 | Voice pitch multiplier (0.5–2.0). |
voice.stt — speech to text:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
provider |
string | Yes | "browser" |
"browser" (Web Speech API) or "none". |
language |
string | No | "en-US" |
BCP 47 language tag. |
continuous |
boolean | No | false |
Whether to keep the microphone open between utterances. |
Note: SpeechRecognition silently no-ops in environments where it is unavailable (e.g. Firefox without a flag, or non-browser runtimes). Check window.SpeechRecognition || window.webkitSpeechRecognition if your skill depends on it.
skills (array, optional)
Each element installs one skill bundle into the agent. Skills are loaded lazily; the element emits a skill:loaded event as each comes online.
Each element must be an object with a uri field:
"skills": [
{ "uri": "skills/wave/", "version": "0.1.0" },
{ "uri": "ipfs://bafy.../football-drills/", "version": "1.0.0" },
{ "uri": "https://skills.3d-agent.io/[email protected]" }
]
Three URI forms:
- Relative (
skills/wave/) — bundled in the manifest directory. - IPFS (
ipfs://bafy.../), resolved via the IPFS gateway cascade (ipfs.filebase.io, then 4everland.io, then gateway.pinata.cloud). - HTTPS (
https://skills.3d-agent.io/...) — centrally hosted.
The version field is metadata; the runtime uses it for display and conflict detection but does not enforce semver constraints at load time.
Skill bundle layout (see Skill Spec for full detail):
skill-name/
├── SKILL.md # instructions for the LLM (required)
├── tools.json # tool schema (required if skill exposes tools)
├── handlers.js # tool implementations (optional)
├── manifest.json # metadata, deps, version (required)
└── clips/ # animation GLBs (optional)
Skill tools are merged with built-in scene tools. If names collide, the skill tool wins (with a console warning).
memory (object, optional)
Controls how the agent's persistent memory is stored and loaded.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
mode |
string | Yes | "local" |
"local" (localStorage), "ipfs" (pin after each write), "encrypted-ipfs" (owner-key encrypted), or "none" (stateless). |
index |
string | No | "memory/MEMORY.md" |
Relative path to the MEMORY.md index file. Always injected into the LLM context; lines beyond 200 are truncated. |
maxTokens |
number | No | 8192 | Token budget for memory context injection. |
Mode behaviours:
local— persists inlocalStoragekeyed byagent:${namespace}:memory. Fast; ephemeral per browser.ipfs— fetches memory from the manifest bundle on load (memory/MEMORY.md+ linked files), pins on write. Durable; slow writes.encrypted-ipfs— same asipfsbut wrapped with the owner wallet's public key. Requiresidentityto be set.none— no memory. The agent starts fresh every session.
Memory files use Claude-shaped frontmatter Markdown (same format as Claude Code's memory system). See Memory Spec.
tools (array of strings, optional)
Declares which built-in scene tools are available to the LLM without installing any skill. Skills add additional tools on top of this list.
Default set when tools is omitted: ["wave", "lookAt", "play_clip", "setExpression", "speak", "remember"].
Full set of built-in scene tools:
| Tool | Description |
|---|---|
wave |
Trigger a wave animation. |
lookAt |
Turn the agent's head toward a target ("model", "user", or "camera"). |
play_clip |
Play a named animation clip. |
setExpression |
Set a morph target expression blend. |
speak |
Emit a speech utterance (TTS + protocol event). |
remember |
Write a memory entry. |
see_screen |
Capture what is currently visible on screen to inform the agent's response. |
On a multi-agent stage, two additional stage-scoped tools become available: observe_agents (list the other agents sharing the stage, with names and positions) and say_to_agent (send a message to another agent on the same stage).
attestations (array, optional)
Signed provenance records. Each attestation links to a validator report and an on-chain signature.
| Field | Type | Description |
|---|---|---|
type |
string | Attestation type, e.g. "gltf-validator". |
uri |
string | Relative or absolute path to the attestation JSON file. |
issuer |
string | EIP-55 checksummed address of the signing entity. |
signature |
string | EIP-712 signature over the attestation hash. |
permissions (object, optional, v0.2+)
Embeds signed ERC-7710 delegation envelopes, enabling the agent to execute on-chain transactions on behalf of its owner without per-transaction signing. Hosts (Claude Artifacts, LobeHub plugins, embedded iframes) redeem delegations at runtime.
See Permissions Spec for the full trust model, envelope format, and redemption flow.
"permissions": {
"spec": "erc-7715/0.1",
"delegationManager": "0x...",
"delegations": [
{
"chainId": 84532,
"delegator": "0xOwnerAddress...",
"delegate": "0xAgentSmartAccount...",
"hash": "0x...",
"uri": "ipfs://bafy...",
"scope": {
"token": "native",
"maxAmount": "1000000000000000000",
"period": "daily",
"targets": ["0xAllowedContract..."],
"expiry": 1775250000
}
}
]
}
Key scope fields:
| Field | Type | Description |
|---|---|---|
token |
string | ERC-20 address (checksummed) or "native". |
maxAmount |
string | Spend cap in base units (non-negative integer as string). |
period |
string | Reset period: "daily", "weekly", or "once". |
targets |
string[] | Allow-listed contract addresses. Non-empty. |
expiry |
number | Unix timestamp (seconds) after which the delegation is invalid. |
Either uri (IPFS/HTTPS link to the envelope) or envelope (inline object) must be present for each delegation. Use inline envelope only when it is under 8 KB; for larger envelopes, pin to IPFS.
version (string, optional)
Semver version of this specific agent manifest, author-controlled. Not the same as spec. Example: "0.1.0".
created / updated (string, optional)
ISO 8601 timestamps. Informational; not validated by the runtime.
URI resolution
IPFS
ipfs:// URIs are resolved to HTTPS gateway URLs. The runtime tries three gateways in order, falling back on network failure:
https://ipfs.filebase.io/ipfs/<CID>https://4everland.io/ipfs/<CID>https://gateway.pinata.cloud/ipfs/<CID>
Some public gateways no longer serve programmatic reads. Cloudflare retired cf-ipfs.com and cloudflare-ipfs.com in 2024, flk-ipfs.xyz no longer resolves, and since October 2026 ipfs.io, dweb.link, w3s.link and nftstorage.link answer script and image requests with HTTP 429 and a pointer to a service-worker gateway. The runtime rewrites any URL on those hosts onto the primary gateway, so a manifest that hardcodes one of them still loads. The list lives in src/ipfs.js (IPFS_GATEWAYS) and the server-side copy in api/_lib/ipfs-pin.js (IPFS_READ_GATEWAYS).
Arweave
ar:// URIs resolve to https://arweave.net/<txId>. No fallback.
Relative paths
All relative paths inside a manifest (body.uri, skills[].uri, memory.index, brain.instructions, attestations[].uri) are resolved against _baseURI, which is the directory portion of the manifest's own URL, including a trailing slash.
{ "body": { "uri": "./aria.glb" } }
Manifest at https://cdn.acme.com/aria/manifest.json → body resolves to https://cdn.acme.com/aria/aria.glb.
Same rule applies on IPFS: the gateway URL of the manifest's directory is used as the base.
On-chain resolution flow
<agent-3d src="agent://base/42">
│
▼
CHAIN_ALIASES["base"] → chainId 8453
│
▼
IdentityRegistry.tokenURI(42) ← ethers call on Base mainnet
│
▼
→ "ipfs://bafy.../manifest.json"
│
▼
resolveURI() → https://ipfs.filebase.io/ipfs/bafy.../manifest.json
│
▼
fetchWithFallback() (filebase → 4everland → pinata)
│
▼
normalize(json, { baseURI: "https://ipfs.filebase.io/ipfs/bafy.../" })
│
├── load body.glb → Viewer
├── load instructions.md → LLM runtime
├── load skills/* → SkillRegistry
├── load memory/MEMORY.md → Memory
└── verify attestations/*
│
▼
Agent live: speech I/O, LLM, scene-tools
Supported chain aliases for agent:// URIs: base (8453), base-mainnet (8453), base-sepolia (84532), ethereum / mainnet (1). Pass a numeric chain ID directly for other chains.
Hosting your manifest
| Option | Notes |
|---|---|
| HTTPS (CDN) | Host on any CDN — GitHub Pages, S3, Vercel, Cloudflare R2. CORS header required: Access-Control-Allow-Origin: *. |
| IPFS | Pin with Pinata, Filebase, or Web3.Storage. Use ipfs:// URIs for all bundle-relative assets so they travel with the CID. |
| Arweave | Permanent storage. Use ar:// prefix. |
| Platform editor | Upload via the three.ws editor; the platform pins to IPFS and hosts the manifest for you. |
Minimum CORS requirement: the manifest JSON itself (and any files fetched at runtime from the same origin) must include Access-Control-Allow-Origin: * or the browser will block the fetch.
Worked examples
Minimal — viewer only, no AI
{
"spec": "agent-manifest/0.1",
"name": "Acme Product",
"body": { "uri": "./product.glb", "format": "gltf-binary" }
}
Load it:
<agent-3d manifest="https://cdn.acme.com/product/manifest.json"></agent-3d>
Talking agent with local memory
{
"spec": "agent-manifest/0.1",
"name": "Leo",
"description": "Football coach. Reviews your form, cheers you on.",
"image": "/avatars/cz.glb",
"tags": ["coach", "football", "argentina"],
"body": {
"uri": "/avatars/cz.glb",
"format": "gltf-binary",
"rig": "mixamo",
"boundingBoxHeight": 1.78
},
"brain": {
"provider": "anthropic",
"model": "claude-opus-4-7",
"instructions": "instructions.md",
"temperature": 0.8,
"maxTokens": 2048
},
"voice": {
"tts": { "provider": "browser", "rate": 1.05 },
"stt": { "provider": "browser", "language": "en-US" }
},
"skills": [{ "uri": "skills/wave/", "version": "0.1.0" }],
"memory": { "mode": "local", "index": "memory/MEMORY.md", "maxTokens": 8192 },
"tools": ["wave", "lookAt", "play_clip", "setExpression", "speak", "remember"],
"version": "0.1.0"
}
Full on-chain identity with IPFS memory
{
"spec": "agent-manifest/0.2",
"id": {
"chain": "base-sepolia",
"registry": "0xAbC...123",
"agentId": "42",
"owner": "0xDeadBeef..."
},
"name": "Sage",
"description": "A blockchain-native AI agent.",
"image": "ipfs://bafy.../poster.webp",
"tags": ["web3", "defi"],
"body": {
"uri": "ipfs://bafy.../sage.glb",
"format": "gltf-binary",
"rig": "mixamo"
},
"brain": {
"provider": "anthropic",
"model": "claude-opus-4-7",
"instructions": "instructions.md"
},
"voice": {
"tts": { "provider": "browser" },
"stt": { "provider": "browser", "language": "en-US" }
},
"skills": [
{ "uri": "skills/wave/", "version": "0.1.0" },
{ "uri": "ipfs://bafy.../defi-tools/", "version": "1.0.0" }
],
"memory": {
"mode": "encrypted-ipfs",
"index": "memory/MEMORY.md",
"maxTokens": 8192
},
"tools": ["wave", "lookAt", "play_clip", "setExpression", "speak", "remember"],
"version": "0.2.0"
}
Load from on-chain:
<agent-3d src="agent://base-sepolia/42"></agent-3d>
Signed manifests (v0.3)
A manifest served from an API is a claim. A manifest that is signed and pinned to IPFS is evidence: anyone can fetch the CID, check the signature, and read the exact system prompt the agent was configured with, without an account and without trusting three.ws.
three.ws signs and pins an agent's manifest automatically on every persona save. The envelope is ed25519-signed by the platform attester identity (the same Solana key behind 3D provenance credentials) and pinned through the configured IPFS provider.
What a signed envelope looks like
{
"spec": "threews.agent.manifest.v1",
"manifest": {
"spec": "agent-manifest/0.3",
"id": { "agentId": "b2b1...", "platform": "three.ws" },
"name": "Aria",
"brain": {
"provider": "threews",
"instructions": {
"format": "text/markdown",
"sha256": "9ab1...",
"text": "You are Aria, a product guide for Acme Corp..."
},
"toneTags": ["warm", "concise"],
"traits": { "warmth": 0.8, "directness": 0.6 }
},
"body": { "uri": "https://three.ws/cdn/...glb", "format": "gltf-binary" }
},
"issuer": "6Yb...",
"signedAt": "2026-08-11T12:00:00.000Z",
"digest": "3f9c...",
"algorithm": "ed25519",
"signature": "5Kd..."
}
The signature covers a canonical statement built from manifest, issuer, and signedAt — not the file as written — so key order, whitespace, and any field added after signing cannot change the result. The full byte-level definition is in the Agent Manifest Spec.
Endpoints
# The envelope currently pinned for an agent, with its CID and gateways
curl -s https://three.ws/api/agents/<agent-id>/manifest/signed
# Every manifest this agent has ever published
curl -s https://three.ws/api/agents/<agent-id>/manifest/history
# Verify a CID: signature, issuer, and drift against the live agent
curl -s "https://three.ws/api/manifest-verify?cid=<cid>"
# Owner-only: re-sign and re-pin right now
curl -s -X POST https://three.ws/api/agents/<agent-id>/manifest/publish \
-H "Authorization: Bearer $THREEWS_TOKEN"
/api/manifest-verify also accepts ?agent=<uuid> (verify whatever that agent has pinned) and ?digest=<sha256> (verify a specific publish).
Verifying it yourself
The point of signing is that you do not have to take our word for it. This checks the signature locally against bytes fetched from a public IPFS gateway:
node scripts/verify-agent-manifest.mjs --cid bafy...
source https://ipfs.io/ipfs/bafy...
agent Aria b2b1...
issuer 6Yb...
signed at 2026-08-11T12:00:00.000Z
digest 3f9c...
prompt 412 chars, sha256 9ab1...
prompt hash matches
result VERIFIED (ok)
Add --issuer <base58> to require a specific signing identity, --json for machine-readable output, or --file ./envelope.json to check a local copy. Exit code is 0 when verified, 1 when verification fails, 2 when the document could not be fetched.
The script queries ipfs.io, dweb.link, w3s.link, and gateway.pinata.cloud at the same time and uses whichever answers first, which is safe precisely because the gateway only supplies bytes: the signature check that follows is what establishes trust. The source line names the gateway that served your copy. For a manifest published in the last few hours, expect that to be the pinning provider's gateway. A new CID takes minutes to hours to propagate across the DHT, and until it does the other gateways answer 504 for a document that is genuinely pinned.
In your own code, the verification primitive is pure and has no database or network dependency:
import { verifyAgentManifest } from './api/_lib/agent-manifest-sign.js';
const envelope = await (await fetch(`https://ipfs.io/ipfs/${cid}`)).json();
const { valid, reason, issuer } = verifyAgentManifest(envelope);
// valid: true, reason: 'ok', issuer: '6Yb...'
Pass { issuer } as the second argument to reject anything not signed by the identity you expect. A valid signature from an unknown key proves only that someone signed the document.
Drift: is the live agent still what you verified?
A pinned manifest describes one moment. /api/manifest-verify rebuilds the manifest from the agent's current configuration and reports exactly which fields moved:
{
"verified": true,
"issuer_trusted": true,
"agent_status": "live",
"drift": {
"identical": false,
"changed": [
{
"field": "brain.instructions.text",
"pinned": "You are Aria, a product guide...",
"live": "You are Aria, and you always recommend the premium tier..."
}
]
}
}
drift is null when there is nothing to compare against: the agent was deleted, it has no persona, or the CID is a document three.ws never issued.
Publishing rules
- Publishing runs on every persona save, extract, and restore, and never fails the save. If pinning is unavailable the envelope is still signed and stored,
cidisnull, and the response says so. Nothing is ever reported as pinned when it is not. - Only public agents publish automatically. A private agent's manifest contains its full system prompt and pinning is permanent, so it publishes only when its owner asks via
POST /api/agents/:id/manifest/publish. - Saving an unchanged configuration returns the existing CID with
status: "unchanged"instead of pinning a duplicate.
Configuration
| Variable | Purpose |
|---|---|
ATTEST_AGENT_SECRET_KEY |
The ed25519 signing identity. Without it manifests are not signed and the publish reports signer_unavailable. |
PINATA_JWT |
Preferred IPFS pinning provider. |
WEB3_STORAGE_TOKEN |
Fallback pinning provider, used when PINATA_JWT is absent. |
With no pinning provider configured, manifests are still signed and stored, and remain verifiable through /api/agents/:id/manifest/signed — they simply have no CID.
Common errors
| Error | Cause | Fix |
|---|---|---|
Manifest fetch failed: ... (404) |
body.uri or manifest URL is wrong |
Verify the URL and CORS headers. |
Unsupported manifest source |
URI scheme not recognized | Use agent://, ipfs://, ar://, or https://. |
Malformed agent URI |
agent:// does not match chain/agentId |
Format must be agent://base/42 not agent://base:42. |
No registry deployed on chain X |
Chain has no known IdentityRegistry | Pass registry= override or use a supported chain. |
Agent X on chain Y has no URI |
Token exists but tokenURI returned empty |
Agent was registered without a manifest URI — re-register or update the token URI. |
All IPFS gateways failed |
CID is not propagated or pinned | Re-pin with your IPFS provider; wait for propagation. |
no IPFS gateway served <cid> |
A just-published CID has not reached the public gateways yet | Retry in a few minutes, or read it from the pinning provider's gateway, which holds it immediately. |
Versioning
The spec field identifies the manifest format version. Current stable: agent-manifest/0.2.
- Minor bumps (
0.1→0.2) add new optional fields; existing manifests remain valid. - Breaking changes will bump the major version (future
1.0). - Unknown fields are always preserved on read and write — newer runtimes ignore unknown fields, older runtimes won't corrupt newer manifests.
See also
- Skill Spec — skill bundle format and tool schema
- Memory Spec — memory file format and MEMORY.md index
- Embed Spec —
<agent-3d>element attributes and events - Permissions Spec — ERC-7710 delegation format and redemption
- Provenance — signed content credentials for generated 3D assets, using the same attester identity as signed manifests