keycardai-a2a 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85d721a792f798ee77ee42405e0c4222f3bceeca3c0174dfe6301e75ebbef9ee
+  data.tar.gz: fae24b8dae14b2babe8a59c77633b43752d0b43e6312340bae8fcc135fdca822
+SHA512:
+  metadata.gz: eb034049a79763b365a4939bfa02035ba2917fd0314777c543c7a0b7cdeeb3c7496747ad80131c8b56cdb5733beaec09cb07ee0aa3f0cb7b5e3aa8e8fed4ed70
+  data.tar.gz: 8cae6a783cba822fd0cdeb62ec3ab848469dbdcaf856f300a687021cce488356690c1c3c15929fabc83204bd91edd2f8f7a20e9de658d70d6a96e84f186381ad

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+Entries from 0.2.0 onward are generated by commitizen on each bump. This first
+one is written by hand because 0.1.0 is published from a baseline tag rather
+than from a bump.
+
+## 0.1.0
+
+Initial release.
+
+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.

data/LICENSE

@@ -0,0 +1,9 @@
+MIT LICENSE
+
+Copyright © 2026 Keycard Labs, inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,78 @@
+# keycardai-a2a
+
+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).
+
+```sh
+bundle add keycardai-a2a
+```
+
+Implements the delegation contract from
+[keycard-sdk-spec](https://github.com/keycardai/keycard-sdk-spec)
+(`specs/a2a/a2a-delegation.md`):
+
+1. **Discover**: fetch and cache the target agent's card from
+   `/.well-known/agent-card.json`
+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
+
+Hosting an agent inside a specific agent framework is out of scope, matching
+the Go SDK's boundary. This gem wraps no A2A SDK.
+
+## Quickstart
+
+### Call another agent on the user's behalf
+
+```ruby
+require "keycardai/a2a"
+
+delegation = Keycardai::A2A::DelegationClient.new(
+  issuer: ENV.fetch("KEYCARD_URL"),
+  client_id: ENV.fetch("KEYCARD_CLIENT_ID"),
+  client_secret: ENV.fetch("KEYCARD_CLIENT_SECRET"),
+)
+
+result = delegation.invoke(
+  target: "https://agent-b.example.com",
+  subject_token: inbound_user_token,
+  message: Keycardai::A2A.text_message("summarize today's incidents"),
+)
+
+result.message      # the JSON-RPC result from agent B
+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
+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.
+
+Failures are typed by stage, so you can tell "B is unreachable" from "the zone
+refused the exchange":
+
+```ruby
+begin
+  delegation.invoke(...)
+rescue Keycardai::A2A::DiscoveryError => e     # no resolvable agent card
+rescue Keycardai::OAuth::OAuthError => e       # the zone rejected the exchange
+rescue Keycardai::A2A::InvocationError => e    # B was reached and failed
+end
+```
+
+### Discover a card without invoking
+
+```ruby
+discovery = Keycardai::A2A::ServiceDiscovery.new
+card = discovery.get_card("https://agent-b.example.com")
+card["url"]
+```
+
+Cards are cached for 15 minutes by default (`cache_ttl:`). `refresh` forces a
+fetch, `clear_cache` drops everything. Passing the same `ServiceDiscovery` into
+`DelegationClient.new(discovery:)` shares one cache across both paths.

data/lib/keycardai/a2a/delegation_client.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Keycardai
+  # The A2A delegation client and its result type.
+  module A2A
+    # The result of a delegated invocation: the target's JSON-RPC result plus
+    # the agent card it was discovered through.
+    Result = Data.define(:message, :agent_card)
+
+    # Calls another agent on the user's behalf, carrying the user's identity
+    # through the hop: discover the target's agent card, exchange the inbound
+    # user token for one scoped to the target (RFC 8693; the user stays the
+    # subject and the authorization server records this agent in the act
+    # chain), and invoke the target's JSON-RPC endpoint with the exchanged
+    # token as the bearer credential.
+    class DelegationClient
+      # @param issuer [String] the zone where exchanges are performed
+      # @param credential [Object, nil] this agent's application credential
+      # @param client_id [String, nil] shared-secret pair alternative
+      # @param client_secret [String, nil]
+      # @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
+      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)
+        @exchange = OAuth::TokenExchangeClient.new(issuer: issuer, credential: credential,
+                                                   client_id: client_id, client_secret: client_secret,
+                                                   http_client: http_client)
+        @discovery = discovery || ServiceDiscovery.new(http_client: http_client)
+        @http_client = http_client
+        @invoke_timeout = invoke_timeout
+        @protocol_version = 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]
+      # @raise [DiscoveryError] the agent card cannot be resolved
+      # @raise [Keycardai::OAuth::OAuthError] the exchange was rejected
+      # @raise [InvocationError] the JSON-RPC call failed
+      def invoke(target:, subject_token:, message:)
+        card = @discovery.get_card(target)
+        token = @exchange.exchange_token(subject_token: subject_token, resource: target.chomp("/"))
+        result = post_jsonrpc(jsonrpc_url(target, card), token.access_token, message)
+        Result.new(message: result, agent_card: card)
+      end
+
+      private
+
+      # The invocation endpoint: read from the card when it names one,
+      # 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}"
+      end
+
+      def post_jsonrpc(url, access_token, message)
+        payload = { "jsonrpc" => "2.0", "id" => SecureRandom.uuid, "method" => MESSAGE_SEND_METHOD,
+                    "params" => message }
+        headers = { "Accept" => "application/json", "Authorization" => "Bearer #{access_token}",
+                    "X-A2A-Protocol-Version" => @protocol_version }
+        response = begin
+          @http_client.post_json(url, payload, headers: headers, timeout: @invoke_timeout)
+        rescue OAuth::NetworkError => e
+          raise InvocationError, "invocation of #{url} failed: #{e.message}"
+        end
+        raise InvocationError, "invocation of #{url} returned HTTP #{response.status}" unless response.success?
+
+        parse_jsonrpc(url, response.body)
+      end
+
+      def parse_jsonrpc(url, body)
+        document = begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          raise InvocationError, "invocation of #{url} returned invalid JSON"
+        end
+        if document["error"]
+          raise InvocationError.new("invocation of #{url} returned a JSON-RPC error: #{document["error"]["message"]}",
+                                    rpc_error: document["error"])
+        end
+
+        document["result"]
+      end
+    end
+
+    # Build A2A message/send params carrying one text part, the common case
+    # for driving a downstream agent.
+    #
+    # @param text [String]
+    # @return [Hash]
+    def self.text_message(text)
+      {
+        "message" => {
+          "role" => "user",
+          "parts" => [{ "kind" => "text", "text" => text }],
+          "messageId" => SecureRandom.uuid
+        }
+      }
+    end
+  end
+end

data/lib/keycardai/a2a/errors.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module A2A
+    # The target agent's card cannot be fetched, is not valid JSON, or is
+    # missing the required name.
+    class DiscoveryError < Keycardai::Error; end
+
+    # The JSON-RPC invocation returned an HTTP error or a JSON-RPC error
+    # response. Carries the JSON-RPC error payload when one was returned.
+    class InvocationError < Keycardai::Error
+      # @return [Hash, nil] the JSON-RPC error object, when present
+      attr_reader :rpc_error
+
+      def initialize(message, rpc_error: nil)
+        super(message)
+        @rpc_error = rpc_error
+      end
+    end
+  end
+end

data/lib/keycardai/a2a/service_discovery.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Keycardai
+  module A2A
+    # Resolves an agent's base URL to its agent card, fetched from
+    # /.well-known/agent-card.json and cached (default 15 minutes,
+    # refreshable). A card must carry a name to be valid.
+    class ServiceDiscovery
+      DEFAULT_CACHE_TTL = 900
+
+      # @param http_client [#get] pluggable transport
+      # @param cache_ttl [Numeric] card cache lifetime in seconds
+      # @param timeout [Numeric, nil] fetch timeout
+      # @param clock [#call] returns the current Time; override in tests
+      def initialize(http_client: OAuth::HTTP::NetHTTPClient.new, cache_ttl: DEFAULT_CACHE_TTL,
+                     timeout: nil, clock: -> { Time.now })
+        @http_client = http_client
+        @cache_ttl = cache_ttl
+        @timeout = timeout
+        @clock = clock
+        @cards = {}
+        @mutex = Mutex.new
+      end
+
+      # The agent card for a base URL, served from cache while fresh.
+      #
+      # @param base_url [String] the agent's base URL
+      # @return [Hash] the agent card
+      # @raise [DiscoveryError]
+      def get_card(base_url)
+        key = base_url.chomp("/")
+        cached = @mutex.synchronize do
+          entry = @cards[key]
+          entry[:card] if entry && @clock.call - entry[:fetched_at] <= @cache_ttl
+        end
+        return cached if cached
+
+        refresh(key)
+      end
+
+      # Fetch a fresh card, replacing any cached one.
+      #
+      # @param base_url [String]
+      # @return [Hash]
+      # @raise [DiscoveryError]
+      def refresh(base_url)
+        key = base_url.chomp("/")
+        card = fetch_card(key)
+        @mutex.synchronize { @cards[key] = { card: card, fetched_at: @clock.call } }
+        card
+      end
+
+      # Drop all cached cards.
+      #
+      # @return [void]
+      def clear_cache
+        @mutex.synchronize { @cards.clear }
+      end
+
+      private
+
+      def fetch_card(base_url)
+        url = "#{base_url}#{AGENT_CARD_PATH}"
+        response = begin
+          @http_client.get(url, headers: { "Accept" => "application/json" }, timeout: @timeout)
+        rescue OAuth::NetworkError => e
+          raise DiscoveryError, "agent card fetch from #{url} failed: #{e.message}"
+        end
+        raise DiscoveryError, "agent card fetch from #{url} returned HTTP #{response.status}" unless response.success?
+
+        parse_card(url, response.body)
+      end
+
+      def parse_card(url, body)
+        card = begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          raise DiscoveryError, "agent card from #{url} is not valid JSON"
+        end
+        unless card.is_a?(Hash) && card["name"].is_a?(String) && !card["name"].empty?
+          raise DiscoveryError, "agent card from #{url} is missing the required name"
+        end
+
+        card
+      end
+    end
+  end
+end

data/lib/keycardai/a2a/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Keycardai
+  module A2A
+    VERSION = "0.1.0"
+  end
+end

data/lib/keycardai/a2a.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "keycardai/oauth"
+require_relative "a2a/version"
+require_relative "a2a/errors"
+require_relative "a2a/service_discovery"
+require_relative "a2a/delegation_client"
+
+module Keycardai
+  # Agent-to-agent delegation: one agent calls another on the user's behalf.
+  # Discover the target's agent card, exchange the user's token for one scoped
+  # to the target (RFC 8693; the user stays the subject, the authorization
+  # server records the caller in the token's act chain), and invoke the target
+  # over JSON-RPC.
+  #
+  # Contract: https://github.com/keycardai/keycard-sdk-spec
+  module A2A
+    # Well-known path of an agent's card, relative to its base URL.
+    AGENT_CARD_PATH = "/.well-known/agent-card.json"
+
+    # 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"
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: keycardai-a2a
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Keycard
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: keycardai-oauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+description: 'The A2A delegation contract: agent card discovery, per-hop RFC 8693
+  token exchange carrying the user''s identity, and JSON-RPC invocation. Framework
+  glue for hosting agents is out of scope.'
+email:
+- support@keycard.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/keycardai/a2a.rb
+- lib/keycardai/a2a/delegation_client.rb
+- lib/keycardai/a2a/errors.rb
+- lib/keycardai/a2a/service_discovery.rb
+- lib/keycardai/a2a/version.rb
+homepage: https://github.com/keycardai/ruby-sdk
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/keycardai/ruby-sdk/tree/main/a2a
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Agent-to-agent delegation with Keycard
+test_files: []