simple_a2a 0.1.0 → 0.3.0

data/docs/index.md

@@ -1,22 +1,67 @@
 # simple_a2a
 
-A Ruby gem implementing the [Agent2Agent (A2A) protocol](https://a2a-protocol.org/latest/) — an open standard by Google and the Linux Foundation for interoperability between AI agents.
+<div class="grid" markdown>
 
-`simple_a2a` provides a complete A2A client and server in a single package, built on the async Ruby ecosystem with [Falcon](https://github.com/socketry/falcon) as the recommended HTTP server.
+<div markdown>
+
+![simple_a2a](assets/images/simple_a2a.jpg){ width="100%" }
+
+<p align="center"><em>"Anyone speak robot?"</em></p>
+
+</div>
+
+<div markdown>
+
+**A Ruby gem implementing the [Agent2Agent (A2A) protocol](https://a2a-protocol.org/latest/)**
+
+A complete A2A client and server in a single package, built on the async Ruby ecosystem with Falcon as the recommended HTTP server.
+
+- Full A2A v1.0 protocol, backward compatible with v0.3
+- JSON-RPC 2.0 over HTTP(S)
+- Server-Sent Events (SSE) streaming
+- Push notifications via webhooks (RS256 JWT)
+- Task lifecycle: `submitted → working → completed/failed/canceled`
+- AgentCard discovery at `GET /agentCard`
+- Multi-agent hosting via `A2A.multi_server`
+- `async` gem ecosystem — non-blocking I/O
+- Falcon HTTP server; any Rack-compatible server
+- In-memory storage; pluggable via `Storage::Base`
+- Roda routing, Zeitwerk autoloading
+- [:material-book-open: Full documentation](https://madbomber.github.io/simple_a2a)
+
+</div>
+
+</div>
+
+<p align="center" markdown>
+[:material-book-open: Documentation](https://madbomber.github.io/simple_a2a){ .md-button .md-button--primary }
+[:material-github: GitHub](https://github.com/MadBomber/simple_a2a){ .md-button }
+</p>
 
 ---
 
-## What is A2A?
+## MCP vs. A2A
 
-The Agent2Agent (A2A) protocol defines how AI agents running on different platforms, frameworks, and vendors can discover each other, exchange tasks, and stream results — without vendor lock-in.
+Two open protocols address different dimensions of AI agent integration — and they are designed to complement each other.
 
-- Agents expose a JSON-RPC 2.0 over HTTP endpoint
-- Clients send tasks and receive structured results
-- Streaming uses Server-Sent Events (SSE)
-- Push notifications use webhooks (RS256 JWT)
-- AgentCards describe capabilities and skills
+### MCP — Vertical Integration (Agent ↕ Environment)
 
-**Protocol Reference:** [https://a2a-protocol.org/latest/](https://a2a-protocol.org/latest/)
+The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), introduced by Anthropic in November 2024, defines how an AI agent connects to the tools, data sources, and services in its environment — file systems, databases, APIs, browsers, and code execution engines. MCP uses a client-server model where the agent is the client and each external capability is a server. This is *vertical* integration: the agent reaches downward into its local context and outward into external services through a uniform interface.
+
+### A2A — Horizontal Integration (Agent ↔ Agent)
+
+The [Agent2Agent Protocol](https://a2a-protocol.org/latest/) (A2A), introduced by Google in April 2025 and donated to the Linux Foundation for vendor-neutral governance, defines how autonomous agents running on different platforms, frameworks, and vendors can discover one another, delegate tasks, and stream results in real time. This is *horizontal* integration: peer agents — each with its own specialization, runtime, and vendor — collaborate as equals across organizational and technology boundaries.
+
+### Together
+
+MCP and A2A are complementary. A single agent can use MCP to access its tools and A2A to delegate subtasks to peer agents. `simple_a2a` implements the A2A layer.
+
+### References
+
+- Anthropic: [Introducing the Model Context Protocol](https://www.anthropic.com/news/model-context-protocol) (November 2024)
+- Google Developers Blog: [A2A: A new era of agent interoperability](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/) (April 2025)
+- Linux Foundation: [Launch of the Agent2Agent Protocol Project](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents)
+- A2A Project on GitHub: [https://github.com/a2aproject/A2A](https://github.com/a2aproject/A2A)
 
 ---
 
@@ -61,23 +106,6 @@ puts task.status.state   # => "completed"
 
 ---
 
-## Features
-
-| Feature | Details |
-|---|---|
-| Protocol | A2A v1.0, backward compatible with v0.3 |
-| Transport | JSON-RPC 2.0 over HTTP(S) |
-| Streaming | Server-Sent Events (SSE) |
-| Push notifications | Webhooks with RS256 JWT signing |
-| Task lifecycle | `submitted → working → completed/failed/canceled` |
-| Discovery | AgentCard endpoint at `GET /agentCard` |
-| Async runtime | `async` gem ecosystem — non-blocking I/O |
-| HTTP server | Falcon (recommended), any Rack-compatible server |
-| HTTP client | `async-http` (`Async::HTTP::Internet`) |
-| Storage | In-memory (thread-safe); pluggable via `Storage::Base` |
-| Routing | Roda with JSON-RPC dispatch |
-| Autoloading | Zeitwerk |
-
 ## Runnable demos
 
 The repository includes three demo applications under `examples/`:

data/examples/04_resubscribe/client.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/04_resubscribe/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/04_resubscribe/server.rb
+#
+# What this demo shows:
+#   1. Subscriber 1 starts a streaming task via tasks/sendSubscribe.
+#   2. Once the task ID is known, Subscriber 2 attaches via tasks/resubscribe.
+#   3. Subscriber 2's first event is the current Task snapshot — not an
+#      artifact or status update — proving it joined an in-flight stream.
+#   4. Both subscribers then receive the remaining events independently.
+#   5. The task completes once; both streams close cleanly.
+
+require_relative "../common_config"
+require "async"
+
+URL   = "http://localhost:9292"
+WIDTH = 42  # column width for side-by-side output
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def col(label, text, width = WIDTH)
+  prefix = "[#{label}]"
+  "#{prefix.ljust(14)} #{text.to_s.ljust(width)}"
+end
+
+def divider = puts("─" * (WIDTH * 2 + 16))
+
+def print_header
+  puts
+  puts col("subscriber-1", "tasks/sendSubscribe (new task)") +
+       col("subscriber-2", "tasks/resubscribe   (join mid-stream)")
+  divider
+end
+
+# ---------------------------------------------------------------------------
+# Agent card — confirm streaming capability
+# ---------------------------------------------------------------------------
+base = A2A.client(url: URL)
+card = base.agent_card
+
+puts "=== Agent Card ==="
+puts "  Name:        #{card.name}"
+puts "  Description: #{card.description}"
+puts "  Streaming:   #{card.capabilities&.streaming}"
+puts
+
+abort "Agent does not advertise streaming support." unless card.capabilities&.streaming
+
+# ---------------------------------------------------------------------------
+# Run both subscribers concurrently inside a single Async reactor.
+# ---------------------------------------------------------------------------
+print_header
+
+sub1_events = []
+sub2_events = []
+captured_task_id = nil
+
+Async do |reactor|
+  client1 = A2A.sse_client(url: URL)
+  client2 = A2A.sse_client(url: URL)
+
+  # Subscriber 1 — starts the task and streams from the beginning.
+  sub1_task = reactor.async do
+    client1.send_subscribe(message: A2A::Models::Message.user("analyze")) do |event|
+      sub1_events << event
+
+      case event
+      when A2A::Models::TaskStatusUpdateEvent
+        captured_task_id ||= event.task_id
+        label = event.final? ? "status (final): #{event.status.state}" : "status: #{event.status.state}"
+        puts col("subscriber-1", label)
+
+      when A2A::Models::TaskArtifactUpdateEvent
+        puts col("subscriber-1", event.artifact.parts.map(&:text).join)
+
+      when Hash
+        puts col("subscriber-1", "(error) #{event.dig('error', 'message')}")
+      end
+    end
+  end
+
+  # Wait until Subscriber 1 has seen the first event and given us the task ID.
+  loop do
+    break if captured_task_id
+    reactor.sleep(0.05)
+  end
+
+  puts col("subscriber-2", "(resubscribing to task #{captured_task_id[0, 8]}…)")
+
+  # Subscriber 2 — joins the running task.
+  # First event is the Task snapshot; remaining events are the live stream.
+  client2.resubscribe(task_id: captured_task_id) do |event|
+    sub2_events << event
+
+    case event
+    when Hash
+      # Task snapshot — the current state at the moment we subscribed.
+      state = event.dig("status", "state") || "unknown"
+      puts col("subscriber-2", "(snapshot) state=#{state}, steps so far: #{event['artifacts']&.length || 0}")
+
+    when A2A::Models::TaskStatusUpdateEvent
+      label = event.final? ? "status (final): #{event.status.state}" : "status: #{event.status.state}"
+      puts col("subscriber-2", label)
+
+    when A2A::Models::TaskArtifactUpdateEvent
+      puts col("subscriber-2", event.artifact.parts.map(&:text).join)
+    end
+  end
+
+  sub1_task.wait
+end
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+divider
+puts
+puts "=== Summary ==="
+
+snapshot = sub2_events.find { |e| e.is_a?(Hash) && e.key?("status") }
+sub2_artifacts = sub2_events.select { |e| e.is_a?(A2A::Models::TaskArtifactUpdateEvent) }
+sub1_artifacts = sub1_events.select { |e| e.is_a?(A2A::Models::TaskArtifactUpdateEvent) }
+
+puts "  Subscriber 1 — events received : #{sub1_events.length}"
+puts "  Subscriber 1 — artifact steps  : #{sub1_artifacts.length}"
+puts
+puts "  Subscriber 2 — events received : #{sub2_events.length}"
+puts "  Subscriber 2 — task snapshot   : #{snapshot ? 'yes' : 'no (unexpected)'}"
+puts "  Subscriber 2 — artifact steps  : #{sub2_artifacts.length}"
+puts "  Subscriber 2 — joined at step  : #{sub1_artifacts.length - sub2_artifacts.length + 1} of 5"
+puts
+puts "  Both streams terminated cleanly: #{
+  sub1_events.any? { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) && e.final? } &&
+  sub2_events.any? { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) && e.final? }
+}"

data/examples/04_resubscribe/server.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/04_resubscribe/server.rb
+#
+# Demonstrates tasks/resubscribe — multiple concurrent SSE subscribers
+# watching the same running task.
+
+require_relative "../common_config"
+
+# ---------------------------------------------------------------------------
+# Executor — simulates a multi-step analysis pipeline with visible pauses
+# so a second subscriber has time to attach mid-stream.
+# ---------------------------------------------------------------------------
+class AnalysisExecutor < A2A::Server::AgentExecutor
+  STEPS = [
+    "Collecting data from sources",
+    "Filtering and normalising records",
+    "Running statistical analysis",
+    "Detecting anomalies",
+    "Generating final report"
+  ].freeze
+
+  STEP_DELAY = 1.2  # seconds between steps — wide enough for client to resubscribe
+
+  def call(ctx)
+    ctx.task.start!
+    ctx.emit_status
+
+    STEPS.each_with_index do |description, i|
+      sleep STEP_DELAY
+
+      artifact = A2A::Models::Artifact.new(
+        index:      i,
+        parts:      [A2A::Models::Part.text("Step #{i + 1}/#{STEPS.length}: #{description}")],
+        last_chunk: true
+      )
+      ctx.emit_artifact(artifact, last_chunk: true)
+    end
+
+    ctx.task.complete!
+    ctx.emit_status(final: true)
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Agent card
+# ---------------------------------------------------------------------------
+card = A2A::Models::AgentCard.new(
+  name:         "AnalysisAgent",
+  version:      "1.0",
+  description:  "Multi-step analysis pipeline — demonstrates tasks/resubscribe",
+  capabilities: A2A::Models::AgentCapabilities.new(streaming: true),
+  skills: [
+    A2A::Models::AgentSkill.new(
+      name:        "analyze",
+      description: "Runs a five-step analysis and streams each step as it completes"
+    )
+  ],
+  interfaces: [
+    A2A::Models::AgentInterface.new(
+      type:    "json-rpc",
+      url:     "http://localhost:9292",
+      version: "1.0"
+    )
+  ]
+)
+
+total = AnalysisExecutor::STEPS.length * AnalysisExecutor::STEP_DELAY
+puts "Starting AnalysisAgent on http://localhost:9292"
+puts "Task runs #{AnalysisExecutor::STEPS.length} steps × #{AnalysisExecutor::STEP_DELAY}s = ~#{total.round(0).to_i}s per run"
+puts "Press Ctrl-C to stop."
+puts
+
+A2A.server(agent_card: card, executor: AnalysisExecutor.new).run

data/examples/05_cancellation/client.rb

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/05_cancellation/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/05_cancellation/server.rb
+#
+# What this demo shows:
+#   1. Three tasks (A, B, C) are started via tasks/sendSubscribe so each
+#      runs asynchronously inside Falcon's reactor.
+#   2. After 3 seconds — while all tasks are still mid-flight — task B is
+#      cancelled via tasks/cancel.
+#   3. Task B's SSE stream receives a final canceled status event and closes.
+#   4. Tasks A and C run to completion, unaffected.
+#   5. Final states: A=completed, B=canceled, C=completed.
+
+require_relative "../common_config"
+
+URL        = "http://localhost:9292"
+CANCEL_SEC = 3   # seconds before we cancel task B
+
+def divider = puts("─" * 60)
+
+def col(label, text)
+  "[task #{label}] #{text}"
+end
+
+# ---------------------------------------------------------------------------
+# Confirm the server is up and supports streaming
+# ---------------------------------------------------------------------------
+card = A2A.client(url: URL).agent_card
+
+puts
+puts "=== Agent Card ==="
+puts "  Name:         #{card.name}"
+puts "  Description:  #{card.description}"
+puts "  Streaming:    #{card.capabilities&.streaming}"
+puts
+abort "Agent does not advertise streaming support." unless card.capabilities&.streaming
+divider
+
+# ---------------------------------------------------------------------------
+# Start three streaming tasks in parallel threads.
+# Each thread drives its own SSE loop and records every event it receives.
+# A shared, mutex-protected hash lets the main thread see task IDs as soon
+# as the first status event arrives from each task.
+# ---------------------------------------------------------------------------
+puts
+puts "Starting tasks A, B, and C via tasks/sendSubscribe…"
+puts "(each would take 10 s; task B will be cancelled after #{CANCEL_SEC}s)"
+puts
+
+task_ids  = {}
+id_mutex  = Mutex.new
+all_events = { "A" => [], "B" => [], "C" => [] }
+
+threads = %w[A B C].map do |label|
+  Thread.new do
+    A2A.sse_client(url: URL).send_subscribe(
+      message: A2A::Models::Message.user("task #{label}")
+    ) do |event|
+      case event
+      when A2A::Models::TaskStatusUpdateEvent
+        id_mutex.synchronize { task_ids[label] ||= event.task_id }
+        all_events[label] << event
+        state = event.status.state
+        msg   = event.status.message ? " (#{event.status.message})" : ""
+        puts col(label, "status=#{state}#{msg}")
+
+      when A2A::Models::TaskArtifactUpdateEvent
+        all_events[label] << event
+
+      when Hash
+        puts col(label, "error: #{event.dig('error', 'message')}")
+      end
+    end
+  rescue => e
+    puts col(label, "stream error: #{e.message}")
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Wait until task B has checked in (first status event), then cancel it.
+# ---------------------------------------------------------------------------
+loop do
+  sleep 0.1
+  break if id_mutex.synchronize { task_ids["B"] }
+end
+
+puts
+puts "Task B is running — waiting #{CANCEL_SEC}s then cancelling…"
+sleep CANCEL_SEC
+
+task_b_id = id_mutex.synchronize { task_ids["B"] }
+puts
+begin
+  cancelled = A2A.client(url: URL).cancel_task(task_b_id)
+  puts col("B", "cancel sent → state=#{cancelled.status.state}")
+rescue A2A::Error => e
+  puts col("B", "cancel failed: #{e.message}")
+end
+puts
+
+# ---------------------------------------------------------------------------
+# Wait for all three SSE streams to close.
+# ---------------------------------------------------------------------------
+threads.each(&:join)
+
+# ---------------------------------------------------------------------------
+# Final summary
+# ---------------------------------------------------------------------------
+divider
+puts
+puts "=== Final States ==="
+
+%w[A B C].each do |label|
+  events  = all_events[label]
+  last_st = events.select { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) }.last
+  artifact = events.select { |e| e.is_a?(A2A::Models::TaskArtifactUpdateEvent) }
+              .last&.artifact&.parts&.first&.text
+
+  state = last_st&.status&.state || "unknown"
+  line  = "state=#{state.ljust(10)}  events received=#{events.length}"
+  line += "  result: #{artifact}"       if artifact
+  line += "  ← cancelled mid-flight"   if state == "canceled"
+  puts col(label, line)
+end
+
+puts
+
+# ---------------------------------------------------------------------------
+# Assertions
+# ---------------------------------------------------------------------------
+puts "=== Verification ==="
+
+def final_state(events)
+  events.select { |e| e.is_a?(A2A::Models::TaskStatusUpdateEvent) }
+        .last&.status&.state
+end
+
+a_ok = final_state(all_events["A"]) == "completed"
+b_ok = final_state(all_events["B"]) == "canceled"
+c_ok = final_state(all_events["C"]) == "completed"
+
+puts "  Task A completed normally : #{a_ok ? 'PASS' : 'FAIL'}"
+puts "  Task B was cancelled      : #{b_ok ? 'PASS' : 'FAIL'}"
+puts "  Task C completed normally : #{c_ok ? 'PASS' : 'FAIL'}"
+puts
+puts(a_ok && b_ok && c_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/05_cancellation/server.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/05_cancellation/server.rb
+#
+# Hosts a single agent whose tasks take ~10 seconds to complete,
+# giving the client time to cancel individual tasks while others
+# keep running.
+
+require_relative "../common_config"
+
+# ---------------------------------------------------------------------------
+# Executor — simulates a slow 10-step pipeline (1 s per step).
+# Emits a status event after each step so the SSE stream shows progress.
+# Checks ctx.task.terminal? between steps so a cancel takes effect promptly.
+# ---------------------------------------------------------------------------
+class SlowExecutor < A2A::Server::AgentExecutor
+  STEPS    = 10
+  STEP_SEC = 1.0
+
+  def call(ctx)
+    ctx.task.start!
+    ctx.emit_status
+
+    STEPS.times do |i|
+      return if ctx.task.terminal?
+      sleep STEP_SEC
+      return if ctx.task.terminal?
+
+      ctx.task.status = A2A::Models::TaskStatus.new(
+        state:   A2A::Models::Types::TaskState::WORKING,
+        message: "Step #{i + 1}/#{STEPS} complete"
+      )
+      ctx.emit_status
+    end
+
+    return if ctx.task.terminal?
+
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "result",
+        parts: [A2A::Models::Part.text("All #{STEPS} steps finished for task #{ctx.task.id[0, 8]}")]
+      )
+    ])
+    ctx.emit_status(final: true)
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Agent card
+# ---------------------------------------------------------------------------
+card = A2A::Models::AgentCard.new(
+  name:         "SlowAgent",
+  version:      "1.0",
+  description:  "A slow 10-step agent — demonstrates mid-flight task cancellation",
+  capabilities: A2A::Models::AgentCapabilities.new(streaming: true),
+  skills: [
+    A2A::Models::AgentSkill.new(
+      name:        "slow_task",
+      description: "Runs 10 steps at 1 s each; can be cancelled at any point"
+    )
+  ],
+  interfaces: [
+    A2A::Models::AgentInterface.new(
+      type:    "json-rpc",
+      url:     "http://localhost:9292",
+      version: "1.0"
+    )
+  ]
+)
+
+puts "Starting SlowAgent on http://localhost:9292"
+puts "Each task takes #{SlowExecutor::STEPS * SlowExecutor::STEP_SEC}s to complete without cancellation."
+puts "Press Ctrl-C to stop."
+puts
+
+A2A.server(agent_card: card, executor: SlowExecutor.new).run