CHO-FAM ANS

Agent Card 규격 v1.7 — 패밀리 공통

규격을 chofam이 소유하는 이유 — ANS 설계 §4.2가 소유권 증명을 "신청한 endpoint의 카드가 신청한 이름을 담고 있으면 인정한다"로 정했다. ANS는 이미 카드를 파싱해야 하므로 규격이 다른 곳에 있으면 검증 로직이 남의 문서를 좇게 된다.

0. 표준을 벗어나지 않는다

카드는 A2A AgentCard(protocolVersion: "1.0.1")이다. 아래 여섯은 전부 표준이 이미 가진 자리에 얹는다 — 표준 파서가 읽을 수 없는 필드를 새로 만들지 않는다.

1차 endpoint 규칙은 필드가 아니라 해석 규칙이므로 §6에 따로 둔다.

1. 최소 카드

{
  "protocolVersion": "1.0.1",
  "name": "Ethos Decision",
  "description": "결정 세션을 진행해 기준과 가정을 명료화한다. 판정을 반환하지 않는다.",
  "url": "https://ethos.internal/a2a",
  "supportedInterfaces": [
    { "url": "https://ethos.internal/a2a", "protocolBinding": "JSONRPC" }
  ],
  "version": "1.0.0",
  "provider": { "organization": "CHOFAM", "url": "https://cho-fam.com" },
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extensions": [
      {
        "uri": "https://cho-fam.com/ans/v1",
        "description": "ANS 이름 — 이름 권위는 chofam ANS",
        "required": false,
        "params": { "name": "ethos.decision.v1" }
      }
    ]
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "securitySchemes": {
    "userBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
  },
  "security": [{ "userBearer": [] }],
  "skills": [
    {
      "id": "decision-session",
      "name": "결정 세션",
      "description": "기준·가정을 되묻고 정리한다. input-required로 질문을 되돌린다.",
      "tags": ["chofam:kind/advisory", "chofam:scope/party"],
      "inputModes": ["text/plain"],
      "outputModes": ["text/plain"]
    }
  ]
}

전송 바인딩은 JSON-RPC 2.0이다(1차 답변서 §4.4) — 단일 호스트·저볼륨이므로 supportedInterfaces[]에 protocolBinding: "JSONRPC" 하나를 둔다. gRPC는 다수 호스트 운영 시 재검토한다.

2. skill 분류 — tags에 예약 태그를 쓴다

