A2A Agent Card 实现指南：构建、校验与签名

# Agent Card lint for A2A v1.0.1.
# Usage: jq -r -f agent-card-lint.jq agent-card.json
# Checks come from the REQUIRED annotations in a2a.proto, specification sections 5.7, 8.3 and 8.4,
# and the v0.3 -> v1.0 renames. ERROR lines break the specification; WARN lines are advisory.

def blank: . == null or . == "" or . == [];

# Required strings, arrays (at least one element, section 5.7) and objects.
def need($o; $path; $strs; $arrs; $objs):
  if ($o | type) != "object" then "ERROR \($path): expected a JSON object"
  else
    ($strs[] as $k | select($o[$k] | blank) | "ERROR \($path)/\($k): required string is missing or empty"),
    ($arrs[] as $k | select(($o[$k] | type) != "array" or ($o[$k] | length) == 0)
      | "ERROR \($path)/\($k): required array is missing or empty"),
    ($objs[] as $k | select($o[$k] == null) | "ERROR \($path)/\($k): required object is missing")
  end;

def v03: {
  "url": "supportedInterfaces[0].url",
  "preferredTransport": "supportedInterfaces[].protocolBinding",
  "additionalInterfaces": "supportedInterfaces[]",
  "protocolVersion": "supportedInterfaces[].protocolVersion",
  "supportsAuthenticatedExtendedCard": "capabilities.extendedAgentCard",
  "security": "securityRequirements"
};

def card_fields: ["name", "description", "supportedInterfaces", "provider", "version", "documentationUrl",
  "capabilities", "securitySchemes", "securityRequirements", "defaultInputModes", "defaultOutputModes",
  "skills", "signatures", "iconUrl"];

# Scheme type -> [required strings, required objects]; flow type -> same.
def scheme_req: {
  "apiKeySecurityScheme": [["location", "name"], []],
  "httpAuthSecurityScheme": [["scheme"], []],
  "oauth2SecurityScheme": [[], ["flows"]],
  "openIdConnectSecurityScheme": [["openIdConnectUrl"], []],
  "mtlsSecurityScheme": [[], []]
};
def flow_req: {
  "authorizationCode": [["authorizationUrl", "tokenUrl"], ["scopes"]],
  "clientCredentials": [["tokenUrl"], ["scopes"]],
  "deviceCode": [["deviceAuthorizationUrl", "tokenUrl"], ["scopes"]],
  "implicit": [[], []],
  "password": [[], []]
};

