llm.rb 10.0.0 → 11.0.0

data/lib/llm/a2a.rb

@@ -0,0 +1,452 @@
+# frozen_string_literal: true
+
+##
+# The {LLM::A2A} class provides access to agents that implement the
+# Agent2Agent (A2A) Protocol. A2A defines a standard way for
+# independent AI agents to discover each other's capabilities,
+# negotiate interaction modalities, and collaborate on tasks.
+#
+# In llm.rb, {LLM::A2A} supports both HTTP+JSON/REST and JSON-RPC 2.0
+# protocol bindings and focuses on discovering agent skills that can be
+# used through {LLM::Context} and {LLM::Agent}.
+#
+# Requests can be made concurrently and responses are matched by task id.
+#
+# @example REST binding (default)
+#   a2a = LLM::A2A.rest(url: "https://agent.example.com")
+#   card = a2a.card
+#   puts card.skills.map(&:name)
+#   task = a2a.send_message("What is the weather in Tokyo?").task
+#   a2a.tasks.get(task.id)
+#
+# @example JSON-RPC binding
+#   a2a = LLM::A2A.jsonrpc(url: "https://agent.example.com")
+#
+# @example Using skills as tools in a context
+#   llm = LLM.openai(key: ENV["KEY"])
+#   a2a = LLM::A2A.rest(url: "https://agent.example.com")
+#   ctx = LLM::Context.new(llm, tools: a2a.skills)
+#   ctx.talk("Analyze this data using the remote agent.")
+#   ctx.talk(ctx.wait(:call)) while ctx.functions?
+class LLM::A2A
+  require_relative "a2a/card"
+  require_relative "a2a/error"
+  require_relative "a2a/tasks"
+  require_relative "a2a/notifications"
+  require_relative "a2a/transport/http"
+
+  ##
+  # @param [Symbol] binding
+  #  The protocol binding to use. One of `:rest` (HTTP+JSON/REST) or
+  #  `:jsonrpc` (JSON-RPC 2.0). Defaults to `:rest`.
+  # @param [Object] transport
+  #  The transport used to communicate with the remote A2A agent
+  # @param [String] base_path
+  #  Optional base path prefix for REST endpoints
+  # @param [String] protocol_version
+  #  The expected A2A protocol version. Defaults to `"1.0"`.
+  # @return [LLM::A2A]
+  def initialize(transport:, binding: :rest, base_path: "", protocol_version: "1.0")
+    @binding = binding
+    @base_path = LLM::Utils.normalize_base_path(base_path)
+    @protocol_version = protocol_version
+    @transport = transport
+  end
+
+  ##
+  # Builds an A2A client over HTTP.
+  # @param [String] url
+  #  The base URL of the A2A agent (e.g., "https://agent.example.com")
+  # @param [Hash<String, String>] headers
+  #  Extra HTTP headers to include in requests (e.g., Authorization)
+  # @param [Integer, nil] timeout
+  #  The timeout in seconds for HTTP requests
+  # @param [LLM::Transport, Class, nil] transport
+  #  Optional override with any {LLM::Transport} instance or subclass
+  # @param [Symbol] binding
+  #  The protocol binding to use. One of `:rest` or `:jsonrpc`
+  # @param [String] base_path
+  #  Optional base path prefix for REST endpoints
+  # @param [String] protocol_version
+  #  The expected A2A protocol version. Defaults to `"1.0"`.
+  # @return [LLM::A2A]
+  def self.http(url:, headers: {}, timeout: 30, transport: nil, binding: :rest, base_path: "", protocol_version: "1.0")
+    new(
+      binding:,
+      base_path:,
+      protocol_version:,
+      transport: Transport::HTTP.new(
+        url:,
+        headers:,
+        timeout:,
+        transport:,
+        protocol_version:
+      )
+    )
+  end
+
+  ##
+  # Builds an A2A client over HTTP+JSON/REST.
+  # @param [String] url
+  # @param [Hash<String, String>] headers
+  # @param [Integer, nil] timeout
+  # @param [LLM::Transport, Class, nil] transport
+  # @return [LLM::A2A]
+  def self.rest(url:, headers: {}, timeout: 30, transport: nil, base_path: "", protocol_version: "1.0")
+    http(
+      url:,
+      headers:,
+      timeout:,
+      transport:,
+      binding: :rest,
+      base_path:,
+      protocol_version:
+    )
+  end
+
+  ##
+  # Builds an A2A client over HTTP+JSON with JSON-RPC 2.0.
+  # @param [String] url
+  # @param [Hash<String, String>] headers
+  # @param [Integer, nil] timeout
+  # @param [LLM::Transport, Class, nil] transport
+  # @return [LLM::A2A]
+  def self.jsonrpc(url:, headers: {}, timeout: 30, transport: nil, base_path: "", protocol_version: "1.0")
+    http(
+      url:,
+      headers:,
+      timeout:,
+      transport:,
+      binding: :jsonrpc,
+      base_path:,
+      protocol_version:
+    )
+  end
+
+  ##
+  # Returns the active protocol binding.
+  # @return [Symbol]
+  attr_reader :binding
+
+  ##
+  # Returns the remote agent card.
+  #
+  # The agent card is fetched from `/.well-known/agent-card.json` and
+  # cached for the lifetime of this client instance.
+  # @return [LLM::A2A::Card]
+  def card
+    return @card if defined?(@card)
+    @card = LLM::A2A::Card.new(transport.get("/.well-known/agent-card.json"))
+  end
+  alias_method :agent_card, :card
+
+  ##
+  # Returns the agent's skills adapted as callable tools.
+  #
+  # Each skill in the agent card is mapped to an {LLM::Tool} subclass
+  # that wraps a {#send_message} call. When the tool is called, it
+  # sends a message to the remote agent and returns the task artifacts
+  # as the result.
+  # @return [Array<Class<LLM::Tool>>]
+  def skills
+    @skills ||= card.skills.map { LLM::Tool.a2a(self, _1) }
+  end
+  alias_method :tools, :skills
+
+  ##
+  # Returns task-oriented A2A operations.
+  # @return [LLM::A2A::Tasks]
+  def tasks
+    @tasks ||= LLM::A2A::Tasks.new(self)
+  end
+
+  ##
+  # Returns push notification configuration operations.
+  # @return [LLM::A2A::Notifications]
+  def notifications
+    @notifications ||= LLM::A2A::Notifications.new(self)
+  end
+
+  ##
+  # Sends a message to the agent and returns the response.
+  # @param [String] text The message text to send
+  # @param [Hash] config
+  #  Optional configuration (accepted_output_modes, return_immediately)
+  # @param [Hash, nil] metadata
+  #  Optional metadata to attach to the request
+  # @return [LLM::Object] The task or message response
+  def send_message(text, configuration = {}, metadata: nil)
+    body = build_request(
+      "SendMessage",
+      message: {role: "ROLE_USER", parts: [{text:}], messageId: SecureRandom.uuid},
+      configuration:,
+      metadata:
+    )
+    execute_request(body)
+  end
+
+  ##
+  # Sends a streaming message to the agent.
+  #
+  # The block is called for each {LLM::Object} event in the stream
+  # (Task, Message, TaskStatusUpdateEvent, TaskArtifactUpdateEvent).
+  # @param [String] text The message text to send
+  # @param [Hash] config Optional configuration
+  # @yieldparam [LLM::Object] event A stream event
+  # @return [void]
+  def send_streaming_message(text, configuration = {}, &on_event)
+    body = build_request(
+      "SendStreamingMessage",
+      message: {role: "ROLE_USER", parts: [{text:}], messageId: SecureRandom.uuid},
+      configuration:
+    )
+    execute_stream(body, &on_event)
+  end
+
+  ##
+  # Gets the current state of a task.
+  # @param [String] task_id The task ID to retrieve
+  # @param [Integer, nil] history_length
+  #  Optional limit on recent messages to include
+  # @return [LLM::Object]
+  def get_task(task_id, history_length: nil)
+    case @binding
+    when :rest
+      path = rest_path("/tasks/#{task_id}")
+      path = "#{path}?historyLength=#{history_length}" if history_length
+      res = transport.get(path)
+    when :jsonrpc
+      body = build_request("GetTask", id: task_id, historyLength: history_length)
+      res = transport.post("/", body)
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::Object.from(res)
+  end
+
+  ##
+  # Cancels a task in progress.
+  # @param [String] task_id The task ID to cancel
+  # @param [Hash, nil] metadata Optional metadata to attach to the request
+  # @return [LLM::Object]
+  def cancel_task(task_id, metadata: nil)
+    body = build_request("CancelTask", id: task_id, metadata:)
+    case @binding
+    when :rest
+      res = transport.post(rest_path("/tasks/#{task_id}:cancel"), body)
+    when :jsonrpc
+      res = transport.post("/", body)
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::Object.from(res)
+  end
+
+  ##
+  # Subscribes to streaming updates for an existing task.
+  # @param [String] task_id The task ID to subscribe to
+  # @yieldparam [LLM::Object] event A stream event
+  # @return [void]
+  def subscribe_to_task(task_id, &on_event)
+    case @binding
+    when :rest
+      transport.get_stream(rest_path("/tasks/#{task_id}:subscribe")) { on_event&.call(LLM::Object.from(_1)) }
+    when :jsonrpc
+      body = build_request("SubscribeToTask", id: task_id)
+      transport.post_stream("/", body) { on_event&.call(LLM::Object.from(_1)) }
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+  end
+
+  ##
+  # Lists tasks with optional filtering.
+  # @param [String, nil] context_id Optional context ID to filter by
+  # @param [String, nil] status Optional task state to filter by
+  # @param [Integer, nil] history_length Optional limit on recent messages to include
+  # @param [String, nil] status_timestamp_after Optional lower bound for status timestamp filtering
+  # @param [Boolean, nil] include_artifacts Whether to include task artifacts
+  # @param [Integer] page_size Maximum number of tasks to return
+  # @param [String, nil] page_token Pagination cursor
+  # @return [LLM::Object]
+  def list_tasks(context_id: nil, status: nil, history_length: nil, status_timestamp_after: nil,
+                 include_artifacts: nil, page_size: 20, page_token: nil)
+    case @binding
+    when :rest
+      params = {}
+      params[:contextId] = context_id if context_id
+      params[:status] = status if status
+      params[:historyLength] = history_length if history_length
+      params[:statusTimestampAfter] = status_timestamp_after if status_timestamp_after
+      params[:includeArtifacts] = include_artifacts unless include_artifacts.nil?
+      params[:pageSize] = page_size if page_size
+      params[:pageToken] = page_token if page_token
+      query = URI.encode_www_form(params)
+      path = rest_path("/tasks")
+      path = "#{path}?#{query}" unless query.empty?
+      res = transport.get(path)
+    when :jsonrpc
+      body = build_request("ListTasks", contextId: context_id, status: status,
+                                        historyLength: history_length,
+                                        statusTimestampAfter: status_timestamp_after,
+                                        includeArtifacts: include_artifacts,
+                                        pageSize: page_size, pageToken: page_token)
+      res = transport.post("/", body)
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::Object.from(res)
+  end
+
+  ##
+  # Creates a push notification configuration for a task.
+  # @param [String] task_id The parent task ID
+  # @param [String] url The callback URL
+  # @param [String, nil] token Optional token to include with notifications
+  # @param [Hash, nil] authentication Optional authentication information
+  # @param [String, nil] id Optional configuration ID
+  # @return [LLM::Object]
+  def create_task_push_notification_config(task_id, url:, token: nil, authentication: nil, id: nil)
+    body = build_request("CreateTaskPushNotificationConfig", taskId: task_id, url:, token:, authentication:, id:)
+    case @binding
+    when :rest
+      res = transport.post(rest_path("/tasks/#{task_id}/pushNotificationConfigs"), body)
+    when :jsonrpc
+      res = transport.post("/", body)
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::Object.from(res)
+  end
+
+  ##
+  # Retrieves a push notification configuration for a task.
+  # @param [String] task_id The parent task ID
+  # @param [String] id The configuration ID
+  # @return [LLM::Object]
+  def get_task_push_notification_config(task_id, id)
+    case @binding
+    when :rest
+      res = transport.get(rest_path("/tasks/#{task_id}/pushNotificationConfigs/#{id}"))
+    when :jsonrpc
+      body = build_request("GetTaskPushNotificationConfig", taskId: task_id, id:)
+      res = transport.post("/", body)
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::Object.from(res)
+  end
+
+  ##
+  # Lists push notification configurations for a task.
+  # @param [String] task_id The parent task ID
+  # @param [Integer, nil] page_size Maximum number of configurations to return
+  # @param [String, nil] page_token Pagination cursor
+  # @return [LLM::Object]
+  def list_task_push_notification_configs(task_id, page_size: nil, page_token: nil)
+    case @binding
+    when :rest
+      params = {}
+      params[:pageSize] = page_size if page_size
+      params[:pageToken] = page_token if page_token
+      query = URI.encode_www_form(params)
+      path = rest_path("/tasks/#{task_id}/pushNotificationConfigs")
+      path = "#{path}?#{query}" unless query.empty?
+      res = transport.get(path)
+    when :jsonrpc
+      body = build_request("ListTaskPushNotificationConfigs", taskId: task_id, pageSize: page_size, pageToken: page_token)
+      res = transport.post("/", body)
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::Object.from(res)
+  end
+
+  ##
+  # Deletes a push notification configuration for a task.
+  # @param [String] task_id The parent task ID
+  # @param [String] id The configuration ID
+  # @return [LLM::Object]
+  def delete_task_push_notification_config(task_id, id)
+    case @binding
+    when :rest
+      res = transport.delete(rest_path("/tasks/#{task_id}/pushNotificationConfigs/#{id}"))
+    when :jsonrpc
+      body = build_request("DeleteTaskPushNotificationConfig", taskId: task_id, id:)
+      res = transport.post("/", body)
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::Object.from(res)
+  end
+
+  ##
+  # Returns the authenticated extended agent card.
+  # @return [LLM::A2A::Card]
+  def extended_card
+    case @binding
+    when :rest
+      res = transport.get(rest_path("/extendedAgentCard"))
+    when :jsonrpc
+      body = build_request("GetExtendedAgentCard")
+      res = transport.post("/", body)
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::A2A::Card.new(res)
+  end
+  alias_method :get_extended_agent_card, :extended_card
+
+  ##
+  # @return [String]
+  def inspect
+    "#<#{LLM::Utils.object_id(self)} @binding=#{@binding.inspect}>"
+  end
+
+  private
+
+  attr_reader :transport
+
+  def build_request(method, **params)
+    case @binding
+    when :rest
+      params
+    when :jsonrpc
+      {jsonrpc: "2.0", method:, params: params.compact, id: SecureRandom.uuid}
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+  end
+
+  def execute_request(body)
+    res = case @binding
+    when :rest
+      transport.post(rest_path("/message:send"), body)
+    when :jsonrpc
+      res = transport.post("/", body)
+      if res["error"]
+        raise LLM::A2A::Error.new(res["error"]["message"], res["error"]["code"])
+      end
+      res["result"] || res
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+    LLM::Object.from(res)
+  end
+
+  def execute_stream(body, &on_event)
+    case @binding
+    when :rest
+      transport.post_stream(rest_path("/message:stream"), body) { on_event&.call(LLM::Object.from(_1)) }
+    when :jsonrpc
+      transport.post_stream("/", body) { on_event&.call(LLM::Object.from(_1)) }
+    else
+      raise LLM::A2A::Error, "Invalid A2A binding: #{@binding.inspect}"
+    end
+  end
+
+  def rest_path(path)
+    return path if @base_path.empty?
+    "#{@base_path}#{path}"
+  end
+end

