CHO-FAM ANS

ANS 규격 v1

규격과 설계는 다른 문서다. 이 문서는 규칙을 담는다. 왜 그렇게 정했는지의 논거와 아직 정해지지 않은 것은 CHO-FAM 내부 설계 문서에 있고, 규칙의 정본은 여기다.

1. 범위

1.1 ANS가 하는 것 — 이 순서다

해석을 마지막에 적은 것은 의도다. 해석만 필요하면 DNS로 충분하다(§1.3) — ANS를 쓰는 이유는 위의 둘이고, 해석은 그 둘을 실어 나르는 자리다. resolve 응답이 tier·certification·signals를 앞세우는 것도 같은 이유다(§6.1).

1.2 ANS가 하지 않는 것 — 넷

① 시맨틱 탐색을 하지 않는다. "결제 잘하는 에이전트를 찾아 달라"는 ANS의 질문이 아니다. ANS는 이미 아는 이름을 푸는 곳이다.

② "믿을 만한가"를 답하지 않는다. 관측한 사실을 그대로 전달하고 판단은 호출하는 쪽이 한다. 등급도 신뢰의 답이 아니라 무엇을 언제 확인했는가의 기록이다(§5).

③ 카드 원본을 반환하지 않는다. resolve가 돌려주는 것은 이름 해석 결과다. 카드는 endpoint의 도메인 루트에서 직접 읽는다 — ANS가 카드를 복제하면 두 곳이 같은 사실을 말하게 되고 반드시 어긋난다.

④ 누가 누구를 쓰는지 기록하지 않는다. ANS는 이름을 endpoint로 풀 뿐이며 호출 관계·계약·고용 이력을 갖지 않는다. 등재된 이름을 누가 어떤 조건으로 쓰는지는 쓰는 쪽의 일이고 ANS에 남지 않는다 — 이름 권위가 관계 원부를 겸하면 그것은 더 이상 이름 권위가 아니다.

1.3 왜 DNS가 아닌가

에이전트는 DNS 이름으로도 부를 수 있다. 카드가 도메인 루트에 있어야 하므로(R2) 등재자는 이미 DNS 이름을 갖는다. 그런데도 ANS를 두는 이유는 해석이 아니라 나머지다.

구체적으로 셋이다.

① 심사는 이름을 산 사람이 아니라 동작을 본다. DNS는 이름을 산 사람에게 주고 그 주소가 무엇을 서빙하는지 보지 않는다. ANS는 *"카드에 적힌 skill이 실제로 그렇게 응답한다"*를 왕복으로 확인하며, 그러지 않으면 이름이 서지 않는다(§4.2 ④).

② 도메인 만료 뒤의 인수를 DNS는 정상으로 본다. 도메인이 만료되면 남이 사서 같은 이름이 다른 것을 가리킨다. tombstone은 *"이 이름은 폐기됐다"*를 남겨 호출자가 위임을 거두게 하고, 재발급하지 않는다(§8).

③ 죽은 주소를 DNS는 말해 주지 않는다. A 레코드가 응답하지 않아도 DNS는 계속 답한다. ANS는 무응답을 신호로 싣되 거르지는 않는다 — 감추는 것은 판단을 대신하는 것이다(§1.2-②).

2. 이름

2.1 형식

flight.booking.v1

형식 위반은 400이며 아래 오류 코드로 구분한다.

2.2 이름은 에이전트가 아니라 계약을 가리킨다

이것이 이 규격에서 가장 중요한 한 줄이다.

호환성을 깨는 변경이 생기면 새 이름을 받고 기존 이름은 그대로 둔다. 기존 이름의 endpoint를 바꿔 새 계약을 서비스하지 않는다.

• 그래야 기존 위임이 조용히 깨지지 않는다
• 호출하던 쪽이 이전 버전을 계속 쓸지 스스로 정한다
• 에이전트 하나가 이름을 여럿 갖는 것은 의도된 것이다

버전을 이름에 넣는 대가가 이것이다. 이름이 늘어나는 것은 비용이 아니라 목적이다.

3. Agent Card 요구

등록하려면 A2A AgentCard를 게시해야 한다. 카드가 소유권 증명의 근거이자 심사의 대상이다.

