Getting Started with MPL Agent Registry

Install the SDK and register your first agent identity.

Summary

Install the @metaplex-foundation/mpl-agent-registry package, configure Umi with the identity and tools plugins, and register your first agent identity on an MPL Core asset.

Install the SDK via npm and configure Umi with mplAgentIdentity() and mplAgentTools()
Create an MPL Core collection and asset if you don't already have one
Register an identity with registerIdentityV1 and verify the attached AgentIdentity plugin
Requires @metaplex-foundation/umi-bundle-defaults and @metaplex-foundation/mpl-core

Installation

npm install @metaplex-foundation/mpl-agent-registry

Setup

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
import { mplCore } from '@metaplex-foundation/mpl-core';
import { mplAgentIdentity, mplAgentTools } from '@metaplex-foundation/mpl-agent-registry';

const umi = createUmi('https://api.mainnet-beta.solana.com')
  .use(mplCore())
  .use(mplAgentIdentity())
  .use(mplAgentTools());

Register an Identity

You need an MPL Core asset. If you don't have one, create it first:

import { generateSigner } from '@metaplex-foundation/umi';
import { create, createCollection } from '@metaplex-foundation/mpl-core';
import {
  registerIdentityV1,
  findAgentIdentityV1Pda,
  fetchAgentIdentityV1,
} from '@metaplex-foundation/mpl-agent-registry';

// Create a collection and asset
const collection = generateSigner(umi);
const asset = generateSigner(umi);

await createCollection(umi, {
  collection,
  name: 'Agent Collection',
  uri: 'https://example.com/collection.json',
}).sendAndConfirm(umi);

await create(umi, {
  asset,
  name: 'My Agent',
  uri: 'https://example.com/agent.json',
  collection,
}).sendAndConfirm(umi);

// Register the identity with a URI pointing to agent metadata
await registerIdentityV1(umi, {
  asset: asset.publicKey,
  collection: collection.publicKey,
  agentRegistrationUri: 'https://example.com/agent-registration.json',
}).sendAndConfirm(umi);

// Verify
const pda = findAgentIdentityV1Pda(umi, { asset: asset.publicKey });
const identity = await fetchAgentIdentityV1(umi, pda);
console.log(identity.asset); // matches asset.publicKey

Verify the AgentIdentity Plugin

After registration, the asset will have an AgentIdentity plugin with the URI and lifecycle checks:

import { fetchAsset } from '@metaplex-foundation/mpl-core';

const assetData = await fetchAsset(umi, asset.publicKey);

// Check the AgentIdentity plugin
const agentIdentity = assetData.agentIdentities?.[0];
console.log(agentIdentity?.uri);               // 'https://example.com/agent-registration.json'
console.log(agentIdentity?.lifecycleChecks?.transfer);  // truthy
console.log(agentIdentity?.lifecycleChecks?.update);    // truthy
console.log(agentIdentity?.lifecycleChecks?.execute);   // truthy

Next Steps

Agent Identity — Full details on the identity program
Agent Tools — Executive profiles and execution delegation

Maintained by Metaplex · Last verified March 2026 · View source on GitHub