simple_a2a 0.1.0

data/docs/api/server/index.md

@@ -0,0 +1,162 @@
+# Server API
+
+## Server::Base
+
+The server entry point. Creates and wires all server components, then runs Falcon.
+
+```ruby
+server = A2A::Server::Base.new(
+  agent_card:  card,        # A2A::Models::AgentCard (required)
+  executor:    MyExecutor.new,  # A2A::Server::AgentExecutor subclass (required)
+  storage:     A2A::Storage::Memory.new,  # default
+  push_sender: nil,         # A2A::Server::PushSender instance, optional
+  host:        "localhost", # default
+  port:        9292         # default
+)
+
+server.run          # blocks — starts Falcon
+server.rack_app     # returns the Rack app (useful for embedding in other servers)
+```
+
+Convenience factory:
+
+```ruby
+server = A2A.server(agent_card: card, executor: MyExecutor.new)
+server.run
+```
+
+---
+
+## Server::MultiAgent
+
+Hosts multiple A2A agents in one Falcon process by mounting each agent at its own URL path. Use this when you want independent AgentCards, executors, storage, and SSE channels behind one port.
+
+```ruby
+server = A2A.multi_server(
+  agents: {
+    "/anthropic" => { agent_card: anthropic_card, executor: AnthropicExecutor.new },
+    "/openai"    => { agent_card: openai_card,    executor: OpenAIExecutor.new },
+    "/evaluator" => { agent_card: evaluator_card, executor: EvaluatorExecutor.new }
+  },
+  host: "localhost",
+  port: 9292
+)
+
+server.run
+```
+
+Each entry in `agents` accepts the same core configuration used by `Server::Base`:
+
+| Key | Required | Description |
+|---|---|---|
+| `:agent_card` | Yes | AgentCard returned by that path's `/agentCard` endpoint |
+| `:executor` | Yes | Executor that handles requests for that path |
+| `:storage` | No | Storage backend for that path; defaults to `A2A::Storage::Memory.new` |
+| `:event_router` | No | SSE event router for that path; defaults to a new router |
+| `:push_sender` | No | Push notification sender for that path |
+
+For a runnable example, see the [Multi-Agent LLM Research demo](../../examples/llm-research.md).
+
+---
+
+## Server::AgentExecutor
+
+Base class for your agent logic. Subclass and implement `#call`:
+
+```ruby
+class MyExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    # ctx is an A2A::Server::Context
+    input = ctx.message.text_content
+    ctx.task.start!
+    # … do work …
+    ctx.task.complete!(artifacts: [ … ])
+  end
+
+  # Optional: handle task cancellation
+  def cancel(ctx)
+    # default implementation calls ctx.task.cancel! and emits a final status event
+    super
+  end
+end
+```
+
+`#call` runs synchronously inside the Falcon reactor. Long-running work should use `Async::Task` internally to stay non-blocking.
+
+---
+
+## Server::Context
+
+Passed to `AgentExecutor#call`. Provides access to the request and helper methods.
+
+```ruby
+ctx.task          # => A2A::Models::Task
+ctx.message       # => A2A::Models::Message (the incoming message)
+ctx.storage       # => A2A::Storage::Base
+ctx.event_router  # => A2A::Server::EventRouter
+ctx.config        # => Hash (arbitrary per-request config, default {})
+
+ctx.save_task           # persists task to storage
+ctx.emit_status(final: false)          # publishes TaskStatusUpdateEvent
+ctx.emit_artifact(artifact, append: false, last_chunk: false)  # publishes TaskArtifactUpdateEvent
+```
+
+---
+
+## Server::ResumeContext
+
+A `Context` subclass for resumed tasks (after `input_required` or `auth_required`).
+
+```ruby
+# Additional attribute:
+ctx.resume_message   # => A2A::Models::Message (the new input from the user)
+```
+
+---
+
+## Server::EventRouter
+
+Manages per-task SSE channels using `TypedBus`. You rarely interact with this directly — use `ctx.emit_status` and `ctx.emit_artifact` instead.
+
+```ruby
+router = A2A::Server::EventRouter.new
+router.open(task_id)                     # creates a channel
+router.publish(task_id, event)           # sends an event to subscribers
+router.subscribe(task_id) { |event| … } # block receives raw event objects
+router.close(task_id)                    # removes the channel
+router.channel?(task_id)                 # => true/false
+```
+
+---
+
+## Server::PushSender
+
+Delivers webhook push notifications.
+
+```ruby
+sender = A2A::Server::PushSender.new(
+  private_key: OpenSSL::PKey::RSA.generate(2048),  # for JWT signing
+  key_id:      "my-key-id",
+  issuer:      "my-agent"
+)
+
+sender.deliver(push_config, event)   # => true (success) or false (failure)
+```
+
+Schemes:
+
+- `"bearer"` — signs a JWT with `RS256` and sends `Authorization: Bearer <token>`
+- `"token"` — sends the static value as `Authorization: Token <value>` (or custom header)
+
+---
+
+## Server::App
+
+The Roda-based Rack application. You don't instantiate this directly — `Server::Base` configures and freezes it.
+
+**Routes:**
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/agentCard` | Returns the AgentCard as JSON |
+| `POST` | `/` | JSON-RPC 2.0 dispatch |

data/docs/api/storage/index.md

@@ -0,0 +1,84 @@
+# Storage API
+
+## Storage::Base
+
+Abstract interface. Subclass this to implement custom storage backends.
+
+```ruby
+class MyStorage < A2A::Storage::Base
+  def save(task)  = …   # persist, return task
+  def find(id)    = …   # return task or nil
+  def find!(id)   = …   # return task or raise A2A::TaskNotFoundError
+  def delete(id)  = …   # remove task
+  def list        = …   # return array of all tasks
+end
+```
+
+Pass your custom storage to `Server::Base`:
+
+```ruby
+A2A::Server::Base.new(
+  agent_card: card,
+  executor:   MyExecutor.new,
+  storage:    MyStorage.new
+)
+```
+
+---
+
+## Storage::Memory
+
+Thread-safe in-process hash store backed by a `Mutex`. Sufficient for single-process servers. Data is lost on restart.
+
+```ruby
+storage = A2A::Storage::Memory.new
+
+storage.save(task)          # => task
+storage.find("task-id")     # => task or nil
+storage.find!("task-id")    # => task or raises A2A::TaskNotFoundError
+storage.delete("task-id")   # => removed task or nil
+storage.list                # => [task, …]
+storage.size                # => Integer
+storage.clear               # clears all tasks
+```
+
+All methods acquire a mutex lock — safe for concurrent Falcon fibers.
+
+---
+
+## Custom storage example (Redis sketch)
+
+```ruby
+require "redis"
+
+class RedisStorage < A2A::Storage::Base
+  def initialize(redis: Redis.new)
+    @redis = redis
+  end
+
+  def save(task)
+    @redis.set("a2a:task:#{task.id}", task.to_h.to_json)
+    task
+  end
+
+  def find(id)
+    raw = @redis.get("a2a:task:#{id}")
+    return nil unless raw
+    A2A::Models::Task.from_hash(JSON.parse(raw))
+  end
+
+  def find!(id)
+    find(id) or raise A2A::TaskNotFoundError, "Task #{id} not found"
+  end
+
+  def delete(id)
+    @redis.del("a2a:task:#{id}")
+  end
+
+  def list
+    keys = @redis.keys("a2a:task:*")
+    return [] if keys.empty?
+    @redis.mget(*keys).compact.map { |raw| A2A::Models::Task.from_hash(JSON.parse(raw)) }
+  end
+end
+```

data/docs/architecture/index.md

@@ -0,0 +1,63 @@
+# Architecture
+
+`simple_a2a` is organized into three top-level namespaces under the `A2A` module:
+
+```
+A2A
+├── Models      — data classes (Task, Message, Part, Artifact, AgentCard, …)
+├── Server      — HTTP server, routing, executor base, event fan-out
+│   ├── App          (Roda JSON-RPC router)
+│   ├── Base         (server bootstrap + Falcon runner)
+│   ├── AgentExecutor (base class for your agent logic)
+│   ├── Context      (per-request helper passed to executor)
+│   ├── ResumeContext (Context + resume_message for interrupted tasks)
+│   ├── EventRouter  (TypedBus SSE fan-out)
+│   ├── PushSender   (webhook delivery with JWT signing)
+│   └── FalconRunner (Falcon adapter)
+├── Client      — async HTTP client
+│   ├── Base    (JSON-RPC client over async/http)
+│   └── SSE     (streaming subscribe client)
+├── Storage     — task persistence
+│   ├── Base    (abstract interface)
+│   └── Memory  (in-process, thread-safe)
+└── JsonRpc     — JSON-RPC 2.0 layer (request/response/error)
+```
+
+## Request lifecycle
+
+```
+Client POST /
+    │
+    ▼
+App (Roda)
+    │  JSON-RPC parse + dispatch
+    │
+    ▼
+handle_send
+    │  creates Task (submitted)
+    │  builds Context
+    │
+    ▼
+Executor#call(ctx)          ← your code lives here
+    │  ctx.task.start!
+    │  ctx.emit_artifact(…)  → EventRouter → SSE subscribers
+    │  ctx.task.complete!(…)
+    │
+    ▼
+Storage#save(task)
+    │
+    ▼
+JsonRpc::Response (task hash) → HTTP response
+```
+
+## Key design decisions
+
+**Zeitwerk autoloading** — all files under `lib/simple_a2a/` load on demand. The top-level module is `A2A` (not `SimpleA2a`), achieved via a custom Zeitwerk inflector.
+
+**Async-first** — the server runs inside Falcon's async reactor. The client uses `Async::HTTP::Internet` and wraps calls in `Async { }.wait` when invoked outside a reactor, keeping the public API synchronous.
+
+**One executor instance** — `Server::Base` holds a single executor object. For concurrent requests, executors must be stateless (or use per-call state inside `#call`).
+
+**Pluggable storage** — `Storage::Base` defines the interface (`save`, `find!`, `list`, `delete`). Swap in Redis or PostgreSQL by subclassing and passing your implementation to `Server::Base`.
+
+**EventRouter** — wraps `TypedBus::MessageBus` to provide per-task SSE channels. Channels are opened on first publish and closed when the SSE connection ends. `subscribe` transparently unwraps `TypedBus::Delivery` and calls `ack!`.

