actionagent 1.5.0 → 1.5.2

data/app/controllers/action_agent/api/agents_controller.rb

@@ -66,7 +66,7 @@ module ActionAgent
             providers: Agent::PROVIDERS,
             preset_types: Agent::PRESET_TYPES,
             instruction_sets: Agent::INSTRUCTION_SETS,
-            available_tools: Agent::AVAILABLE_TOOLS
+            available_tools: Agent.available_tools
           }
         }
       end

data/app/controllers/action_agent/dashboard_controller.rb

@@ -41,7 +41,7 @@ module ActionAgent
         providers: Agent::PROVIDERS,
         presetTypes: Agent::PRESET_TYPES,
         instructionSets: Agent::INSTRUCTION_SETS,
-        availableTools: Agent::AVAILABLE_TOOLS,
+        availableTools: Agent.available_tools,
         executionEnabled: ActionAgent.execution_enabled?,
         assistantEnabled: ActionAgent.assistant_enabled?,
         multiTenant: ActionAgent.multi_tenant?,

data/app/models/action_agent/agent.rb

@@ -41,6 +41,7 @@ module ActionAgent
 
     # Callbacks
     before_validation :generate_slug, on: :create
+    before_validation :apply_conventional_schema_tools, on: :create
     after_create :create_initial_version
     after_update :create_version_on_config_change, if: :configuration_changed?
 
@@ -72,17 +73,62 @@ module ActionAgent
       github ruby rails aws gcp python typescript docker kubernetes
     ].freeze
 
-    # Available tools/MCPs
+    # Built-in tools/MCPs. Host-declared schema tools are offered alongside
+    # these — see .available_tools, which is what the editor and the APIs
+    # serialize. This constant stays the built-in set so existing references
+    # keep their meaning.
     AVAILABLE_TOOLS = %w[
       terminal playwright filesystem code database slack fetch search edit translate memory agents ui
     ].freeze
 
+    # Every tool an agent may enable: the built-ins plus each tool generated by
+    # the host's declared ActiveAgent::SchemaTools classes (ActionAgent.schema_tools).
+    #
+    # Computed per call, never memoized: in development the host's tool classes
+    # are autoloaded and reloaded, so a cached list would either miss them at
+    # boot or go stale after a reload.
+    # @return [Array<String>]
+    def self.available_tools
+      AVAILABLE_TOOLS | ActionAgent.schema_tool_names
+    end
+
     # Available providers
     PROVIDERS = %w[openai anthropic ollama openrouter].freeze
 
     # The ActiveAgent class name this agent's runs are recorded under — the
     # correlation key between platform Agent records and telemetry traces
     # (TelemetryTrace#agent_class) and solid_agent contexts.
+    # Tools a schema tool class claims for this agent by naming convention:
+    # Reservation -> ReservationTools -> ReservationAgent.
+    #
+    # This is a DEFAULT SELECTION, never a restriction. Any agent may enable
+    # any tool in .available_tools; the convention only decides what a newly
+    # created ReservationAgent starts with.
+    # @return [Array<String>]
+    def conventional_schema_tools
+      # Compared on letters only. `telemetry_agent_class` is not reliable here:
+      # it runs `parameterize.camelize`, which turns an already-camelised
+      # "TicketAgent" into "Ticketagent" and matches nothing, while
+      # "Milestone Agent" happens to survive. Normalising both sides makes
+      # "TicketAgent", "Ticket Agent" and "ticket_agent" all match.
+      identifier = (agent_class_name.presence || name.to_s).gsub(/[^a-z]/i, "").downcase
+      return [] if identifier.blank?
+
+      ActionAgent.schema_tool_classes.select do |klass|
+        "#{klass.model.name}Agent".downcase == identifier
+      end.flat_map(&:tool_names).map(&:to_s)
+    end
+
+    # Seeds a new agent named after a model with that model's tools. Only on
+    # create, and only when none were chosen — a deliberate selection, empty
+    # included, is never overwritten, and the editor can deselect afterwards.
+    def apply_conventional_schema_tools
+      return if tools.present?
+
+      defaults = conventional_schema_tools
+      self.tools = defaults if defaults.any?
+    end
+
     def telemetry_agent_class
       base = agent_class_name.presence || name.parameterize(separator: "_").camelize
       base.end_with?("Agent") ? base : "#{base}Agent"

data/app/services/action_agent/agent_toolbox.rb

@@ -203,11 +203,23 @@ module ActionAgent
       # Tool definitions for the subset of an agent's enabled tools that have
       # server-side implementations.
       def definitions_for(tool_names)
-        Array(tool_names).flat_map { |name| DEFINITIONS[name.to_s] || [] }
+        Array(tool_names).flat_map do |name|
+          DEFINITIONS[name.to_s] || schema_tool_definitions(name.to_s)
+        end
       end
 
       def function?(name)