data/lib/llm/active_record/acts_as_agent.rb

@@ -11,19 +11,24 @@ module LLM::ActiveRecord
   # class and forwarded to an internal agent subclass.
   module ActsAsAgent
     module ClassMethods
-      def model(model = nil)
-        return agent.model if model.nil?
-        agent.model(model)
+      def model(model = nil, &block)
+        return agent.model if model.nil? && !block
+        agent.model(model, &block)
       end
 
-      def tools(*tools)
-        return agent.tools if tools.empty?
-        agent.tools(*tools)
+      def tools(*tools, &block)
+        return agent.tools if tools.empty? && !block
+        agent.tools(*tools, &block)
       end
 
-      def schema(schema = nil)
-        return agent.schema if schema.nil?
-        agent.schema(schema)
+      def skills(*skills, &block)
+        return agent.skills if skills.empty? && !block
+        agent.skills(*skills, &block)
+      end
+
+      def schema(schema = nil, &block)
+        return agent.schema if schema.nil? && !block
+        agent.schema(schema, &block)
       end
 
       def instructions(instructions = nil)
@@ -121,6 +126,7 @@ module LLM::ActiveRecord
             when :json, :jsonb then ctx.restore(data:)
             else raise ArgumentError, "Unknown format: #{options[:format].inspect}"
             end