data/docs/architecture/protocol.md

@@ -0,0 +1,112 @@
+# Protocol Details
+
+## Transport
+
+All A2A communication uses **JSON-RPC 2.0 over HTTP POST** to a single endpoint (the server root `/`). The AgentCard is served at `GET /agentCard`.
+
+### Request format
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "abc-123",
+  "method": "tasks/send",
+  "params": {
+    "message": {
+      "messageId": "msg-1",
+      "role": "user",
+      "parts": [{ "text": "hello", "kind": "text" }]
+    }
+  }
+}
+```
+
+### Response format
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "abc-123",
+  "result": {
+    "id": "task-uuid",
+    "contextId": "ctx-uuid",
+    "status": { "state": "completed", "timestamp": "2026-01-01T00:00:00Z" },
+    "artifacts": [ ... ]
+  }
+}
+```
+
+## Methods
+
+| Method | Description |
+|---|---|
+| `tasks/send` | Send a message, execute synchronously, return completed task |
+| `tasks/sendSubscribe` | Send a message, stream events via SSE |
+| `tasks/get` | Retrieve a task by ID |
+| `tasks/list` | List all tasks |
+| `tasks/cancel` | Cancel a non-terminal task |
+| `tasks/pushNotification/set` | Register a push notification endpoint |
+| `tasks/pushNotification/get` | Retrieve push notification config |
+| `tasks/pushNotification/delete` | Remove push notification config |
+| `tasks/pushNotification/list` | List push notification configs |
+
+## Error codes
+
+| Code | Constant | Description |
+|---|---|---|
+| -32700 | `PARSE_ERROR` | Invalid JSON |
+| -32600 | `INVALID_REQUEST` | Not a valid JSON-RPC 2.0 object |
+| -32601 | `METHOD_NOT_FOUND` | Unknown method |
+| -32602 | `INVALID_PARAMS` | Missing or invalid parameters |
+| -32603 | `INTERNAL_ERROR` | Unhandled server error |
+| -32001 | `TASK_NOT_FOUND` | No task with the given ID |
+| -32002 | `TASK_NOT_CANCELABLE` | Task is already in a terminal state |
+| -32003 | `PUSH_NOT_SUPPORTED` | Agent doesn't support push notifications |
+| -32004 | `UNSUPPORTED_OPERATION` | Operation not supported (e.g. SSE on non-streaming agent) |
+| -32005 | `CONTENT_TYPE_NOT_SUPPORTED` | |
+| -32006 | `INVALID_AGENT_RESPONSE` | |
+| -32007 | `EXTENSION_REQUIRED` | |
+| -32008 | `VERSION_NOT_SUPPORTED` | Unsupported A2A-Version header value |
+
+## Version negotiation
+
+Clients may include an `A2A-Version` header. The server accepts `1.0` and `0.3`. Any other value returns a `VERSION_NOT_SUPPORTED` error.
+
+```http
+POST / HTTP/1.1
+A2A-Version: 1.0
+Content-Type: application/json
+```
+
+## Task lifecycle
+
+```
+submitted
+    │
+    ▼
+working
+    │
+    ├──→ completed   (terminal)
+    ├──→ failed      (terminal)
+    ├──→ canceled    (terminal)
+    ├──→ rejected    (terminal)
+    ├──→ input_required  (interrupted — waiting for user)
+    └──→ auth_required   (interrupted — waiting for credentials)
+```
+
+Terminal tasks cannot be canceled (`TASK_NOT_CANCELABLE`).  
+Interrupted tasks can be resumed by sending a new message.
+
+## Streaming (SSE)
+
+`tasks/sendSubscribe` keeps the HTTP connection open and streams `text/event-stream` events:
+
+```
+data: {"jsonrpc":"2.0","result":{"type":"TaskStatusUpdateEvent","taskId":"…","status":{"state":"working"},"final":false}}
+
+data: {"jsonrpc":"2.0","result":{"type":"TaskArtifactUpdateEvent","taskId":"…","artifact":{…},"final":false}}
+
+data: {"jsonrpc":"2.0","result":{"type":"TaskStatusUpdateEvent","taskId":"…","status":{"state":"completed"},"final":true}}
+```
+
+Events with `"final": true` signal that the stream is complete.

