llm.rb 16.0.0 → 17.0.0

data/lib/llm/agent.rb

@@ -2,48 +2,30 @@
 
 module LLM
   ##
-  # {LLM::Agent LLM::Agent} is the recommended entry point for most
-  # use-cases. It provides a class-level DSL for defining reusable,
-  # preconfigured assistants with defaults for model, tools, schema,
-  # and instructions.
+  # Unlike {LLM::Context LLM::Context}
+  # the {LLM::Agent LLM::Agent} class
+  # automatically manages the tool loop.
   #
-  # It wraps the same stateful runtime surface as
-  # {LLM::Context LLM::Context}: message history, usage, persistence,
-  # streaming parameters, and provider-backed requests still flow through
-  # an underlying context. The defining behavior of an agent is that it
-  # automatically resolves pending tool calls for you during `talk`,
-  # instead of leaving tool loops to the caller.
+  # @example class Agent < LLM::Agent
+  #   class Agent < LLM::Agent
+  #     set name: "sam altman",
+  #         description: "a ceo",
+  #         instructions: "beat the competition",
+  #         tools: :toolset,
+  #         stream: proc { Stream.new(llm) }
   #
-  # **Notes:**
-  # * Instructions are injected once, and kept in step after that. A
-  #   restored conversation carries the instructions that were current
-  #   when it started, and the message is brought up to date before the
-  #   next request goes out.
-  # * An agent automatically executes tool loops (unlike {LLM::Context LLM::Context}).
-  # * The tool loop can be bounded with `tool_budget`. Once the budget is
-  #   spent, no further tool calls are run for that turn: the agent sends an
-  #   in-band advisory message back through the model instead, and keeps
-  #   sending it while the model keeps asking for tools. The budget counts
-  #   tool calls, so a batch of calls is spent as a batch, and a batch that
-  #   would take the turn past its budget is not run at all. By default no
-  #   budget is set (`nil`), so the feature is disabled.
-  # * Tool loop execution can be configured with `concurrency :sequential`,
-  #   `:thread`, `:async`, `:fiber`, `:fork`, or `:ractor`.
-  #
-  # @example Subclass with defaults
-  #   class SystemAdmin < LLM::Agent
-  #     set model: "gpt-4.1-nano",
-  #         instructions: "You are a Linux system admin",
-  #         tools: [LLM::Tool::Exec],
-  #         schema: Result
+  #     private
+  #     def toolset
+  #       [LLM::Tool::Exec]
+  #     end
   #   end
   #
-  #   llm = LLM.openai(key: ENV["KEY"])
-  #   agent = SystemAdmin.new(llm)
-  #   agent.talk("Run 'date'")
+  #   llm   = LLM.openai
+  #   agent = Agent.new(llm)
+  #   agent.talk("setup ollama to run gpt-oss")
   #
-  # @example Direct instance
-  #   llm = LLM.deepseek(key: ENV["KEY"])
+  # @example LLM::Agent.new
+  #   llm   = LLM.deepseek
   #   agent = LLM::Agent.new(llm, stream: $stdout)
   #   agent.talk "Hello world"
   #
@@ -52,6 +34,7 @@ module LLM
   # @see LLM::Stream Stream callbacks for model output
   class Agent
     require_relative "agent/interrupt"
+    require_relative "agent/registry"
 
     ##
     # @api private
@@ -59,15 +42,12 @@ module LLM
     private_constant :UNDEFINED
 
     ##
-    # Marks the message an agent injects as its own, so that a later
-    # turn can tell it from a message the caller composed. The role
-    # cannot do that: it is true of whatever the caller put there.
+    # @return [Hash]
     # @api private
     INSTRUCTIONS = {instructions: true}.freeze
     private_constant :INSTRUCTIONS
 
     ##
-    # Ugh :)
     # @api private
     FIELDS = %i[record
                 name description
@@ -76,12 +56,14 @@ module LLM
                 skills schema
                 tracer stream
                 tools concurrency
-                instructions confirm]
+                instructions confirm
+                intercept]
     IVARS  =  %i[record
                  name description
                  path tool_budget
                  tracer concurrency
-                 instructions confirm]
+                 instructions confirm
+                 intercept]
     private_constant :FIELDS, :IVARS
 
     ##
