keycardai-a2a 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85d721a792f798ee77ee42405e0c4222f3bceeca3c0174dfe6301e75ebbef9ee
-  data.tar.gz: fae24b8dae14b2babe8a59c77633b43752d0b43e6312340bae8fcc135fdca822
+  metadata.gz: b1573597b5a3ee265b3a30b56b8e0681b70b5993aefd619da4f761efcd46eac1
+  data.tar.gz: a42a9591d4fdeaf4a409aad1b7b9a2f83ccf064f17ae8e739105d1ed70e318ea
 SHA512:
-  metadata.gz: eb034049a79763b365a4939bfa02035ba2917fd0314777c543c7a0b7cdeeb3c7496747ad80131c8b56cdb5733beaec09cb07ee0aa3f0cb7b5e3aa8e8fed4ed70
-  data.tar.gz: 8cae6a783cba822fd0cdeb62ec3ab848469dbdcaf856f300a687021cce488356690c1c3c15929fabc83204bd91edd2f8f7a20e9de658d70d6a96e84f186381ad
+  metadata.gz: fc0107c8c5b975c24518c9589e64d0d9afe0db248c1dc49a121fcd6deb3ad6dfd87150376eaab736a3bcbe091fbefad6e149fae8b3813e452af7ab44358eac64
+  data.tar.gz: 8281680b4456cc7066e404875ea766282b4d28adb2e1c2221933997748e73ffa950f2ed73ef4b7267ea75d09811577ef0d1ee1842b21f1694b668d851247c08e

data/CHANGELOG.md

@@ -12,3 +12,31 @@ Agent-to-agent delegation: agent card discovery with caching, per-hop RFC 8693
 token exchange that keeps the user as the subject, and JSON-RPC `message/send`
 invocation. Wraps no A2A SDK; hosting an agent inside a framework is out of
 scope.