모든 skill은 아래 셋 중 정확히 하나의 chofam:kind/* 태그를 갖는다. 분류 기준은 부작용의 유무와 소재다.

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

2.1 실행성 skill의 전용 요구

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

{
  "id": "event-ingest",
  "name": "이벤트 수신",
  "description": "society 전이 이벤트를 받아 SOURCE로 기록한다. 같은 id 재전송은 중복을 만들지 않는다.",
  "tags": ["chofam:kind/action", "chofam:effect/reversible", "chofam:scope/party"],
  "inputModes": ["application/json"],
  "outputModes": ["application/json"]
}

규격은 여기까지다. 무엇을 실제로 노출할지는 §2.2가 정한다.

2.2 무엇을 노출할지는 저장소의 불변 조건과 현 단계가 정한다

이것이 규격의 일이 아닌 이유 — 노출 범위는 각 저장소의 로드맵과 불변 조건에 딸린 것이고, 단계가 올라가면 바뀐다. 공용 규격이 그것을 미리 못박으면 다른 저장소의 계획을 규격 개정 없이는 못 밟게 만든다.

afo의 실행성 부재는 현 단계의 사실이지 영구 규정이 아니다. 상위 적용 단계의 계획에는 실행성이 있고, 그 단계에서 E1~E5를 만족하고 그때의 afo I-1이 허용하면 카드에 오른다. 규격을 고칠 일이 아니다.

저장소 불변 조건이 규격을 이긴다. 규격이 E1~E5로 길을 열어도 저장소의 불변 조건이 금지하면 노출하지 않는다 — afo I-1, society I-4(법적 효력 있는 행위 미실행)가 그 예다. 규격은 불변 조건을 대신하지 않는다.

2.3 대상 선언 — chofam:scope/party (v1.4)

모든 skill은 chofam:kind/* 하나와 함께 chofam:scope/party 태그를 갖는다. 같은 skills[].tags에 얹으므로 새 필드가 생기지 않는다(§0).

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

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

선언하지 않은 카드는 등재 심사에서 떨어진다(§8 V8). 패밀리 시드도 같은 검사를 거친다.

3. ANS 이름 — capabilities.extensions[]

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

소유권 증명이 이 필드에 걸린다. ANS apply 심사는 신청한 endpoint의 카드를 읽어 params.name이 신청한 이름과 같은지 본다. 다르면 등록되지 않는다.

이름을 지운 채로 카드를 갱신하면 card_mismatch 신호가 붙는다(ANS 설계 §4.3). 이름을 그만 쓰려면 카드에서 빼는 것이 아니라 tombstone을 요청한다 — 조용히 빼면 호출자가 이유를 모른다.

4. trustTier는 카드에 담지 않는다

A2A에 신뢰 등급 개념이 없고, ANS도 "믿을 만한가"를 답하지 않는다(ANS 설계 §1).

자기 신뢰도를 자기가 선언하는 필드를 만들지 않는다. society가 자기 채널에 무엇을 들일지 정하는 값이므로 Directory에 남는다(ANS 설계 §11.1).

4.1 고용료 단가 — 카드는 호가다 (v1.4 · v1.6 정정)

society registry.ts가 계약의 unit_price를 필수 항목으로 세웠다 — *"값이 없는 채로 고용이 열리면 얼마를 받기로 했는지가 사후에 정해진다."* 패밀리는 그 값이 어디서 오는지 내부 합의로 알지만 외부 에이전트는 실을 자리가 없다.

카드에 싣는다. §3과 같은 자리를 쓴다 — ANS 이름이 이미 capabilities.extensions[]로 나가고 있으므로 새 기계장치가 없다.

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

단위는 크레딧이고 양의 정수다. 실화폐를 싣지 않는다 — 에이전트 고용료는 크레딧으로 지불한다는 것이 P-4다.

단가는 세 단계로 선다 (v1.6)

주관자 확정: *"단가는 비용에서 시작하고 가격 협상을 거쳐 계약으로 확정된다."*

②와 ③은 다를 수 있다. 협상이 그 사이에 있기 때문이다. 카드에서 읽어 계약에 박는 것이 아니다 — 카드는 협상의 출발점이고, 합의가 없으면 계약이 서지 않는다.

②가 없어도 ③은 선다. 출발점이 게시돼 있지 않을 뿐이고, 협상은 그래도 일어난다 — 그것이 §4.2다.

계약이 선 뒤 카드가 바뀌어도 그 계약은 변하지 않는다. 카드는 상대가 언제든 고쳐 게시할 수 있는 문서이고, 계약은 두 쪽이 합의한 시점의 기록이다.

D-18은 이 절이 답하지 않는다. 누가 파티에 에이전트를 들일 수 있는가는 society 소관이고, 카드는 *무엇을 제시하는가*만 정한다.

4.2 적용 범위 — 호가가 없어도 고용된다 (v1.6)

hire/v1 확장은 선택이다. 호가를 미리 게시하는 에이전트가 싣는다. 패밀리는 ⓐ 환산이 서기 전까지 싣지 않는다(업무지시서 §7.9).

주관자 회신(AP-1) — *"단가는 비용에서 시작하고 가격 협상을 거쳐 계약으로 확정된다."* 따라서 주관자가 패밀리 단가를 정해 카드에 박는 일은 일어나지 않는다. AP-1은 값이 채워져서가 아니라 정할 주체가 남지 않아서 소멸한다(업무지시서 §7.9).

K-2가 태그를 만든 이유(*"전부 그렇다는 말은 검사할 수 없는 말이 된다"*)와 어긋나지 않는다. 대상 선언은 카드가 아니면 확인할 자리가 없고, 계약가는 카드가 아닌 자리에서 정해진다. 둘은 성질이 다르다 — 하나는 카드에만 있는 사실이고, 하나는 카드에 없어도 서는 값이다.

5. 인증 선언 — 경로별로 다르다

1차 답변서 §4.3이 경로별로 확정했다. 카드의 securitySchemes는 그 경로가 실제로 받는 것을 그대로 적는다.

"securitySchemes": {
  "serviceBearer": {
    "type": "http", "scheme": "bearer",
    "description": "배포 설정의 공유 비밀. 1차는 토큰 교환 없음"
  },
  "userBearer": {
    "type": "http", "scheme": "bearer", "bearerFormat": "JWT",
    "description": "Dex 발급 사용자 토큰. iss·sub·aud·exp만"
  }
},
"security": [{ "serviceBearer": [] }]

5.1 대리 경로의 클레임 범위

iss·sub·aud·exp만이다. 프로필·이메일을 넘기지 않는다.

5.2 실행 경로는 자문·조회와 스킴을 나눈다 (E3)

chofam:kind/action skill을 노출하는 카드는 그 경로 전용 스킴을 따로 선언한다.

"securitySchemes": {
  "userBearer": {
    "type": "http", "scheme": "bearer", "bearerFormat": "JWT",
    "description": "자문·조회용 사용자 대리 토큰"
  },
  "actionBearer": {
    "type": "http", "scheme": "bearer", "bearerFormat": "JWT",
    "description": "실행용. 자문 토큰으로는 열리지 않는다"
  }
}

한 스킴으로 묶지 않는 이유 — 사용자가 자문을 받으려고 넘긴 토큰이 그대로 실행 권한이 되면, 호출자는 자문을 청했는데 실행이 일어날 수 있는 상태가 된다. 스킴이 나뉘어 있으면 실행에는 별도 발급이 필요하다는 사실이 카드에 드러난다.

스킴을 나누는 것으로 충분하지 않다면(사람의 명시적 확인이 필요한 경우 등) 그것은 skill의 대화 흐름으로 처리한다 — A2A input-required로 확인을 되돌리고 응답을 받아 진행한다. 카드가 표현할 수 있는 것은 여기까지다.

5.3 mentor 경로는 비식별이 따로다

mentor행 요청에는 참여자 식별자가 어떤 형태로도 들어가지 않는다. 이것은 카드가 강제하지 못한다 — A2A는 페이로드 내용에 관여하지 않는 프로토콜이므로 비식별 변환은 society Agent Gateway의 책임이다. 카드는 serviceBearer를 선언해 사용자 토큰을 받지 않는다는 사실까지만 말한다.

6. 1차 endpoint — 배포 설정이 카드보다 우선한다

1차는 패밀리 에이전트가 ANS를 런타임 경로로 쓰지 않는다(ANS 설계 §11.4). ANS는 GCP에 있고 1차는 자체 서버라, 매 자문마다 resolve를 부르면 자체 서버가 GCP 왕복에 묶인다.

→ society는 배포 설정의 고정 목록으로 endpoint를 안다. 그 결과 카드의 url과 배포 설정이 어긋날 수 있다.

카드의 url은 그래도 정확히 유지한다. 부정확하면 ANS 프로브가 endpoint_unreachable을 붙이고, 외부 호출자는 카드만 보고 온다. "어차피 고정 목록을 쓰니까"는 카드를 방치할 이유가 되지 않는다.

7. 게시 요구사항

8. 완료 기준

카드 게시는 완료가 아니다(총괄 R1). A-1의 완료는 Task 왕복 성공이다.

각 저장소가 아래를 통과하면 A-1이 끝난다.

V4는 terra에 실제로 걸린다 — 이벤트 인입이 실행이므로 멱등 검증이 T-M1 완료 기준("같은 id 재전송 시 중복 저장 없음")과 같은 것을 본다. 1차에 action을 노출하는 저장소는 terra뿐이다.

ANS 이름 배정(업무지시서 §3.2) — mentor.knowledge.v1 · ethos.decision.v1 · afo.finance.v1 · terra.observer.v1 · guild.watch.v1 · chopilot.observe.v1. 등재 주체는 chofam이다. 각 저장소는 카드를 게시하고 endpoint를 회신하면 된다.

9. 미결