-        FUNCTIONS.key?(name.to_s)
+        FUNCTIONS.key?(name.to_s) || ActionAgent.schema_tool_class_for(name.to_s).present?
+      end
+
+      # Definitions for a host-declared schema tool, or [] when the name is
+      # not one. Each generated tool is its own entry so an agent enables them
+      # individually rather than as a group.
+      def schema_tool_definitions(name)
+        klass = ActionAgent.schema_tool_class_for(name)
+        return [] unless klass
+
+        Array(klass.tool_definitions).select { |definition| definition[:name].to_s == name }
       end
 
       # Executes a tool call. Returns a result hash; errors are returned as
@@ -218,6 +230,16 @@ module ActionAgent
       # instead of re-running the side effect.
       def call(name, **kwargs)
         return { error: "Unknown tool: #{name}" } unless function?(name)
+
+        schema_tool = ActionAgent.schema_tool_class_for(name.to_s)
+        if schema_tool
+          # `actor:` is the host's authorization seam — the scope block runs
+          # inside the call. It is passed through untouched, including nil,
+          # so a host scope decides what an unattributed run may read rather
+          # than the engine widening it.
+          return schema_tool.call(name.to_s, actor: kwargs.delete(:actor), **kwargs)
+        end
+
         return public_send(FUNCTIONS.fetch(name.to_s), **kwargs) if UNCACHED_FUNCTIONS.include?(name.to_s)
 
         cached_fetch(name, kwargs) do

data/app/services/action_agent/mcp_tool_dispatcher.rb

@@ -57,7 +57,15 @@ module ActionAgent
     # contributes nothing rather than failing the run — the tools it serves
     # then simply are not offered, and a scenario expecting them fails with a
     # fault naming them.
+    #
+    # A server that fails discovery also records why, in +discovery_errors+.
+    # Contributing nothing keeps the run alive, but silence is indistinguishable
+    # from a server that legitimately serves no tools — and an agent offered no
+    # tools answers from the model alone, which reads as a confident, fabricated
+    # result rather than a transport failure (#425).
     def tool_definitions
+      @discovery_errors = {}
+
       resolver.declared_server_keys.flat_map do |key|
         entry = MCPCatalog.find(key)
         next [] unless entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS) && entry[:url].present?
@@ -66,11 +74,35 @@ module ActionAgent
           client_for(entry).list_tools
         rescue MCPClient::Error => e
           Rails.logger.warn("[MCPToolDispatcher] #{key} tools/list failed: #{e.message}")
+          @discovery_errors[key] =
+            "Cannot load tools from MCP server '#{key}' (#{entry[:url]}): #{e.message}. " \
+            "Check its URL, transport and credentials."
           []
         end
       end
     end
 
+    # Why each declared server contributed no tools, keyed by server. Empty
+    # until +tool_definitions+ has run, and empty after a run where every
+    # declared server answered.
+    #
+    # @return [Hash{String => String}]
+    def discovery_errors
+      @discovery_errors ||= {}
+    end
+
+    # Whether every server the agent declares failed discovery. The tool-less
+    # execution that follows cannot produce a meaningful result, so a caller
+    # can fail loudly instead of scoring an answer the model invented.
+    def all_servers_failed?
+      keys = resolver.declared_server_keys.select do |key|
+        entry = MCPCatalog.find(key)
+        entry && entry[:transport].to_s.in?(HTTP_TRANSPORTS) && entry[:url].present?
+      end
+
+      keys.any? && keys.all? { |key| discovery_errors.key?(key) }
+    end
+
     private
 
     attr_reader :agent, :resolver

data/app/services/action_agent/scenario_evaluation_runner.rb

@@ -80,6 +80,7 @@ module ActionAgent
         scores: scores_for(report, run),
         samples_evaluated: report.results.size,
         samples_passed: report.results.count(&:passed?),
+        error_message: discovery_warning,
         completed_at: Time.current
       )
       run
@@ -240,10 +241,48 @@ module ActionAgent
       end
     end
 
+    # Every tool the agent could actually call, for the diagnosis roster: the
+    # engine's own toolbox plus whatever its MCP servers serve.
+    #
+    # Listing only the toolbox understated the roster, so a diagnosis could
+    # report "none of the available tools covers this task" while naming a list
+    # the agent's MCP tools were missing from.
     def tool_roster
-      @tool_roster ||= AgentToolbox.definitions_for(@evaluation.agent.tools).to_h do |definition|
-        [ definition[:name].to_s, definition[:description].to_s ]
+      @tool_roster ||= begin
+        definitions = mcp_dispatcher.tool_definitions +
+          AgentToolbox.definitions_for(@evaluation.agent.tools)
+
+        definitions.to_h { |definition| [ definition[:name].to_s, definition[:description].to_s ] }
+      end
+    end
+
+    # Discovery failures from the roster above, keyed by server. Reading them
+    # requires tool_definitions to have run, which tool_roster does.
+    def mcp_discovery_errors
+      tool_roster
+      mcp_dispatcher.discovery_errors
+    end
+
+    def mcp_dispatcher
+      @mcp_dispatcher ||= MCPToolDispatcher.new(@evaluation.agent)
+    end
+
+    # A run whose every declared MCP server failed discovery scored an agent
+    # that had no tools to call. The scores are real but meaningless — the
+    # model answered from its own weights — so the run says so rather than
+    # leaving the cause in a log line (#425).
+    def discovery_warning
+      errors = mcp_discovery_errors
+      return nil if errors.empty?
+
+      prefix = if mcp_dispatcher.all_servers_failed?
+        "Every MCP server this agent declares failed tool discovery, so it ran with no MCP tools " \
+        "and any specifics in its answers are unverified."
+      else
+        "Some of this agent's MCP servers failed tool discovery, so part of its toolset was unavailable."
       end