def requirement_names($path):
  (. // []) | to_entries[] | .key as $i | .value
  | if (type == "object" and (.schemes | type) == "object") then (.schemes | keys[] | {name: ., at: "\($path)/\($i)"})
    else {bad: "\($path)/\($i)"} end;

. as $card
| if type != "object" then "ERROR /: an Agent Card must be a JSON object" else
  [
    need($card; ""; ["name", "description", "version"];
      ["supportedInterfaces", "defaultInputModes", "defaultOutputModes", "skills"]; ["capabilities"]),

    (keys[] | select(. as $k | card_fields | index($k) | not) | . as $k
      | if v03[$k] then "ERROR /\($k): v0.3 field, use \(v03[$k]) in v1.0"
        else "WARN /\($k): not an AgentCard field in v1.0.1 (typo?)" end),

    (($card.supportedInterfaces // []) | to_entries[] | .key as $i | .value as $v
      | need($v; "/supportedInterfaces/\($i)"; ["url", "protocolBinding", "protocolVersion"]; []; []),
        (select(($v | type) == "object") | $v
          | (select((.url // "https://") | startswith("https://") | not)
              | "WARN /supportedInterfaces/\($i)/url: production URLs must be absolute HTTPS"),
            (select((.protocolBinding // "JSONRPC") as $b | ["JSONRPC", "GRPC", "HTTP+JSON"] | index($b) == null and ($b | test("^[a-z][a-z0-9+.-]*:") | not))
              | "WARN /supportedInterfaces/\($i)/protocolBinding: not JSONRPC, GRPC or HTTP+JSON; custom bindings should use a URI (section 5.8)"),
            (select((.protocolVersion // "1.0") | test("^[0-9]+\\.[0-9]+$") | not)
              | "WARN /supportedInterfaces/\($i)/protocolVersion: expected major.minor such as 1.0"))),

    (select($card.provider != null) | need($card.provider; "/provider"; ["url", "organization"]; []; [])),

    (($card.skills // []) | to_entries[] | .key as $i | .value as $s
      | need($s; "/skills/\($i)"; ["id", "name", "description"]; ["tags"]; []),
        (select(($s | type) == "object" and ($s | has("security"))) | "ERROR /skills/\($i)/security: v0.3 field, use securityRequirements in v1.0")),
    ((($card.skills // []) | map(select(type == "object") | .id) | group_by(.)[] | select(length > 1 and .[0] != null) | .[0])
      | "WARN /skills: id \"\(.)\" is used more than once"),

    (($card.securitySchemes // {}) | to_entries[] | .key as $n | .value as $v
      | "/securitySchemes/\($n)" as $p
      | ($v | if type == "object" then keys else [] end) as $ks
      | if ($ks | length) != 1 or (scheme_req | has($ks[0]) | not)
          then "ERROR \($p): set exactly one of \(scheme_req | keys_unsorted | join(", "))"
        else $ks[0] as $t
          | need($v[$t]; "\($p)/\($t)"; scheme_req[$t][0]; []; scheme_req[$t][1]),
            (select($t == "oauth2SecurityScheme" and ($v[$t].flows | type) == "object")
              | ($v[$t].flows | keys) as $fk
              | "\($p)/\($t)/flows" as $fp
              | if ($fk | length) != 1 or (flow_req | has($fk[0]) | not)
                  then "ERROR \($fp): set exactly one of \(flow_req | keys_unsorted | join(", "))"
                else need($v[$t].flows[$fk[0]]; "\($fp)/\($fk[0])"; flow_req[$fk[0]][0]; []; flow_req[$fk[0]][1]),
                     (select(["implicit", "password"] | index($fk[0])) | "WARN \($fp)/\($fk[0]): deprecated in v1.0.1")
                end)
        end),

    ([$card.securityRequirements | requirement_names("/securityRequirements"),
      (($card.skills // []) | to_entries[] | .key as $i | .value | select(type == "object")
        | .securityRequirements | requirement_names("/skills/\($i)/securityRequirements"))][]
      | if .bad then "ERROR \(.bad): a requirement is an object with a \"schemes\" map"
        elif (.name as $n | ($card.securitySchemes // {}) | has($n) | not) then "ERROR \(.at): scheme \"\(.name)\" is not defined in securitySchemes"
        else empty end),

    (select($card.capabilities.extendedAgentCard == true and (($card.securitySchemes // {}) | length) == 0)
      | "WARN /capabilities/extendedAgentCard: GetExtendedAgentCard needs authentication, but no securitySchemes are declared"),
    (($card.capabilities.extensions // []) | to_entries[] | select(.value.uri | blank)
      | "WARN /capabilities/extensions/\(.key): extension without a uri"),

    (($card.signatures // []) | to_entries[] | .key as $i | .value as $g
      | need($g; "/signatures/\($i)"; ["protected", "signature"]; []; []),
        (select(($g | type) == "object" and ($g.protected | blank | not)) | $g.protected
          | (try (gsub("-"; "+") | gsub("_"; "/") | @base64d | fromjson) catch null) as $h
          | if $h == null then "ERROR /signatures/\($i)/protected: not base64url-encoded JSON"
            else (("alg", "kid") as $k | select($h[$k] | blank) | "ERROR /signatures/\($i)/protected: header needs \($k)"),
                 (select($h.typ != "JOSE") | "WARN /signatures/\($i)/protected: typ should be JOSE") end))
  ] | if length == 0 then "OK: no findings" else .[] end
end