처음 뵙겠습니다.

『DApps 개발 입문』이라는 책과 다양한 기사를 쓰고 있는 카루데네(かるでね)입니다.

이하에서도 정보를 발신하고 있으니, 관심 있는 기사가 있다면 꼭 읽어봐 주세요!

이번에는 "AI 에이전트가 사용하는 도구를 온체인에서 발견·검증하는 Agent Tool Registry를 정의하는 ERC8257"에 대해 정리해 보겠습니다.

ERC8257은 AI 에이전트용 도구를 온체인 레지스트리(Registry)에 등록하여, 도구의 매니페스트(manifest), 액세스 조건, 가격 힌트, 실행 환경 검증 정보를 발견할 수 있도록 하는 제안입니다.

도구의 실행이나 결제는 레지스트리가 처리하지 않으며, 도구를 찾고, 올바른 매니페스트인지 검증하며, 이용 가능한지를 판정하기 위한 최소한의 토대를 정의합니다.

아래에 정리된 내용을 해설하며 정리해 나가겠습니다.

ERC8257은 AI 에이전트가 이용할 수 있는 도구를 등록하는 온체인 레지스트리입니다.

등록 정보는 ToolConfig로서 저장되며, 도구의 설명 본체는 HTTPS로 취득할 수 있는 매니페스트(manifest)에 위치합니다.

레지스트리가 온체인에서 가지는 정보는 누가 등록했는지, 매니페스트를 어디에서 취득하는지, 해당 매니페스트의 keccak256 해시, 그리고 액세스 판정을 맡길 외부 컨트랙트(External Contract)입니다.

도구의 입출력 스키마, 가격, 액세스 조건, 실행 환경에 대한 설명은 매니페스트에 포함되며, 매니페스트 전체의 올바름은 온체인의 manifestHash로 검증합니다.

ERC8257의 책임 분담은 다음과 같습니다.

도구 제공자는 매니페스트를 자신의 도메인 하위에서 공개하고, 그 URI와 해시를 ToolRegistry에 등록합니다.

에이전트나 월렛(Wallet)은 getToolConfig로 온체인 설정을 읽고, 매니페스트를 취득하여 해시 검증과 생성자(creator) 검증을 수행한 뒤, 필요하다면 hasAccess로 이용 가능 여부를 확인합니다.

이 구성에서 레지스트리는 결제를 처리하지 않습니다.

가격 정보는 매니페스트의 힌트로서 공개되며, 실제 결제 확인은 도구의 엔드포인트(endpoint)나 결제 프로토콜이 담당합니다.

그렇기 때문에 레지스트리는 "검색과 검증의 토대"에 집중할 수 있습니다.

AI 에이전트용 도구는 각 서비스나 각 플랫폼의 카탈로그에 분산되기 쉽습니다.

에이전트가 자율적으로 도구를 선택하려면 도구의 위치, 입출력, 가격, 액세스 조건, 실행 환경을 기계적으로 읽을 수 있어야 합니다.

하지만 단순한 Web 카탈로그만으로는 어떤 도구 정보가 올바른지를 온체인의 주체와 결합하기 어려워집니다.

그래서 ERC8257은 매니페스트의 해시를 온체인에 기록하여, 도구 정보가 변조되지 않았음을 확인할 수 있도록 합니다.

도구별 액세스 조건은 NFT 보유, 구독(Subscription), Allowlist, DAO 투표, 평판 점수 등으로 다양합니다.

이것들을 레지스트리 본체에 나열하면, 새로운 조건을 추가할 때마다 레지스트리를 변경해야 합니다.

ERC8257은 accessPredicate라는 하나의 주소에 액세스 판정을 위임합니다.

accessPredicate가 address(0)라면 누구나 이용할 수 있으며, 외부 컨트랙트가 설정되어 있다면 해당 컨트랙트로 staticcall하여 이용 가능 여부를 판정합니다.