@@ -94,39 +76,54 @@ module LLM
     File = ::File
     private_constant :File
 
+    ##
+    # @return [LLM::Agent::Registry]
+    REGISTRY = Registry.new
+    private_constant :REGISTRY
+
     ##
     # Returns a provider
     # @return [LLM::Provider]
     attr_reader :llm
 
     ##
-    # Bulk-assign class-level agent defaults from a Hash.
-    #
-    # Each key is resolved by calling the corresponding class method on the
-    # agent subclass. An error is raised for unknown keys so that typos are
-    # caught early.
+    # Returns an instance of {LLM::Agent::Registry LLM::Agent::Registry}.
+    # @note
+    #  The registry holds all _active_
+    #  instances of {LLM::Agent LLM::Agent}
+    #  and inactive agents are automatically
+    #  removed from the registry. The registry
+    #  is local to a process, and its children.
+    # @return [LLM::Agent::Registry]
+    def self.registry
+      REGISTRY
+    end
+
+    ##
+    # Bulk-assign class-level defaults
     #
     # @example
-    #   class AdminAgent < LLM::Agent
-    #     set name: "admin",
-    #         instructions: "You are a system administrator",
-    #         model: "gpt-4.1-nano",
+    #   class Agent < LLM::Agent
+    #     set name: "007",
+    #         description: "a secret agrent",
+    #         instructions: "find top secret material",
     #         tools: [LLM::Tool::Exec, LLM::Tool::ReadFile]
     #   end
     #
     # @param [Hash] properties
     # @option properties [String, Symbol, Proc] :name
     # @option properties [String, Symbol, Proc] :description
-    # @option properties [String] :instructions
-    # @option properties [String] :model
-    # @option properties [Array<LLM::Function>] :tools
-    # @option properties [Array<String>] :skills
-    # @option properties [#to_json] :schema
+    # @option properties [String, Symbol, Proc] :instructions
+    # @option properties [String, Symbol, Proc] :model
+    # @option properties [LLM::Tracer, Symbol, Proc] :tracer
+    # @option properties [LLM::Stream, Symbol, Proc] :stream
+    # @option properties [LLM::Schema, Symbol, Proc] :schema
+    # @option properties [Array<LLM::Function>, Symbol, Proc] :tools
+    # @option properties [Array<String>, Symbol, Proc] :skills
     # @option properties [Symbol, Array<Symbol>] :concurrency
-    # @option properties [LLM::Tracer, Proc] :tracer
-    # @option properties [Object, Proc] :stream
     # @option properties [String, Symbol, Array<String, Symbol>, Proc] :confirm
-    # @raise [KeyError] when a property key does not match a class-level accessor
+    # @raise [KeyError]
+    #   When a given key does not match a class-level accessor
     # @return [void]
     def self.set(properties)
       properties.each do
@@ -189,162 +186,121 @@ module LLM
     end
 
     ##
-    # Set or get the default model
-    # @param [String, nil] model
-    #  The model identifier
-    # @return [String, nil]
-    #  Returns the current model when no argument is provided
-    def self.model(model = nil, &block)
-      return @model if model.nil? and !block
-      @model = block || model
-    end
-
-    ##
-    # Set or get the default schema
-    # @param [#to_json, nil] schema
-    #  The schema
-    # @return [#to_json, nil]
-    #  Returns the current schema when no argument is provided
-    def self.schema(schema = nil, &block)
-      return @schema if schema.nil? and !block
-      @schema = block || schema
-    end
-
-    ##
-    # Set or get the default tools
-    # @param [Array<LLM::Function>, nil] tools
-    #  One or more tools
-    # @return [Array<LLM::Function>]
-    #  Returns the current tools when no argument is provided
-    def self.tools(*tools, &block)
-      return @tools || [] if tools.empty? and !block
-      if block
-        @tools = block
-      elsif single_callable?(tools)
-        @tools = tools.first
+    # Set or get the tool execution concurrency.
+    # @param [Symbol, Array<Symbol>, nil] concurrency
+    #  Controls how pending tool loops are executed:
+    #  - `:sequential`: sequential calls
+    #  - `:thread`: concurrent threads
+    #  - `:async`: concurrent async tasks
+    #  - `:fiber`: concurrent scheduler-backed fibers
+    #  - `:fork`: a child process
+    #  - `:ractor`: Ruby-based ractors
+    # @return [Symbol, Array<Symbol>, nil]
+    def self.concurrency(concurrency = UNDEFINED)
+      if concurrency.equal?(UNDEFINED)
+        @concurrency
       else
