robot_lab-a2a 0.1.0

data/examples/04_io_bridge/client.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/04_io_bridge/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/04_io_bridge/server.rb
+#
+# Or run both together:
+#   bundle exec ruby examples/run 04_io_bridge
+#
+# What this demo shows:
+#
+#   Turn 1 — client sends a topic ('stoicism').
+#             QuoteRobot writes the prompt to @output (buffered by IoBridge)
+#             then calls @input.gets. IoBridge flushes the buffer as the
+#             input_required message and blocks. The A2A task enters the
+#             input_required state with the prompt as its status message.
+#
+#   Turn 2 — client sends a follow-up with task_id: pointing at the same task.
+#             IoBridge pushes the answer to the robot thread, unblocking gets.
+#             The robot completes and the task reaches the "completed" state.
+#
+# Note: Turn 2 requires simple_a2a >= 0.3.1 to route the follow-up to the
+# waiting robot thread via a ResumeContext. With earlier versions Turn 1 still
+# demonstrates the input_required suspension.
+
+require_relative '../common_config'
+
+URL = 'http://localhost:9292/quote-robot'
+
+client = A2A.client(url: URL)
+
+def divider = puts('─' * 60)
+
+# ---------------------------------------------------------------------------
+# Discover the agent
+# ---------------------------------------------------------------------------
+puts
+puts '=== Agent Card ==='
+card = client.agent_card
+puts <<~HEREDOC
+    Name:        #{card.name}
+    Description: #{card.description}
+
+HEREDOC
+
+divider
+
+# ---------------------------------------------------------------------------
+# Turn 1 — initial request; expect input_required
+# ---------------------------------------------------------------------------
+puts <<~HEREDOC
+
+  === Turn 1: Initial request ===
+    Sending topic: 'stoicism'
+
+HEREDOC
+
+task1 = client.send_task(message: A2A::Models::Message.user('stoicism'))
+
+state1  = task1.status.state
+prompt  = task1.status.message&.parts&.first&.text
+
+puts "  Task ID: #{task1.id}"
+puts "  State:   #{state1}"
+puts "  Prompt:  #{prompt}" if prompt
+puts
+
+if state1 != 'input_required'
+  puts "Expected input_required — got #{state1.inspect}."
+  puts 'Check that the server is running with interactive: :io_bridge.'
+  exit 1
+end
+
+divider
+
+# ---------------------------------------------------------------------------
+# Turn 2 — answer the robot's question using the same task ID
+# ---------------------------------------------------------------------------
+puts <<~HEREDOC
+
+  === Turn 2: Answer ===
+    Answering: 'Ada'
+
+HEREDOC
+
+begin
+  task2 = client.send_task(
+    message: A2A::Models::Message.user('Ada'),
+    task_id: task1.id
+  )
+
+  state2   = task2.status.state
+  reply    = task2.artifacts&.first&.parts&.first&.text
+  new_task = task2.id != task1.id
+
+  puts "  Task ID: #{task2.id}"
+  puts "  State:   #{state2}"
+  puts "  Reply:   #{reply}" if reply
+  puts
+
+  divider
+  puts
+
+  puts '=== Verification ==='
+  if new_task
+    puts <<~HEREDOC
+        Turn 1 returned input_required : PASS
+        Turn 2 skipped — server created a new task instead of resuming
+              (simple_a2a >= 0.3.1 required for full two-turn resume)
+
+      Turn 1 passed. Upgrade simple_a2a to >= 0.3.1 for the full two-turn demo.
+    HEREDOC
+  else
+    turn1_ok = state1 == 'input_required'
+    turn2_ok = state2 == 'completed'
+    reply_ok = reply&.include?('Ada')
+
+    puts <<~HEREDOC
+        Turn 1 returned input_required : #{turn1_ok ? 'PASS' : 'FAIL'}
+        Turn 2 completed after answer  : #{turn2_ok ? 'PASS' : 'FAIL'}
+        Reply addresses the caller     : #{reply_ok ? 'PASS' : 'FAIL'}
+
+    HEREDOC
+
+    all_ok = turn1_ok && turn2_ok && reply_ok
+    puts(all_ok ? 'All assertions passed.' : 'One or more assertions failed.')
+  end
+rescue A2A::Error => e
+  puts <<~HEREDOC
+      A2A error on Turn 2: #{e.message}
+
+    === Verification ===
+      Turn 1 returned input_required : #{state1 == 'input_required' ? 'PASS' : 'FAIL'}
+      Turn 2 skipped (server does not yet support resume via task_id)
+
+    Turn 1 passed. Upgrade simple_a2a to >= 0.3.1 for the full two-turn demo.
+  HEREDOC
+end

