activeagent 1.8.1 → 1.9.0

data/README.md

@@ -57,6 +57,9 @@ bundle add openai
 # Requesty (uses OpenAI-compatible API)
 bundle add openai
 
+# DeepSeek (uses OpenAI-compatible API)
+bundle add openai
+
 # RubyLLM (unified API for 15+ providers)
 bundle add ruby_llm
 ```
@@ -140,6 +143,11 @@ development:
     service: "Ollama"
     model: "llama3.2"
 
+  deepseek:
+    service: "DeepSeek"
+    api_key: <%= Rails.application.credentials.dig(:deepseek, :api_key) %>
+    model: "deepseek-flash"
+
   ruby_llm:
     service: "RubyLLM"
 ```
@@ -179,7 +187,7 @@ a free low-volume trial.
 ## Features
 
 - **Agent-Oriented Programming**: Build AI applications using familiar Rails patterns
-- **Multiple Provider Support**: Works with OpenAI, Anthropic, Ollama, RubyLLM, and more
+- **Multiple Provider Support**: Works with OpenAI, Anthropic, Ollama, DeepSeek, RubyLLM, and more
 - **Action-Based Design**: Define agent capabilities through actions
 - **View Templates**: Use ERB templates for prompts (text, JSON, HTML)
 - **Streaming Support**: Real-time response streaming with ActionCable

data/lib/active_agent/base.rb

@@ -7,6 +7,7 @@ require "active_support/core_ext/string/inflections"
 require "active_agent/concerns/authorization"
 require "active_agent/concerns/callbacks"
 require "active_agent/concerns/delegation"
+require "active_agent/concerns/input_requests"
 require "active_agent/concerns/observers"
 require "active_agent/concerns/parameterized"
 require "active_agent/concerns/preview"
@@ -47,6 +48,7 @@ module ActiveAgent
     include Callbacks
     # After Rescue: the refusal handler is registered with rescue_from.
     include Delegation
+    include InputRequests
     include Parameterized
     include Provider
     include Queueing
@@ -261,7 +263,9 @@ module ActiveAgent
         run_callbacks(:prompting) do
           parameters = prepare_prompt_parameters
 
-          prompt_provider_klass.new(**parameters).prompt
+          prompt_provider_klass.new(**parameters).prompt.tap do |response|
+            run_input_request_callbacks(response)
+          end
         end
       end
     end
@@ -332,6 +336,9 @@ module ActiveAgent
         exception_handler:,
         stream_broadcaster:,
         tools_function:,
+        action_name: generation_action_name,
+        input_request_resume: @_input_request_resume,
+        announce_input_requests: !input_requests_silenced?
       )
 
       # Apply Templates
@@ -389,6 +396,7 @@ module ActiveAgent
       end
 
       if response_format[:type].to_sym == :json_schema
+        response_format = nest_flat_json_schema(response_format)
         response_format[:json_schema] = prompt_view_schema(response_format[:json_schema])
         response_format[:json_schema].deep_transform_keys! { _1.to_s.camelize(:lower) }
       end
@@ -396,6 +404,19 @@ module ActiveAgent
       response_format
     end
 
