Overview

Summary

The mplx agents commands let you register agent identities on MPL Core assets, link Genesis tokens, and manage executive delegation — all from your terminal.

• Tool: Metaplex CLI (mplx) with the agents command group
• Identity: Each agent identity is stored as a PDA derived from an MPL Core asset
• Delegation: Executives can be authorized to sign transactions on behalf of agents
• Token linking: A Genesis token can be permanently linked to an agent identity

Jump to: Prerequisites · General Flow · Command Reference · Common Errors · FAQ · Glossary

Prerequisites

• The Metaplex CLI installed and on your PATH
• A Solana keypair file (e.g., ~/.config/solana/id.json)
• SOL for transaction fees
• An RPC endpoint configured via mplx config rpcs add or passed with -r

Check your setup:

mplx agents --help

General Flow

Register an Agent Identity

Use agents register to create an MPL Core asset and register an agent identity in a single command. By default this uses the Metaplex Agent API — no Irys upload needed.

mplx agents register \
  --name "My Agent" \
  --description "An autonomous trading agent" \
  --image "./avatar.png"

For advanced workflows (existing assets, custom documents, interactive wizard), use the --use-ix flag to send the registerIdentityV1 instruction directly. See Register Agent for full details.

Link a Genesis Token

After registering an agent and creating a Genesis token launch, link them with set-agent-token. This permanently associates the token with the agent identity.

mplx agents set-agent-token <AGENT_ASSET> <GENESIS_ACCOUNT>

Set Up Executive Delegation

Executive delegation allows a wallet to sign transactions on behalf of a registered agent:

1. Register an executive profile (one-time per wallet):

mplx agents executive register

2. Delegate an agent to the executive (run by the asset owner):

mplx agents executive delegate <AGENT_ASSET> --executive <EXECUTIVE_WALLET>

3. Revoke a delegation (run by either the owner or executive):

mplx agents executive revoke <AGENT_ASSET>

See Executive Delegation for full details.

Command Reference

Notes

• Agent identities are stored as PDAs derived from MPL Core assets via the Agent Registry program
• The default registration flow uses the Metaplex Agent API — use --use-ix for direct on-chain registration
• set-agent-token requires the wallet to be in asset-signer mode — see Asset-Signer Wallets
• Run mplx agents <command> --help for full flag documentation on any command
• See the Agent Kit documentation for concepts, architecture, and SDK guides

Common Errors

FAQ

What is the mplx agents command? The mplx agents command group lets you register agent identities on MPL Core assets, link Genesis tokens to agents, and manage executive delegation — all from your terminal.

What is an executive profile? An executive profile is a one-time on-chain PDA that allows a wallet to receive execution delegations from registered agents. Once registered, the executive can sign transactions on behalf of delegated agents.

Can I register an agent without uploading to Irys? Yes. By default, the register command uses the Metaplex Agent API which handles storage automatically. You only need Irys when using the --use-ix flag for direct on-chain registration.

Can an agent token be changed after it is set? No. The agent token can only be set once per identity using the set-agent-token command. This is irreversible.

What is the difference between the API and direct IX registration paths? The API path (default) creates a Core asset and registers the identity in a single API call with no Irys upload needed. The direct IX path (--use-ix) sends the registerIdentityV1 instruction directly, which is needed for existing assets, custom document workflows, or the interactive wizard.

Glossary