agent2agent 1.0.0

data/lib/a2a/agent.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  # DSL wrapper that collects operation handlers for an A2A agent.
+  #
+  # An Agent produces handler objects that conform to the Dispatcher's
+  # duck-type contract (#operations, #call). Register an agent on a
+  # Server the same way you would register a plain handler.
+  #
+  #   agent = A2A::Agent.new do
+  #     on "SendMessage" do |request|
+  #       respond A2A::Schema["Send Message Response"].new({})
+  #     end
+  #
+  #     on "GetTask" do |request|
+  #       task = store.get(request.id)
+  #       respond A2A::Schema["Task"].new(task.to_h)
+  #     end
+  #   end
+  #
+  #   server.register(agent)
+  #
+  class Agent
+    attr_reader :handlers
+
+    def initialize(&block)
+      @handlers = []
+
+      instance_eval(&block) if block
+    end
+
+    # Register a handler block for one or more A2A operations.
+    #
+    # Operations are identified by their proto name (e.g. "SendMessage",
+    # "GetTask", "CancelTask"). See A2A::Proto.operations for the full list.
+    #
+    def on(*operations, &block)
+      raise ArgumentError, "on requires at least one operation" if operations.empty?
+      raise ArgumentError, "on requires a block" unless block
+
+      handler = Handler.new(
+        agent:      self,
+        operations: operations.flatten,
+        block:      block
+      )
+
+      @handlers << handler
+      handler
+    end
+
+    # Internal handler object produced by the #on DSL method.
+    # Conforms to the Dispatcher duck-type: #operations, #call.
+    class Handler
+      attr_reader :operations
+
+      def initialize(agent:, operations:, block:)
+        @agent      = agent
+        @operations = operations
+        @block      = block
+      end
+
+      def call(env)
+        Context.new(env).execute(&@block)
+      end
+    end
+
+    # Execution context for handler blocks.
+    # Provides helper methods so blocks can call store, respond, stream, etc.
+    # directly without holding a reference to the env hash.
+    class Context
+      def initialize(env)
+        @env = env
+      end
+
+      def execute(&block)
+        instance_exec(@env["a2a.request"], &block)
+      end
+
+      def store
+        @env["a2a.store"]
+      end
+
+      def request
+        @env["a2a.request"]
+      end
+
+      def agent_card
+        @env["a2a.agent_card"]
+      end
+
+      def respond(result)
+        @env["a2a.result"] = result
+      end
+
+      # Create an SSE stream for streaming responses.
+      #
+      # Automatically selects the right stream type based on the binding:
+      #   - JSON-RPC binding -> JsonRpcStream (wraps events in envelopes)
+      #   - REST binding     -> RestStream (bare JSON events)
+      #
+      # The stream is registered on env["a2a.stream"] so the binding
+      # middleware returns it as the Rack body. Falcon streams it natively
+      # via Protocol::HTTP::Body::Writable — no threads, no polling.
+      #
+      # Usage in a handler block:
+      #
+      #   on "SendStreamingMessage" do |request|
+      #     s = stream
+      #     Async do
+      #       s.event({ "task" => { ... } })
+      #       s.event({ "statusUpdate" => { ... } })
+      #       s.finish
+      #     end
+      #   end
+      #
+      def stream
+        require "a2a/sse"
+
+        s = if @env["a2a.json_rpc_id"]
+          A2A::SSE::JsonRpcStream.new(json_rpc_id: @env["a2a.json_rpc_id"])
+        else
+          A2A::SSE::RestStream.new
+        end
+
+        @env["a2a.stream"] = s
+        s
+      end
+    end
+  end
+end
+
+test do
+  describe "A2A::Agent" do
+    it "registers handlers via the on DSL" do
+      agent = A2A::Agent.new do
+        on "SendMessage" do |request|
+          # no-op
+        end
+      end
+
+      agent.handlers.length.should == 1
+      agent.handlers.first.operations.should == ["SendMessage"]
+    end
+
+    it "registers multiple operations on a single handler" do
+      agent = A2A::Agent.new do
+        on "SendMessage", "GetTask" do |request|
+          # no-op
+        end
+      end
+
+      agent.handlers.first.operations.should == ["SendMessage", "GetTask"]
+    end
+
+    it "raises if on is called without operations" do
+      lambda {
+        A2A::Agent.new do
+          on do |request|; end
+        end
+      }.should.raise(ArgumentError)
+    end
+
+    it "raises if on is called without a block" do
+      lambda {
+        agent = A2A::Agent.new
+        agent.on "SendMessage"
+      }.should.raise(ArgumentError)
+    end
+
+    it "executes handler block in Context with access to env" do
+      agent = A2A::Agent.new do
+        on "SendMessage" do |request|
+          respond({ "echo" => true })
+        end
+      end
+
+      env = {
+        "a2a.store"      => A2A::TaskStore.new,
+        "a2a.request"    => { "message" => "hello" },
+        "a2a.agent_card" => { "name" => "Test" },
+      }
+
+      agent.handlers.first.call(env)
+
+      env["a2a.result"].should == { "echo" => true }
+    end
+
+    it "provides store access in handler context" do
+      store = A2A::TaskStore.new
+      seen_store = nil
+
+      agent = A2A::Agent.new do
+        on "SendMessage" do |request|
+          seen_store = store
+        end
+      end
+
+      env = { "a2a.store" => store, "a2a.request" => {} }
+      agent.handlers.first.call(env)
+
+      seen_store.should == store
+    end
+
+    it "creates a JsonRpcStream when JSON-RPC binding is active" do
+      agent = A2A::Agent.new do
+        on "SendStreamingMessage" do |request|
+          s = stream
+          s.is_a?(A2A::SSE::JsonRpcStream).should == true
+        end
+      end
+
+      env = {
+        "a2a.store"       => A2A::TaskStore.new,
+        "a2a.request"     => {},
+        "a2a.json_rpc_id" => 42,
+      }
+      agent.handlers.first.call(env)
+
+      env["a2a.stream"].should.not.be.nil
+      env["a2a.stream"].is_a?(Protocol::HTTP::Body::Readable).should == true
+    end
+
+    it "creates a RestStream when REST binding is active" do
+      agent = A2A::Agent.new do
+        on "SendStreamingMessage" do |request|
+          s = stream
+          s.is_a?(A2A::SSE::RestStream).should == true
+        end
+      end
+
+      env = {
+        "a2a.store"   => A2A::TaskStore.new,
+        "a2a.request" => {},
+      }
+      agent.handlers.first.call(env)
+
+      env["a2a.stream"].should.not.be.nil
+    end
+  end
+end