+            ctx
           end
         end
       end

data/lib/llm/active_record/acts_as_llm.rb

@@ -59,12 +59,12 @@ module LLM::ActiveRecord
       end
 
       ##
-      # Continues the stored context through the Responses API and flushes it.
-      # @see LLM::Context#respond
+      # Continues the stored context with new input and flushes it.
+      # @see LLM::Context#ask
       # @return [LLM::Response]
-      def respond(...)
+      def ask(...)
         options = self.class.llm_plugin_options
-        ctx.respond(...).tap { Utils.save!(self, ctx, options) }
+        ctx.ask(...).tap { Utils.save!(self, ctx, options) }
       end
 
       ##

data/lib/llm/agent.rb

@@ -221,9 +221,14 @@ module LLM
     #   response = agent.talk("Hello, what is your name?")
     #   puts response.choices[0].content
     def talk(prompt, params = {})
-      run_loop(prompt, params)
+      run_loop(prompt, params, :talk)
+    end
+
+    ##
+    # @see LLM::Context#ask
+    def ask(prompt, params = {})
+      run_loop(prompt, params, :ask)
     end
-    alias_method :chat, :talk
 
     ##
     # @return [LLM::Buffer<LLM::Message>]
@@ -366,13 +371,13 @@ module LLM
     ##
     # @return [String]
     def to_json(...)
