CHO-FAM · Agent Card 확장

ANS 확장 v1

A2A AgentCard의 capabilities.extensions[].uri가 아래 주소일 때의 의미를 정의한다.

https://cho-fam.com/ans/v1

이 페이지는 규범적 어휘만 담는다. 설계 배경과 각 저장소의 적용 범위는 전체 규격 문서에 있다.

1. 확장 — ANS 이름

이름 권위는 CHO-FAM ANS에 있다. 카드는 자기가 주장하는 ANS 이름을 이 확장으로 선언한다.

"capabilities": {
  "extensions": [
    {
      "uri": "https://cho-fam.com/ans/v1",
      "description": "ANS 이름 — 이름 권위는 chofam ANS",
      "required": false,
      "params": { "name": "ethos.decision.v1" }
    }
  ]
}

`uri`	위 주소 고정. ANS가 이 값으로 확장을 찾는다
`params.name`	ANS 이름 정확히 하나. 이름이 여럿이면 확장을 여러 개 둔다 — 이름은 에이전트가 아니라 계약을 가리킨다
`required`	`false`. ANS를 모르는 표준 클라이언트도 이 카드를 쓸 수 있어야 한다

소유권 증명이 이 필드에 걸린다. ANS 심사는 신청한 endpoint의 카드를 읽어 params.name이 신청한 이름과 같은지 본다. 등재 후에도 프로브가 주기적으로 확인하며, 카드에서 이름이 사라지면 card_mismatch 신호가 붙는다. 이름을 그만 쓰려면 카드에서 빼는 것이 아니라 tombstone을 요청한다 — 조용히 빼면 호출자가 이유를 모른다.

2. 이름 형식

flight.booking.v1 — 소문자 영숫자와 .만 쓰고, 마지막 세그먼트가 버전이다.

세그먼트는 [a-z0-9]+, 최대 8개
버전 세그먼트는 v1·v2… 형태이며 마지막에만 온다
호환성을 깨는 변경에는 새 이름을 발급하고 기존 이름은 그대로 둔다 — 기존 위임이 조용히 깨지지 않는다

3. 예약 태그 어휘

모든 skill은 chofam:kind/* 태그를 정확히 하나 갖는다. A2A는 skill의 성격을 표준 필드로 말해 주지 않으므로, 태그가 없으면 호출자는 설명문을 읽어 짐작해야 한다.

태그	뜻	부작용
`chofam:kind/advisory`	자문 — 판단 재료를 돌려준다	없음
`chofam:kind/query`	조회 — 저장된 사실을 읽어 돌려준다	없음
`chofam:kind/action`	실행 — 상태를 바꾼다	있음

chofam:kind/action skill은 되돌릴 수 있는지를 함께 표기한다.

`chofam:effect/reversible`	되돌릴 수 있다
`chofam:effect/irreversible`	되돌릴 수 없다 — 호출 측이 보통 사람의 확인을 요구한다

4. 실행성 skill의 요구

규격은 실행성 skill을 금지하지 않는다. 다만 자문·조회와 같이 취급하지 않는다 — 실행은 되돌릴 수 없을 수 있고, 재시도가 이중 실행이 되며, 사후에 누가 무엇을 시켰는지 물어야 한다. chofam:kind/action skill을 노출하려면 아래 다섯을 만족한다.

E1	`chofam:kind/action` 태그를 붙인다
E2	`chofam:effect/*`로 되돌림 가능 여부를 표기한다
E3	자문·조회와 다른 인증 스킴을 요구한다 — 자문을 부르려고 넘긴 대리 토큰이 실행까지 열어서는 안 된다
E4	멱등 키를 받고, 같은 키의 재전송이 이중 실행을 만들지 않는다 — A2A는 재시도를 막아 주지 않는다
E5	실행 1건마다 감사 증적을 남긴다 — 호출자 신원·시각·입력

무엇을 노출할지는 이 규격이 정하지 않는다. 각 저장소의 불변 조건과 현 단계 범위가 정하며, 저장소 불변 조건이 규격을 이긴다 — 규격이 E1~E5로 길을 열어도 불변 조건이 금지하면 노출하지 않는다.

5. 카드 게시 위치

카드는 도메인 루트의 /.well-known/agent-card.json에 있다. well-known URI는 오리진 기준으로 정의되므로(RFC 8615) A2A endpoint 경로 아래가 아니다 — url이 https://example.com/a2a여도 카드는 https://example.com/.well-known/agent-card.json이다. ANS 프로브는 이 자리만 본다.

카드 자체는 인증 없이 읽힌다. 프로브가 주기적으로 읽으므로 캐시 헤더를 과도하게 길게 두지 않는다.

6. ANS API

GET	`/api/ans/resolve?name=`	이름 → endpoint·신호
GET	`/api/ans/names?prefix=`	접두 목록
POST	`/api/ans/apply`	등록 신청 → 심사 큐

시맨틱 탐색은 없다. ANS는 이름을 endpoint로 해석만 한다. resolve는 신호가 있어도 레코드를 감추지 않고, tombstone된 이름에는 404가 아니라 200과 tombstone 사실을 돌려준다 — 호출자가 "없는 이름"과 "폐기된 이름"을 구분할 수 있어야 하기 때문이다. 판단은 호출하는 에이전트가 한다.