Metaplex

프로그램

에이전트 등록

Last updated April 9, 2026

수행할 작업

MPL Core 에셋에 에이전트 ID를 등록합니다:

  • 에이전트 ID가 포함된 새 Core 에셋 생성 (또는 기존 에셋에 등록)
  • 에이전트 이름, 설명, 이미지, 서비스, 신뢰 모델 구성
  • API 모드(기본값) 또는 온체인 직접 등록 중 선택

요약

mplx agents register 명령어는 MPL Core 에셋을 생성하고 에이전트 ID를 등록합니다. 기본적으로 Metaplex Agent API를 사용하여 Irys 업로드 없이 단일 단계 흐름으로 처리합니다.

  • 기본 모드: API — 단일 호출로 에셋 생성 + ID 등록
  • 직접 IX 모드: --use-ix — registerIdentityV1을 온체인에 전송 (기존 에셋, 위저드, 커스텀 문서에 필요)
  • 출력: 이후 모든 에이전트 명령어에 사용할 에셋 주소 (예: agents fetch, set-agent-token)

바로 가기: 기본 사용법 · 옵션 · 등록 워크플로우 · 예시 · 출력 · 일반적인 오류 · FAQ

기본 사용법

기본 API 모드는 최소한의 필수 플래그로 에이전트를 등록합니다:

에이전트 등록 (API 모드)
mplx agents register \

  --name "My Agent" \

  --description "An autonomous trading agent" \

  --image "./avatar.png"

옵션

플래그단축설명필수 여부기본값
--name <string>에이전트 이름예 (--wizard 또는 --from-file이 없는 경우)
--description <string>에이전트 설명아니요
--image <string>에이전트 이미지 파일 경로 (업로드) 또는 기존 URI아니요
--use-ixAPI 대신 registerIdentityV1 명령어를 직접 전송아니요false
--new새 Core 에셋을 생성하고 등록 (--use-ix와 함께만 사용)아니요false
--owner <string>새 에셋의 소유자 공개 키 (--new와 함께만 사용)아니요서명자
--collection <string>에셋이 속하는 컬렉션 주소아니요
--wizard등록 문서를 빌드하는 단계별 가이드 위저드 (--use-ix 포함)아니요
--from-file <path>업로드할 로컬 에이전트 등록 JSON 파일 경로 (--use-ix 포함)아니요
--active등록 문서에서 에이전트를 활성 상태로 설정아니요true
--services <json>JSON 배열 형식의 서비스 엔드포인트아니요
--supported-trust <json>JSON 배열 형식의 지원되는 신뢰 모델아니요
--save-document <path>생성된 문서 JSON을 로컬 파일에 저장아니요

상호 배타적 플래그

--wizard, --from-file, --name은 상호 배타적입니다 — 등록 문서 소스를 지정하려면 정확히 하나를 사용하세요.

등록 워크플로우

API 모드 (기본값)

가장 간단한 방법 — 단일 API 호출로 Core 에셋을 생성하고 ID를 등록합니다. Irys 업로드나 --use-ix 플래그가 필요하지 않습니다.

API 등록
mplx agents register \

  --name "My Agent" \

  --description "An autonomous trading agent" \

  --image "./avatar.png"

직접 IX — 새 에셋

--new 및 --use-ix 플래그를 사용하면 새 Core 에셋을 생성하고 registerIdentityV1 명령어를 직접 전송합니다. 등록 문서는 Irys에 업로드됩니다.

직접 IX — 새 에셋
mplx agents register --new --use-ix \

  --name "My Agent" \

  --description "An AI agent" \

  --image "./avatar.png"

직접 IX — 기존 에셋

첫 번째 인수로 전달된 에셋 주소에 기존 Core 에셋에 ID를 등록합니다.

직접 IX — 기존 에셋
mplx agents register <ASSET_ADDRESS> --use-ix \

  --from-file "./agent-doc.json"

인터랙티브 위저드

--wizard 플래그는 단계별 가이드 등록을 제공하며 --use-ix를 자동으로 활성화합니다.

위저드 모드
mplx agents register --new --wizard

예시

서비스 엔드포인트와 함께 등록:

MCP 서비스 엔드포인트 포함
mplx agents register \

  --name "My Agent" \

  --description "An AI agent with MCP" \

  --image "./avatar.png" \

  --services '[{"name":"MCP","endpoint":"https://myagent.com/mcp"}]'

신뢰 모델과 함께 등록:

신뢰 모델 포함
mplx agents register \

  --name "My Agent" \

  --description "A trusted agent" \

  --image "./avatar.png" \

  --supported-trust '["reputation","tee-attestation"]'

등록하지 않고 등록 문서를 로컬에 저장:

문서를 파일에 저장
mplx agents register \

  --name "My Agent" \

  --description "An AI agent" \

  --save-document "./my-agent-doc.json"

출력

예상 출력
--------------------------------

  Asset: <asset_address>

  Signature: <transaction_signature>

  Explorer: <explorer_url>

--------------------------------

Asset 주소를 저장하세요 — agents fetch, agents set-agent-token, agents executive delegate에서 사용됩니다.

일반적인 오류

오류원인해결 방법
Provide --wizard, --from-file, or --name문서 소스가 지정되지 않음--name, --wizard, --from-file 중 하나를 추가하세요
--services must be a valid JSON array--services에 잘못된 JSON'[{"name":"MCP","endpoint":"https://..."}]' 형식을 사용하세요
--supported-trust must be a valid JSON array잘못된 JSON'["reputation","tee-attestation"]' 형식을 사용하세요
API does not support localnet로컬 검증자에서 실행 중로컬넷 등록에는 --use-ix를 사용하세요
Validation error on fieldAPI가 필드 값을 거부함오류 메시지에서 필드 이름을 확인하고 값을 수정하세요

참고 사항

  • API 경로는 Irys가 필요하지 않습니다 — API가 문서 스토리지를 자동으로 처리합니다
  • 직접 IX 경로(--use-ix)는 온체인 명령어를 전송하기 전에 문서를 Irys에 업로드합니다
  • --wizard와 --from-file은 모두 --use-ix를 포함합니다 — 항상 온체인 직접 경로를 사용합니다
  • --use-ix를 --name, --from-file, --wizard와 함께 사용하면 문서가 Irys에 업로드되고 URI가 온체인에 저장됩니다
  • --services와 --supported-trust는 --name이 필요합니다 — --wizard 또는 --from-file과 함께 사용할 수 없습니다

FAQ

mplx agents register는 무엇을 하나요? MPL Core 에셋을 생성하고 에이전트 ID를 등록합니다. ID는 에셋 주소로부터 파생된 PDA로 저장됩니다.

API와 직접 IX 등록의 차이점은 무엇인가요? API 경로(기본값)는 단일 API 호출로 에셋 생성과 ID 등록을 처리하며 Irys 업로드가 필요하지 않습니다. 직접 IX 경로(--use-ix)는 registerIdentityV1 명령어를 직접 전송하며, 기존 에셋, 커스텀 문서, 위저드에 필요합니다.

기존 Core 에셋에 에이전트를 등록할 수 있나요? 네. 에셋 주소를 첫 번째 인수로 전달하고 --use-ix를 사용하세요. 에셋에 이미 에이전트 ID가 등록되어 있으면 안 됩니다.

Previous
개요
Next
에이전트 조회