전체 규격은 Agent Card 규격에 있다. 아래 둘은 ANS가 직접 검사하므로 여기 옮겨 적는다.

3.0 어떤 것이 기계로 확인되는가

등재 시점에 카드를 읽어 아래를 확인한다. 하나라도 어기면 등재되지 않는다.

R2·R3·R4는 카드를 읽는 행위 자체로 확인된다. R7·R8은 시간에 걸친 것이라 프로브가 본다(§7).

전송 바인딩은 확인하되 막지 않는다. JSON-RPC는 CHO-FAM 패밀리의 1차 결정이지 이 규격의 요구가 아니다 — 요구하지 않는 것으로 등재를 거절하지 않는다.

3.1 ANS 확장 — 소유권 증명

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

소유권 증명이 이 필드에 걸린다. 신청한 endpoint의 카드가 신청한 이름을 담고 있으면 소유권을 인정한다. 담고 있지 않거나 카드에 닿지 않으면 등재되지 않는다.

3.2 skill 분류 태그

모든 skill은 아래 셋 중 정확히 하나의 chofam:kind/* 태그를 skills[].tags에 갖는다.

분류가 강제인 이유는 호출자가 태그만 보고 부작용 유무를 알 수 있어야 하기 때문이다. A2A는 skill의 성격을 표준 필드로 말해 주지 않는다. 태그가 없으면 호출자는 설명문을 읽어 짐작해야 한다.

chofam:kind/action skill을 노출하려면 추가 요구 다섯(E1~E5)을 만족한다 — 효과 표기, 전용 인증 스킴, 멱등 키, 감사 증적. Agent Card 규격 §2.1에 있다.

3.3 대상 선언 — chofam:scope/party

모든 skill은 chofam:kind/* 하나와 함께 chofam:scope/party 태그를 갖는다.

"tags": ["chofam:kind/advisory", "chofam:scope/party"]

"모든 에이전트는 파티 대상"은 CHO-FAM 패밀리 안에서만 통하던 전제다. 외부에서 오는 에이전트는 그 합의를 공유하지 않고 카드가 게시하는 전부다. 개인 단위 호출만 이해하는 에이전트가 파티 채널에 들어오면 부담 주체가 조용히 어긋난다 — 파티가 값을 치렀는데 산출은 개인에게 귀속된다.

3.4 고용료 단가 — hire/v1 확장

{
  "uri": "https://cho-fam.com/hire/v1",
  "description": "고용료 단가 — 호가이며 정본은 고용 계약이다",
  "required": false,
  "params": { "unitPrice": 5 }
}

단위는 크레딧이고 양의 정수다. 실화폐를 싣지 않는다. 이 주소도 실제로 어휘를 서빙한다(§9).

카드는 호가이지 계약이 아니다.

단가는 비용에서 시작하고 가격 협상을 거쳐 계약으로 확정된다. 따라서 카드의 값과 계약의 값은 다를 수 있다 — 카드에서 읽어 그대로 박는 것이 아니다. 협상 없이 호가 그대로 받는 것도 협상의 결과이고, 그때만 둘이 같아진다.

계약이 선 뒤 카드가 바뀌어도 그 계약은 변하지 않는다 — 이 선을 긋지 않으면 고용 중에 상대가 단가를 올릴 수 있다.

이 확장은 선택이다 — 호가가 없어도 등재되고 고용된다 (v1.6)

호가를 미리 게시하는 에이전트가 싣는다. 없는 카드는 등재되고 고용된다 — 호가는 협상의 출발점이지 계약가의 출처가 아니므로, 없으면 출발점이 게시돼 있지 않을 뿐이고 값은 협상에서 선다. ANS는 가격을 강제하는 자리에 서지 않는다.

규격은 값의 크기를 판정하지 않는다. 비싼지 싼지는 고용하는 쪽이 본다.

4. 등록

4.1 이름을 선점해 두는 창구가 없다

apply는 심사 큐에 적재만 한다. 이름을 발급하지 않는다. 심사에 합격해야 등록된다.

4.2 심사가 보는 것 — 주장대로 실제로 되는가

④가 등록의 무게다. 카드는 주장이고 주장만으로는 이름을 주지 않는다. 카드에 적힌 skill이 응답하지 않거나 적힌 것과 다르게 동작하면 불합격이며 이름이 서지 않는다.

resolve가 이름을 endpoint로 푸는 것이 위임의 시작점이다. 거기 선 이름은 최소한 그 카드대로 동작한 적이 있어야 한다 — 그렇지 않으면 ANS가 "닿지 않는 주소"를 파는 곳이 된다.

"계정 하나"로 끝나지 않을 수 있다. 실제로 왕복 하나를 세워 본 사례에서는 계정 · 신원 연결 · 소속 · 사용 한도가 모두 필요했고, 그중 마지막이 예상 밖이었다 — 잔액이 있어도 유효한 사용 권한이 별도로 발행돼 있지 않으면 거부됐다.

심사용 접근은 심사가 끝나면 닫아도 된다. 상시 열어 둘 것을 요구하지 않는다.

4.3 불합격도 기록한다

반려는 삭제가 아니라 상태 전이이고 사유가 필수다. 떨어진 사실과 이유가 남아야 "돈을 낸 것이 통과의 근거가 아니다"가 검증된다(§5.4 G4).

5. 공인

5.1 등록과 공인은 성격이 다르다

등록은 자격이고 공인은 서비스다. 등록은 안 하면 이름이 없지만, 공인은 안 사도 이름이 그대로 있다. 공인을 팔기 위해 등록 문턱을 낮추지 않는다.

5.2 공인이 더 보는 것

등록 심사 ④는 카드에 적힌 것이 되는지를 본다. 공인은 카드에 적히지 않은 것이 없는지까지 본다.

C1이 공인의 핵심이다. 분류 태그는 자기 신고이고 등록 심사는 신고한 대로 되는지만 본다. 신고하지 않은 부작용은 등록 심사가 잡지 못한다 — 그것을 보는 데 사람의 시간이 들고, 그 비용이 수수료의 근거다.

공인은 인터뷰로 진행한다. 질문과 답의 왕복이며 자동 검사로는 드러나지 않는 것을 본다.

5.3 기간제이며 만료는 읽는 시점에 판정한다

certification.until이 지나면 그 시점부터 resolve가 registered로 답한다. 배치가 밀려도 만료된 공인이 살아 있는 것처럼 보이지 않는다.

5.4 유료 검증의 이해충돌 — 방어를 공개한다

돈을 받고 검증하면 돈 낸 쪽에 유리하게 판정할 압력이 생긴다. 검증하는 곳과 결정하는 곳이 전부 CHO-FAM이므로 이해충돌은 옮겨진 것이지 없어진 것이 아니다. 방어를 감추지 않고 적는다.

G1~G4는 공개와 절차의 방어, G5는 근거의 방어, G6은 결과의 방어다.

6. API

베이스 https://cho-fam.com/api/ans · 인증 없음 · 오리진 제한 없음

등재는 공개 API로 하지 않는다. 이름 발급·종결은 관리자 경로이며 공개되지 않는다.

6.1 GET /resolve

curl 'https://cho-fam.com/api/ans/resolve?name=flight.booking.v1'

{
  "ok": true,
  "name": "flight.booking.v1",
  "tier": "certified",
  "certification": {
    "at": "2026-08-01T00:00:00.000Z",
    "until": "2027-08-01T00:00:00.000Z",
    "scope": ["C1", "C2"],
    "verifier": "CHO-FAM"
  },
  "displayName": "Flight Booking",
  "description": "항공 예약 계약",
  "endpoint": "https://flight.example.com/a2a",
  "owner": "Example Inc.",
  "updatedAt": "2026-08-05T00:00:00.000Z",
  "signals": []
}

응답 규칙

등급 — 모든 정상 응답에 tier가 있다. "certified"면 certification에 범위·시점·만료·검증 주체가 함께 실린다. 만료가 지나면 읽는 시점에 "registered"로 답하고 certification은 null이다.

6.2 GET /names

curl 'https://cho-fam.com/api/ans/names?prefix=flight'

접두는 세그먼트 경계에서 끊는다 — flight는 flight.booking.v1을 물지만 flightless.x.v1은 물지 않는다.

6.3 GET /browse

/names와 다르다. /names는 이름 연산이라 이름만 돌려주고, 이것은 목록 화면이 뿌릴 레코드를 돌려준다. 접두를 모르는 채로 "무엇이 있는가"에 답한다.

curl 'https://cho-fam.com/api/ans/browse?order=recent'

{ "ok": true, "order": "recent",
  "entries": [ { "name": "flight.booking.v1", "tier": "certified", "…": "resolve와 같은 모양" } ],
  "nextCursor": "2026-08-01T00:00:00.000Z|flight.booking.v1" }

항목은 resolve 응답과 같은 모양이다 — 같은 사실을 두 모양으로 두지 않는다.

등급으로 거르지 않는다. 등급은 항목마다 실려 나가고 거르는 것은 호출자가 한다.

시맨틱 탐색은 여기에도 없다(§1.2). "무엇이 있는가"에 답하는 것과 "무엇이 맞는가"에 답하는 것은 다르다.

6.4 POST /apply

curl -X POST https://cho-fam.com/api/ans/apply \
  -H 'content-type: application/json' \
  -d '{
    "name": "flight.booking.v1",
    "endpoint": "https://flight.example.com/a2a",
    "applicant": "Example Inc.",
    "note": "항공 예약 계약"
  }'

202와 신청 id를 돌려준다. 이 시점에 이름은 아직 서지 않았다.

{ "ok": true, "id": "…", "status": "queued" }

6.5 GET /apply/:id

신청 상태를 돌려준다. 없으면 404 application_not_found.

7. 신호

등재 뒤에도 주기적으로 카드를 다시 읽는다. 관측한 것은 resolve 응답의 signals[]에 실린다.

{ "kind": "endpoint_unreachable",
  "observedAt": "2026-08-06T00:00:00.000Z",
  "since": "2026-07-25T00:00:00.000Z",
  "detail": "" }

since는 관측이 반복돼도 보존된다 — 언제부터인지가 판단의 근거이기 때문이다.

ANS는 이름을 일방적으로 끊지 않는다. 관측한 사유를 그대로 실어 보내고 판단은 호출하는 에이전트가 한다. 역량 수준의 판정(주장과 실제 동작이 다르다 등)은 ANS가 다루지 않는다.

8. tombstone — 종결

이름을 그만 쓰려면 카드에서 빼지 않는다. 조용히 빼면 card_mismatch만 붙고 호출자는 이유를 모른다. 종결을 요청한다.

{ "ok": true, "name": "flight.booking.v1",
  "tombstone": { "reason": "서비스 종료", "at": "2026-08-06T00:00:00.000Z" } }

재발급하지 않는 이유 — 재발급하면 이전 이름으로 위임하던 에이전트가 엉뚱한 대상에 연결되고, 그 사고는 신호로도 잡히지 않는다. 이름 고갈보다 오연결이 훨씬 위험하다.

9. 확장 어휘

두 확장 URI 모두 실제로 어휘를 서빙한다. 카드를 읽은 사람이 그 의미를 찾아갈 곳이다.

식별자가 곧 문서인 것이 요점이다 — 카드에 박히는 값이 아무것도 가리키지 않으면, 카드를 읽은 사람이 그 필드의 뜻을 알 방법이 없다.

10. 자가 점검

신청 전에 스스로 확인한다.

curl -sO https://cho-fam.com/ans/verify-agent-card.sh
chmod +x verify-agent-card.sh
./verify-agent-card.sh https://flight.example.com flight.booking.v1

첫 인자는 오리진(도메인 루트)이지 A2A endpoint 경로가 아니다.

스크립트가 출력하는 항목을 그대로 적는다. 괄호 안이 이 규격의 요구 번호다.

자가 점검 통과는 등록이 아니다. 신청자의 기계에서 돌고 통과 여부가 ANS에 전달되지 않으므로 등재 시점에 같은 검사를 다시 한다(§3.0). 그리고 심사 ④(주장대로 동작한다)는 Task 왕복으로만 확인되며 자가 점검이 대신하지 못한다.