simple_a2a 0.1.0 → 0.3.0

data/examples/08_interrupted_states/client.rb

@@ -0,0 +1,148 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/08_interrupted_states/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/08_interrupted_states/server.rb
+#
+# What this demo shows:
+#
+#   Scenario A — input_required (OrderAgent):
+#     Turn 1: client sends an initial request → agent pauses with input_required
+#             and a question in status.message
+#     Turn 2: client reads the question, sends the answer with the same
+#             context_id → agent completes the task
+#
+#   Scenario B — auth_required (VaultAgent):
+#     Turn 1: client requests protected data → agent pauses with auth_required
+#     Turn 2: client sends the wrong token → agent stays in auth_required
+#     Turn 3: client sends the correct token → agent completes the task
+#
+# Each turn is a separate tasks/send call. The agents use message.context_id
+# to thread the conversation across calls.
+
+require_relative "../common_config"
+
+BASE_URL  = "http://localhost:9292"
+ORDER_URL = "#{BASE_URL}/order"
+VAULT_URL = "#{BASE_URL}/vault"
+
+def divider = puts("─" * 60)
+
+def msg(text, context_id:)
+  A2A::Models::Message.new(
+    role:       A2A::Models::Types::Role::USER,
+    parts:      [A2A::Models::Part.text(text)],
+    context_id: context_id
+  )
+end
+
+def show_task(label, task)
+  state   = task.status.state
+  message = task.status.message
+  artifact = task.artifacts&.first&.parts&.first&.text
+
+  puts "  [#{label}] state=#{state}"
+  puts "            agent says: #{message}"  if message
+  puts "            result:     #{artifact}" if artifact
+end
+
+# ---------------------------------------------------------------------------
+# Scenario A — input_required
+# ---------------------------------------------------------------------------
+puts
+puts "=== Scenario A: input_required (OrderAgent) ==="
+puts
+
+order = A2A.client(url: ORDER_URL)
+conv_a = SecureRandom.uuid
+
+puts "  context_id: #{conv_a[0, 8]}…"
+puts
+
+# Turn 1 — agent doesn't know what to make yet
+task_a1 = order.send_task(message: msg("I'd like to place an order", context_id: conv_a))
+show_task("turn 1", task_a1)
+
+abort "Expected input_required, got #{task_a1.status.state}" unless task_a1.status.state == "input_required"
+
+puts
+puts "  Client reads the question and answers: 'pasta'"
+puts
+
+# Turn 2 — client answers with the same context_id
+task_a2 = order.send_task(message: msg("pasta", context_id: conv_a))
+show_task("turn 2", task_a2)
+
+divider
+
+# ---------------------------------------------------------------------------
+# Scenario B — auth_required (with a wrong token first)
+# ---------------------------------------------------------------------------
+puts
+puts "=== Scenario B: auth_required (VaultAgent) ==="
+puts
+
+vault  = A2A.client(url: VAULT_URL)
+conv_b = SecureRandom.uuid
+
+puts "  context_id: #{conv_b[0, 8]}…"
+puts
+
+# Turn 1 — agent demands a token
+task_b1 = vault.send_task(message: msg("show me the secret data", context_id: conv_b))
+show_task("turn 1", task_b1)
+
+abort "Expected auth_required, got #{task_b1.status.state}" unless task_b1.status.state == "auth_required"
+
+puts
+puts "  Client sends the wrong token: 'wrong-token'"
+puts
+
+# Turn 2 — wrong token; agent stays blocked
+task_b2 = vault.send_task(message: msg("wrong-token", context_id: conv_b))
+show_task("turn 2", task_b2)
+
+abort "Expected auth_required, got #{task_b2.status.state}" unless task_b2.status.state == "auth_required"
+
+puts
+puts "  Client sends the correct token: 'open-sesame'"
+puts
+
+# Turn 3 — correct token; agent unlocks
+task_b3 = vault.send_task(message: msg("open-sesame", context_id: conv_b))
+show_task("turn 3", task_b3)
+
+divider
+
+# ---------------------------------------------------------------------------
+# Verification
+# ---------------------------------------------------------------------------
+puts
+puts "=== Verification ==="
+
+a_paused   = task_a1.status.state == "input_required"
+a_asked    = task_a1.status.message&.include?("Options:")
+a_complete = task_a2.status.state == "completed"
+a_artifact = task_a2.artifacts&.first&.parts&.first&.text&.include?("pasta")
+
+b_blocked1  = task_b1.status.state == "auth_required"
+b_blocked2  = task_b2.status.state == "auth_required"
+b_complete  = task_b3.status.state == "completed"
+b_artifact  = task_b3.artifacts&.first&.parts&.first&.text&.include?("treasure")
+
+puts "  [order] turn 1 paused with input_required : #{a_paused   ? 'PASS' : 'FAIL'}"
+puts "  [order] turn 1 included a question        : #{a_asked    ? 'PASS' : 'FAIL'}"
+puts "  [order] turn 2 completed after answer     : #{a_complete ? 'PASS' : 'FAIL'}"
+puts "  [order] turn 2 artifact mentions pasta    : #{a_artifact ? 'PASS' : 'FAIL'}"
+puts
+puts "  [vault] turn 1 paused with auth_required  : #{b_blocked1 ? 'PASS' : 'FAIL'}"
+puts "  [vault] turn 2 stayed blocked (bad token) : #{b_blocked2 ? 'PASS' : 'FAIL'}"
+puts "  [vault] turn 3 completed after good token : #{b_complete ? 'PASS' : 'FAIL'}"
+puts "  [vault] turn 3 artifact contains secret   : #{b_artifact ? 'PASS' : 'FAIL'}"
+puts
+
+all_ok = a_paused && a_asked && a_complete && a_artifact &&
+         b_blocked1 && b_blocked2 && b_complete && b_artifact
+puts(all_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/08_interrupted_states/server.rb

@@ -0,0 +1,142 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/08_interrupted_states/server.rb
+#
+# Two agents on one port demonstrating the two interrupted task states:
+#
+#   /order  — uses input_required to ask the user what they want before
+#              completing the order
+#   /vault  — uses auth_required to demand a token before revealing data
+#
+# Each turn from the client is a separate tasks/send call. The executors
+# use message.context_id as a conversation key to distinguish first turns
+# from follow-ups.
+
+require_relative "../common_config"
+
+BASE_URL = "http://localhost:9292"
+
+# ---------------------------------------------------------------------------
+# OrderExecutor — demonstrates input_required.
+#
+# Turn 1: any message → input_required: "What would you like?"
+# Turn 2: message containing a menu item → completed with confirmation
+# ---------------------------------------------------------------------------
+class OrderExecutor < A2A::Server::AgentExecutor
+  MENU = %w[pizza pasta salad].freeze
+
+  def initialize
+    @pending = {}
+    @mutex   = Mutex.new
+  end
+
+  def call(ctx)
+    conv_id = ctx.message.context_id
+    input   = ctx.message.text_content.strip.downcase
+    state   = @mutex.synchronize { @pending[conv_id] }
+
+    if state.nil?
+      @mutex.synchronize { @pending[conv_id] = :awaiting_item }
+      ctx.task.require_input!(
+        message: "What would you like to order? Options: #{MENU.join(', ')}"
+      )
+    else
+      @mutex.synchronize { @pending.delete(conv_id) }
+      item = MENU.find { |m| input.include?(m) }
+
+      if item
+        ctx.task.complete!(artifacts: [
+          A2A::Models::Artifact.new(
+            name:  "confirmation",
+            parts: [A2A::Models::Part.text("Order confirmed: #{item}! It will be ready in 20 minutes.")]
+          )
+        ])
+      else
+        ctx.task.fail!(message: "Unknown item '#{input}'. Please choose from: #{MENU.join(', ')}")
+      end
+    end
+  end
+end
+
+# ---------------------------------------------------------------------------
+# VaultExecutor — demonstrates auth_required.
+#
+# Turn 1: any message → auth_required: "Provide your access token"
+# Turn 2: correct token → completed with secret data
+#          wrong token  → auth_required again (stays blocked)
+# ---------------------------------------------------------------------------
+class VaultExecutor < A2A::Server::AgentExecutor
+  SECRET_TOKEN = "open-sesame"
+  SECRET_DATA  = "The treasure is buried under the old oak tree at coordinates 48.8566°N, 2.3522°E."
+
+  def initialize
+    @pending = {}
+    @mutex   = Mutex.new
+  end
+
+  def call(ctx)
+    conv_id = ctx.message.context_id
+    input   = ctx.message.text_content.strip
+    state   = @mutex.synchronize { @pending[conv_id] }
+
+    if state.nil?
+      @mutex.synchronize { @pending[conv_id] = :awaiting_token }
+      ctx.task.require_auth!(message: "Access restricted. Provide your token to continue.")
+    elsif input == SECRET_TOKEN
+      @mutex.synchronize { @pending.delete(conv_id) }
+      ctx.task.complete!(artifacts: [
+        A2A::Models::Artifact.new(
+          name:  "secret",
+          parts: [A2A::Models::Part.text(SECRET_DATA)]
+        )
+      ])
+    else
+      ctx.task.require_auth!(message: "Invalid token. Try again.")
+    end
+  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
+
+order_card = make_card(
+  name:        "OrderAgent",
+  description: "Takes food orders — pauses with input_required to ask what the user wants",
+  skill:       "order",
+  path:        "/order"
+)
+
+vault_card = make_card(
+  name:        "VaultAgent",
+  description: "Guards secret data — pauses with auth_required until a valid token is provided",
+  skill:       "vault",
+  path:        "/vault"
+)
+
+puts "Starting interrupted-states server on #{BASE_URL}"
+puts "  /order  → OrderAgent  (demonstrates input_required)"
+puts "  /vault  → VaultAgent  (demonstrates auth_required)"
+puts "Press Ctrl-C to stop."
+puts
+
+A2A.multi_server(
+  agents: {
+    "/order" => { agent_card: order_card, executor: OrderExecutor.new },
+    "/vault" => { agent_card: vault_card, executor: VaultExecutor.new }
+  },
+  port: 9292
+).run

data/examples/09_multipart/client.rb

@@ -0,0 +1,117 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/09_multipart/client.rb [topic]
+#
+# Start the server first:
+#   bundle exec ruby examples/09_multipart/server.rb
+#
+# What this demo shows:
+#   A single artifact can carry multiple parts of different types.
+#   The client inspects each part using the predicate methods (text?,
+#   json?, raw?, url?) and processes each one appropriately:
+#
+#     Part.text     → print the prose
+#     Part.json     → pretty-print the hash
+#     Part.binary   → decode from base64, display as text or byte count
+#     Part.from_url → display the URL reference
+
+require_relative "../common_config"
+require "json"
+
+URL   = "http://localhost:9292"
+topic = ARGV.first || "agent to agent protocol design"
+
+def divider = puts("─" * 60)
+def header(title) = puts("\n  ── #{title} ──\n")
+
+# ---------------------------------------------------------------------------
+# Discover the agent
+# ---------------------------------------------------------------------------
+client = A2A.client(url: URL)
+card   = client.agent_card
+
+puts
+puts "=== Agent Card ==="
+puts "  Name:        #{card.name}"
+puts "  Description: #{card.description}"
+puts
+
+# ---------------------------------------------------------------------------
+# Send the task
+# ---------------------------------------------------------------------------
+puts "=== Sending task: #{topic.inspect} ==="
+puts
+
+task = client.send_task(message: A2A::Models::Message.user(topic))
+
+puts "  state:     #{task.status.state}"
+puts "  artifacts: #{task.artifacts.length}"
+
+artifact = task.artifacts.first
+puts "  artifact:  #{artifact.name} (#{artifact.parts.length} parts)"
+divider
+
+# ---------------------------------------------------------------------------
+# Inspect each part by type
+# ---------------------------------------------------------------------------
+puts
+puts "=== Parts ==="
+
+artifact.parts.each_with_index do |part, i|
+  puts
+  puts "  Part #{i + 1} of #{artifact.parts.length}"
+
+  if part.text?
+    header "text  (media_type: #{part.media_type})"
+    part.text.each_line { |l| puts "    #{l}" }
+
+  elsif part.json?
+    header "json  (filename: #{part.filename})"
+    JSON.pretty_generate(part.data).each_line { |l| puts "    #{l}" }
+
+  elsif part.raw?
+    header "binary  (media_type: #{part.media_type}, filename: #{part.filename})"
+    bytes = part.decoded_bytes
+    puts "    base64 length : #{part.raw.length} chars"
+    puts "    decoded bytes : #{bytes.bytesize}"
+    puts "    content:"
+    bytes.force_encoding("UTF-8").each_line { |l| puts "      #{l}" }
+
+  elsif part.url?
+    header "url  (media_type: #{part.media_type}, filename: #{part.filename})"
+    puts "    #{part.url}"
+  end
+end
+
+divider
+
+# ---------------------------------------------------------------------------
+# Verification
+# ---------------------------------------------------------------------------
+parts = artifact.parts
+
+text_part   = parts.find(&:text?)
+json_part   = parts.find(&:json?)
+binary_part = parts.find(&:raw?)
+url_part    = parts.find(&:url?)
+
+puts
+puts "=== Verification ==="
+puts "  text   part present and non-empty : #{(text_part   && !text_part.text.empty?)           ? 'PASS' : 'FAIL'}"
+puts "  json   part present with hash     : #{(json_part   && json_part.data.is_a?(Hash))        ? 'PASS' : 'FAIL'}"
+puts "  binary part decodes correctly     : #{(binary_part && binary_part.decoded_bytes.bytesize > 0) ? 'PASS' : 'FAIL'}"
+puts "  url    part is a valid URL        : #{(url_part    && url_part.url.start_with?("https://")) ? 'PASS' : 'FAIL'}"
+puts "  json   part topic matches input   : #{(json_part   && json_part.data["topic"] == topic)  ? 'PASS' : 'FAIL'}"
+puts "  binary part is valid CSV          : #{(binary_part && binary_part.decoded_bytes.include?("rank")) ? 'PASS' : 'FAIL'}"
+puts
+
+all_ok = text_part && json_part && binary_part && url_part &&
+         !text_part.text.empty? &&
+         json_part.data.is_a?(Hash) &&
+         binary_part.decoded_bytes.bytesize > 0 &&
+         url_part.url.start_with?("https://") &&
+         json_part.data["topic"] == topic &&
+         binary_part.decoded_bytes.include?("rank")
+
+puts(all_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/09_multipart/server.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/09_multipart/server.rb
+#
+# Demonstrates all four Part types in a single artifact:
+#
+#   Part.text      — plain prose summary
+#   Part.json      — structured metadata as a Ruby hash
+#   Part.binary    — raw bytes (a CSV here), base64-encoded in transit
+#   Part.from_url  — a URL reference to an external resource
+#
+# The agent treats any input as a topic and fabricates a four-part
+# report artifact so the client can exercise every Part type.
+
+require_relative "../common_config"
+
+class ReportExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    topic = ctx.message.text_content.strip
+    topic = "unknown topic" if topic.empty?
+
+    # Part 1 — prose summary
+    summary = A2A::Models::Part.text(<<~TEXT.strip, media_type: "text/plain")
+      Report on: #{topic}
+      Generated at #{Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')}
+
+      This is a synthetic report for demonstration purposes. In a real agent,
+      this section would contain the executive summary of the analysis.
+    TEXT
+
+    # Part 2 — structured JSON metadata
+    metadata = A2A::Models::Part.json(
+      {
+        "topic"      => topic,
+        "word_count" => topic.split.length,
+        "tags"       => topic.downcase.split.first(3),
+        "confidence" => 0.92,
+        "generated"  => true
+      },
+      filename: "metadata.json"
+    )
+
+    # Part 3 — binary blob (a tiny CSV), base64-encoded in transit
+    csv_rows  = [["rank", "term", "score"]] +
+                topic.split.first(5).each_with_index.map { |w, i| [i + 1, w, (0.9 - i * 0.1).round(2)] }
+    csv_bytes = csv_rows.map { |row| row.join(",") }.join("\n").b
+
+    csv_part = A2A::Models::Part.binary(
+      csv_bytes,
+      media_type: "text/csv",
+      filename:   "term_scores.csv"
+    )
+
+    # Part 4 — URL reference to a related external resource
+    search_url = "https://en.wikipedia.org/wiki/Special:Search?search=#{URI.encode_uri_component(topic)}"
+    url_part   = A2A::Models::Part.from_url(
+      search_url,
+      media_type: "text/html",
+      filename:   "reference.html"
+    )
+
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "report",
+        parts: [summary, metadata, csv_part, url_part]
+      )
+    ])
+  end
+end
+
+card = A2A::Models::AgentCard.new(
+  name:         "ReportAgent",
+  version:      "1.0",
+  description:  "Returns a four-part artifact: text summary, JSON metadata, binary CSV, and a URL reference",
+  capabilities: A2A::Models::AgentCapabilities.new,
+  skills: [
+    A2A::Models::AgentSkill.new(
+      name:        "report",
+      description: "Generates a multi-part report artifact for any topic"
+    )
+  ],
+  interfaces: [
+    A2A::Models::AgentInterface.new(
+      type:    "json-rpc",
+      url:     "http://localhost:9292",
+      version: "1.0"
+    )
+  ]
+)
+
+puts "Starting ReportAgent on http://localhost:9292"
+puts "Returns a 4-part artifact (text + JSON + binary + URL) for any topic."
+puts "Press Ctrl-C to stop."
+puts
+
+A2A.server(agent_card: card, executor: ReportExecutor.new).run

