simple_a2a 0.1.0

data/lib/simple_a2a/server/multi_agent.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rack"
+
+module A2A
+  module Server
+    # Hosts multiple A2A agents on a single server, each at its own URL path.
+    #
+    # Usage:
+    #   A2A.multi_server(
+    #     agents: {
+    #       "/anthropic" => { agent_card: card1, executor: exec1 },
+    #       "/openai"    => { agent_card: card2, executor: exec2 }
+    #     },
+    #     port: 9292
+    #   ).run
+    class MultiAgent
+      def initialize(agents:, host: "localhost", port: 9292)
+        @agents = agents
+        @host   = host
+        @port   = port
+      end
+
+      def run
+        FalconRunner.new(rack_app, host: @host, port: @port).run
+      end
+
+      private
+
+      def rack_app
+        url_map = @agents.transform_values { |cfg| build_app(cfg) }
+        Rack::URLMap.new(url_map)
+      end
+
+      # Each agent needs its own App subclass so class-level configure state
+      # doesn't bleed between agents.
+      def build_app(cfg)
+        klass = Class.new(App)
+        klass.configure(
+          agent_card:   cfg[:agent_card],
+          storage:      cfg[:storage]      || Storage::Memory.new,
+          executor:     cfg[:executor],
+          event_router: cfg[:event_router] || EventRouter.new,
+          push_sender:  cfg[:push_sender]
+        )
+        klass.freeze.app
+      end
+    end
+  end
+end

data/lib/simple_a2a/server/push_sender.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "jwt"
+require "net/http"
+require "uri"
+
+module A2A
+  module Server
+    class PushSender
+      SUPPORTED_SCHEMES = %w[bearer token].freeze
+
+      def initialize(private_key: nil, key_id: nil, issuer: "simple_a2a")
+        @private_key = private_key
+        @key_id      = key_id
+        @issuer      = issuer
+      end
+
+      def deliver(config, event)
+        return unless config.is_a?(Models::PushNotificationConfig)
+        return unless config.valid?
+
+        payload = build_payload(event)
+        headers = build_headers(config, payload)
+        post(config.webhook_url, payload, headers)
+      rescue StandardError => e
+        A2A.logger&.warn("PushSender: delivery failed to #{config&.webhook_url} — #{e.class}: #{e.message}")
+        false
+      end
+
+      private
+
+      def build_payload(event)
+        JSON.generate(event.to_h)
+      end
+
+      def build_headers(config, payload)
+        headers = { "Content-Type" => "application/json" }
+        auth = config.authentication_info
+        return headers unless auth
+
+        case auth.scheme.to_s.downcase
+        when "bearer"
+          token = jwt_token(payload)
+          headers[auth.header_name || "Authorization"] = "Bearer #{token}"
+        when "token"
+          headers[auth.header_name || "Authorization"] = "Token #{auth.value}"
+        else
+          headers[auth.header_name || "Authorization"] = auth.value
+        end
+
+        headers
+      end
+
+      def jwt_token(payload)
+        return "no-key" unless @private_key
+
+        claims = {
+          iss: @issuer,
+          iat: Time.now.to_i,
+          exp: Time.now.to_i + 300,
+          payload_hash: Digest::SHA256.hexdigest(payload)
+        }
+        JWT.encode(claims, @private_key, "RS256", { kid: @key_id }.compact)
+      end
+
+      def post(url, body, headers)
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 5
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(uri.request_uri, headers)
+        request.body = body
+        response = http.request(request)
+        response.code.to_i < 300
+      end
+    end
+  end
+end

data/lib/simple_a2a/server/resume_context.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module A2A
+  module Server
+    class ResumeContext < Context
+      attr_reader :resume_message
+
+      def initialize(resume_message:, **kwargs)
+        super(**kwargs)
+        @resume_message = resume_message
+      end
+    end
+  end
+end

data/lib/simple_a2a/storage/base.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module A2A
+  module Storage
+    class Base
+      def save(task)    = raise NotImplementedError, "#{self.class}#save"
+      def find(id)      = raise NotImplementedError, "#{self.class}#find"
+      def delete(id)    = raise NotImplementedError, "#{self.class}#delete"
+      def list          = raise NotImplementedError, "#{self.class}#list"
+    end
+  end
+end