-      to_h.to_json(...)
+      LLM.json.dump(to_h, ...)
     end
 
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "#<#{LLM::Utils.object_id(self)} " \
       "@llm=#{@llm.class}, @mode=#{mode.inspect}, @messages=#{messages.inspect}>"
     end
 
@@ -451,22 +456,23 @@ module LLM
     ##
     # Runs the tool loop
     # @api private
-    def run_loop(prompt, params)
+    def run_loop(prompt, params, target)
       run = proc do
+        talk = @ctx.method(target)
         max = params.key?(:tool_attempts) ? params.delete(:tool_attempts) : 25
         max = Integer(max) if max
         stream = params[:stream] || @ctx.params[:stream]
         stream.extra[:concurrency] = concurrency if LLM::Stream === stream
-        res = @ctx.talk(apply_instructions(prompt), params)
+        res = talk.call(apply_instructions(prompt), params)
         while @ctx.functions?
           if max
             max.times do
               break unless @ctx.functions?
-              res = @ctx.talk(call_functions, params)
+              res = talk.call(call_functions, params)
             end
-            res = @ctx.talk(@ctx.functions.map(&:rate_limit), params) if @ctx.functions?
+            res = talk.call(@ctx.functions.map(&:rate_limit), params) if @ctx.functions?
           else
