Feat: Ruby SDK - initial implementation, tests, and documentation by aboneto · Pull Request #1 · bukhr/ag-ui

aboneto · 2025-12-22T14:41:31Z

This PR introduces the Ruby SDK for the AG‑UI (Agent‑User Interaction) Protocol, including the initial SDK implementation, a test suite, and reference documentation pages.

The goal is to provide Ruby building blocks for:

Strongly-typed protocol types
Strongly-typed protocol events
An SSE event encoder that outputs text/event-stream, serializes keys as camelCase, and omits nil values

What changed:

Ruby SDK (ag-ui-protocol gem)
Protocol types under AgUiProtocol::Core::Types
Protocol events under AgUiProtocol::Core::Events
SSE encoder via AgUiProtocol::EventEncoder

Tests:

Coverage for JSON serialization, input normalization, and SSE encoding

Docs:

New .mdx pages for the Ruby SDK:
- docs/sdk/ruby/overview.mdx
- docs/sdk/ruby/core/overview.mdx
- docs/sdk/ruby/core/types.mdx
- docs/sdk/ruby/core/events.mdx
- docs/sdk/ruby/encoder/overview.mdx

fsateler

Hay varios (aunque no todos) docs de sdk que tienen un overview.mdx general, con instrucciones generales de instalación y uso. Por ejemplo go. Quizas podemos linkear al README de la gema.

Agregar a integrations.mdx el link tambien.

docs/sdk/ruby/encoder/overview.mdx

fsateler · 2025-12-22T18:10:16Z

docs/sdk/ruby/encoder/overview.mdx

+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `accept` | `String` (optional) | Content type accepted by the client |


La descripción más arriba dice que emite SSE. Si solo emitimos SSE, el accept siempre seria application/json o no?

Tu puede responder application/json si no va enviar eventos, responder directo o puede hacerlo por text/event-stream que es por evento.

sdks/community/ruby/lib/ag_ui_protocol/core/events.rb

fsateler · 2025-12-22T18:22:24Z

sdks/community/ruby/lib/ag_ui_protocol/encoder/event_encoder.rb

+        # @return [String, Object]
+        sig { params(event: T.untyped).returns(T.untyped) }
+        def convert_payload_to_sse(event)
+          if event.respond_to?(:as_json)


Por que aca aceptas as_json, pero en los otros lados usas normalize_value que no? Creo que conviene ser consistente

normalize_value es para transformar en un hash a partir del método to_h definido en cada tipo de clase. Ya as_json es para converter en en JSON, pero en el formato esperado por el protocolo, más allá de simplesmente converter en json (This converts keys to camelCase and removes nil values recursively).

Entonces si paso un hash no se van a convertir los keys a camelCase... es eso lo esperado?

encoder.encode({ bla_bla: true }) # => "data: {\"bla_bla\": true}\n\n" encoder.encode(OpenStruct.new(bla_bla: true) # => "data: {"blaBla": true}\n\n"

Esto pasará porque Hash responde a as_json

No había visto que Model define as_json. Encuentro raro que la misma transformación la hagamos en 2 partes.

Es verdad, esa parte lo hizo la IA, ahora que veo se quedó redundante si todo hereda de Model. Quité el método y ocupo directamente event.as_json.

fsateler · 2025-12-22T18:23:43Z

sdks/community/ruby/lib/ag_ui_protocol/util.rb

+          acc[k] = compacted
+        end
+      when Array
+        arr = value.map { |v| deep_compact(v) }.reject(&:nil?)


Esto genera 2 arrays, usando reject! eliminas la segunda copia.

Eso es para eliminar los valores que quedan en nil para evitar tener propiedades en nil.

Sí, a lo que me refiero es que este codigo es equivalente a:

tmp1 = value.map{ |v| deep_compact(v) } tmp2 = value.reject(&:nil?) arr = tmp2

Donde tmp1 y tmp2 son objetos distintos, con su asignación de memoria independiente (tmp1.object_id != tmp2.object_id). Lo que propongo es:

tmp1 = value.map{ |v| deep_compact(v) } tmp1.reject!(&:nil?) arr = tmp1