이 "외부 컨트랙트에 판정을 맡기는" 설계는 ERC4337의 Paymaster나, Uniswap v4의 hook, Seaport의 zone과 유사한 개념입니다.

ERC4337에 대해서는 아래 기사를 참고해 주세요.

에이전트가 동일한 목적의 도구를 비교할 때, 실행 전에 가격을 알 필요가 있습니다.

ERC8257에서는 가격 정보를 매니페스트의 pricing 배열에 둡니다.

단, 레지스트리는 자금을 취급하지 않습니다.

pricing은 "얼마를, 어떤 자산으로, 누구에게, 어떤 프로토콜로 지불할 것인가"를 나타내는 발견용 정보이며, 결제의 강제는 엔드포인트나 결제 프로토콜 측에서 수행합니다.

ToolConfig는 등록된 도구의 온체인 설정입니다.

struct ToolConfig {
address creator;
string metadataURI;
...
}

각 필드의 역할은 다음과 같습니다.

metadataURI는 빈 문자열이 아니어야 하며, 2,048 bytes 이내여야 합니다.

manifestHash는 bytes32(0) 이외의 값이어야 합니다.

실재하는 콘텐츠의 keccak256이 0이 될 것이라는 전제를 두기 어렵기 때문에, 제로 해시(zero hash)는 의미 없는 커밋먼트(commitment)로 간주되어 거부됩니다.

IToolRegistry는 등록, 업데이트, 삭제, 참조, 액세스 판정을 통합한 인터페이스입니다.

