Metaplex

はじめに

エージェントデータの読み取り

Last updated July 8, 2026

登録後にエージェントIDを読み取り、確認します — SDKでオンチェーンから直接、またはインデックス済みのDAS API経由で行います。

サマリー

エージェントIDはAgent Registry SDKでオンチェーンから読み取るか、インデックス済みフィールドはDAS API経由で読み取ります。

  • オンチェーン（SDK） — 登録の確認、AgentIdentityプラグインの検査、ERC-8004ドキュメントの取得、Asset Signer PDAの派生
  • インデックス済み（DAS） — getAssetからis_agent、asset_signer、agent_tokenを読み取る。searchAssetsでエージェントを検出
  • 同じウォレットアドレス — findAssetSignerPdaとDASのasset_signerは同じPDAを返す

クイックスタート

このページでは、SDKによる登録確認、登録ドキュメント、ウォレットPDA、およびDASでインデックス済みのエージェントフィールドを扱います。

ジャンプ先： 登録を確認 · 登録ドキュメント · エージェントのウォレット · DAS経由で読み取り

  1. 1件のエージェント、詳細情報 — safeFetchAgentIdentityV1とfetchAssetを使用（下記のSDKセクション）
  2. 1件のエージェント、インデックス済みフィールド — Coreアセットアドレスを指定してgetAssetを呼び出す（下記のDASセクション）
  3. エージェントの検出 — isAgent: trueを指定してsearchAssetsを呼び出す、またはagentToken / assetSignerでフィルタ

