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/* (v1.4, individual은 2026-08-26)

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

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

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

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

individual은 «파티 채널에서 부르지 못한다»는 뜻이 아니다. 부담과 귀속이 개인이라는 뜻이다. 방에 사람이 여럿이면 부른 사람의 것이고, 그 사람이 누구인지 정해지지 않는 호출이면 그 skill은 애초에 성립하지 않는다(D-17).

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을 요청한다 — 조용히 빼면 호출자가 이유를 모른다.

3.1 채널 표면 — capabilities.extensions[]

society의 C3 방은 그 에이전트 하나와 사람 하나가 있는 자리다. 그 방에 무엇이 보이는지를 에이전트가 정한다.

사다리 — 세 칸

① 직접 참조   에이전트 화면의 부분을 프레임으로   원본의 양식·스타일이 그대로 온다
② 그림        프레임을 못 들일 때. 출력에만       입력을 받지 못한다
③ 자체 카드   글로 낸다                          society가 그린다

내려가는 것은 받는 쪽이 정한다. 프레임이 거부되는지, 그림이 오는지를 보고 다음 칸으로 간다 — 에이전트는 «할 수 있는 것»을 선언할 뿐이다.

③은 «못 할 때»만의 자리가 아니다. society가 에이전트의 API를 직접 부르는 경우도 그 칸이다 — 그때는 받은 값을 society가 자기 조각으로 그린다(text·need). 그 편이 맞는 것도 있다: 한 줄짜리 입력에 프레임을 띄우는 것은 과하다.

{
  "uri": "https://cho-fam.com/channel-surface/v1",
  "description": "방에 낼 한 줄을 읽을 경로",
  "required": false,
  "params": { "path": "/v1/channel-surface" }
}

부르는 쪽이 붙이는 질의 둘 — party · ask

society는 카드가 밝힌 경로에 질의를 얹는다. 경로 자체는 바꾸지 않으므로 이 인자를 모르는 상대는 종전대로 전부 낸다.

ask는 선언해야 온다.

{
  "uri": "https://cho-fam.com/channel-surface/v1",
  "params": { "path": "/v1/channel-surface", "ask": true }
}

고른 것이 비면 그 사실을 말한다. 말로 고르면 목록이 좁아지고 좁힌 것이 비어 있을 수 있는데, 그때 빈 목록을 내면 사람은 왜 비었는지 모른다 — 「고장인가」와 「없는 건가」가 같아 보인다. 실측으로 그렇게 났다(「라이선스 보여줘」에 방이 통째로 비었다). 한 장을 내서 비었다고 말한다.

그 경로가 돌려줄 것 — 모양이 하나뿐이다.

{ "title": "오늘의 질문", "text": "지금 피하고 있는 대가는 무엇인가요?" }

무언가가 필요하면 need로 말한다

에이전트가 «이것을 받아야 답할 수 있다»고 판단할 때가 있다 — afo가 스냅샷을 받은 적이 없으면 자산 현황을 낼 수 없다. 그때 입력칸이 방에 나타나야 한다.

{ "title": "자산 현황", "text": "아직 올린 가계부가 없습니다",
  "need": { "kind": "text", "name": "가계부 스냅샷", "hint": "afo 화면에서 내려받은 JSON" } }

«어떻게 보일지»를 말하지 않는다. need는 *무엇이 필요한가*이고, 그것을 입력칸으로 만드는 것은 society, 그리는 것은 slime이다 — 이 절이 {title, text}로 좁혀 둔 이유가 그대로다.

결과창을 따로 두지 않는다. 쓰고 나서 다시 읽으면 text가 새 값이다.

화면 조각을 그대로 보일 수도 있다 — embed

많은 에이전트가 웹사이트다. 표·차트·다단계 양식을 need 하나로 옮기는 것은 확장되지 않는다. 그럴 때는 에이전트가 그린 것을 그대로 방에 들인다.

{ "uri": "https://cho-fam.com/channel-surface/v1",
  "params": { "path": "/v1/channel-surface", "auth": "delegated",
              "embed": [
                { "path": "/?only=snapshot", "height": 520, "name": "가계부 스냅샷" },
                { "path": "/?only=debts", "height": 300, "name": "부채 구조" }
              ] } }

여럿은 조각 여럿이 된다. 하나로 합치지 않는다 — 조각이 곧 읽는 사람이 지나가는 단위이고, 합치면 «둘 중 무엇을 보는 중인지»가 흐려진다.

부분의 모양을 규격이 정하지 않는다. afo는 정적 HTML이라 ?only=<절>이 맞고, mentor는 SPA라 ?tab=<탭>이 맞다 — 에이전트가 자기 결로 정한다.

프레임을 못 들이면 그림으로 내려간다 — embed[].image

{ "path": "/board", "height": 300, "name": "지표판", "image": "/board.png" }

입력을 받지 못하므로 출력에만 쓴다. 그림은 누를 수도 쓸 수도 없다 — 「입력이 없을 때」의 자리다.

프레임이 거부되면 들이지 않는다

X-Frame-Options나 frame-ancestors를 세운 페이지는 브라우저가 막고, 화면에는 빈 칸만 남는다 — 무엇이 잘못됐는지 어디에도 나타나지 않는다.

society가 미리 본다. 카드를 읽을 때 그 주소의 헤더를 함께 보고, 막혀 있으면 프레임을 내지 않는다. 확인하지 못해도 «막힘»으로 본다 — 확인하지 못한 것을 «열려 있다»로 읽으면 빈 칸이 뜬다.

계열 밖 에이전트는 대개 막아 두고 그것이 정상적인 보안 설정이다. 뚫을 수도 없고 뚫어서도 안 된다 — 알아보고 다른 칸으로 내려간다.

이 안은 계획이 통제하지 못한다

밀도 적응·가림·음성 대체·확인 관문이 프레임 안에서 멈춘다. density·targetSize는 무의미하다.

그래서 들일지는 계획이 정한다. 웹 표면에서만 들이고, 워치·글래스에서는 이 선언을 무시하고 text를 글로 보인다 — 안을 통제하지 못하니 들일지 말지를 통제한다. 가려야 하는 조각(PrivacyVeil)도 들이지 않는다: 프레임 안을 가릴 방법이 없다.

글을 함께 낸다. 프레임이 막히거나 늦으면 빈칸만 남는데, 그때 무엇이 있어야 했는지를 아무도 말하지 않는다. text가 그 자리다.

need와 함께 쓴다

둘은 서로 다른 것을 위한 것이다. 한 줄짜리 입력에 프레임을 띄우는 것은 과하고, 표가 여럿인 양식을 need 하나로 옮기는 것은 되지 않는다. 카드가 둘 다 선언할 수 있고 에이전트가 사정에 맞게 고른다.

초안을 보관할지는 privacy가 정한다

slime의 작성 영역은 persisted면 서버가 24시간까지 보관한다. 그러면 personal한 입력이 society에 남는다 — 대리 토큰조차 저장하지 않기로 한 자리에서 초안으로는 저장하는 모순이 된다.

에이전트가 «내 자료를 저장해 두라»고 선언할 자리를 두지 않는다. 보관은 그 자료의 성격에서 따라오지 받는 쪽의 편의로 정할 것이 아니다.

왜 society의 표가 아니라 카드인가. 표로 두면 에이전트가 늘 때마다 society를 고치고 재배포해야 하고, society가 남의 응답 모양을 알고 있게 된다. 실제로 그 위험이 났다 — ethos 명세 문서는 question.text로 적혀 있는데 실제 응답은 question.question이다. 문서를 믿고 적었으면 화면이 조용히 비었을 것이다. 한 줄의 문구를 정하는 쪽이 그것을 아는 쪽이어야 한다.

auth: "delegated" — 그 사람의 것을 그 사람에게만

afo 자산 현황처럼 사람마다 갈리는 한 줄이 있다. 그것을 공개로 낼 수는 없고, society가 원자료를 읽어 합산할 수도 없다 — 순자산이 둘이고(netWorth · netWorthAtCost) 어느 것이 «자산 현황»인지는 afo의 판단이다. 한 줄의 문구를 정하는 쪽이 그것을 아는 쪽이라는 이 절의 원칙이 금액에서도 그대로다.

"params": { "path": "/v1/channel-surface", "auth": "delegated" }

선언했다고 토큰이 생기지 않는다. 촉발은 사람이 그 방을 연 것이고, 받는 토큰은 aud가 그 에이전트라 다른 데서 쓸 수 없다. 즉 «선언했으니 준다»가 아니라 «사람이 열었으니 그 상대에게만»이다.

방향은 카드가 정하지 못한다. 경로는 카드를 읽은 오리진에 붙고 절대 URL은 거부되므로(위 두 규칙), 대리 토큰은 그 토큰이 향하는 바로 그 에이전트에게만 간다. 그 두 규칙은 내부 CA 때문에 넣은 것인데 여기서 값을 한다.

A2A 축은 그대로 막힌다. 이것은 C3 방의 읽기이고, society가 파티를 대신해 부르는 자리(*.v1 skill)와 다르다 — 거기서는 상대가 참여자를 알아서는 안 된다(§5).

risk·privacy는 에이전트가 정하지 않는다

society가 low/public으로 고정한다. 자기 신고를 받으면 개인 정보를 public으로 선언해 화면의 취급(가림·공유 가능 여부)을 낮출 수 있다.

있어도 없어도 방은 열린다

선언이 없거나, 그 경로가 죽어 있거나, 시한(2초)을 넘기면 조각만 빠지고 방은 열린다 — INFRA-13이 *"core가 없으면 계획이 없다. 그래도 채널은 열린다"*로 정한 그 자리다. 404도 «오늘 것이 아직 없다»이지 고장이 아니다.

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을 노출하는 카드는 그 경로 전용 스킴을 따로 선언한다 — 그 카드에 자문·조회 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. 미결