interface IToolRegistry {
event ToolRegistered(
uint256 indexed toolId,
...

function registerTool(
string calldata metadataURI,
bytes32 manifestHash,
...

도구를 신규 등록하는 함수입니다.

호출자가 creator로 기록되며, 일련번호 형태의 toolId가 할당됩니다.

인자 (Arguments)

반환값 (Return Values)

등록 시에는 metadataURI와 manifestHash의 제약 조건을 확인하며, accessPredicate도 검증합니다.

accessPredicate가 ERC165를 지원하는 경우, IAccessPredicate를 지원해야 합니다.

ERC165를 지원하지 않는 컨트랙트나 아직 코드가 존재하지 않는 주소는 Best-effort 방식으로 수용되지만, 실행 시점의 액세스 판정에서 실패하면 액세스 거부로 처리됩니다.

function deregisterTool(uint256 toolId) external;

도구를 영구적으로 삭제하는 함수입니다.

creator만이 호출할 수 있습니다.

삭제된 toolId는 재사용되지 않습니다.

삭제 후 getToolConfig, hasAccess, tryHasAccess, updateToolMetadata, setAccessPredicate, deregisterTool을 호출하면 ToolIsDeregistered 에러와 함께 revert됩니다.

일시 정지하고 싶은 경우에는 삭제가 아니라, 항상 거부하는 predicate로 setAccessPredicate를 통해 전환하는 것을 상정합니다.

삭제는 되돌릴 수 없는 작업으로 취급됩니다.

function updateToolMetadata(
uint256 toolId,
string calldata newURI,
...

manifest의 URI와 해시를 동시에 업데이트하는 함수입니다.

creator만이 호출할 수 있습니다.

인자 (Arguments)

manifest의 입출력 스키마, 가격, 액세스 힌트, 검증 정보를 변경했을 때는 새로운 manifest를 공개하고, 그 JCS 정규화 후 해시를 온체인(on-chain)에 반영합니다.

URI와 해시 중 하나라도 변경되면 ToolMetadataUpdated 이벤트가 발행됩니다.

function setAccessPredicate(
uint256 toolId,
address newPredicate
...

액세스 판정 컨트랙트(access predicate contract)를 업데이트하는 함수입니다.

호출할 수 있는 권한은 creator에게만 있습니다.

인자 (Arguments)

새로운 predicate로 변경할 때는 등록 시와 동일한 검증 규칙이 적용됩니다.

동일한 predicate를 설정하는 호출은 상태가 변하지 않으므로, 구현 시 검증이나 이벤트 발행을 생략할 수 있습니다.

function getToolConfig(
uint256 toolId
) external view returns (ToolConfig memory);

등록된 도구의 설정을 반환하는 참조 함수입니다.

인자 (Arguments)

반환값 (Returns)

등록되지 않은 ID라면 ToolNotFound, 삭제된 도구라면 ToolIsDeregistered로 revert합니다.

미등록, 삭제됨, 액세스 불가 상태는 각각 별개의 상태로 취급됩니다.

function hasAccess(
uint256 toolId,
address account,
...

지정된 계정이 도구에 액세스할 수 있는지 여부를 반환하는 참조 함수입니다.

인자 (Arguments)

반환값 (Returns)

accessPredicate가 address(0)라면, predicate를 호출하지 않고 true를 반환합니다.

predicate가 설정되어 있는 경우에는 staticcall로 호출하며, 올바른 ABI 인코딩된 true만을 액세스 허용으로 취급합니다.

predicate의 revert, 가스(gas) 부족, 반환값의 길이 불일치, 0과 1 이외의 bool 값, 코드가 없는 predicate는 모두 false가 됩니다.

안전한 방향(fail-safe)으로 설계되었기 때문에, 손상된 predicate로 인해 액세스가 허용되는 일은 없습니다.

function tryHasAccess(
uint256 toolId,
address account,
...

액세스 가능 여부와 더불어, predicate 호출이 정상적으로 해석되었는지 여부를 반환하는 참조 함수입니다.

인자 (Arguments)

반환값 (Returns)

반환값의 의미는 다음과 같습니다.

(false, true)는 유효하지 않은 조합으로 취급해야 합니다.

지갑이나 에이전트는 tryHasAccess를 사용함으로써 "조건을 충족하지 못함"인지 "predicate가 고장 남"인지를 구분하여 표시할 수 있습니다.

액세스 판정 흐름은 다음과 같습니다.

hasAccess는 단순한 bool을 반환하는 편리한 함수입니다.

반면, tryHasAccess는 predicate의 정상 응답 여부와 액세스 가능 여부를 분리하기 때문에, UI나 에이전트가 원인을 표시하기 용이합니다.

function toolCount() external view returns (uint256);

등록된 도구 ID의 최댓값을 반환하는 참조 함수입니다.

반환값

toolId는 1부터 시작하는 연속된 번호입니다.

삭제된 ID는 재사용되지 않으므로, toolCount()는 현재 이용 가능한 개수가 아니라 할당된 ID의 상한을 나타냅니다.

function name() external view returns (string memory);
function version() external view returns (string memory);

레지스트리 구현을 식별하기 위한 참조 함수입니다.

둘 다 빈 문자열 이외의 값을 반환해야 합니다.

참조 구현에서는 name()이 "ToolRegistry"를 반환하고, version()은 "0.1"이나 "1.0"과 같은 문자열을 반환합니다.

이 값은 엄격한 semver(유의적 버전)가 아니라, 배포된 레지스트리의 대략적인 식별자로 사용됩니다.

IAccessPredicate는 액세스 판정을 외부화하기 위한 인터페이스입니다.

struct AccessRequirement {
bytes4 kind;
bytes data;
...

function hasAccess(
uint256 toolId,
address account,
...

predicate가 지정된 account가 toolId 도구를 이용할 수 있는지 여부를 반환하는 함수입니다.

인자

반환값

ToolRegistry는 이 함수를 staticcall로 호출합니다.

반환값은 올바른 bool로 해석될 수 있어야 합니다.

해석에 실패할 경우, 액세스는 거부된 것으로 처리됩니다.

function name() external view returns (string memory);

predicate 구현의 표시 이름을 반환하는 함수입니다.

반환값

지갑이나 에이전트는 이 값을 액세스 조건 설명에 사용할 수 있습니다.

function getRequirements(
uint256 toolId
)
...

에이전트가 사전에 필요 조건을 파악하기 위한 기계 판독 가능한 힌트를 반환하는 함수입니다.

인자

반환값

AccessRequirement.kind는 ERC165 스타일의 4바이트 식별자입니다.

알려진 종류는 다음과 같습니다.

ERC165는 컨트랙트가 특정 인터페이스를 지원하는지 확인하기 위한 규격입니다.

ERC8257에서는 IToolRegistry와 IAccessPredicate의 인터페이스 ID도 고정되어 있습니다.

ERC165에 대해서는 다음 기사를 참고하십시오.

getRequirements는 발견과 준비를 위한 힌트입니다.

최종적인 액세스 가능 여부는 hasAccess나 tryHasAccess로 확인합니다. 이는 predicate 설정이 변경되면 manifest의 access 힌트와 온체인 predicate 상태가 어긋날 수 있기 때문입니다.

toolId는 단독으로는 글로벌 식별자가 아닙니다. 동일한 toolId가 다른 체인이나 다른 레지스트리에서 서로 다른 도구를 가리킬 수 있습니다.

따라서 도구 참조는 chainId, registryAddress, toolId를 함께 다룹니다. 권장되는 문자열 표현은 다음과 같습니다.

eip155:<chainId>/erc8257:<registryAddress>/<toolId>

erc8257의 CAIP 네임스페이스는 제안 시점에서 아직 CAIP 측에 등록되지 않았습니다. 하지만 향후 등록을 고려하여 상호 운용성이 높은 표기법으로서 이 문자열이 권장됩니다.

metadataURI가 가리키는 manifest는 JSON입니다. 도구의 이름, 설명, endpoint, 입출력 스키마, 생성자(creator) 주소, 가격, 액세스 힌트, 실행 환경 검증 정보를 포함합니다.

manifest에 포함되는 발견 정보는 다음과 같습니다. 에이전트는 manifest를 읽음으로써 도구의 목적, 호출 방법, 가격, 액세스 조건, 신뢰 판단에 필요한 정보를 실행 전에 확인할 수 있습니다.

레지스트리는 이러한 상세 정보를 온체인에 직접 저장하지 않고, manifest의 해시를 저장하여 위변조 감지에 사용합니다.

manifestHash는 JSON을 그대로 해싱한 값이 아닙니다. RFC8785의 JSON Canonicalization Scheme (JCS)로 정규화된 bytes에 대한 keccak256입니다.

JCS는 객체 키 순서, 공백, 숫자 표현, 문자열 이스케이프를 통일합니다. 그 위에 ERC8257은 JCS 이전에 다음과 같은 규칙도 요구합니다.

이러한 조건을 충족하지 않는 manifest는 검증에 실패합니다. 컨슈머는 임의로 NFC로 수정하거나, BOM을 제거하거나, hex를 소문자로 변환하지 않고 실패로 처리합니다. 묵시적인 보정을 수행하면 온체인에 커밋된 bytes와 다른 bytes를 검증하게 되기 때문입니다.

manifest의 주요 필수 필드는 다음과 같습니다.

endpoint는 https://로 시작하는 URL이어야 합니다.

creatorAddress는 `^0x[0-9a-f]{40}

verifiability는 도구의 실행 환경 및 데이터 처리 방식에 대해 에이전트가 사전에 신뢰 여부를 판단하기 위한 정보입니다.

이 또한 온체인의 ToolConfig가 아니라 매니페스트(manifest)에 포함됩니다.

주요 필드는 다음과 같습니다.

tier의 값은 다음과 같습니다.

execution의 값은 다음과 같습니다.

tier는 자기 신고 방식입니다.

에이전트는 tier만으로 높은 신뢰를 부여하지 않으며, attestation이나 reproducibleBuild의 구조가 해당 주장을 뒷받침하는지 확인합니다.

예를 들어, tier가 verifiable