data/lib/simple_a2a/storage/memory.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module A2A
+  module Storage
+    class Memory < Base
+      def initialize
+        @store = {}
+        @mutex = Mutex.new
+      end
+
+      def save(task)
+        @mutex.synchronize { @store[task.id] = task }
+        task
+      end
+
+      def find(id)
+        @mutex.synchronize { @store[id] }
+      end
+
+      def find!(id)
+        find(id) or raise TaskNotFoundError, "Task #{id} not found"
+      end
+
+      def delete(id)
+        @mutex.synchronize { @store.delete(id) }
+      end
+
+      def list
+        @mutex.synchronize { @store.values.dup }
+      end
+
+      def size
+        @mutex.synchronize { @store.size }
+      end
+
+      def clear
+        @mutex.synchronize { @store.clear }
+      end
+    end
+  end
+end

data/lib/simple_a2a/version.rb

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

data/lib/simple_a2a.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "json"
+require "securerandom"
+require "time"
+require "uri"
+require "base64"
+
+module A2A
+  class << self
+    attr_accessor :logger
+
+    def server(**opts)
+      Server::Base.new(**opts)
+    end
+
+    def multi_server(**opts)
+      Server::MultiAgent.new(**opts)
+    end
+
+    def client(**opts)
+      Client::Base.new(**opts)
+    end
+
+    def sse_client(**opts)
+      Client::SSE.new(**opts)
+    end
+  end
+end
+
+# Require files that don't follow Zeitwerk naming conventions first
+require_relative "simple_a2a/version"
+require_relative "simple_a2a/errors"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "simple_a2a" => "A2A",
+  "sse"        => "SSE"
+)
+loader.ignore(
+  "#{__dir__}/simple_a2a/version.rb",
+  "#{__dir__}/simple_a2a/errors.rb",
+  "#{__dir__}/simple_a2a/json_rpc.rb"
+)
+loader.setup
+
+# json_rpc.rb depends on error classes; load after errors + loader setup
+require_relative "simple_a2a/json_rpc"

data/mkdocs.yml

@@ -0,0 +1,143 @@
+site_name: simple_a2a
+site_description: Ruby gem implementing the Agent2Agent (A2A) protocol
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/simple_a2a
+copyright: Copyright © 2026 Dewayne VanHoozer
+
+repo_name: MadBomber/simple_a2a
+repo_url: https://github.com/MadBomber/simple_a2a
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+
+  palette:
+    - scheme: default
+      primary: blue
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: blue
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/connection
+
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - tags
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: MadBomber
+      repo: simple_a2a
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+extra_css:
+  - assets/css/custom.css
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/MadBomber/simple_a2a
+      name: simple_a2a on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/simple_a2a
+      name: simple_a2a on RubyGems
+    - icon: fontawesome/solid/book
+      link: https://a2a-protocol.org/latest/
+      name: A2A Protocol Specification
+
+nav:
+  - Home: index.md
+  - Getting Started:
+      - Installation: getting-started/installation.md
+      - Quick Start: getting-started/quick-start.md
+  - Architecture:
+      - Overview: architecture/index.md
+      - Protocol Details: architecture/protocol.md
+  - API Reference:
+      - Overview: api/index.md
+      - Models: api/models/index.md
+      - Server: api/server/index.md
+      - Client: api/client/index.md
+      - Storage: api/storage/index.md
+  - Guides:
+      - Streaming Responses: guides/streaming.md
+      - Push Notifications: guides/push-notifications.md
+      - Custom Storage: guides/custom-storage.md
+  - Examples:
+      - Overview: examples/index.md
+      - Basic Usage: examples/basic-usage.md
+      - Streaming: examples/streaming.md
+      - Multi-Agent LLM Research: examples/llm-research.md

data/sig/simple_a2a.rbs

@@ -0,0 +1,4 @@
+module SimpleA2a
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end