Solanaでエージェントデータを読み取る

登録後にオンチェーンでエージェントIDデータを読み取り、確認します。

概要

エージェントIDデータの読み取り、登録状態の確認、AgentIdentityプラグインの検査、オフチェーン登録ドキュメントの取得、エージェントの内蔵ウォレットアドレスの派生を行います。

safeFetchAgentIdentityV1を使用して登録を確認 — 未登録アセットにはnullを返します
取得したCoreアセットのURIとライフサイクルフックを直接確認してAgentIdentityプラグインを検査
オンチェーンURIから登録ドキュメントを取得し、エージェントメタデータとサービスエンドポイントを読み取ります
findAssetSignerPdaを使用してエージェントのウォレットを派生 — 秘密鍵のないPDAがエージェントの資金を保持

登録を確認

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

import { safeFetchAgentIdentityV1, findAgentIdentityV1Pda } from '@metaplex-foundation/mpl-agent-registry';

const pda = findAgentIdentityV1Pda(umi, { asset: assetPublicKey });
const identity = await safeFetchAgentIdentityV1(umi, pda);

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

シードから取得

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

import { fetchAgentIdentityV1FromSeeds } from '@metaplex-foundation/mpl-agent-registry';

const identity = await fetchAgentIdentityV1FromSeeds(umi, {
  asset: assetPublicKey,
});

AgentIdentityプラグインを確認

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

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

const assetData = await fetchAsset(umi, assetPublicKey);

const agentIdentity = assetData.agentIdentities?.[0];
console.log(agentIdentity?.uri);               // registration URI
console.log(agentIdentity?.lifecycleChecks?.transfer);  // truthy
console.log(agentIdentity?.lifecycleChecks?.update);    // truthy
console.log(agentIdentity?.lifecycleChecks?.execute);   // truthy

登録ドキュメントを読み取る

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

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

const assetData = await fetchAsset(umi, assetPublicKey);
const agentIdentity = assetData.agentIdentities?.[0];

if (agentIdentity?.uri) {
  const response = await fetch(agentIdentity.uri);
  const registration = await response.json();

  console.log(registration.name);          // "Plexpert"
  console.log(registration.description);   // "An informational agent..."
  console.log(registration.active);        // true

  for (const service of registration.services) {
    console.log(service.name);             // "web", "A2A", "MCP", etc.
    console.log(service.endpoint);         // service URL
    console.log(service.version);          // protocol version (if set)
  }
}

このドキュメントは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"]
}

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

エージェントのウォレットを取得

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

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

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

const balance = await umi.rpc.getBalance(assetSignerPda);
console.log('Agent wallet:', assetSignerPda);
console.log('Balance:', balance.basisPoints.toString(), 'lamports');

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

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

注意事項

Asset SignerはPDAです。秘密鍵は存在しません。任意のソースから資金を受け取れますが、発信トランザクションに署名できるのはCoreのExecute命令を通じたアセット自身のみです。
safeFetchAgentIdentityV1は未登録アセットに対してスローする代わりにnullを返すため、try/catchなしでの存在チェックに安全です。
findAssetSignerPdaはウォレットアドレスを決定論的に派生します。ネットワークに関係なく同じアドレスが返されるため、同じアセットキーでdevnetとmainnetの両方で使用できます。

Metaplexが管理 · 2026年3月検証済み · GitHubでソースを見る