data/docs/assets/css/custom.css

@@ -0,0 +1,6 @@
+/* simple_a2a documentation custom styles */
+
+:root {
+  --md-primary-fg-color: #1565C0;
+  --md-accent-fg-color:  #F57F17;
+}

data/docs/examples/basic-usage.md

@@ -0,0 +1,77 @@
+# Basic Usage Demo
+
+`examples/01_basic_usage` is the smallest complete client/server demo. It shows the non-streaming JSON-RPC flow for an A2A agent.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/01_basic_usage/server.rb` | Defines `BasicExecutor`, builds the `BasicAgent` card, and starts the A2A server |
+| `examples/01_basic_usage/client.rb` | Discovers the agent, sends tasks, lists tasks, retrieves a task, and handles an expected error |
+
+## Run it
+
+From the repository root:
+
+```bash
+bundle exec ruby examples/run 01_basic_usage
+```
+
+The launcher starts the server on `http://localhost:9292`, runs the client, and stops the server afterward.
+
+Manual run:
+
+```bash
+bundle exec ruby examples/01_basic_usage/server.rb
+bundle exec ruby examples/01_basic_usage/client.rb
+```
+
+## Server behavior
+
+`BasicExecutor` subclasses `A2A::Server::AgentExecutor` and implements `#call(ctx)`. It reads the incoming user message with `ctx.message.text_content`, prepends a random greeting, and completes the task with one text artifact.
+
+```ruby
+class BasicExecutor < A2A::Server::AgentExecutor
+  GREETINGS = %w[Hello Greetings Salutations Hey Howdy].freeze
+
+  def call(ctx)
+    input = ctx.message.text_content.strip
+    reply = "#{GREETINGS.sample}: #{input}"
+
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        name: "reply",
+        parts: [A2A::Models::Part.text(reply)]
+      )
+    ])
+  end
+end
+```
+
+The server advertises one skill named `greet` and one JSON-RPC interface at `http://localhost:9292`.
+
+## Client flow
+
+The client demonstrates the core client API:
+
+```ruby
+client = A2A.client(url: "http://localhost:9292")
+
+card = client.agent_card
+task = client.send_task(message: A2A::Models::Message.user("world"))
+tasks = client.list_tasks
+retrieved = client.get_task(task.id)
+```
+
+It also calls `client.get_task("no-such-task-id")` and rescues `A2A::Error`, which is a compact example of handling protocol or server errors from a client.
+
+## What to study next
+
+Use this demo when learning the minimal server shape:
+
+| Concept | Where to look |
+|---|---|
+| Executor contract | `BasicExecutor#call` in `server.rb` |
+| Agent discovery | `client.agent_card` in `client.rb` |
+| Task submission | `client.send_task` in `client.rb` |
+| Storage-backed task lookup | `client.list_tasks` and `client.get_task` |