-        @tools = tools.flatten
+        @concurrency = concurrency
       end
     end
 
     ##
-    # Set or get the default skills
-    # @param [Array<String>, nil] skills
-    #  One or more skill directories
-    # @return [Array<String>, nil]
-    #  Returns the current skills when no argument is provided
-    def self.skills(*skills, &block)
-      return @skills if skills.empty? and !block
-      if block
-        @skills = block
-      elsif single_callable?(skills)
-        @skills = skills.first
+    # Set or get the model an agent will use
+    # @param [String, Symbol] model
+    #  The model
+    # @param [Proc] block
+    #  A block that is lazy-evaled.
+    # @return [String, nil]
+    #  Returns the model
+    def self.model(model = UNDEFINED, &block)
+     if model.equal?(UNDEFINED) and block.nil?
+        @model
       else
-        @skills = skills.flatten
+        @model = block || model
       end
     end
 
     ##
-    # Set or get the tool names that require confirmation before they can run.
-    #
-    # When a single Symbol is given, it is stored as-is and resolved at
-    # initialization time by calling the method with that name on the agent
-    # instance. This allows dynamic tool confirmation lists.
-    #
-    # @example
-    #   class MyAgent < LLM::Agent
-    #     confirm :tools_that_need_confirmation
-    #
-    #     def tools_that_need_confirmation
-    #       some_condition ? %w[delete destroy] : %w[delete]
-    #     end
-    #   end
-    #
-    # @param [String, Symbol, Array<String, Symbol>, Proc] tool_names
-    #  One or more tool names.
+    # Set or get an agent's schema
+    # @param [LLM::Schema, Symbol] schema
+    #  The schema
     # @param [Proc] block
-    #  An optional, lazy-evaluated Proc
-    # @return [Array<String>, Proc, Symbol, nil]
-    def self.confirm(*tool_names, &block)
-      return @confirm if tool_names.empty? and !block
-      if block
-        @confirm = block
-      elsif single_callable?(tool_names)
-        @confirm = tool_names.first
+    #  A block that is lazy-evaled.
+    # @return [LLM::Schema, nil]
+    #  Returns a schema
+    def self.schema(schema = UNDEFINED, &block)
+     if schema.equal?(UNDEFINED) and block.nil?
+        @schema
       else
-        @confirm = tool_names.flatten.map(&:to_s)
+        @schema = block || schema
       end
     end
 
     ##
-    # Set or get the default instructions
-    # @param [String, nil] instructions
+    # Set or get an agent's instructions
+    # @param [String, Symbol, nil] instructions
     #  The system instructions
+    # @param [Proc] block
+    #  A block that is lazy-evaled.
     # @return [String, nil]
-    #  Returns the current instructions when no argument is provided
-    def self.instructions(instructions = nil)
-      return @instructions if instructions.nil?
-      @instructions = instructions
-    end
-
-    ##
-    # Set or get the tool execution concurrency.
-    #
-    # @param [Symbol, Array<Symbol>, nil] concurrency
-    #  Controls how pending tool loops are executed:
-    #  - `:sequential`: sequential calls
-    #  - `:thread`: concurrent threads
-    #  - `:async`: concurrent async tasks
-    #  - `:fiber`: concurrent scheduler-backed fibers
-    #  - `:fork`: forked child processes
-    #  - `:ractor`: concurrent Ruby ractors for class-based tools; MCP tools are not supported,
-    #    and this mode is especially useful for CPU-bound tool work
-    #  Usually pass a single strategy. Arrays are only for advanced mixed-work
-    #  cases and are not needed for normal queued stream tool loops.
-    # @return [Symbol, Array<Symbol>, nil]
-    def self.concurrency(concurrency = nil)
-      return @concurrency if concurrency.nil?
-      @concurrency = concurrency
+    #  Returns the instructions
+    def self.instructions(instructions = UNDEFINED, &block)
+     if instructions.equal?(UNDEFINED) and block.nil?
+        @instructions
+      else
+        @instructions = block || instructions
+      end
     end
 
     ##