data/lib/a2a/bindings/json_rpc.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+require "a2a/sse"
+
+module A2A
+  module Bindings
+    # Rack middleware implementing the A2A JSON-RPC 2.0 protocol binding.
+    #
+    # Strips the JSON-RPC envelope from the inbound request, setting
+    # env keys for the method name, request id, and parsed params.
+    # Calls downstream. On return, wraps env["a2a.result"] back into
+    # a JSON-RPC response envelope.
+    #
+    # Streaming operations (SendStreamingMessage, SubscribeToTask):
+    # When the handler sets env["a2a.stream"] to an SSE::Stream (which is
+    # a Protocol::HTTP::Body::Writable, which is a Readable), Falcon's
+    # protocol-rack passes it through untouched. True async streaming
+    # with backpressure — no Thread::Queue, no #each polling.
+    #
+    class JsonRpc
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        req  = Rack::Request.new(env)
+        body = req.body.read
+        req.body.rewind
+
+        begin
+          rpc = JSON.parse(body)
+        rescue JSON::ParserError
+          return error_response(nil, -32700, "Parse error")
+        end
+
+        unless rpc.is_a?(Hash) && rpc["jsonrpc"] == "2.0"
+          return error_response(nil, -32600, "Invalid Request")
+        end
+
+        id     = rpc["id"]
+        method = rpc["method"]
+        params = rpc["params"] || {}
+
+        env["a2a.json_rpc_id"]     = id
+        env["a2a.json_rpc_method"] = method
+        env["a2a.body"]            = params
+
+        @app.call(env)
+
+        # Check if handler signalled a JSON-RPC error
+        if (err = env["a2a.error"])
+          return error_response(id, err[:code], err[:message], err[:data])
+        end
+
+        # Check if handler set up a streaming response.
+        # The stream is an SSE::Stream (Protocol::HTTP::Body::Readable).
+        if (stream = env["a2a.stream"])
+          return [200, A2A::SSE::Stream.headers, stream]
+        end
+
+        result = env["a2a.result"]
+        success_response(id, result)
+      end
+
+      private
+
+        def success_response(id, result)
+          body = result.respond_to?(:to_h) ? result.to_h : (result || {})
+          [200, { "content-type" => "application/json" },
+           [JSON.generate(jsonrpc: "2.0", id: id, result: body)]]
+        end
+
+        def error_response(id, code, message, data = nil)
+          err = { code: code, message: message }
+          err[:data] = data if data
+          [200, { "content-type" => "application/json" },
+           [JSON.generate(jsonrpc: "2.0", id: id, error: err)]]
+        end
+    end
+  end
+end
+
+test do
+  server = A2A::Server.new(agent_card: { "name" => "Test" })
+  rack   = Rack::MockRequest.new(server)
+
+  A2A::Proto.operations.each do |op|
+    it "#{op.json_rpc_method} returns valid #{op.response_type}" do
+      body = JSON.generate({
+        jsonrpc: "2.0",
+        id: 1,
+        method: op.json_rpc_method,
+        params: {}
+      })
+
+      response = rack.post("/a2a", input: body, "CONTENT_TYPE" => "application/json")
+      parsed   = JSON.parse(response.body)
+
+      parsed["error"].should.be.nil
+
+      if op.response_schema
+        result = parsed["result"]
+        schema_obj = op.response_schema.new(result)
+        schema_obj.valid?.should == true
+      end
+    end
+  end
+end