+    # Moves a json_schema given flat, with its name, schema and strict flag
+    # beside +type+, under +json_schema+, so it is not mistaken for a
+    # json_schema that names a view. Without a top-level schema, or with a
+    # +json_schema+ already, the format is returned as it came.
+    #
+    # @api private
+    def nest_flat_json_schema(response_format)
+      return response_format if response_format.key?(:json_schema) || response_format[:schema].nil?
+
+      flat_keys = %i[name schema strict]
+      response_format.except(*flat_keys).merge(json_schema: response_format.slice(*flat_keys))
+    end
+
     # @api private
     def instrument_payload(key)
       {

data/lib/active_agent/concerns/delegation.rb

@@ -92,6 +92,10 @@ module ActiveAgent
     # schema and the policy is +:raise+.
     class InvalidResultError < StandardError; end
 
+    # Raised when a sub-agent pauses to ask the user for input and the budget
+    # policy is +:raise+.
+    class InputRequiredError < StandardError; end
+
     included do
       # Contracts this agent exposes to callers, keyed by action.
       class_attribute :delegation_contracts, instance_accessor: false, default: {}.freeze

data/lib/active_agent/concerns/input_requests.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "active_agent/input_request"
+
+module ActiveAgent
+  # Lets a generation pause for the user and continue with the answers.
+  #
+  # A tool asks by returning an {InputRequest}. The generation then ends
+  # paused, and {Generation#resume_now} continues it from the response's
+  # checkpoint. See {InputRequest} for the kinds of request and what an
+  # answer does.
+  #
+  # @example Asking for confirmation before a side effect
+  #   class SupportAgent < ApplicationAgent
+  #     on_input_request :notify_reviewer
+  #
+  #     def issue_refund(order_id:, amount:)
+  #       return ActiveAgent::InputRequest.confirm("Refund #{amount} on order #{order_id}?") unless input_answer
+  #
+  #       Refund.create!(order_id:, amount:)
+  #     end
+  #
+  #     private
+  #
+  #     def notify_reviewer(response)
+  #       ReviewMailer.pending(response.input_requests.map(&:prompt)).deliver_later
+  #     end
+  #   end
+  module InputRequests
+    extend ActiveSupport::Concern
+
+    included do
+      define_callbacks :input_request
+    end
+
+    class_methods do
+      # Registers callbacks run when a generation pauses for input, before the
+      # paused response is returned. A callback that takes an argument receives
+      # the paused response.
+      #
+      # @param names [Array<Symbol>] methods to call
+      # @param block [Proc] optional block to call
+      # @return [void]
+      def on_input_request(*names, &block)
+        _insert_callbacks(names, block) do |callback, options|
+          set_callback(:input_request, :before, ->(agent) { agent.send(:run_input_request_callback, callback) }, **options)
+        end
+
+        # The first callback a class sets makes ActiveSupport alias the chain's
+        # runner into that class as a public method, which would list it among
+        # the agent's actions and in its release digest.
+        private :_run_input_request_callbacks if public_method_defined?(:_run_input_request_callbacks, false)
+      end
+    end
+
+    # Stops a pause of this generation from being announced with
+    # `input_requested.active_agent` or passed to on_input_request callbacks.
+    #
+    # @return [void]
+    # @api private
+    def silence_input_requests!
+      @_input_requests_silenced = true
+    end
+
+    # Whether this generation continues one that paused for input.
+    #
+    # @return [Boolean]
+    def resuming?
+      !@_input_request_resume.nil?
+    end
+
+    # Returns the answer for the tool call being run, when the call is being
+    # dispatched again on resume; nil otherwise.
+    #
+    # @return [Object, nil]
+    def input_answer
+      InputRequest.answer_for(InputRequest.current_tool_call_id)
+    end
+
+    # Continues a generation that paused for input. The action has already
+    # run, so tools, instructions and options are current; the conversation
+    # is replaced with the checkpoint's, not merged with what the action
+    # added.
+    #
+    # Answers to `:secret` requests are scrubbed from every tool result and
+    # tool error of this generation, so they reach neither the model nor
+    # telemetry.
+    #
+    # @param checkpoint [Hash] the paused response's checkpoint
+    # @param answers [Hash] an answer per paused tool call id
+    # @return [ActiveAgent::Providers::Common::PromptResponse]
+    # @raise [InputRequest::ResumeError] before any tool runs or any request
+    #   is sent, when the answers or the checkpoint do not fit
+    def resume_prompt(checkpoint:, answers:)
+      resume = InputRequest::Resume.new(checkpoint:, answers:)
+      resume.assert_action!(generation_action_name)
+
+      input_request_secrets.concat(resume.secret_answers)
+      prompt_options[:messages] = resume.messages
+      @_input_request_resume = resume
+
+      process_prompt
+    ensure
+      @_input_request_resume = nil
+    end
+
+    private
+
+    # Records the action the generation runs. A tool call runs through
+    # `process` as well, and replaces `action_name` with the tool's name.
+    def process(method_name, ...)
+      @_generation_action_name = method_name.to_s unless tool_call?
+      super
+    end
+
+    # @return [String, nil] the action this agent's generation runs
+    def generation_action_name
+      @_generation_action_name
+    end
+
+    # @return [Boolean] whether a pause is kept from the host
+    def input_requests_silenced?
+      @_input_requests_silenced == true
+    end
+
+    # @return [Array<String>] the secret answers this generation has received
+    def input_request_secrets
+      @_input_request_secrets ||= []
+    end
+
+    # @param value [Object]
+    # @return [Object] `value` without any secret answer in it
+    def scrub_input_request_secrets(value)
+      InputRequest.scrub(value, input_request_secrets)
+    end
+
+    # @param error [Exception]
+    # @raise [Exception] `error`, or a replacement without the secret answers
+    #   (see InputRequest.raise_scrubbed)
+    def raise_without_input_request_secrets(error)
+      InputRequest.raise_scrubbed(error, input_request_secrets)
+    end
+
+    # Calls one on_input_request callback, with the paused response when it
+    # takes an argument.
+    #
+    # @param callback [Symbol, Proc]
+    # @return [void]
+    def run_input_request_callback(callback)
+      if callback.is_a?(Proc)
+        callback.arity.zero? ? instance_exec(&callback) : instance_exec(@_input_request_response, &callback)
+      else
+        method(callback).arity.zero? ? send(callback) : send(callback, @_input_request_response)
+      end
+    end
+
+    # Runs the on_input_request callbacks for a paused response.
+    #
+    # @param response [ActiveAgent::Providers::Common::PromptResponse]
+    # @return [void]
+    def run_input_request_callbacks(response)
+      return if input_requests_silenced?
+      return unless response.respond_to?(:awaiting_input?) && response.awaiting_input?
+
+      # `only:` and `except:` compare against action_name, which the tool
+      # calls before the pause replaced with their own names.
+      tool_action_name, self.action_name = action_name, generation_action_name
+      @_input_request_response = response
+
+      begin
+        run_callbacks(:input_request)
+      ensure
+        self.action_name = tool_action_name
+        @_input_request_response = nil
+      end
+    end
+  end
+end

data/lib/active_agent/concerns/parameterized.rb

@@ -208,8 +208,9 @@ module ActiveAgent
       #
       # @param generation_method [Symbol, String] the generation method to call
       # @param job_options [Hash] options to pass to the job (e.g., queue, priority)
+      # @param job_arguments [Hash] further keyword arguments for the job
       # @return [Object] the enqueued job instance
-      def enqueue_generation(generation_method, job_options = {})
+      def enqueue_generation(generation_method, job_options = {}, **job_arguments)
         if processed?
           super
         else
@@ -218,7 +219,7 @@ module ActiveAgent
           # another machine authorizes as the same caller.
           agent_class.generation_job.set(job_options).perform_later(
             agent_class.name, action_name.to_s, generation_method.to_s,
-            params: @params, args: args, kwargs: kwargs, actor: @actor
+            params: @params, args: args, kwargs: kwargs, actor: @actor, **job_arguments
           )
         end
       end
@@ -305,8 +306,9 @@ module ActiveAgent
       #
       # @param generation_method [Symbol, String] the generation method to call
       # @param job_options [Hash] options to pass to the job
+      # @param job_arguments [Hash] further keyword arguments for the job
       # @return [Object] the enqueued job instance
-      def enqueue_generation(generation_method, job_options = {})
+      def enqueue_generation(generation_method, job_options = {}, **job_arguments)
         if processed?
           super
         else
@@ -320,7 +322,8 @@ module ActiveAgent
             kwargs: kwargs,
             direct_generation_type: @generation_type,
             direct_args: @direct_args,
-            direct_options: @direct_options
+            direct_options: @direct_options,
+            **job_arguments
           )
         end
       end