-            res = @ctx.talk(call_functions, params)
+            res = talk.call(call_functions, params)
           end
         end
         res

data/lib/llm/buffer.rb

@@ -97,8 +97,7 @@ module LLM
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
-      "message_count=#{@messages.size}>"
+      "#<#{LLM::Utils.object_id(self)} message_count=#{@messages.size}>"
     end
 
     ##

data/lib/llm/context.rb

@@ -201,12 +201,37 @@ module LLM
       @messages.concat [res.choices[-1]]
       res
     end
-    alias_method :chat, :talk
+
+    ##
+    # Ask a question and return the content string directly.
+    # Accepts `with:` for file attachments and a block for streaming.
+    # This interface is compatible with RubyLLM's `ask` method.
+    # @param [String] prompt
+    # @param [Hash] options
+    # @option options [String, Array<String>, nil] :with
+    #  File path(s) to attach
+    # @option options [#<<, LLM::Stream, nil] :stream
+    #  A stream target
+    # @yield [String] content chunks when streaming
+    # @return [LLM::Response]
+    def ask(prompt, options = {}, &block)
+      options = {with: nil, stream: nil}.merge!(options || {})
+      with, stream = options.values_at(:with, :stream)
+      prompt = with ? [prompt, [*with].map { local_file(_1) }] : prompt
+      target = if block
+        blk = block.dup
+        blk.singleton_class.alias_method(:<<, :call)
+        blk
+      else
+        stream
+      end
+      target ? talk(prompt, stream: target) : talk(prompt)
+    end
 
     ##
     # @return [String]
     def inspect
-      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+      "#<#{LLM::Utils.object_id(self)} " \
       "@llm=#{@llm.class}, @mode=#{@mode.inspect}, @params=#{@params.inspect}, " \
       "@messages=#{@messages.inspect}>"
     end
@@ -414,7 +439,7 @@ module LLM
     ##
     # @return [String]
     def to_json(...)
-      to_h.to_json(...)
+      LLM.json.dump(to_h, ...)
     end
 
     ##
@@ -475,8 +500,9 @@ module LLM
     # Returns the bound stream queue, if available.
     # @api private
     def queue
-      return @queue if @queue
-      stream.queue if LLM::Stream === stream
+      [@queue, stream&.queue].compact.first
+    rescue NoMethodError
+      nil
     end
 
     ##

data/lib/llm/file.rb

@@ -43,6 +43,13 @@ class LLM::File
     mime_type == "application/pdf"
   end
 
+  ##
+  # @return [Boolean]
+  #  Returns true if the file exists on disk
+  def exist?
+    File.exist?(path)
+  end
+
   ##
   # @return [Integer]
   #  Returns the size of the file in bytes

data/lib/llm/function.rb

@@ -182,7 +182,7 @@ class LLM::Function
   def define(klass = nil, &b)
     @runner = klass || b
   end
-  alias_method :register, :define
+  alias_method :def, :define
 
   ##
   # Call the function