data/docs/examples/index.md

@@ -0,0 +1,92 @@
+# Examples
+
+The `examples/` directory contains runnable demo applications that exercise the gem from a client and server process. Each demo uses `examples/common_config.rb`, which adds the repository `lib/` directory to `$LOAD_PATH` before requiring `simple_a2a`, so the examples run against the local checkout.
+
+<svg viewBox="0 0 900 330" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="examples-title examples-desc">
+  <title id="examples-title">simple_a2a example applications</title>
+  <desc id="examples-desc">Dark themed transparent-background diagram showing the three example applications and the A2A capabilities they demonstrate.</desc>
+  <defs>
+    <linearGradient id="blue" x1="0" x2="1">
+      <stop offset="0" stop-color="#38bdf8"/>
+      <stop offset="1" stop-color="#2563eb"/>
+    </linearGradient>
+    <linearGradient id="green" x1="0" x2="1">
+      <stop offset="0" stop-color="#34d399"/>
+      <stop offset="1" stop-color="#16a34a"/>
+    </linearGradient>
+    <linearGradient id="amber" x1="0" x2="1">
+      <stop offset="0" stop-color="#fbbf24"/>
+      <stop offset="1" stop-color="#f97316"/>
+    </linearGradient>
+    <filter id="glow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#000000" flood-opacity="0.35"/>
+    </filter>
+  </defs>
+  <g fill="none" stroke="#334155" stroke-width="2">
+    <path d="M295 165H365"/>
+    <path d="M535 165H605"/>
+  </g>
+  <g filter="url(#glow)">
+    <rect x="45" y="65" width="250" height="200" rx="14" fill="#0f172a" stroke="url(#blue)" stroke-width="2"/>
+    <rect x="325" y="65" width="250" height="200" rx="14" fill="#0f172a" stroke="url(#green)" stroke-width="2"/>
+    <rect x="605" y="65" width="250" height="200" rx="14" fill="#0f172a" stroke="url(#amber)" stroke-width="2"/>
+  </g>
+  <g font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+    <text x="70" y="108" fill="#e2e8f0" font-size="24" font-weight="700">01 Basic Usage</text>
+    <text x="70" y="145" fill="#93c5fd" font-size="16">JSON-RPC request/response</text>
+    <text x="70" y="180" fill="#cbd5e1" font-size="15">agent card discovery</text>
+    <text x="70" y="205" fill="#cbd5e1" font-size="15">send, list, and get tasks</text>
+    <text x="70" y="230" fill="#cbd5e1" font-size="15">client error handling</text>
+    <text x="350" y="108" fill="#e2e8f0" font-size="24" font-weight="700">02 Streaming</text>
+    <text x="350" y="145" fill="#86efac" font-size="16">SSE task subscription</text>
+    <text x="350" y="180" fill="#cbd5e1" font-size="15">working/final statuses</text>
+    <text x="350" y="205" fill="#cbd5e1" font-size="15">append artifact chunks</text>
+    <text x="350" y="230" fill="#cbd5e1" font-size="15">incremental client output</text>
+    <text x="630" y="108" fill="#e2e8f0" font-size="24" font-weight="700">03 LLM Research</text>
+    <text x="630" y="145" fill="#fcd34d" font-size="16">multi-agent orchestration</text>
+    <text x="630" y="180" fill="#cbd5e1" font-size="15">Anthropic + OpenAI agents</text>
+    <text x="630" y="205" fill="#cbd5e1" font-size="15">evaluator agent</text>
+    <text x="630" y="230" fill="#cbd5e1" font-size="15">CLI and web clients</text>
+  </g>
+</svg>
+
+## Run a demo
+
+From the repository root:
+
+```bash
+bundle exec ruby examples/run 01_basic_usage
+bundle exec ruby examples/run 02_streaming
+```
+
+The launcher starts the demo server on `http://localhost:9292`, waits for it to accept connections, runs the demo client, and then shuts the server down.
+
+To run a demo manually, start its `server.rb` in one terminal and its `client.rb` in another:
+
+```bash
+bundle exec ruby examples/01_basic_usage/server.rb
+bundle exec ruby examples/01_basic_usage/client.rb
+```
+
+## Demo-specific dependencies
+
+The basic and streaming demos use only the gem and its normal development setup. The LLM research demo intentionally keeps its LLM and web UI dependencies out of the gem runtime dependency list. Install the demo-specific gems before running it:
+
+```bash
+bundle add ruby_llm async-http-faraday sinatra
+```
+
+Then set API keys:
+
+```bash
+export ANTHROPIC_API_KEY=your_key_here
+export OPENAI_API_KEY=your_key_here
+```
+
+## Demo index
+
+| Demo | Command | Documentation |
+|---|---|---|
+| Basic Usage | `bundle exec ruby examples/run 01_basic_usage` | [Basic Usage](basic-usage.md) |
+| Streaming | `bundle exec ruby examples/run 02_streaming` | [Streaming](streaming.md) |
+| Multi-Agent LLM Research | `bundle exec ruby examples/run 03_llm_research` | [Multi-Agent LLM Research](llm-research.md) |