data/lib/active_agent/concerns/provider.rb

@@ -11,6 +11,7 @@ module ActiveAgent
     PROVIDER_SERVICE_NAMES_REMAPS = {
       "Openrouter"  => "OpenRouter",
       "Openai"      => "OpenAI",
+      "Deepseek"    => "DeepSeek",
       "AzureOpenai" => "AzureOpenAI",
       "Azureopenai" => "AzureOpenAI",
       "Rubyllm"     => "RubyLLM",

data/lib/active_agent/concerns/tooling.rb

@@ -11,14 +11,19 @@ module ActiveAgent
     # Returns a proc that handles tool/function calls from providers.
     #
     # The proc routes tool calls to the appropriate action method using
-    # the {#process} method.
+    # the {#process} method. Secret answers the generation received (see
+    # InputRequests) are scrubbed from the result and from any error, before
+    # either reaches the provider or telemetry.
     #
     # @return [Proc] callback proc that accepts (action_name, *args, **kwargs)
     def tools_function
       proc do |action_name, *args, **kwargs|
         # Marked as a tool call so a refusal is reported to the model as a
         # result rather than raised through the run (see Authorization).
-        with_tool_call { process(action_name, *args, **kwargs) }
+        result = with_tool_call { process(action_name, *args, **kwargs) }
+        scrub_input_request_secrets(result)
+      rescue StandardError => error
+        raise_without_input_request_secrets(error)
       end
     end
   end

data/lib/active_agent/delegation/runner.rb

@@ -32,6 +32,8 @@ module ActiveAgent
       # @return [Object] the sub-agent's result, or a structured error the
       #   calling model can act on
       # @raise [BudgetExceededError] when the budget policy is +:raise+
+      # @raise [InputRequiredError] when the sub-agent pauses for input and
+      #   the budget policy is +:raise+
       # @raise [InvalidResultError] when the returns policy is +:raise+
       def call(**arguments)
         if (violation = budget_violation)
@@ -123,6 +125,9 @@ module ActiveAgent
         definition.backend.apply(agent)
         apply_returns_format(agent)
         inherit_trace_id(agent)
+        # A pause becomes this call's result (see #input_required), and its
+        # checkpoint is dropped, so nothing outside the call may act on it.
+        agent.silence_input_requests!
 
         agent.process_prompt
       end
@@ -193,6 +198,8 @@ module ActiveAgent
       # @param payload [Hash] instrumentation payload
       # @return [Object]
       def result(response, payload)
+        return input_required(response, payload) if response.try(:awaiting_input?)
+
         message = response.message
         return nil if message.nil?
 
@@ -251,6 +258,30 @@ module ActiveAgent
         }
       end
 
+      # A delegated agent cannot pause for the user: nothing holds its
+      # checkpoint once the tool call returns. Its questions go back to the
+      # calling model instead.
+      #
+      # @param response [ActiveAgent::Providers::Common::PromptResponse] a paused response
+      # @param payload [Hash] instrumentation payload
+      # @return [Hash]
+      # @raise [InputRequiredError] when the budget policy is +:raise+
+      def input_required(response, payload)
+        payload[:status] = :input_required
+
+        if budget.policy == :raise
+          raise InputRequiredError, "#{definition.agent_class}##{definition.action} stopped to ask the user for input " \
+                                    "(#{response.input_requests.map(&:tool_name).join(", ")}), which a delegated agent cannot do"
+        end
+
+        {
+          error: "input_required",
+          questions: response.input_requests.map(&:prompt),
+          message: "The #{definition.tool_name} delegation stopped to ask the user for input, which a delegated agent cannot do. " \
+                   "Answer with the information you already have, or ask the user yourself."
+        }
+      end
+
       # @param missing [Array<Symbol>]
       # @param content [String]
       # @return [Hash]