simple_a2a 0.1.0 → 0.3.0

data/examples/06_push_notifications/client.rb

@@ -0,0 +1,192 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/06_push_notifications/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/06_push_notifications/server.rb
+#
+# What this demo shows:
+#   1. A local webhook receiver starts on port 9293 to capture push deliveries.
+#   2. A task is submitted via tasks/sendSubscribe to get its ID immediately.
+#   3. The client registers a webhook URL via tasks/pushNotification/set.
+#   4. The server delivers an HTTP POST to the webhook after each step — no
+#      open SSE connection required for the client to receive updates.
+#   5. tasks/pushNotification/get and list confirm the config is stored.
+#   6. tasks/pushNotification/delete removes the config; list confirms it gone.
+
+require_relative "../common_config"
+require "webrick"
+require "json"
+
+A2A_URL      = "http://localhost:9292"
+WEBHOOK_PORT = 9293
+WEBHOOK_URL  = "http://localhost:#{WEBHOOK_PORT}/webhook"
+
+def divider = puts("─" * 60)
+
+# ---------------------------------------------------------------------------
+# Webhook receiver — a minimal WEBrick server that captures every incoming
+# POST and forwards the parsed payload to a Queue for the main thread.
+# ---------------------------------------------------------------------------
+webhook_queue  = Queue.new
+webhook_server = WEBrick::HTTPServer.new(
+  Port:      WEBHOOK_PORT,
+  Logger:    WEBrick::Log.new(File::NULL),
+  AccessLog: []
+)
+webhook_server.mount_proc "/webhook" do |req, res|
+  payload = JSON.parse(req.body) rescue { "raw" => req.body }
+  webhook_queue << payload
+  res.status = 200
+  res.body   = "ok"
+end
+webhook_thread = Thread.new { webhook_server.start }
+at_exit { webhook_server.shutdown }
+
+puts
+puts "=== Webhook receiver listening on #{WEBHOOK_URL} ==="
+puts
+
+# ---------------------------------------------------------------------------
+# Confirm the server is up and supports push notifications
+# ---------------------------------------------------------------------------
+base_client = A2A.client(url: A2A_URL)
+card        = base_client.agent_card
+
+puts "=== Agent Card ==="
+puts "  Name:               #{card.name}"
+puts "  Description:        #{card.description}"
+puts "  push_notifications: #{card.capabilities&.push_notifications}"
+puts "  streaming:          #{card.capabilities&.streaming}"
+puts
+abort "Agent does not advertise push notification support." unless card.capabilities&.push_notifications
+divider
+
+# ---------------------------------------------------------------------------
+# Submit the task via sendSubscribe so it starts asynchronously.
+# We only need the task ID from the first event; the SSE thread then drains
+# silently in the background while we watch the webhook instead.
+# ---------------------------------------------------------------------------
+puts
+puts "Submitting task via tasks/sendSubscribe…"
+
+task_id     = nil
+id_mutex    = Mutex.new
+sse_thread  = Thread.new do
+  A2A.sse_client(url: A2A_URL).send_subscribe(
+    message: A2A::Models::Message.user("run push demo")
+  ) do |event|
+    case event
+    when A2A::Models::TaskStatusUpdateEvent
+      id_mutex.synchronize { task_id ||= event.task_id }
+    end
+  end
+rescue => e
+  puts "  SSE error: #{e.message}"
+end
+
+# Wait until we have the task ID (arrives with the first working event).
+loop do
+  sleep 0.05
+  break if id_mutex.synchronize { task_id }
+end
+
+puts "  Task started: id=#{task_id[0, 8]}"
+puts
+
+# ---------------------------------------------------------------------------
+# Register the webhook via tasks/pushNotification/set
+# ---------------------------------------------------------------------------
+puts "Registering webhook via tasks/pushNotification/set…"
+base_client.send(:rpc_call, "tasks/pushNotification/set", {
+  "id"                   => task_id,
+  "pushNotificationConfig" => { "webhookUrl" => WEBHOOK_URL }
+})
+puts "  Webhook registered: #{WEBHOOK_URL}"
+puts
+
+# ---------------------------------------------------------------------------
+# Confirm storage via tasks/pushNotification/get and list
+# ---------------------------------------------------------------------------
+get_result  = base_client.send(:rpc_call, "tasks/pushNotification/get",  { "id" => task_id })
+list_result = base_client.send(:rpc_call, "tasks/pushNotification/list", {})
+
+puts "tasks/pushNotification/get  → webhookUrl=#{get_result&.dig("pushNotificationConfig", "webhookUrl")}"
+puts "tasks/pushNotification/list → #{list_result.length} config(s) registered"
+divider
+
+# ---------------------------------------------------------------------------
+# Watch push deliveries arrive from the server.
+# The server posts after each step; we print each payload as it lands.
+# Stop when we see a final=true delivery.
+# ---------------------------------------------------------------------------
+puts
+puts "Watching webhook for incoming push notifications…"
+puts "(the client has NO open SSE connection — all updates arrive out-of-band)"
+puts
+
+received = []
+loop do
+  payload = webhook_queue.pop
+  received << payload
+
+  status  = payload.dig("status", "state") || "unknown"
+  message = payload.dig("status", "message")
+  final   = payload["final"]
+
+  line = "  push received → state=#{status}"
+  line += " (#{message})" if message
+  line += "  [FINAL]"     if final
+  puts line
+
+  break if final
+end
+
+puts
+divider
+
+# ---------------------------------------------------------------------------
+# Delete the push config and confirm it is gone
+# ---------------------------------------------------------------------------
+puts
+puts "Calling tasks/pushNotification/delete…"
+base_client.send(:rpc_call, "tasks/pushNotification/delete", { "id" => task_id })
+
+list_after = base_client.send(:rpc_call, "tasks/pushNotification/list", {})
+puts "tasks/pushNotification/list → #{list_after.length} config(s) remaining"
+puts
+
+# Wait for the SSE thread to close naturally now that the task is complete.
+sse_thread.join(5)
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+divider
+puts
+puts "=== Summary ==="
+puts "  Push notifications received : #{received.length}"
+puts "  States delivered            : #{received.map { |p| p.dig("status", "state") }.join(" → ")}"
+puts "  Final delivery seen         : #{received.any? { |p| p["final"] } ? 'yes' : 'no'}"
+puts "  Config cleaned up           : #{list_after.empty? ? 'yes' : 'no'}"
+puts
+
+# ---------------------------------------------------------------------------
+# Verification
+# ---------------------------------------------------------------------------
+puts "=== Verification ==="
+states     = received.map { |p| p.dig("status", "state") }
+last_state = states.last
+
+push_ok    = received.length >= 2
+final_ok   = received.last&.fetch("final", false)
+state_ok   = last_state == "completed"
+cleanup_ok = list_after.empty?
+
+puts "  Push notifications received (≥2) : #{push_ok    ? 'PASS' : 'FAIL'}"
+puts "  Final push delivery seen         : #{final_ok   ? 'PASS' : 'FAIL'}"
+puts "  Final state is completed         : #{state_ok   ? 'PASS' : 'FAIL'}"
+puts "  Config deleted successfully      : #{cleanup_ok ? 'PASS' : 'FAIL'}"
+puts
+puts(push_ok && final_ok && state_ok && cleanup_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/06_push_notifications/server.rb

@@ -0,0 +1,123 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/06_push_notifications/server.rb
+#
+# Demonstrates push notifications: the server delivers out-of-band HTTP POST
+# payloads to a client-registered webhook URL as a task progresses, without
+# the client needing to hold an open SSE connection.
+#
+# The executor holds shared references to the push_sender and push_config_store
+# so it can deliver after each state change. The same push_config_store is
+# passed to Server::Base so the App's pushNotification/* RPC methods read and
+# write the same store.
+
+require_relative "../common_config"
+
+# ---------------------------------------------------------------------------
+# Executor — 5-step pipeline; delivers a push notification after each step.
+# ---------------------------------------------------------------------------
+class PushExecutor < A2A::Server::AgentExecutor
+  STEPS    = 5
+  STEP_SEC = 2.0
+
+  def initialize(push_sender:, push_config_store:)
+    @push_sender       = push_sender
+    @push_config_store = push_config_store
+  end
+
+  def call(ctx)
+    ctx.task.start!
+    ctx.emit_status
+    push_status(ctx)
+
+    STEPS.times do |i|
+      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
+      push_status(ctx)
+    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)
+    push_status(ctx, final: true)
+  end
+
+  private
+
+  def push_status(ctx, final: false)
+    config = @push_config_store.get(ctx.task.id)
+    return unless config
+
+    event = A2A::Models::TaskStatusUpdateEvent.new(
+      task_id:    ctx.task.id,
+      context_id: ctx.task.context_id,
+      status:     ctx.task.status,
+      final:      final
+    )
+    @push_sender.deliver(config, event)
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Shared push infrastructure — the executor and the App both reference these
+# so that RPC-registered configs are visible to the executor at delivery time.
+# ---------------------------------------------------------------------------
+push_config_store = A2A::Server::PushConfigStore.new
+push_sender       = A2A::Server::PushSender.new
+executor          = PushExecutor.new(
+  push_sender:       push_sender,
+  push_config_store: push_config_store
+)
+
+# ---------------------------------------------------------------------------
+# Agent card — push_notifications: true is required for the RPC methods
+# to be accepted by the server.
+# ---------------------------------------------------------------------------
+card = A2A::Models::AgentCard.new(
+  name:         "PushAgent",
+  version:      "1.0",
+  description:  "Demonstrates out-of-band push notification delivery",
+  capabilities: A2A::Models::AgentCapabilities.new(
+    streaming:          true,
+    push_notifications: true
+  ),
+  skills: [
+    A2A::Models::AgentSkill.new(
+      name:        "push_demo",
+      description: "Runs a 5-step task and pushes a status update after each step"
+    )
+  ],
+  interfaces: [
+    A2A::Models::AgentInterface.new(
+      type:    "json-rpc",
+      url:     "http://localhost:9292",
+      version: "1.0"
+    )
+  ]
+)
+
+puts "Starting PushAgent on http://localhost:9292"
+puts "  push_notifications: true"
+puts "  #{PushExecutor::STEPS} steps × #{PushExecutor::STEP_SEC}s = ~#{(PushExecutor::STEPS * PushExecutor::STEP_SEC).to_i}s per task"
+puts "Press Ctrl-C to stop."
+puts
+
+A2A.server(
+  agent_card:        card,
+  executor:          executor,
+  push_sender:       push_sender,
+  push_config_store: push_config_store
+).run