Lo que nos ahorra el generar un array. (ahora que lo releo, podría ser compact! tambien)

Puede que sea una optimización irrelevante, pero no se de que tamaño son los objetos que estarás generando.

sdks/community/ruby/Gemfile

fsateler · 2025-12-22T18:34:09Z

sdks/community/ruby/lib/ag_ui_protocol/encoder/event_encoder.rb

+        # @return [String]
+        sig { params(event: T.untyped).returns(String) }
+        def encode_sse(event)
+          payload = convert_payload_to_sse(event)


esto en realidad es convirtiendo a json, no a sse.

Nop, es SSE, ese formato "data: #{json_data}\n\n" es lo que se espera en el protocolo.

Pero el data: lo agregas despues. No lo haces dentro de convert_payload_to_sse

Ahora entendí lo que quiere decir, es el nombre del método convert_payload_to_sse . Tan poco es JSON, porque genera después igual, en la misma linea del SSE. Quité el método porque todo viene de Model y siempre van tener as_json. Agregué el tipo también a event para garantizar eso.

fsateler · 2025-12-22T18:39:18Z

docs/sdk/ruby/core/events.mdx

+description: "Documentation for the events used in the Agent User Interaction Protocol (Ruby SDK)"
+---
+
+# Events


Esto habrá que mantenerlo sincronizado con el codigo, pues es basicamente la docu del modulo Events. No podremos generarlo desde el yard? Idem para los otros docs

Lo voy hacer con yard-markdown.

Listo documentación creada con yard-markdown para mantener siempre actualizada con la documentación del modulo.

Basta ejecutar rake doc que actualiza los markdowns de acuerdo a la documentación de Ruby.

fsateler · 2025-12-22T21:23:53Z

sdks/community/ruby/lib/ag_ui_protocol/encoder/event_encoder.rb

+        # @return [String]
+        sig { params(event: T.untyped).returns(String) }
+        def encode_sse(event)
+          payload = convert_payload_to_sse(event)


Pero el data: lo agregas despues. No lo haces dentro de convert_payload_to_sse

fsateler · 2025-12-22T21:28:06Z

sdks/community/ruby/lib/ag_ui_protocol/encoder/event_encoder.rb

+        # @return [String, Object]
+        sig { params(event: T.untyped).returns(T.untyped) }
+        def convert_payload_to_sse(event)
+          if event.respond_to?(:as_json)


Entonces si paso un hash no se van a convertir los keys a camelCase... es eso lo esperado?

encoder.encode({ bla_bla: true }) # => "data: {\"bla_bla\": true}\n\n" encoder.encode(OpenStruct.new(bla_bla: true) # => "data: {"blaBla": true}\n\n"

Esto pasará porque Hash responde a as_json

fsateler · 2025-12-22T21:33:44Z

sdks/community/ruby/lib/ag_ui_protocol/util.rb

+          acc[k] = compacted
+        end
+      when Array
+        arr = value.map { |v| deep_compact(v) }.reject(&:nil?)


Sí, a lo que me refiero es que este codigo es equivalente a:

tmp1 = value.map{ |v| deep_compact(v) } tmp2 = value.reject(&:nil?) arr = tmp2

Donde tmp1 y tmp2 son objetos distintos, con su asignación de memoria independiente (tmp1.object_id != tmp2.object_id). Lo que propongo es:

tmp1 = value.map{ |v| deep_compact(v) } tmp1.reject!(&:nil?) arr = tmp1

Lo que nos ahorra el generar un array. (ahora que lo releo, podría ser compact! tambien)

Puede que sea una optimización irrelevante, pero no se de que tamaño son los objetos que estarás generando.

fsateler · 2025-12-22T21:35:45Z

sdks/community/ruby/lib/ag_ui_protocol/util.rb

+        value.each_with_object({}) do |(k, v), acc|
+          next if v.nil?
+          compacted = deep_compact(v)
+          next if compacted.nil?
+          acc[k] = compacted
+        end


Suggested change

value.each_with_object({}) do |(k, v), acc|

next if v.nil?