data/examples/04_io_bridge/server.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/04_io_bridge/server.rb
+#
+# Demonstrates :io_bridge interactive mode.
+#
+# IoBridge replaces robot.input and robot.output before each robot.run()
+# call. Text written to @output is buffered; when the robot calls @input.gets,
+# the buffer is emitted as an input_required A2A message and the call blocks
+# until the client resumes the task. The robot thread then unblocks, receiving
+# the answer as if a user had typed it at a terminal.
+#
+# Key point: QuoteRobot has NO knowledge of A2A. It reads and writes plain Ruby
+# IO — the same code runs interactively in a terminal:
+#
+#   robot = QuoteRobot.new
+#   robot.run('stoicism')        # prompts and reads from $stdin/$stdout
+#
+# Contrast with :a2a_tool, which requires the robot to call an injected tool.
+# Use :io_bridge for existing robots that already use puts/gets directly.
+
+require_relative '../common_config'
+
+# ---------------------------------------------------------------------------
+# Robot — standard Ruby IO; no mention of A2A, tools, or queues.
+# attr_writer :input, :output lets RobotAdapter inject the IoBridge before run.
+# Without injection, run() falls back to $stdin/$stdout (terminal mode).
+# ---------------------------------------------------------------------------
+class QuoteRobot
+  Result = Struct.new(:reply)
+
+  def name        = 'quote_robot'
+  def description = 'Composes an inspirational quote addressed to the caller'
+
+  attr_writer :input, :output
+
+  def run(topic)
+    out = @output || $stdout
+    inp = @input  || $stdin
+
+    out.puts "Who should I address this #{topic} quote to?"
+    name = inp.gets.chomp
+
+    Result.new(
+      "#{name}: \"#{topic.capitalize} is not a destination — it is a way of travelling.\""
+    )
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Server — :io_bridge injects IoBridge as robot.input and robot.output.
+# ---------------------------------------------------------------------------
+server = RobotLab::A2A::Server.new(host: 'localhost', port: 9292, interactive: :io_bridge)
+server.add_robot(QuoteRobot.new)
+
+puts <<~HEREDOC
+  Starting QuoteRobot on http://localhost:9292/quote-robot
+  Interactive mode: :io_bridge  (plain IO replaced by IoBridge)
+  Press Ctrl-C to stop.
+
+HEREDOC
+
+server.run