-    # Set or get the default tracer.
-    #
-    # When a block is provided, it is stored and evaluated lazily against the
-    # agent instance during initialization so it can build a tracer from the
-    # resolved provider.
-    #
+    # Set or get an agent's tracer.
     # @example
     #   class Agent < LLM::Agent
-    #     tracer { LLM::Tracer.logger(llm, io: $stdout) }
+    #     set tracer: proc { LLM::Tracer.logger(llm, io: $stdout) }
     #   end
-    #
-    # @param [LLM::Tracer, Proc, nil] tracer
-    # @yieldreturn [LLM::Tracer, nil]
+    # @param [LLM::Tracer, Symbol, nil] tracer
+    #  A tracer.
+    # @param [Proc] block
+    #  A block that is lazy-evaled.
     # @return [LLM::Tracer, Proc, nil]
-    def self.tracer(tracer = nil, &block)
-      return @tracer if tracer.nil? && !block
-      @tracer = block || tracer
+    def self.tracer(tracer = UNDEFINED, &block)
+     if tracer.equal?(UNDEFINED) and block.nil?
+        @tracer
+      else
+        @tracer = block || tracer
+      end
     end
 
     ##
-    # Set or get the default stream.
-    #
-    # When a block is provided, it is stored and evaluated lazily against the
-    # agent instance during initialization so it can build a fresh stream for
-    # each agent.
-    #
+    # Set or get an agent's intercept.
+    # @param [LLM::Intercept] intercept
+    #  An intercept object
+    # @param [Proc] block
+    #  A block that is lazy-evaled.
+    # @return [LLM::Intercept, nil]
+    def self.intercept(intercept = UNDEFINED, &block)
+     if intercept.equal?(UNDEFINED) and block.nil?
+        @intercept
+      else
+        @intercept = block || intercept
+      end
+    end
+
+    ##
+    # Set or get an agent's stream
     # @example
     #   class Agent < LLM::Agent
-    #     stream { MyStream.new }
+    #     set stream: proc { Stream.new }
     #   end
-    #
     # @param [Object, Proc, nil] stream
     # @yieldreturn [Object, nil]
     # @return [Object, Proc, nil]
-    def self.stream(stream = nil, &block)
-      return @stream if stream.nil? && !block
-      @stream = block || stream
+    def self.stream(stream = UNDEFINED, &block)
+     if stream.equal?(UNDEFINED) and block.nil?
+        @stream
+      else
+        @stream = block || stream
+      end
     end
 
     ##
@@ -363,22 +319,14 @@ module LLM
 
     ##
     # Set or get the maximum number of tool calls
-    # that are allowed in a single turn. Once the
-    # budget is spent, no further tool calls are run:
-    # we return an in-band message that informs the
-    # model it has spent its tool call budget, and
-    # keep returning it while the model keeps asking
-    # for tools - a model will usually change course
-    # afterwards. The budget counts tool calls, so a
-    # batch of calls is spent as a batch, and a batch
-    # that would take the turn past its budget is not
-    # run at all.
+    # an agent can make in a single turn.
     # @note
-    #  By default this feature is disabled
-    #  (set to `nil`).
+    #  This feature is disabled by default.
     # @param [Integer] budget
     #  The maximum number of tool calls to allow in
     #  a single turn.