登録を確認 {#check-registration}

安全取得メソッドはIDが存在しない場合にスローする代わりにnullを返すため、アセットが登録されているかどうかのチェックに便利です：

1import {

2  safeFetchAgentIdentityV1,

3  findAgentIdentityV1Pda,

4  mplAgentIdentity,

5} from '@metaplex-foundation/mpl-agent-registry'

6import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

7import { publicKey } from '@metaplex-foundation/umi'

8

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

10const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

11

12const pda = findAgentIdentityV1Pda(umi, { asset: assetPublicKey })

13const identity = await safeFetchAgentIdentityV1(umi, pda)

14

15console.log('Registered:', identity !== null)

16

17// Registered: true

シードから取得

PDAを手動で派生せずに、アセットの公開鍵から直接IDを取得することもできます：

1import {

2  fetchAgentIdentityV1FromSeeds,

3  mplAgentIdentity,

4} from '@metaplex-foundation/mpl-agent-registry'

5import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

6import { publicKey } from '@metaplex-foundation/umi'

7

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

9const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

10

11// Throws if the identity account does not exist — use safeFetchAgentIdentityV1 for unregistered assets.

12const identity = await fetchAgentIdentityV1FromSeeds(umi, {

13  asset: assetPublicKey,

14})

15

16console.log('Identity:', identity)

17

18// Identity: { ... }

AgentIdentityプラグインの確認

登録によりAgentIdentityプラグインがCoreアセットにアタッチされます。取得したアセットから直接読み取って、登録URIとライフサイクルフックを検査できます：

1import { fetchAsset, mplCore } from '@metaplex-foundation/mpl-core'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3import { publicKey } from '@metaplex-foundation/umi'

4

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

6const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

7

8const assetData = await fetchAsset(umi, assetPublicKey)

9const agentIdentity = assetData.agentIdentities?.[0]

10

11console.log(agentIdentity?.uri)

12console.log(agentIdentity?.lifecycleChecks?.transfer)

13console.log(agentIdentity?.lifecycleChecks?.update)

14console.log(agentIdentity?.lifecycleChecks?.execute)

15

16// https://example.com/agent-registration.json

17// { __kind: 'Listen' }

18// { __kind: 'Listen' }

19// { __kind: 'Listen' }

登録ドキュメントの読み取り {#read-the-registration-document}

AgentIdentityプラグインのuriは、エージェントの完全なプロファイル（名前、説明、サービスエンドポイントなど）を含むオフチェーンJSONドキュメントを指します。他のURIと同様に取得します：

1import { fetchAsset, mplCore } from '@metaplex-foundation/mpl-core'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3import { publicKey } from '@metaplex-foundation/umi'

4

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

6const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

7

8const assetData = await fetchAsset(umi, assetPublicKey)

9const agentIdentity = assetData.agentIdentities?.[0]

10

11if (agentIdentity?.uri) {

12  const response = await fetch(agentIdentity.uri)

13  if (!response.ok) {

14    throw new Error(`Registration document fetch failed: HTTP ${response.status}`)

15  }

16  const registration = await response.json()

17

18  console.log(registration.name)

19  console.log(registration.description)

20  console.log(registration.active)

21

22  for (const service of registration.services ?? []) {

23    console.log(service.name)

24    console.log(service.endpoint)

25    console.log(service.version)

26  }

27}

28

29// Plexpert

30// An informational agent...

31// true

32// web

33// https://metaplex.com/agent/<ASSET_PUBKEY>

34// undefined

このドキュメントはERC-8004エージェント登録標準に準拠しています。典型的な例は以下の通りです：

{

  "type": "https://eips.ethereum.org/EIPS/eip-8004#registration-v1",

  "name": "An informational agent providing help related to Metaplex protocols and tools.",

  "description": "An autonomous agent that executes DeFi strategies on Solana.",

  "image": "https://arweave.net/agent-avatar-tx-hash",

  "services": [

    {

      "name": "web",

      "endpoint": "https://metaplex.com/agent/<ASSET_PUBKEY>"

    },

    {

      "name": "A2A",

      "endpoint": "https://metaplex.com/agent/<ASSET_PUBKEY>/agent-card.json",

      "version": "0.3.0"

    }

  ],

  "active": true,

  "registrations": [

    {

      "agentId": "<MINT_ADDRESS>",

      "agentRegistry": "solana:101:metaplex"

    }

  ],

  "supportedTrust": ["reputation", "crypto-economic"]

}

フィールドの完全なリファレンスについては、エージェントを登録をご覧ください。

エージェントのウォレットを取得 {#fetch-the-agents-wallet}

すべてのCoreアセットにはAsset Signerと呼ばれる内蔵ウォレットがあります。アセットの公開鍵から派生したPDAです。秘密鍵は存在しないため、盗まれることはありません。ウォレットはSOL、トークン、その他のアセットを保持できます。findAssetSignerPdaでアドレスを派生します：

1import { findAssetSignerPda, mplCore } from '@metaplex-foundation/mpl-core'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3import { publicKey } from '@metaplex-foundation/umi'

4

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

6const assetPublicKey = publicKey('AGENT_CORE_ASSET_ADDRESS')

7

8const assetSignerPda = findAssetSignerPda(umi, { asset: assetPublicKey })

9const balance = await umi.rpc.getBalance(assetSignerPda)

10

11console.log('Agent wallet:', assetSignerPda)

12console.log('Balance:', balance.basisPoints.toString(), 'lamports')

13

14// Agent wallet: 6ttUwc5VVmHeVKTddB6XM5vQgBMfw62DThuoiVEufVZq

15// Balance: 1000000 lamports

アドレスは決定論的なので、誰でもアセットの公開鍵からアドレスを派生して資金を送信したり残高を確認したりできます。このウォレットに対して署名できるのは、委任されたエグゼクティブを通じたCoreのExecute命令によるアセット自身のみです。

アカウントレイアウト、PDA派生の詳細、エラーコードについては、MPL Agent Registryスマートコントラクトドキュメントをご覧ください。

DAS API経由でエージェントデータを読み取る {#read-agent-data-via-das-api}

DAS APIはMPL Coreアセット上のエージェントフィールド（登録状態、ウォレットPDA、正規トークンミント）をインデックス化するため、Coreアカウントを自分で解析せずに読み取れます。

前提条件： DAS対応RPCエンドポイントと、Umiインスタンス上の@metaplex-foundation/digital-asset-standard-api。

DASエージェント応答フィールド

DASは2つのオンチェーンソースからエージェントメタデータを導出し、トップレベルの応答フィールドとして公開します。

フィールド型含まれる対象ソース
is_agentbooleanCoreインターフェース行（アセット、コレクション、グループ）AgentIdentityがあるMplCoreAssetのみtrue；コレクション/グループはfalse
asset_signerstring (pubkey)MplCoreAssetのみ上記のfindAssetSignerPdaと同じPDA
agent_tokenstring (pubkey)設定時のMplCoreAssetsetAgentTokenV1で書き込まれるAgentIdentityV2 PDAミント

エージェントになり得るのは**MplCoreAsset**行のみです（is_agent: true）。コレクションやグループはDASレスポンスにis_agent: falseを含む場合がありますが、エージェント登録は個別のCoreアセットにのみ適用されます。非Coreアセット（Token Metadata NFT、圧縮NFT、代替可能トークン）は3つのフィールドすべてを省略します。

トークンがリンクされていない登録済みエージェントはis_agent: trueとasset_signerを返しますが、agent_tokenは省略します：

getAsset response (registered, no token)
{

  "interface": "MplCoreAsset",

  "id": "84jw9dw7hMRJXFvzJXrBzVQpmVWaGUtYT7R6QhNU9qt3",

  "is_agent": true,

  "asset_signer": "6ttUwc5VVmHeVKTddB6XM5vQgBMfw62DThuoiVEufVZq",

  "external_plugins": [

    {

      "type": "AgentIdentity",

      "adapter_config": { "uri": "https://example.com/agent-registration.json" }

    }

  ]

}

setAgentTokenV1の後、DASはagent_tokenを含めます：

getAsset response (registered with token)
{

  "interface": "MplCoreAsset",

  "id": "84jw9dw7hMRJXFvzJXrBzVQpmVWaGUtYT7R6QhNU9qt3",

  "is_agent": true,

  "agent_token": "FakeToken11111111111111111111111111111111111",

  "asset_signer": "6ttUwc5VVmHeVKTddB6XM5vQgBMfw62DThuoiVEufVZq"

}

JSON-RPCレスポンスはsnake_case（is_agent、agent_token、asset_signer）を使用します。searchAssetsのリクエストパラメータはcamelCase（isAgent、agentToken、assetSigner）を使用します。snake_caseのエイリアスも受け付けます。

DASで1件のエージェントを取得

Coreアセットアドレスが分かっている場合はgetAssetを使用します。

1import { dasApi } from '@metaplex-foundation/digital-asset-standard-api'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3import { publicKey } from '@metaplex-foundation/umi'

4

5const umi = createUmi('<DAS_ENDPOINT>').use(dasApi())

6

7const asset = await umi.rpc.getAsset(publicKey('AGENT_CORE_ASSET_ADDRESS'))

8

9if (asset.is_agent) {

10  console.log('Agent wallet (asset_signer):', asset.asset_signer)

11  console.log('Canonical token mint:', asset.agent_token ?? 'not set')

12} else {

13  console.log('Core asset is not a registered agent')

14}

15

16// Agent wallet (asset_signer): 6ttUwc5VVmHeVKTddB6XM5vQgBMfw62DThuoiVEufVZq

17// Canonical token mint: not set

登録済みエージェントを検索

isAgent: trueを指定してsearchAssetsを使用し、登録済みエージェントを一覧表示します。interface: "MplCoreAsset"と組み合わせてコレクションとグループを除外します。

1import { dasApi } from '@metaplex-foundation/digital-asset-standard-api'

2import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

3

4const umi = createUmi('<DAS_ENDPOINT>').use(dasApi())

5

6const results = await umi.rpc.searchAssets({

7  isAgent: true,

8  interface: 'MplCoreAsset',

9  limit: 100,

10})

11

12for (const agent of results.items) {

13  console.log(agent.id, agent.asset_signer, agent.agent_token ?? 'no token')

14}

15

16// 1RUC5FMQherGNoLF9wDBxa1oznbq1mTieWLZ8gU8S31 DwgDrVVwcuXGU2MjHcZEcNtG2cGF6cLXCS35gPiUsU6p no token

トークンミントでエージェントを検索

エージェントが正規トークンをリンクした後、agentTokenでフィルタしてミントアドレスからエージェントのCoreアセットを解決します。各エージェントは最大1つのトークンを持てます — バインディングは永久的です。

1curl -X POST <DAS_ENDPOINT> \

2  -H "Content-Type: application/json" \

3  -d '{

4    "jsonrpc": "2.0",

5    "id": 1,

6    "method": "searchAssets",

7    "params": {

8      "agentToken": "TOKEN_MINT_ADDRESS",

9      "interface": "MplCoreAsset",

10      "limit": 1

11    }

12  }'

Asset Signerでエージェントを検索

assetSignerフィルタは、指定されたアドレスと一致するexecute PDAを持つCoreアセットを見つけます。エージェントのウォレットは分かっているがアセットの公開鍵が分からない場合に使用します。

1curl -X POST <DAS_ENDPOINT> \

2  -H "Content-Type: application/json" \

3  -d '{

4    "jsonrpc": "2.0",

5    "id": 1,

6    "method": "searchAssets",

7    "params": {

8      "assetSigner": "ASSET_SIGNER_PDA_ADDRESS",

9      "limit": 1

10    }

11  }'

DASインデックスの仕組み

DASは取り込み中に2つのオンチェーンソースからエージェントフィールドを設定します。MPL Coreアセットアカウントの更新はis_agent（AgentIdentityプラグインが存在する場合）を設定し、MplCoreAsset行のasset_signerを派生します。Agent Registry PDAの更新は、AgentIdentityV2ミントが存在する場合、既存のMplCoreAsset行にagent_tokenを設定します。

イベント更新されるフィールド備考
Coreアセットの作成または更新is_agent、asset_signerMplCoreAsset行にのみ適用。is_agentはAgentIdentity外部プラグインを反映。asset_signerはインデックス化されたすべてのCoreアセットに対して派生
AgentIdentityV2 PDAの更新agent_tokenAgent Registryトランスフォーマーが書き込み。既存の未バーンMplCoreAsset行のみを更新
アセットのバーン—以降のAgent Registry更新は無視される
古いスロットのPDAリプレイ—slot_updated_agent_registryより低いスロットの更新はスキップされる

注意事項

  • Asset SignerはPDAです — 秘密鍵は存在しません。任意のソースから資金を受け取れますが、発信トランザクションに署名できるのはCoreのExecute命令を通じたアセット自身のみです。
  • safeFetchAgentIdentityV1は未登録アセットに対してスローする代わりにnullを返すため、try/catchなしでの存在チェックに安全です。
  • findAssetSignerPdaとDASのasset_signerは、すべてのネットワークで同じ決定論的なアドレスを返します。
  • agent_tokenはsetAgentTokenV1で設定すると永久的です — クリアや再割り当ての命令はありません。
  • DASのasset_signerは登録済みエージェントだけでなく、**MplCoreAsset**行に返されます。エージェントと通常のCore NFTを区別するにはis_agentを使用してください。
  • トークンがリンクされていない登録済みエージェントはagent_tokenを省略します — createAndRegisterLaunchまたは手動のsetAgentTokenV1の前は想定される動作です。
  • Agent Registryの更新は新しいアセット行を作成しません。Coreアセットが先にインデックス化されている必要があります。
  • プロバイダーのサポートは異なります — DASプロバイダーがエージェントレジストリサポート付きのインデクサーを実行していることを確認してください。

クイックリファレンス

この表は、エージェント関連のDASフィルタ、応答フィールド、プログラムIDをまとめています。

項目値
Agent Registryプログラム1DREGFgysWYxLnRnKQnwrxnJQeSMk2HmGaC6whw2B2p
MPL CoreプログラムCoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d
Asset Signerシード['mpl-core-execute', <core_asset_pubkey>]
DAS isAgentフィルタsearchAssetsパラメータ isAgent: true | false
DAS agentTokenフィルタsearchAssetsパラメータ agentToken: <mint_pubkey>
DAS assetSignerフィルタsearchAssetsパラメータ assetSigner: <pda_pubkey>
DAS応答メソッドgetAsset、getAssets、searchAssets

FAQ

agentTokenはいつDASレスポンスに含まれますか？

agent_tokenは、エージェントのAgentIdentityV2 PDAにsetAgentTokenV1でトークンミントが設定されている場合にのみ含まれます。トークンがリンクされていない登録済みエージェントはこのフィールドを省略します。AgentIdentityV1 PDAにはトークンミントがなく、agent_tokenは決して設定されません。

assetSignerはエージェントのウォレットと同じですか？

はい。DASのasset_signerはCore Asset Signer PDAであり、findAssetSignerPdaと同じアドレスです。MplCoreAsset行に返されます。登録済みエージェントではオンチェーンウォレットとして機能します。

isAgentで非Coreアセットをフィルタできますか？

いいえ。is_agent、agent_token、asset_signerは**MplCoreAsset**にのみ適用されます。Token Metadata NFTやその他のアセットタイプはこれらのフィールドを省略します。

すべてのDASプロバイダーがエージェントトークンフィールドをサポートしていますか？

エージェントトークンのインデックス作成はMetaplex DASインデクサーに含まれています。サードパーティのプロバイダーは、エージェントレジストリトランスフォーマーとデータベースマイグレーションを含む互換性のあるインデクサーバージョンを実行する必要があります。

用語集

以下の用語は、エージェントのDAS応答と上記のSDK読み取りパスで使用されます。

用語定義
AgentIdentityプラグイン登録時にCoreアセットに設定される外部プラグイン。オフチェーン登録URIを保持する
is_agentCoreアセットにAgentIdentity外部プラグインがあることを示すDASのブール値
agent_tokenAgentIdentityV2 PDAからインデックス化された正規トークンミントの公開鍵。setAgentTokenV1で一度だけ設定される
asset_signerエージェントのオンチェーンウォレットとして機能するCore execute PDA。['mpl-core-execute', <asset>]から派生
AgentIdentityV2リンクされたトークンミントを格納するAgent Registry PDA。Coreアセットアカウントとは独立して更新される
Agent Registry transformerAgent Registry PDAの更新からagent_tokenを既存のCoreアセット行に書き込むDAS取り込みハンドラー
Next
エージェントファイナンス