data/examples/10_auth_headers/client.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/10_auth_headers/client.rb
+#
+# Start the server first:
+#   bundle exec ruby examples/10_auth_headers/server.rb
+#
+# What this demo shows:
+#   1. Agent card discovery (GET) works for both clients — it is public.
+#   2. An unauthenticated client (no headers) is rejected on send_task.
+#   3. An authenticated client (headers: { "Authorization" => "Bearer ..." })
+#      succeeds on send_task.
+#   4. The headers: option accepts any key/value pairs, making it suitable
+#      for Bearer tokens, API keys, or any custom header scheme.
+
+require_relative "../common_config"
+
+URL   = "http://localhost:9292"
+TOKEN = "super-secret-token"
+
+def divider = puts("─" * 60)
+
+# ---------------------------------------------------------------------------
+# Two clients — same URL, different headers
+# ---------------------------------------------------------------------------
+unauth_client = A2A.client(url: URL)
+auth_client   = A2A.client(url: URL, headers: { "Authorization" => "Bearer #{TOKEN}" })
+
+# ---------------------------------------------------------------------------
+# Agent card — public endpoint, both clients can discover it
+# ---------------------------------------------------------------------------
+puts
+puts "=== Agent Card (public — no auth required) ==="
+card = unauth_client.agent_card
+puts "  Name:        #{card.name}"
+puts "  Description: #{card.description}"
+puts
+divider
+
+# ---------------------------------------------------------------------------
+# Unauthenticated client — rejected on RPC call
+# ---------------------------------------------------------------------------
+puts
+puts "=== Unauthenticated client — no Authorization header ==="
+puts
+
+unauth_error = nil
+begin
+  unauth_client.send_task(message: A2A::Models::Message.user("hello"))
+  puts "  (unexpected success)"
+rescue A2A::Error => e
+  unauth_error = e
+  puts "  Rejected as expected: #{e.message}"
+end
+
+divider
+
+# ---------------------------------------------------------------------------
+# Authenticated client — accepted
+# ---------------------------------------------------------------------------
+puts
+puts "=== Authenticated client — Authorization: Bearer #{TOKEN} ==="
+puts
+
+auth_task   = auth_client.send_task(message: A2A::Models::Message.user("hello from authorized client"))
+auth_result = auth_task.artifacts&.first&.parts&.first&.text
+
+puts "  state:  #{auth_task.status.state}"
+puts "  result: #{auth_result}"
+
+divider
+
+# ---------------------------------------------------------------------------
+# Verification
+# ---------------------------------------------------------------------------
+puts
+puts "=== Verification ==="
+
+card_ok      = card.name == "SecureAgent"
+rejected_ok  = unauth_error&.message&.include?("Unauthorized")
+accepted_ok  = auth_task.status.state == "completed"
+result_ok    = auth_result&.include?("[authorized]")
+
+puts "  Agent card discoverable without auth : #{card_ok     ? 'PASS' : 'FAIL'}"
+puts "  Unauthenticated call rejected        : #{rejected_ok ? 'PASS' : 'FAIL'}"
+puts "  Authenticated call accepted          : #{accepted_ok ? 'PASS' : 'FAIL'}"
+puts "  Authenticated result is correct      : #{result_ok   ? 'PASS' : 'FAIL'}"
+puts
+
+all_ok = card_ok && rejected_ok && accepted_ok && result_ok
+puts(all_ok ? "All assertions passed." : "One or more assertions failed.")