+
+      "#{prefix} #{errors.values.join(' ')}"
     end
 
     # The judge the evaluation's owner has credentials for, wrapped for the

data/lib/action_agent/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActionAgent
-  VERSION = "1.5.0"
+  VERSION = "1.5.2"
 end

data/lib/action_agent.rb

@@ -330,6 +330,30 @@ module ActionAgent
     # @return [Array<Hash>]
     attr_accessor :mcp_catalog
 
+    # Host-declared ActiveAgent::SchemaTools subclasses whose generated tools
+    # are offered alongside AgentToolbox's built-ins: each generated tool is
+    # individually selectable in the agent editor, dispatched by name at
+    # execution, and named in an evaluation's +tools:+ expectation.
+    #
+    #   ActionAgent.configure do |config|
+    #     config.schema_tools = [TicketTools, TaskTools, MilestoneTools]
+    #   end
+    #
+    # Accepts classes or class-name strings; strings are resolved lazily so a
+    # host can declare them from an initializer before autoloading has run.
+    #
+    # Leave it unset and every ActiveAgent::SchemaTools subclass found in
+    # {#schema_tools_path} is offered instead — a host adds a tool by adding a
+    # file, without naming it twice.
+    # @return [Array<Class, String>, nil]
+    attr_accessor :schema_tools
+
+    # Directory scanned for SchemaTools subclasses when {#schema_tools} is
+    # unset. Relative to the host's root. Set to nil to disable discovery and
+    # require an explicit declaration.
+    # @return [String, nil]
+    attr_accessor :schema_tools_path
+
     # Value stored in polymorphic *_type columns for dashboard agents
     # (agent_memories.memorable_type, agent_contexts.contextable_type).
     # Unset means the class name. A host app whose existing rows were
@@ -495,6 +519,63 @@ module ActionAgent
       @sign_out_path = nil
       @sign_in_path = nil
       @mcp_catalog = []
+      @schema_tools = nil
+      @schema_tools_path = "app/agent_tools"
+    end
+
+    # Host-declared schema tool classes, resolved from names and filtered to
+    # those that are usable (declared a model and generated a roster).
+    #
+    # Resolution happens per call rather than at configure time: a host
+    # declares these in an initializer, before its own classes are autoloaded.
+    # @return [Array<Class>]
+    def schema_tool_classes
+      declared = @schema_tools.nil? ? discovered_schema_tools : Array(@schema_tools)
+
+      declared.filter_map do |entry|
+        klass = entry.is_a?(String) ? entry.safe_constantize : entry
+        next unless klass.respond_to?(:tool_definitions) && klass.respond_to?(:model)
+        next if klass.model.blank?
+        # An anonymous class built at runtime is usable but not discoverable —
+        # it would accumulate across reloads with no way to supersede itself.
+        next if entry.is_a?(Class) && klass.name.blank? && @schema_tools.nil?
+
+        klass
+      end
+    end
+
+    # Every tool name generated by the declared schema tool classes.
+    # @return [Array<String>]
+    def schema_tool_names
+      schema_tool_classes.flat_map(&:tool_names).map(&:to_s)
+    end
+
+    # SchemaTools subclasses defined under {#schema_tools_path}.
+    #
+    # The files are loaded before reading +descendants+: in development nothing
+    # has referenced those constants yet, so the list would otherwise be empty
+    # at boot and fill in only once something happened to touch them.
+    # @return [Array<Class>]
+    def discovered_schema_tools
+      return [] if @schema_tools_path.blank? || !defined?(ActiveAgent::SchemaTools)
+      return [] unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      root = Rails.root.join(@schema_tools_path)
+      return [] unless Dir.exist?(root)
+
+      Dir[root.join("**/*.rb")].sort.each do |path|
+        require_dependency path
+      rescue StandardError, ScriptError => e
+        warn "[ActionAgent] could not load #{path}: #{e.class} - #{e.message}"
+      end
+
+      ActiveAgent::SchemaTools.descendants.select { |klass| klass.name.present? }
+    end
+
+    # The schema tool class that generated +name+, or nil.
+    # @return [Class, nil]
+    def schema_tool_class_for(name)
+      schema_tool_classes.find { |klass| klass.tool?(name) }
     end
   end
 

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actionagent
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.2
 platform: ruby
 authors:
 - Justin Bowen
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activeagent
@@ -237,6 +238,7 @@ metadata:
   documentation_uri: https://docs.activeagents.ai/framework/self-hosted-observability
   source_code_uri: https://github.com/activeagents/activeagent
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -251,7 +253,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: The Active Agent dashboard, as a mountable Rails engine
 test_files: []