data/examples/07_agent_chaining/client.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/07_agent_chaining/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/07_agent_chaining/server.rb
+#
+# What this demo shows:
+#   1. Three agents are discoverable via their individual agent cards.
+#   2. The client calls only /pipeline — it has no knowledge of the other agents.
+#   3. PipelineAgent internally calls /reverse then /shout via A2A.client,
+#      demonstrating agent-to-agent chaining over the A2A protocol.
+#   4. The result exposes all three stages so the chain is visible.
+#   5. The sub-agents are also called directly to confirm they work standalone.
+
+require_relative "../common_config"
+
+BASE_URL     = "http://localhost:9292"
+REVERSE_URL  = "#{BASE_URL}/reverse"
+SHOUT_URL    = "#{BASE_URL}/shout"
+PIPELINE_URL = "#{BASE_URL}/pipeline"
+
+def divider = puts("─" * 60)
+
+def artifact_text(task)
+  task.artifacts&.first&.parts&.first&.text || "(no artifact)"
+end
+
+# ---------------------------------------------------------------------------
+# Discover all three agents
+# ---------------------------------------------------------------------------
+puts
+puts "=== Agent Discovery ==="
+[
+  ["ReverseAgent",  REVERSE_URL],
+  ["ShoutAgent",    SHOUT_URL],
+  ["PipelineAgent", PIPELINE_URL]
+].each do |expected_name, url|
+  card = A2A.client(url: url).agent_card
+  puts "  #{url.ljust(32)} → #{card.name}: #{card.description}"
+end
+puts
+divider
+
+# ---------------------------------------------------------------------------
+# Call the pipeline with several inputs — client speaks only to /pipeline
+# ---------------------------------------------------------------------------
+pipeline = A2A.client(url: PIPELINE_URL)
+
+inputs = [
+  "the quick brown fox jumps over the lazy dog",
+  "agent to agent communication is the future",
+  "simple is better than complex"
+]
+
+puts
+puts "=== Pipeline calls (client speaks only to /pipeline) ==="
+puts
+
+results = inputs.map do |text|
+  task   = pipeline.send_task(message: A2A::Models::Message.user(text))
+  output = artifact_text(task)
+  puts "Input:  #{text}"
+  puts output.lines.map { |l| "  #{l}" }.join
+  puts
+  { input: text, output: output, state: task.status.state }
+end
+
+divider
+
+# ---------------------------------------------------------------------------
+# Call sub-agents directly to show they work standalone
+# ---------------------------------------------------------------------------
+puts
+puts "=== Sub-agents called directly (verification) ==="
+puts
+
+sample = "hello world from A2A"
+
+reverse_task = A2A.client(url: REVERSE_URL).send_task(
+  message: A2A::Models::Message.user(sample)
+)
+shout_task = A2A.client(url: SHOUT_URL).send_task(
+  message: A2A::Models::Message.user(sample)
+)
+
+puts "  Input:                  #{sample}"
+puts "  /reverse result:        #{artifact_text(reverse_task)}"
+puts "  /shout   result:        #{artifact_text(shout_task)}"
+puts
+
+divider
+
+# ---------------------------------------------------------------------------
+# Verification
+# ---------------------------------------------------------------------------
+puts
+puts "=== Verification ==="
+
+all_completed = results.all? { |r| r[:state] == "completed" }
+
+pipeline_correct = results.all? do |r|
+  words    = r[:input].split
+  reversed = words.reverse.join(" ")
+  shouted  = reversed.upcase
+  r[:output].include?(shouted)
+end
+
+standalone_reverse_ok = artifact_text(reverse_task) == sample.split.reverse.join(" ")
+standalone_shout_ok   = artifact_text(shout_task)   == sample.upcase
+
+puts "  All pipeline tasks completed       : #{all_completed          ? 'PASS' : 'FAIL'}"
+puts "  Pipeline output matches chain      : #{pipeline_correct       ? 'PASS' : 'FAIL'}"
+puts "  ReverseAgent standalone correct    : #{standalone_reverse_ok  ? 'PASS' : 'FAIL'}"
+puts "  ShoutAgent standalone correct      : #{standalone_shout_ok    ? 'PASS' : 'FAIL'}"
+puts
+
+all_ok = all_completed && pipeline_correct && standalone_reverse_ok && standalone_shout_ok
+puts(all_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/07_agent_chaining/server.rb

@@ -0,0 +1,150 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/07_agent_chaining/server.rb
+#
+# Three agents on one port via A2A.multi_server:
+#
+#   /reverse   — reverses the word order of the input text
+#   /shout     — uppercases the input text
+#   /pipeline  — calls /reverse then /shout and returns all three stages
+#
+# The client only ever speaks to /pipeline. The chaining between agents
+# happens entirely inside PipelineExecutor using A2A.client — the same
+# client interface any external caller would use.
+
+require_relative "../common_config"
+
+BASE_URL = "http://localhost:9292"
+
+# ---------------------------------------------------------------------------
+# ReverseExecutor — reverses the word order of the input.
+# ---------------------------------------------------------------------------
+class ReverseExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    input    = ctx.message.text_content.strip
+    reversed = input.split.reverse.join(" ")
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "reversed",
+        parts: [A2A::Models::Part.text(reversed)]
+      )
+    ])
+  end
+end
+
+# ---------------------------------------------------------------------------
+# ShoutExecutor — uppercases the input.
+# ---------------------------------------------------------------------------
+class ShoutExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    input  = ctx.message.text_content.strip
+    shouted = input.upcase
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "shouted",
+        parts: [A2A::Models::Part.text(shouted)]
+      )
+    ])
+  end
+end
+
+# ---------------------------------------------------------------------------
+# PipelineExecutor — orchestrates the other two agents via A2A.client,
+# then composes a result showing every stage.
+# ---------------------------------------------------------------------------
+class PipelineExecutor < A2A::Server::AgentExecutor
+  def initialize(base_url:)
+    @reverse_client = A2A.client(url: "#{base_url}/reverse")
+    @shout_client   = A2A.client(url: "#{base_url}/shout")
+  end
+
+  def call(ctx)
+    input = ctx.message.text_content.strip
+
+    # Stage 1: call the ReverseAgent
+    reversed = @reverse_client
+      .send_task(message: A2A::Models::Message.user(input))
+      .artifacts.first&.parts&.first&.text || input
+
+    # Stage 2: feed the reversed text to the ShoutAgent
+    shouted = @shout_client
+      .send_task(message: A2A::Models::Message.user(reversed))
+      .artifacts.first&.parts&.first&.text || reversed
+
+    result = <<~RESULT.strip
+      Input:    #{input}
+      Reversed: #{reversed}
+      Shouted:  #{shouted}
+    RESULT
+
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "pipeline_result",
+        parts: [A2A::Models::Part.text(result)]
+      )
+    ])
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Agent cards
+# ---------------------------------------------------------------------------
+def make_card(name:, description:, skill:, path:)
+  A2A::Models::AgentCard.new(
+    name:         name,
+    version:      "1.0",
+    description:  description,
+    capabilities: A2A::Models::AgentCapabilities.new,
+    skills: [
+      A2A::Models::AgentSkill.new(name: skill, description: description)
+    ],
+    interfaces: [
+      A2A::Models::AgentInterface.new(
+        type:    "json-rpc",
+        url:     "#{BASE_URL}#{path}",
+        version: "1.0"
+      )
+    ]
+  )
+end
+
+reverse_card  = make_card(
+  name:        "ReverseAgent",
+  description: "Reverses the word order of input text",
+  skill:       "reverse",
+  path:        "/reverse"
+)
+
+shout_card = make_card(
+  name:        "ShoutAgent",
+  description: "Uppercases input text",
+  skill:       "shout",
+  path:        "/shout"
+)
+
+pipeline_card = make_card(
+  name:        "PipelineAgent",
+  description: "Chains ReverseAgent then ShoutAgent and returns all three stages",
+  skill:       "pipeline",
+  path:        "/pipeline"
+)
+
+# ---------------------------------------------------------------------------
+# Start the multi-agent server
+# ---------------------------------------------------------------------------
+puts "Starting multi-agent server on #{BASE_URL}"
+puts "  /reverse   → ReverseAgent"
+puts "  /shout     → ShoutAgent"
+puts "  /pipeline  → PipelineAgent (chains the other two)"
+puts "Press Ctrl-C to stop."
+puts
+
+A2A.multi_server(
+  agents: {
+    "/reverse"  => { agent_card: reverse_card,  executor: ReverseExecutor.new },
+    "/shout"    => { agent_card: shout_card,     executor: ShoutExecutor.new },
+    "/pipeline" => { agent_card: pipeline_card,  executor: PipelineExecutor.new(base_url: BASE_URL) }
+  },
+  port: 9292
+).run