data/examples/05_multi_agent/client.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/05_multi_agent/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/05_multi_agent/server.rb
+#
+# Or run both together:
+#   bundle exec ruby examples/run 05_multi_agent
+#
+# What this demo shows:
+#
+#   Two independent A2A clients, each pointing at a different agent path on
+#   the same server. Each agent has its own agent card and processes the same
+#   input text in a completely different way. From the A2A protocol's point of
+#   view they are separate agents — the shared server process is invisible.
+
+require_relative '../common_config'
+
+BASE_URL     = 'http://localhost:9292'
+HEADLINE_URL = "#{BASE_URL}/headline"
+TAGS_URL     = "#{BASE_URL}/tags"
+
+headline_client = A2A.client(url: HEADLINE_URL)
+tags_client     = A2A.client(url: TAGS_URL)
+
+def divider = puts('─' * 60)
+
+# ---------------------------------------------------------------------------
+# Discover both agents
+# ---------------------------------------------------------------------------
+puts
+puts '=== Agent Cards ==='
+headline_card = headline_client.agent_card
+tags_card     = tags_client.agent_card
+
+puts <<~HEREDOC
+    /headline  #{headline_card.name}: #{headline_card.description}
+    /tags      #{tags_card.name}: #{tags_card.description}
+
+HEREDOC
+
+divider
+
+# ---------------------------------------------------------------------------
+# Send the same text to both agents
+# ---------------------------------------------------------------------------
+INPUT = 'the agent2agent protocol enables robots to collaborate over HTTP'
+
+puts <<~HEREDOC
+
+  === Sending to both agents ===
+    Input: #{INPUT.inspect}
+
+HEREDOC
+
+headline_task = headline_client.send_task(message: A2A::Models::Message.user(INPUT))
+tags_task     = tags_client.send_task(message: A2A::Models::Message.user(INPUT))
+
+headline_reply = headline_task.artifacts.first&.parts&.first&.text || '(no reply)'
+tags_reply     = tags_task.artifacts.first&.parts&.first&.text     || '(no reply)'
+
+puts <<~HEREDOC
+    HeadlineRobot [#{headline_task.status.state}]
+      #{headline_reply}
+
+    TagRobot [#{tags_task.status.state}]
+      #{tags_reply}
+
+HEREDOC
+
+divider
+puts
+
+# ---------------------------------------------------------------------------
+# Verify
+# ---------------------------------------------------------------------------
+puts '=== Verification ==='
+
+headline_ok  = headline_task.status.state == 'completed'
+tags_ok      = tags_task.status.state == 'completed'
+distinct_ok  = headline_reply != tags_reply
+headline_cap = headline_reply.match?(/\A[A-Z]/)
+tags_hash    = tags_reply.include?('#')
+
+puts <<~HEREDOC
+    HeadlineRobot completed    : #{headline_ok  ? 'PASS' : 'FAIL'}
+    TagRobot completed         : #{tags_ok      ? 'PASS' : 'FAIL'}
+    Responses are distinct     : #{distinct_ok  ? 'PASS' : 'FAIL'}
+    Headline starts capitalised: #{headline_cap ? 'PASS' : 'FAIL'}
+    Tags contain hash symbols  : #{tags_hash    ? 'PASS' : 'FAIL'}
+
+HEREDOC
+
+all_ok = headline_ok && tags_ok && distinct_ok && headline_cap && tags_hash
+puts(all_ok ? 'All assertions passed.' : 'One or more assertions failed.')

data/examples/05_multi_agent/server.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/05_multi_agent/server.rb
+#
+# Demonstrates multiple A2A agents on a single server using the fluent
+# builder API with explicit path overrides.
+#
+# Each robot is mounted at its own URL path and exposed as an independent
+# A2A agent with its own agent card. An A2A client discovers and addresses
+# each agent separately — they share the same server process but are
+# completely independent from the protocol's point of view.
+#
+# Server builder pattern:
+#   server.add_robot(robot_a, path: '/headline')
+#         .add_robot(robot_b, path: '/tags')
+#         .run
+
+require_relative '../common_config'
+
+# ---------------------------------------------------------------------------
+# HeadlineRobot — turns a passage of text into a punchy headline.
+# Registered at /headline via an explicit path: override.
+# ---------------------------------------------------------------------------
+class HeadlineRobot
+  Result = Struct.new(:reply)
+
+  def name        = 'headline_robot'
+  def description = 'Condenses input text into a short, punchy headline'
+
+  def run(input)
+    words    = input.strip.split
+    headline = words.first(6).map(&:capitalize).join(' ')
+    headline += '…' if words.length > 6
+    Result.new(headline)
+  end
+end
+
+# ---------------------------------------------------------------------------
+# TagRobot — extracts hashtag-style keywords from a passage of text.
+# Registered at /tags via an explicit path: override.
+# ---------------------------------------------------------------------------
+class TagRobot
+  Result = Struct.new(:reply)
+
+  def name        = 'tag_robot'
+  def description = 'Extracts hashtag keywords from input text'
+
+  def run(input)
+    tags = input.downcase
+                .scan(/\b[a-z]{4,}\b/)
+                .uniq
+                .first(5)
+                .map { |w| "##{w}" }
+                .join('  ')
+    Result.new(tags)
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Server — two robots, two paths, one server process.
+# The fluent add_robot calls return self so they can be chained.
+# ---------------------------------------------------------------------------
+server = RobotLab::A2A::Server.new(host: 'localhost', port: 9292)
+server.add_robot(HeadlineRobot.new, path: '/headline')
+      .add_robot(TagRobot.new,      path: '/tags')
+
+puts <<~HEREDOC
+  Starting multi-agent server on http://localhost:9292
+    /headline  — HeadlineRobot
+    /tags      — TagRobot
+  Press Ctrl-C to stop.
+
+HEREDOC
+
+server.run

data/examples/06_rack_mount/client.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/06_rack_mount/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/06_rack_mount/server.rb
+#
+# Or run both together:
+#   bundle exec ruby examples/run 06_rack_mount
+#
+# What this demo shows:
+#
+#   The A2A agent and a plain Rack endpoint live on the same server process.
+#   The client exercises both, proving that non-A2A routes and A2A agent routes
+#   coexist correctly when the agent is mounted via server.to_app.
+
+require_relative '../common_config'
+require 'net/http'
+require 'json'
+
+BASE_URL  = 'http://localhost:9292'
+AGENT_URL = "#{BASE_URL}/echo-robot"
+
+a2a_client = A2A.client(url: AGENT_URL)
+
+def divider = puts('─' * 60)
+
+# ---------------------------------------------------------------------------
+# 1. Health check — plain HTTP GET to the non-A2A Rack endpoint
+# ---------------------------------------------------------------------------
+puts
+puts '=== Health Check (plain Rack endpoint) ==='
+
+health_response = Net::HTTP.get_response(URI("#{BASE_URL}/health"))
+health_body     = JSON.parse(health_response.body) rescue {}
+
+puts <<~HEREDOC
+    Status code : #{health_response.code}
+    Body        : #{health_response.body}
+
+HEREDOC
+
+divider
+
+# ---------------------------------------------------------------------------
+# 2. A2A agent — standard task send/receive
+# ---------------------------------------------------------------------------
+puts
+puts '=== Agent Card ==='
+card = a2a_client.agent_card
+puts <<~HEREDOC
+    Name:        #{card.name}
+    Description: #{card.description}
+
+HEREDOC
+
+puts '=== Send Task ==='
+task  = a2a_client.send_task(message: A2A::Models::Message.user('hello from rack mount'))
+reply = task.artifacts.first&.parts&.first&.text || '(no reply)'
+
+puts <<~HEREDOC
+    State : #{task.status.state}
+    Reply : #{reply}
+
+HEREDOC
+
+divider
+puts
+
+# ---------------------------------------------------------------------------
+# Verify
+# ---------------------------------------------------------------------------
+puts '=== Verification ==='
+
+health_ok = health_response.code == '200'
+status_ok = health_body['status'] == 'ok'
+task_ok   = task.status.state == 'completed'
+reply_ok  = reply.include?('HELLO')
+
+puts <<~HEREDOC
+    Health endpoint returned 200 : #{health_ok ? 'PASS' : 'FAIL'}
+    Health body status is ok     : #{status_ok ? 'PASS' : 'FAIL'}
+    A2A task completed           : #{task_ok   ? 'PASS' : 'FAIL'}
+    A2A reply contains echo      : #{reply_ok  ? 'PASS' : 'FAIL'}
+
+HEREDOC
+
+all_ok = health_ok && status_ok && task_ok && reply_ok
+puts(all_ok ? 'All assertions passed.' : 'One or more assertions failed.')

data/examples/06_rack_mount/config.ru

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# config.ru — standalone Rack / Rails mount reference
+#
+# This file shows how to embed a RobotLab A2A agent inside any Rack-compatible
+# server using server.to_app.  It is NOT used by the demo runner (which uses
+# server.rb); it is here as a copy-paste reference.
+#
+# Run standalone with:
+#   bundle exec rackup examples/06_rack_mount/config.ru -p 9292
+#
+# Mount inside a Rails app (config/routes.rb):
+#   a2a = RobotLab::A2A::Server.new
+#   a2a.add_robot(MyRobot.new)
+#   mount a2a.to_app, at: '/'
+#
+# Mount inside a Sinatra app:
+#   use Rack::URLMap, '/' => RobotLab::A2A::Server.new.add_robot(MyRobot.new).to_app
+
+$LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
+require 'robot_lab/a2a'
+require 'json'
+
+class EchoRobot
+  Result = Struct.new(:reply)
+  def name        = 'echo_robot'
+  def description = 'Echoes input back in uppercase with a character count'
+  def run(input)
+    text = input.strip
+    Result.new("#{text.upcase}  [#{text.length} chars]")
+  end
+end
+
+a2a = RobotLab::A2A::Server.new
+a2a.add_robot(EchoRobot.new)
+
+health = lambda do |_env|
+  [200, { 'content-type' => 'application/json' }, [{ status: 'ok' }.to_json]]
+end
+
+run Rack::URLMap.new(
+  '/health' => health,
+  '/'       => a2a.to_app
+)

data/examples/06_rack_mount/server.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/06_rack_mount/server.rb
+#
+# Demonstrates server.to_app — embedding A2A agents inside a larger Rack app.
+#
+# server.run       — starts a dedicated Falcon server for A2A agents only.
+# server.to_app    — returns a Rack::URLMap that can be composed with other
+#                    Rack middleware and mounted in any Rack-compatible server
+#                    (Rails, Sinatra, Puma, Falcon, etc.).
+#
+# This demo composes the A2A agent with a /health JSON endpoint, runs the
+# combined Rack app using the same Falcon runner simple_a2a uses internally.
+#
+# In a Rails application the equivalent is:
+#
+#   # config/routes.rb
+#   mount RobotLab::A2A::Server.new.add_robot(my_robot).to_app, at: '/'
+#
+# See config.ru in this directory for the standalone Rack equivalent.
+
+require_relative '../common_config'
+require 'json'
+
+# ---------------------------------------------------------------------------
+# Robot — simple sync robot, identical role to EchoRobot in 01_sync_robot.
+# The interesting part here is how the server is wired up, not the robot.
+# ---------------------------------------------------------------------------
+class EchoRobot
+  Result = Struct.new(:reply)
+
+  def name        = 'echo_robot'
+  def description = 'Echoes input back in uppercase with a character count'
+
+  def run(input)
+    text = input.strip
+    Result.new("#{text.upcase}  [#{text.length} chars]")
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Build the A2A Rack app via to_app.
+# ---------------------------------------------------------------------------
+a2a = RobotLab::A2A::Server.new(host: 'localhost', port: 9292)
+a2a.add_robot(EchoRobot.new)
+
+a2a_app = a2a.to_app   # returns a Rack::URLMap — composable with any Rack app
+
+# ---------------------------------------------------------------------------
+# Compose with a /health endpoint to simulate a real multi-purpose app.
+# ---------------------------------------------------------------------------
+health = lambda do |_env|
+  body = { status: 'ok', agents: ['echo_robot'] }.to_json
+  [200, { 'content-type' => 'application/json' }, [body]]
+end
+
+combined_app = Rack::URLMap.new(
+  '/health' => health,
+  '/'       => a2a_app
+)
+
+puts <<~HEREDOC
+  Starting combined Rack app on http://localhost:9292
+    /health     — JSON health check (plain Rack lambda)
+    /echo-robot — A2A EchoRobot (via server.to_app)
+  Press Ctrl-C to stop.
+
+HEREDOC
+
+# Run the composed Rack app with the same Falcon runner simple_a2a uses.
+A2A::Server::FalconRunner.new(combined_app, host: 'localhost', port: 9292).run

data/examples/common_config.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# robot_lab-a2a/examples/common_config.rb
+#
+# Loaded by every example. Puts the gem's lib/ on the path so examples run
+# from a checkout without a gem install.
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'robot_lab/a2a'