Class: Keycardai::A2A::Wire

Inherits:
Object
  • Object
show all
Defined in:
lib/keycardai/a2a/wire.rb

Overview

One protocol generation's wire conventions: the JSON-RPC method, the version header, and how message roles and text parts are spelled. The version selects the whole envelope, never only the header.

Constant Summary collapse

LEGACY_ROLES = 
{ ROLE_USER => "user", ROLE_AGENT => "agent" }.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(version:, header:, method_name:) ⇒ Wire

Returns a new instance of Wire.



51
52
53
54
55
 
# File 'lib/keycardai/a2a/wire.rb', line 51

def initialize(version:, header:, method_name:)
  @version = version
  @header = header
  @method_name = method_name
end

Instance Attribute Details

#header ⇒ Object (readonly)

Returns the value of attribute header.



49
50
51
 
# File 'lib/keycardai/a2a/wire.rb', line 49

def header
  @header
end

#method_name ⇒ Object (readonly)

Returns the value of attribute method_name.



49
50
51
 
# File 'lib/keycardai/a2a/wire.rb', line 49

def method_name
  @method_name
end

#version ⇒ Object (readonly)

Returns the value of attribute version.



49
50
51
 
# File 'lib/keycardai/a2a/wire.rb', line 49

def version
  @version
end

Class Method Details

.for(version) ⇒ Object

Parameters:

  • version (String) —

    PROTOCOL_VERSION or LEGACY_PROTOCOL_VERSION

Raises:

  • (ArgumentError) —

    any other value



37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/keycardai/a2a/wire.rb', line 37

def self.for(version)
  case version
  when PROTOCOL_VERSION
    new(version: version, header: PROTOCOL_VERSION_HEADER, method_name: MESSAGE_SEND_METHOD)
  when LEGACY_PROTOCOL_VERSION
    new(version: version, header: LEGACY_PROTOCOL_VERSION_HEADER, method_name: LEGACY_MESSAGE_SEND_METHOD)
  else
    raise ArgumentError, "unsupported A2A protocol version #{version.inspect} " \
                         "(supported: #{PROTOCOL_VERSION}, #{LEGACY_PROTOCOL_VERSION})"
  end
end

Instance Method Details

#encode_params(params) ⇒ Object

Encode 1.0-shaped params (as built by A2A.text_message) for the wire. On 1.0 they pass through; on 0.3 the message role takes its 0.3 name and text parts gain the kind tag 0.3 requires.



64
65
66
67
68
69
70
71
72
 
# File 'lib/keycardai/a2a/wire.rb', line 64

def encode_params(params)
  message = params.is_a?(Hash) ? params["message"] : nil
  return params unless legacy? && message.is_a?(Hash)

  params.merge("message" => message.merge(
    "role" => LEGACY_ROLES.fetch(message["role"], message["role"]),
    "parts" => Array(message["parts"]).map { |part| legacy_part(part) }
  ))
end

#endpoint_from(card) ⇒ Object

The invocation endpoint from an agent card: a 1.0 card's JSONRPC interface (preferring the one matching this version), else a 0.3 card's url, else nil.



77
78
79
80
81
82
83
 
# File 'lib/keycardai/a2a/wire.rb', line 77

def endpoint_from(card)
  interfaces = Array(card["supportedInterfaces"]).select { |iface| jsonrpc_interface?(iface) }
  matching = interfaces.find { |iface| iface["protocolVersion"] == version } || interfaces.first
  return matching["url"] if matching

  card["url"] if card["url"].is_a?(String) && !card["url"].empty?
end

#legacy? ⇒ Boolean

Returns:

  • (Boolean) 


57
58
59
 
# File 'lib/keycardai/a2a/wire.rb', line 57

def legacy?
  version == LEGACY_PROTOCOL_VERSION
end