compacted = deep_compact(v)

next if compacted.nil?

acc[k] = compacted

end

value.transform_values { |v| deep_compact(v) unless v.nil? }.tap(&:compact!)

Mi obsesión por las asignaciones de memoria continúa jaja. (este tiene la ventaja de que no hace crecer el hash lo que puede ser que hagas varias asignaciones, pide una del tamaño máximo que podría tener el hash)

fsateler · 2025-12-22T21:37:04Z

sdks/community/ruby/test/ag_ui_protocol/core/events_test.rb

+require "test_helper"
+require "json"
+
+class EventsTest < Minitest::Test


Aca deberian haber tests de que el mensaje se codifica de manera exacta o no? Estas solo validando un atributo por evento (el type)

He mejorado los tests.

sdks/community/ruby/lib/ag_ui_protocol/core/types.rb

fsateler · 2025-12-22T21:40:14Z

sdks/community/ruby/lib/ag_ui_protocol/core/types.rb

+        # @return [Hash<Symbol, Object>]
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {}


Como esta es una clase abstracta, debería ser raise NotImplementedError creo yo

Ahí lo apliqué.

fsateler · 2025-12-22T21:41:47Z

sdks/community/ruby/lib/ag_ui_protocol/encoder/event_encoder.rb

+        # @return [String, Object]
+        sig { params(event: T.untyped).returns(T.untyped) }
+        def convert_payload_to_sse(event)
+          if event.respond_to?(:as_json)


No había visto que Model define as_json. Encuentro raro que la misma transformación la hagamos en 2 partes.

fsateler · 2025-12-22T21:42:14Z

sdks/community/ruby/lib/ag_ui_protocol/core/events.rb

+          {
+            type: @type,
+            timestamp: @timestamp,
+            raw_event: @raw_event


porque no retornamos altiro los keys camelCased?

Porque en Ruby normalmente no escribimos así. En la versión de Python igual convierte después, porque quien le gusta así es el front.

aboneto · 2025-12-23T20:18:32Z

Aplicado todos los cambios solicitados.

aboneto self-assigned this Dec 22, 2025

aboneto marked this pull request as draft December 22, 2025 14:45

aboneto force-pushed the feat/ruby-sdk branch 3 times, most recently from efe557e to 1334710 Compare December 22, 2025 18:26

fsateler reviewed Dec 22, 2025

View reviewed changes

aboneto force-pushed the feat/ruby-sdk branch from 1334710 to 69c1076 Compare December 22, 2025 18:39

fsateler reviewed Dec 22, 2025

View reviewed changes

aboneto force-pushed the feat/ruby-sdk branch 7 times, most recently from 3001f9e to c81f4ad Compare December 23, 2025 20:14

aboneto requested a review from fsateler December 23, 2025 20:18

aboneto force-pushed the feat/ruby-sdk branch 12 times, most recently from 92a7532 to 540a5f5 Compare December 29, 2025 14:24

aboneto force-pushed the feat/ruby-sdk branch from 540a5f5 to 7acddf6 Compare January 2, 2026 14:15

aboneto force-pushed the feat/ruby-sdk branch 2 times, most recently from 2e3f4b8 to 570279b Compare January 2, 2026 14:30

Antonio Barbosa added 3 commits January 5, 2026 20:45

feat: add Ruby SDK for AG-UI protocol

91c8e96

test: add test suite for Ruby SDK types, events and encoding

182b7d6

docs: add Ruby SDK documentation

7fffbc7

aboneto force-pushed the feat/ruby-sdk branch from 570279b to 7fffbc7 Compare January 5, 2026 23:45

aboneto closed this Jan 6, 2026

aboneto deleted the feat/ruby-sdk branch February 11, 2026 12:25

Conversation

aboneto commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fsateler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aboneto Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aboneto Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aboneto Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aboneto commented Dec 23, 2025

aboneto commented Dec 22, 2025 •

edited

Loading

aboneto Dec 23, 2025 •

edited

Loading

aboneto Dec 22, 2025 •

edited

Loading

aboneto Dec 23, 2025 •

edited

Loading