+    # @param [Proc] block
+    #  A block that is lazy-evaled
     # @return [Integer, nil]
     def self.tool_budget(budget = UNDEFINED, &block)
       if budget.equal?(UNDEFINED) and block.nil?
@@ -389,21 +337,80 @@ module LLM
     end
 
     ##
-    # Sets or returns the retry budget for the agent.
-    #
-    # The retry budget is the maximum number of times a rate-limited
-    # request will be retried before giving up. Each retry sleeps a
-    # growing interval, so an exhausted budget surfaces the rate-limit
-    # error instead of blocking indefinitely. Enabled (5) by default; a
-    # raw {LLM::Context} disables it (0) unless configured.
+    # Set or get the number of attempts an agent
+    # will make when given a failed request.
     # @param [Integer] budget
-    #  The maximum number of rate-limit retries in a turn.
+    #  The maximum number of retries in a turn.
+    # @param [Proc] block
+    #  A block that is lazy-evaled
     # @return [Integer, nil]
-    def self.retry_budget(budget = UNDEFINED)
-      if budget.equal?(UNDEFINED)
-        @retry_budget.nil? ? UNDEFINED : @retry_budget
+    def self.retry_budget(budget = UNDEFINED, &block)
+      if budget.equal?(UNDEFINED) and block.nil?
+        @retry_budget
+      else
+        @retry_budget = block || budget
+      end
+    end
+
+    ##
+    # Set or get the default tools
+    # @param [Array<LLM::Function>, nil] tools
+    #  One or more tools
+    # @return [Array<LLM::Function>]
+    #  Returns the current tools when no argument is provided
+    def self.tools(*tools, &block)
+      return @tools || [] if tools.empty? and !block
+      if block
+        @tools = block
+      elsif single_callable?(tools)
+        @tools = tools.first
+      else
+        @tools = tools.flatten
+      end
+    end
+
+    ##
+    # Set or get the default skills
+    # @param [Array<String>, nil] skills
+    #  One or more skill directories
+    # @return [Array<String>, nil]
+    #  Returns the current skills when no argument is provided
+    def self.skills(*skills, &block)
+      return @skills if skills.empty? and !block
+      if block
+        @skills = block
+      elsif single_callable?(skills)
+        @skills = skills.first
+      else
+        @skills = skills.flatten
+      end
+    end
+
+    ##
+    # Set or get the agent tools that require confirmation.
+    #
+    # @example
+    #   class MyAgent < LLM::Agent
+    #     confirm :dangerous_tools
+    #     private
+    #     def dangerous_tools
+    #       %w[delete]
+    #     end
+    #   end
+    #
+    # @param [String, Symbol, Array<String, Symbol>, Proc] tool_names
+    #  One or more tool names.
+    # @param [Proc] block
+    #  An optional, lazy-evaluated Proc
+    # @return [Array<String>, Proc, Symbol, nil]
+    def self.confirm(*tool_names, &block)
+      return @confirm if tool_names.empty? and !block
+      if block
+        @confirm = block
+      elsif single_callable?(tool_names)
+        @confirm = tool_names.first
       else
-        @retry_budget = budget
+        @confirm = tool_names.flatten.map(&:to_s)
       end
     end
 
@@ -449,14 +456,9 @@ module LLM
           instance_variable_set(:"@#{field}", resolved)
         end
       end
-      ##
-      # The provider decides how patient a turn should be: it
-      # knows its own API, and how often it recovers from a
-      # rate limit rather than failing outright.
-      params[:retry_budget] = llm.retry_budget if params[:retry_budget].equal?(UNDEFINED)
-      ##
-      # The context is bound to the same record the agent holds, so code
-      # written against a context alone can find it through `ctx.record`.
+      if params[:retry_budget].nil?
+        params[:retry_budget] = llm.retry_budget
+      end
       @ctx = LLM::Context.new(llm, params.merge(record: @record).compact)
       @path and File.readable?(@path) ? @ctx.restore(path:) : nil
     end
@@ -707,17 +709,14 @@ module LLM
     end
 
     ##