data/examples/10_auth_headers/server.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby examples/10_auth_headers/server.rb
+#
+# Demonstrates the headers: option on A2A.client by running a server that
+# enforces Bearer token authentication on all RPC calls (POST requests).
+# Agent card discovery (GET /agentCard) is intentionally left public.
+#
+# The middleware wraps the standard rack_app — no library changes required.
+# Any Rack middleware (OAuth, mTLS, API key, custom headers) can be layered
+# the same way.
+#
+# Valid token: "super-secret-token"
+
+require_relative "../common_config"
+
+VALID_TOKEN = "super-secret-token"
+
+# ---------------------------------------------------------------------------
+# Rack middleware — checks Authorization: Bearer <token> on POST requests.
+# Returns a JSON-RPC shaped error so the A2A client can parse it cleanly.
+# ---------------------------------------------------------------------------
+class BearerAuthMiddleware
+  def initialize(app, token:)
+    @app   = app
+    @token = token
+  end
+
+  def call(env)
+    if env["REQUEST_METHOD"] == "POST"
+      auth = env["HTTP_AUTHORIZATION"].to_s
+      unless auth == "Bearer #{@token}"
+        body = JSON.generate({
+          "jsonrpc" => "2.0",
+          "id"      => nil,
+          "error"   => {
+            "code"    => -32_000,
+            "message" => "Unauthorized: valid Bearer token required"
+          }
+        })
+        return [200, { "Content-Type" => "application/json" }, [body]]
+      end
+    end
+
+    @app.call(env)
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Executor — echoes the input back, confirming the request was authorized.
+# ---------------------------------------------------------------------------
+class SecureEchoExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    input = ctx.message.text_content.strip
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name:  "reply",
+        parts: [A2A::Models::Part.text("[authorized] echo: #{input}")]
+      )
+    ])
+  end
+end
+
+# ---------------------------------------------------------------------------
+# Agent card and server
+# ---------------------------------------------------------------------------
+card = A2A::Models::AgentCard.new(
+  name:         "SecureAgent",
+  version:      "1.0",
+  description:  "Requires a Bearer token on all RPC calls; agent card is public",
+  capabilities: A2A::Models::AgentCapabilities.new,
+  skills: [
+    A2A::Models::AgentSkill.new(
+      name:        "secure_echo",
+      description: "Echoes input — only reachable with a valid Bearer token"
+    )
+  ],
+  interfaces: [
+    A2A::Models::AgentInterface.new(
+      type:    "json-rpc",
+      url:     "http://localhost:9292",
+      version: "1.0"
+    )
+  ]
+)
+
+# Build the rack app and wrap it with auth middleware.
+inner_app = A2A.server(agent_card: card, executor: SecureEchoExecutor.new).rack_app
+auth_app  = BearerAuthMiddleware.new(inner_app, token: VALID_TOKEN)
+
+puts "Starting SecureAgent on http://localhost:9292"
+puts "  GET  /agentCard  — public (no auth required)"
+puts "  POST /           — requires Authorization: Bearer #{VALID_TOKEN}"
+puts "Press Ctrl-C to stop."
+puts
+
+A2A::Server::FalconRunner.new(auth_app, port: 9292).run