+
+## 0.2.0-keycardai-a2a (2026-09-07)
+
+
+- feat(keycardai-a2a): speak A2A protocol 1.0 by default
+- ECO-161 Ruby leg, after typescript-sdk #173 and go-sdk #47. DelegationClient sends 1.0-generation requests by default (SendMessage, A2A-Version: 1.0, ROLE_USER roles, untagged text parts, endpoint read from the card's JSONRPC supportedInterfaces entry) instead of the 0.3 envelope, so invoking a keycardai-a2a (Python) or @keycardai/a2a agent no longer returns MethodNotFound. protocol_version: now selects the whole wire generation through Keycardai::A2A::Wire: LEGACY_PROTOCOL_VERSION sends a real 0.3 envelope (role and part shapes translated on the way out), and any other value raises ArgumentError instead of being sent verbatim. A2A.text_message builds the 1.0 shape either way. The JSON-RPC result is returned as the agent sent it, the gem's existing contract.
+- BREAKING CHANGE(keycardai-a2a): PROTOCOL_VERSION and MESSAGE_SEND_METHOD constant values moved to the 1.0 generation, and 0.3 interop requires protocol_version: LEGACY_PROTOCOL_VERSION.
+
+## 0.1.0-keycardai-a2a (2026-08-19)
+
+
+- feat(keycardai-a2a): delegation client and agent card discovery (#10)
+- Phase 3: the A2A delegation contract per specs/a2a/a2a-delegation.md,
+matching the Go boundary (delegation client only; agent-framework
+hosting glue is out of scope, and no community A2A gem dependency):
+- - ServiceDiscovery: agent card fetch from /.well-known/agent-card.json
+  with a 15-minute refreshable cache; a card must carry a name
+- DelegationClient: discover, RFC 8693 exchange (subject = the user
+  token, resource = the target agent, this agent authenticates with its
+  credential, no actor_token), then JSON-RPC message/send with the
+  exchanged bearer token and X-A2A-Protocol-Version 0.3; the invocation
+  endpoint is read from the card or derived by convention
+- Typed DiscoveryError / InvocationError (with the JSON-RPC error
+  payload); exchange failures surface as the oauth OAuthError per hop
+- A2A.text_message convenience for single-text-part params
+- Conformance suite maps to all five spec unit rows, plus card-declared
+endpoint and cache-TTL coverage; the multi-hop act-chain rows are the
+integration table for the E2E phase.

data/README.md

@@ -2,7 +2,6 @@
 
 Agent-to-agent delegation for Ruby agents on the Keycard platform.
 
-> **Preview.** APIs may change between minor versions while the surface settles.
 > Conformance against the cross-SDK contract is tracked in the
 > [conformance report](https://github.com/keycardai/ruby-sdk/blob/main/docs/conformance-report.md).
 
@@ -19,8 +18,8 @@ Implements the delegation contract from
 2. **Exchange**: RFC 8693 token exchange, subject = the inbound user token,
    authenticated by the calling agent's credential; the user stays the subject
    and the authorization server appends the caller to the `act` chain
-3. **Invoke**: JSON-RPC `message/send` against the target with the exchanged
-   token as the bearer credential
+3. **Invoke**: JSON-RPC `SendMessage` (A2A protocol 1.0) against the target
+   with the exchanged token as the bearer credential
 
 Hosting an agent inside a specific agent framework is out of scope, matching
 the Go SDK's boundary. This gem wraps no A2A SDK.
@@ -49,10 +48,21 @@ result.agent_card   # the card that was discovered on the way
 ```
 
 One call covers all three steps: fetch and cache agent B's card, exchange the
-inbound token for one scoped to B, then send JSON-RPC `message/send` with the
+inbound token for one scoped to B, then send JSON-RPC `SendMessage` with the
 exchanged token as the bearer credential. The user stays the subject across the
 hop; agent B verifies a token whose `sub` is the original user, not this agent.
 
+### Protocol version
+
+The client speaks A2A protocol 1.0 by default: `SendMessage`, an `A2A-Version:
+1.0` header, `ROLE_USER` roles, untagged text parts, and the invocation URL read
+from the card's JSONRPC `supportedInterfaces` entry. Agents still on protocol
+0.3 do not interoperate with the default; to reach one, pass
+`protocol_version: Keycardai::A2A::LEGACY_PROTOCOL_VERSION`. That switches the
+whole envelope generation (`message/send`, `X-A2A-Protocol-Version: 0.3`,
+`user` roles, `kind`-tagged parts), so `Keycardai::A2A.text_message` output is
+still the input either way. Any other value raises `ArgumentError`.
+
 Failures are typed by stage, so you can tell "B is unreachable" from "the zone
 refused the exchange":
 

data/lib/keycardai/a2a/delegation_client.rb

@@ -24,7 +24,12 @@ module Keycardai
       # @param http_client [#get, #post_form, #post_json] pluggable transport
       # @param discovery [ServiceDiscovery, nil] card resolution override
       # @param invoke_timeout [Numeric, nil] JSON-RPC call timeout
-      # @param protocol_version [String] sent as X-A2A-Protocol-Version
+      # @param protocol_version [String] the A2A generation to speak: PROTOCOL_VERSION
+      #   (1.0: SendMessage, A2A-Version header, ROLE_USER roles, untagged text parts)
+      #   or LEGACY_PROTOCOL_VERSION (0.3: message/send, X-A2A-Protocol-Version header,
+      #   "user" roles, kind-tagged parts). Build the message with A2A.text_message
+      #   either way; the client translates it for 0.3.
+      # @raise [ArgumentError] protocol_version is neither supported generation
       def initialize(issuer:, credential: nil, client_id: nil, client_secret: nil,
                      http_client: OAuth::HTTP::NetHTTPClient.new, discovery: nil,
                      invoke_timeout: nil, protocol_version: PROTOCOL_VERSION)
@@ -34,15 +39,17 @@ module Keycardai
         @discovery = discovery || ServiceDiscovery.new(http_client: http_client)
         @http_client = http_client
         @invoke_timeout = invoke_timeout
-        @protocol_version = protocol_version
+        @wire = Wire.for(protocol_version)
       end
 
       # Delegate a call to another agent: discover, exchange, invoke.
       #
       # @param target [String] the downstream agent's base URL
       # @param subject_token [String] the inbound user's verified access token
-      # @param message [Hash] the A2A message/send params
-      # @return [Result]
+      # @param message [Hash] the A2A SendMessage params (see A2A.text_message)
+      # @return [Result] message is the JSON-RPC result as the agent returned it:
+      #   for a 1.0 agent an object with a +message+ or +task+ key
+      # @raise [ArgumentError] protocol_version is unsupported
       # @raise [DiscoveryError] the agent card cannot be resolved
       # @raise [Keycardai::OAuth::OAuthError] the exchange was rejected
       # @raise [InvocationError] the JSON-RPC call failed
@@ -55,17 +62,18 @@ module Keycardai
 
       private
 
-      # The invocation endpoint: read from the card when it names one,
-      # otherwise derived by convention from the target base URL.
+      # The invocation endpoint: read from the card when it names one (a 1.0
+      # card's JSONRPC interface or a 0.3 card's url), otherwise derived by
+      # convention from the target base URL.
       def jsonrpc_url(target, card)
-        card["url"].is_a?(String) && !card["url"].empty? ? card["url"] : "#{target.chomp("/")}#{JSONRPC_PATH}"
+        @wire.endpoint_from(card) || "#{target.chomp("/")}#{JSONRPC_PATH}"
       end
 
       def post_jsonrpc(url, access_token, message)
-        payload = { "jsonrpc" => "2.0", "id" => SecureRandom.uuid, "method" => MESSAGE_SEND_METHOD,
-                    "params" => message }
+        payload = { "jsonrpc" => "2.0", "id" => SecureRandom.uuid, "method" => @wire.method_name,
+                    "params" => @wire.encode_params(message) }
         headers = { "Accept" => "application/json", "Authorization" => "Bearer #{access_token}",
-                    "X-A2A-Protocol-Version" => @protocol_version }
+                    @wire.header => @wire.version }
         response = begin
           @http_client.post_json(url, payload, headers: headers, timeout: @invoke_timeout)
         rescue OAuth::NetworkError => e
@@ -91,16 +99,17 @@ module Keycardai
       end
     end
 
-    # Build A2A message/send params carrying one text part, the common case
-    # for driving a downstream agent.
+    # Build A2A 1.0 SendMessage params carrying one text part, the common case
+    # for driving a downstream agent. A client configured for 0.3 translates
+    # the role and part shape on the way out.
     #
     # @param text [String]
     # @return [Hash]
     def self.text_message(text)
       {
         "message" => {
-          "role" => "user",
-          "parts" => [{ "kind" => "text", "text" => text }],
+          "role" => ROLE_USER,
+          "parts" => [{ "text" => text }],
           "messageId" => SecureRandom.uuid
         }
       }

data/lib/keycardai/a2a/version.rb

@@ -2,6 +2,6 @@
 
 module Keycardai
   module A2A
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/keycardai/a2a/wire.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module A2A
+    # A2A protocol version spoken by default: the 1.0 generation, which is
+    # what keycardai-a2a (Python) and @keycardai/a2a (TypeScript) serve.
+    PROTOCOL_VERSION = "1.0"
+
+    # The 0.3 generation, for agents not yet on 1.0. Pass it as
+    # DelegationClient's protocol_version: to send 0.3-shaped requests.
+    LEGACY_PROTOCOL_VERSION = "0.3"
+
+    # JSON-RPC method that delivers a message to a 1.0 agent.
+    MESSAGE_SEND_METHOD = "SendMessage"
+
+    # JSON-RPC method that delivers a message to a 0.3 agent.
+    LEGACY_MESSAGE_SEND_METHOD = "message/send"
+
+    # Header carrying the protocol version on a 1.0 request.
+    PROTOCOL_VERSION_HEADER = "A2A-Version"
+
+    # Header carrying the protocol version on a 0.3 request.
+    LEGACY_PROTOCOL_VERSION_HEADER = "X-A2A-Protocol-Version"
+
+    # Message roles as the 1.0 protocol names them (0.3 used "user"/"agent").
+    ROLE_USER = "ROLE_USER"
+    ROLE_AGENT = "ROLE_AGENT"
+
+    # One protocol generation's wire conventions: the JSON-RPC method, the
+    # version header, and how message roles and text parts are spelled. The
+    # version selects the whole envelope, never only the header.
+    class Wire
+      LEGACY_ROLES = { ROLE_USER => "user", ROLE_AGENT => "agent" }.freeze
+
+      # @param version [String] PROTOCOL_VERSION or LEGACY_PROTOCOL_VERSION
+      # @raise [ArgumentError] any other value
+      def self.for(version)
+        case version
+        when PROTOCOL_VERSION
+          new(version: version, header: PROTOCOL_VERSION_HEADER, method_name: MESSAGE_SEND_METHOD)
+        when LEGACY_PROTOCOL_VERSION
+          new(version: version, header: LEGACY_PROTOCOL_VERSION_HEADER, method_name: LEGACY_MESSAGE_SEND_METHOD)
+        else
+          raise ArgumentError, "unsupported A2A protocol version #{version.inspect} " \
+                               "(supported: #{PROTOCOL_VERSION}, #{LEGACY_PROTOCOL_VERSION})"
+        end
+      end
+
+      attr_reader :version, :header, :method_name
+
+      def initialize(version:, header:, method_name:)
+        @version = version
+        @header = header
+        @method_name = method_name
+      end
+
+      def legacy?
+        version == LEGACY_PROTOCOL_VERSION
+      end
+
+      # Encode 1.0-shaped params (as built by A2A.text_message) for the wire.
+      # On 1.0 they pass through; on 0.3 the message role takes its 0.3 name
+      # and text parts gain the kind tag 0.3 requires.
+      def encode_params(params)
+        message = params.is_a?(Hash) ? params["message"] : nil
+        return params unless legacy? && message.is_a?(Hash)
+
+        params.merge("message" => message.merge(
+          "role" => LEGACY_ROLES.fetch(message["role"], message["role"]),
+          "parts" => Array(message["parts"]).map { |part| legacy_part(part) }
+        ))
+      end
+
+      # The invocation endpoint from an agent card: a 1.0 card's JSONRPC
+      # interface (preferring the one matching this version), else a 0.3
+      # card's url, else nil.
+      def endpoint_from(card)
+        interfaces = Array(card["supportedInterfaces"]).select { |iface| jsonrpc_interface?(iface) }
+        matching = interfaces.find { |iface| iface["protocolVersion"] == version } || interfaces.first
+        return matching["url"] if matching
+
+        card["url"] if card["url"].is_a?(String) && !card["url"].empty?
+      end
+
+      private
+
+      def legacy_part(part)
+        return part unless part.is_a?(Hash) && part.key?("text") && !part.key?("kind")
+
+        { "kind" => "text" }.merge(part)
+      end
+
+      def jsonrpc_interface?(iface)
+        iface.is_a?(Hash) && iface["protocolBinding"].to_s.casecmp?("JSONRPC") &&
+          iface["url"].is_a?(String) && !iface["url"].empty?
+      end
+    end
+  end
+end

data/lib/keycardai/a2a.rb

@@ -3,6 +3,7 @@
 require "keycardai/oauth"
 require_relative "a2a/version"
 require_relative "a2a/errors"
+require_relative "a2a/wire"
 require_relative "a2a/service_discovery"
 require_relative "a2a/delegation_client"
 
@@ -21,10 +22,7 @@ module Keycardai
     # JSON-RPC invocation path, relative to an agent's base URL.
     JSONRPC_PATH = "/a2a/jsonrpc"
 
-    # JSON-RPC method used to deliver a message to an agent.
-    MESSAGE_SEND_METHOD = "message/send"
-
-    # A2A protocol version sent with each invocation.
-    PROTOCOL_VERSION = "0.3"
+    # The protocol-generation constants (PROTOCOL_VERSION, MESSAGE_SEND_METHOD,
+    # ROLE_USER, and their LEGACY_ 0.3 counterparts) live in a2a/wire.rb.
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycardai-a2a
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Keycard
@@ -40,6 +40,7 @@ files:
 - lib/keycardai/a2a/errors.rb
 - lib/keycardai/a2a/service_discovery.rb
 - lib/keycardai/a2a/version.rb
+- lib/keycardai/a2a/wire.rb
 homepage: https://github.com/keycardai/ruby-sdk
 licenses:
 - MIT