data/docs/examples/llm-research.md

@@ -0,0 +1,92 @@
+# Multi-Agent LLM Research Demo
+
+`examples/03_llm_research` demonstrates a multi-agent A2A server with two streaming research agents and one evaluator agent. It includes both a CLI client and a Sinatra web client.
+
+## What it runs
+
+| Path | Agent | Model |
+|---|---|---|
+| `http://localhost:9292/anthropic` | `AnthropicResearchAgent` | `claude-sonnet-4-6` |
+| `http://localhost:9292/openai` | `OpenAIResearchAgent` | `gpt-5.4` |
+| `http://localhost:9292/evaluator` | `EvaluatorAgent` | `claude-sonnet-4-6` |
+| `http://localhost:4567` | Sinatra web UI | Streams both responses and the evaluation to the browser |
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `examples/03_llm_research/server.rb` | Configures RubyLLM, defines three executors, and starts a path-routed multi-agent A2A server |
+| `examples/03_llm_research/client.rb` | CLI client that queries both research agents in parallel and sends both responses to the evaluator |
+| `examples/03_llm_research/web_client.rb` | Sinatra UI that streams both research responses and the evaluator response to the browser |
+| `examples/03_llm_research/run` | Lifecycle script that starts the A2A server and web client together |
+
+## Setup
+
+The demo uses LLM and web UI libraries that are intentionally not runtime dependencies of the `simple_a2a` gem. Add them to your local bundle before running the demo:
+
+```bash
+bundle add ruby_llm async-http-faraday sinatra
+```
+
+Set both provider keys:
+
+```bash
+export ANTHROPIC_API_KEY=your_key_here
+export OPENAI_API_KEY=your_key_here
+```
+
+## Run the web demo
+
+From the repository root:
+
+```bash
+bundle exec ruby examples/run 03_llm_research
+```
+
+The custom runner starts:
+
+| Service | URL |
+|---|---|
+| A2A multi-agent server | `http://localhost:9292` |
+| Web client | `http://localhost:4567` |
+
+Open `http://localhost:4567`, enter a topic, and the page streams output from both research agents followed by the evaluator.
+
+## Run the CLI client
+
+Start the multi-agent server:
+
+```bash
+bundle exec ruby examples/03_llm_research/server.rb
+```
+
+Then run the CLI client from another terminal:
+
+```bash
+bundle exec ruby examples/03_llm_research/client.rb "compare the practical tradeoffs of A2A and MCP"
+```
+
+If no topic is supplied, the client uses its built-in default topic.
+
+## Server design
+
+The server uses `A2A.multi_server` to mount multiple agents under one Falcon process:
+
+```ruby
+A2A.multi_server(
+  agents: {
+    "/anthropic" => { agent_card: anthropic_card, executor: AnthropicResearchExecutor.new },
+    "/openai"    => { agent_card: openai_card,    executor: OpenAIResearchExecutor.new },
+    "/evaluator" => { agent_card: evaluator_card, executor: EvaluatorExecutor.new }
+  },
+  port: 9292
+).run
+```
+
+Each executor includes a shared streaming helper that calls RubyLLM and emits `TaskArtifactUpdateEvent` chunks while the model response arrives.
+
+## Web client design
+
+The web client exposes a browser-facing SSE endpoint at `/research`. Internally it opens A2A SSE subscriptions to the Anthropic and OpenAI agents in parallel, buffers both complete responses, then streams the evaluator response back to the browser.
+
+This is useful as a reference for bridging A2A streaming into another application protocol while keeping the A2A agents independently addressable.