data/lib/a2a/bindings/rest.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+require "a2a/sse"
+
+module A2A
+  module Bindings
+    # Rack middleware implementing the A2A HTTP+JSON/REST protocol binding.
+    #
+    # Extracts the HTTP verb, path, and request body/params into env keys.
+    # Calls downstream. On return, wraps env["a2a.result"] into a REST
+    # response with content-type application/a2a+json.
+    #
+    # Streaming operations:
+    # When the handler sets env["a2a.stream"] to an SSE::Stream (which is
+    # a Protocol::HTTP::Body::Readable), Falcon streams it natively —
+    # no wrapping, no #each conversion, true async with backpressure.
+    #
+    class Rest
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        req = Rack::Request.new(env)
+
+        env["a2a.verb"] = req.request_method.downcase
+        env["a2a.path"] = req.path_info
+
+        params = {}
+        if req.post? || req.put? || req.patch?
+          begin
+            params = JSON.parse(req.body.read) rescue {}
+          end
+        end
+
+        # Merge query params for GET/DELETE
+        params.merge!(req.params) if req.get? || req.delete?
+
+        env["a2a.body"] = params
+
+        @app.call(env)
+
+        # Check if handler signalled a REST error
+        if (err = env["a2a.error"])
+          return error_response(err[:http_status] || 400, err[:message], err[:data])
+        end
+
+        # Check if handler set up a streaming response.
+        # The stream is an SSE::Stream (Protocol::HTTP::Body::Readable).
+        if (stream = env["a2a.stream"])
+          return [200, A2A::SSE::Stream.headers, stream]
+        end
+
+        result = env["a2a.result"]
+        success_response(result)
+      end
+
+      private
+
+        def success_response(result)
+          body = result.respond_to?(:to_h) ? result.to_h : (result || {})
+          [200, { "content-type" => "application/a2a+json" },
+           [JSON.generate(body)]]
+        end
+
+        def error_response(status, message, data = nil)
+          body = { "type" => "error", "title" => message, "status" => status }
+          body["detail"] = data if data
+          [status, { "content-type" => "application/problem+json" },
+           [JSON.generate(body)]]
+        end
+    end
+  end
+end
+
+test do
+  server = A2A::Server.new(agent_card: { "name" => "Test" })
+  rack   = Rack::MockRequest.new(server)
+
+  A2A::Proto.operations.each do |op|
+    it "#{op.rest_verb.upcase} #{op.rest_path} returns valid #{op.response_type}" do
+      # Build request path, replacing {id=*} etc with a placeholder value
+      path = op.rest_path.gsub(/\{[^}]+\}/, "test-id")
+
+      input = nil
+      if op.http_bindings.first.body
+        input = JSON.generate({})
+      end
+
+      response = rack.request(op.rest_verb.upcase, path,
+        input: input,
+        "CONTENT_TYPE" => "application/a2a+json")
+
+      parsed = JSON.parse(response.body)
+
+      parsed["error"].should.be.nil
+
+      if op.response_schema
+        schema_obj = op.response_schema.new(parsed)
+        schema_obj.valid?.should == true
+      end
+    end
+  end
+end

data/lib/a2a/client.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "a2a"
+
+module A2A
+  # Async-HTTP based A2A protocol client.
+  #
+  # Discovers agent cards and invokes operations via JSON-RPC:
+  #
+  #   Async do
+  #     client = A2A::Client.new("http://localhost:9292")
+  #     card   = client.agent_card
+  #     result = client.send_message(message: { ... })
+  #     task   = client.get_task(id: "task-123")
+  #   end
+  #
+  class Client
+    def initialize(url)
+      @url = url.chomp("/")
+    end
+
+    # GET /.well-known/agent-card.json
+    def agent_card
+      get("/.well-known/agent-card.json")
+    end
+
+    # JSON-RPC operations — each maps to a Proto operation name.
+    Proto.operations.each do |op|
+      method_name = op.name.gsub(/([A-Z])/) { "_#{$1.downcase}" }.sub(/^_/, "")
+
+      define_method(method_name) do |params = {}|
+        json_rpc(op.name, params)
+      end
+    end
+
+    private
+
+      def json_rpc(method, params)
+        body = JSON.generate(
+          jsonrpc: "2.0",
+          id: next_id,
+          method: method,
+          params: params,
+        )
+
+        response = post("/", body, "application/json")
+        parsed = JSON.parse(response)
+
+        if (error = parsed["error"])
+          raise "JSON-RPC error #{error["code"]}: #{error["message"]}"
+        end
+
+        parsed["result"]
+      end
+
+      def get(path)
+        Async do
+          internet = Async::HTTP::Internet.new
+          response = internet.get("#{@url}#{path}")
+          body = response.read
+          internet.close
+          JSON.parse(body)
+        end.wait
+      end
+
+      def post(path, body, content_type)
+        Async do
+          internet = Async::HTTP::Internet.new
+          response = internet.post(
+            "#{@url}#{path}",
+            [["content-type", content_type]],
+            [body],
+          )
+          result = response.read
+          internet.close
+          result
+        end.wait
+      end
+
+      def next_id
+        @id_counter = (@id_counter || 0) + 1
+      end
+  end
+end