-    # Start an agent console that can interact
-    # with the agent and its current state. This
-    # method requires the following gems to be
-    # installed and available to require:
-    # 'unicode-display_width', 'kramdown', 'curses',
-    # 'test-cmd.rb', and 'xchan.rb'.
+    # Start an agent console.
     #
     # @note
-    #  By default this method disables the tracer for
-    #  the duration of the console session, and restores
-    #  it afterwards.
+    # This method requires the following gems
+    # to be installed and available to require:
+    # 'unicode-display_width', 'kramdown',
+    # 'curses', 'test-cmd.rb', and 'xchan.rb'.
+    #
     # @param [String] name
     #  The agent's name.
     #  Defaults to {LLM::Agent#name}.
@@ -732,11 +731,7 @@ module LLM
     #  When true, the tracer is kept alive during the
     #  console session. Default is false.
     # @return [void]
-    def console(name: self.name, path: nil, tools: [], skills: [], tracer: false, trace: nil)
-      if trace != nil
-        warn "llm.rb: trace option is deprecated, use tracer instead"
-        tracer = trace
-      end
+    def console(name: self.name, path: nil, tools: [], skills: [], tracer: false)
       if !tracer
         previous    = self.tracer
         self.tracer = nil
@@ -849,7 +844,7 @@ module LLM
     #
     # An agent with no instructions returns first. The caller reaches
     # this through `apply_instructions`, which already returns early for
-    # the same reason, and the guard is repeated here so that the method
+    # the same reason, and the check is repeated here so that the method
     # cannot replace a message with nil however it is reached.
     #
     # Comparing content rather than the message is deliberate.
@@ -949,46 +944,26 @@ module LLM
         end
         res
       end
-      ##
-      # One turn, one trace group. A tracer
-      # is told where the turn begins and
-      # where it ends. The trace group ID
-      # identifies the turn.
-      tracer = @tracer || @llm.tracer
-      tracer.start_trace(name: "llm.turn", trace_group_id: SecureRandom.uuid_v7)
-      ##
-      # Where the turn is running, for as long as it runs.
-      #
-      # A cancel reaches a request in flight and the tools that are
-      # running, and between those it reached nothing: the loop is
-      # between two requests, or waiting out a retry, or building the
-      # next one. What is left over is a raise into the caller the turn
-      # is running under, and this names it - recorded here rather than in
-      # `Context#talk`, because a turn is a loop and not a request.
-      #
-      # The scheduler is part of it, and read here rather than by the
-      # caller: a cancel runs on the canceller's thread, which is not the
-      # thread a scheduler was installed on. The fiber strategy names it
-      # for the same reason. The tracer is part of it too, because the
-      # caller announces the turn's last phase to it before raising.
-      #
-      # Set to nil below once the turn is over, and that is not a
-      # formality: a worker's thread is reused for the turn after this
-      # one, and a cancel that arrived late would otherwise land in
-      # whatever that thread is doing.
-      @ctx.instance_variable_set(
-        :@caller,
-        LLM::Object.from(
-          thread: Thread.current,
-          fiber: @llm.request_owner,
-          scheduler: Fiber.scheduler,
-          tracer:
-        ).extend(Interrupt)
-      )
-      @llm.with_tracer(tracer, &run)
-    ensure
-      @ctx.instance_variable_set(:@caller, nil)
-      tracer&.stop_trace
+
+      begin
+        tracer = @tracer || @llm.tracer
+        caller = LLM::Object.from(thread: Thread.current,
+                                  fiber: @llm.request_owner,
+                                  scheduler: Fiber.scheduler).extend(Interrupt)
+        @ctx.instance_variable_set(:@caller, caller)
+        tracer.start_trace(name: "llm.turn", trace_group_id: SecureRandom.uuid_v7)
+        REGISTRY.enter(self)
+        @llm.with_tracer(tracer) do
+          run.call
+        rescue LLM::Interrupt
+          tracer&.on_interrupt(scope: :agent)
+          raise
+        end
+      ensure
+        REGISTRY.exit(self)
+        @ctx.instance_variable_set(:@caller, nil)
+        tracer&.stop_trace
+      end
     end
 
     ##