actionagent 1.6.4 → 1.7.0

data/app/models/action_agent/agent.rb

@@ -37,6 +37,7 @@ module ActionAgent
     validates :provider, presence: true
     validates :model, presence: true
     validate :validate_action_prompts
+    validate :provider_client_installed, if: :will_save_change_to_provider?, unless: :observed?
 
     # Status enum
     # `observed` agents were discovered from reported telemetry rather than
@@ -52,6 +53,7 @@ module ActionAgent
     before_validation :apply_conventional_schema_tools, on: :create
     after_create :create_initial_version
     after_update :create_version_on_config_change, if: :configuration_changed?
+    after_destroy :release_telemetry_traces, if: :observed?
 
     # Scopes
     scope :active_agents, -> { where(status: :active) }
@@ -122,9 +124,6 @@ module ActionAgent
     # 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.
     #
@@ -156,11 +155,58 @@ module ActionAgent
       self.tools = defaults if defaults.any?
     end
 
+    # 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. An observed
+    # agent's reported class need not end in Agent, so its traces are
+    # matched on #reported_agent_class rather than on this name.
     def telemetry_agent_class
       base = agent_class_name.presence || name.parameterize(separator: "_").camelize
       base.end_with?("Agent") ? base : "#{base}Agent"
     end
 
+    # Returns the class name this agent's traces carry in
+    # TelemetryTrace#agent_class: the application's own class for an observed
+    # agent (`"SupportBot"`), #telemetry_agent_class for any other.
+    def reported_agent_class
+      observed? ? agent_class_name : telemetry_agent_class
+    end
+
+    # The traces in +traces+ recorded for this agent.
+    #
+    # An observed agent is registered from its application's own class name,
+    # one agent per action, so its traces are the ones AgentRegistrar
+    # attributed to it plus #unattributed_telemetry_traces. Every other agent
+    # reads every trace reported under #telemetry_agent_class, attributed or
+    # not.
+    #
+    # @param traces [ActiveRecord::Relation] the traces the caller may read,
+    #   already narrowed to its tenant
+    # @return [ActiveRecord::Relation]
+    def telemetry_traces(traces)
+      return traces.for_agent(reported_agent_class) unless observed?
+
+      traces.where(agent_id: id).or(unattributed_telemetry_traces(traces))
+    end
+
+    # The traces in +traces+ attributed to no agent that carry this agent's
+    # identity, such as those ingested before AgentRegistrar ran or recorded
+    # for an observed agent since deleted. An observed agent's identity is the
+    # service, class and action it was registered from; any other agent's is
+    # #telemetry_agent_class.
+    #
+    # @param traces [ActiveRecord::Relation] the traces the caller may read,
+    #   already narrowed to its tenant
+    # @return [ActiveRecord::Relation]
+    def unattributed_telemetry_traces(traces)
+      identity = { agent_id: nil, agent_class: reported_agent_class }
+      # AgentRegistrar registers a trace with an empty action under a nil
+      # action_name, so both spellings are this agent's.
+      identity.update(service_name: service_name, agent_action: action_name.nil? ? [ nil, "" ] : action_name) if observed?
+
+      traces.where(identity)
+    end
+
     # The agent's long-term memory (solid_agent HasMemory contract) — the
     # summary list its runs read/write via the memory tools.
     def memory
@@ -390,6 +436,13 @@ module ActionAgent
 
     private
 
+    # Leaves the traces AgentRegistrar attributed to this observed agent
+    # unattributed, so an agent registered again for the same identity reads
+    # them through #unattributed_telemetry_traces.
+    def release_telemetry_traces
+      ActionAgent.trace_model.where(agent_id: id).update_all(agent_id: nil)
+    end
+
     # Refuses files before creating anything: a run that exists but lost
     # its attachments would execute against the wrong prompt.
     def create_run(input_prompt, action:, attachments:, params:, actor: nil, **attributes)
@@ -491,6 +544,21 @@ module ActionAgent
       action && available_actions.include?(action) ? action : nil
     end
 
+    # Provider client gems are optional dependencies of activeagent (OpenAI,
+    # Ollama and OpenRouter need `openai`, Anthropic needs `anthropic`), so a
+    # provider can be picked here that the host never installed. Refuse it
+    # when it is chosen, naming the gem, rather than on the agent's first
+    # run. Only the providers the engine offers are checked; the host's
+    # config/active_agent.yml may point one at another service.
+    def provider_client_installed
+      return unless PROVIDERS.include?(provider)
+
+      service = ActiveAgent::Base.provider_config_load(provider)[:service] || provider.camelize
+      ActiveAgent::Base.provider_load(service)
+    rescue LoadError => e
+      errors.add(:provider, "#{provider} can't be used yet: #{e.message}")
+    end
+
     def validate_action_prompts
       return if action_prompts.blank?
 

data/app/models/action_agent/application_record.rb

@@ -17,6 +17,10 @@ module ActionAgent
 
     self.abstract_class = true
 
+    # After abstract_class, so a concern's included block that reads
+    # table_name sees nil.
+    ActionAgent.model_concern_modules.each { |concern| include concern }
+
     # Models that are not themselves owned still answer the ownership
     # questions, so callers can scope any dashboard relation uniformly.
     class << self

data/app/models/action_agent/evaluation_run.rb

@@ -79,26 +79,74 @@ module ActionAgent
       (values.sum.to_f / values.size).round(3)
     end
 
-    # Aggregate usage over the run's scenario results, for display after a
-    # run: estimated cost, token totals, summed model time, and the run's
-    # wall-clock runtime. Returns nil for a generation-sampling run, which
-    # replays nothing itself.
+    # The judge's own spend on this run — calls, tokens, estimated cost and
+    # how many calls served each purpose — as the runner recorded it; nil
+    # for a run that never asked a judge.
+    def judge_usage
+      value = scores&.dig("_judge_usage")
+      value.is_a?(Hash) ? value : nil
+    end
+
+    # Per-model summaries of a generation-sampling run's cohorts, keyed by
+    # model; empty for a scenario run or a run recorded before they were.
+    def cohorts
+      value = scores&.dig("_cohorts")
+      value.is_a?(Hash) ? value : {}
+    end
+
+    # What the run spent, for display after it: the agent's side and the
+    # judge's, kept apart because they answer different questions.
+    #
+    # The agent's side is the operating figure — what the interactions cost
+    # to serve. For a scenario run that is the replays' estimated cost,
+    # tokens and summed model time (`replays` of them); for a
+    # generation-sampling run it is the sampled generations' (`samples`),
+    # which were served before the run and cost it nothing. `per_interaction`
+    # is that cost spread over the interactions, the number a per-conversation
+    # budget is set against.
+    #
+    # `judge` is the evaluation's own overhead: the judge model's calls
+    # (scoring, recommending, the verdict, authoring KPIs), which run
+    # agent-to-agent and offline. It is present only when a judge was asked.
+    #
+    # Returns nil for a run that recorded nothing on either side.
     def usage
       totals = scenario_results.pick(
         Arel.sql("COUNT(*)"), Arel.sql("SUM(cost)"), Arel.sql("SUM(input_tokens)"),
         Arel.sql("SUM(output_tokens)"), Arel.sql("SUM(duration_ms)")
       )
       replays = totals&.first.to_i
-      return nil if replays.zero?
+      judge = judge_usage
+      runtime_ms = completed_at.present? ? ((completed_at - created_at) * 1000).round : nil
 
-      {
-        replays: replays,
-        cost: totals[1]&.to_f,
-        input_tokens: totals[2].to_i,
-        output_tokens: totals[3].to_i,
-        model_time_ms: totals[4].to_i,
-        runtime_ms: completed_at.present? ? ((completed_at - created_at) * 1000).round : nil
-      }
+      if replays.positive?
+        cost = totals[1]&.to_f
+        {
+          replays: replays,
+          cost: cost,
+          per_interaction: cost && (cost / replays).round(6),
+          input_tokens: totals[2].to_i,
+          output_tokens: totals[3].to_i,
+          model_time_ms: totals[4].to_i,
+          runtime_ms: runtime_ms,
+          judge: judge
+        }.compact
+      elsif cohorts.any?
+        samples = cohorts.values.sum { |cohort| cohort["samples"].to_i }
+        costs = cohorts.values.filter_map { |cohort| cohort["cost"] }
+        cost = costs.any? ? costs.sum.to_f.round(6) : nil
+        {
+          samples: samples,
+          cost: cost,
+          per_interaction: cost && samples.positive? ? (cost / samples).round(6) : nil,
+          input_tokens: cohorts.values.sum { |cohort| cohort["input_tokens"].to_i },
+          output_tokens: cohorts.values.sum { |cohort| cohort["output_tokens"].to_i },
+          runtime_ms: runtime_ms,
+          judge: judge
+        }.compact
+      elsif judge
+        { runtime_ms: runtime_ms, judge: judge }.compact
+      end
     end
 
     # Route templates for the report's fix item actions, relative to the

data/app/models/action_agent/telemetry_trace.rb

@@ -16,9 +16,10 @@ module ActionAgent
   # @example Creating a trace with account (multi-tenant mode)
   #   ActionAgent::TelemetryTrace.create_from_payload(trace_payload, sdk_info, account: account)
   #
-  class TelemetryTrace < ::ActiveRecord::Base
-    include ActionAgent::AdapterAware
-
+  class TelemetryTrace < ApplicationRecord
+    # Fixed rather than derived from ActionAgent.table_name_prefix: the
+    # telemetry migration the install generator writes creates this table
+    # under its literal name, whatever prefix the host sets.
     self.table_name = "active_agent_telemetry_traces"
 
     # Optional account association for multi-tenant mode

data/app/models/concerns/action_agent/ownable.rb

@@ -73,13 +73,14 @@ module ActionAgent
     # The record's owner under the current configuration, or nil.
     #
     # The belongs_to is declared when the class loads, from the
-    # configuration at that moment; an owner model configured afterwards
-    # (a test, or an initializer that ran late) has the column but not the
-    # association, so the foreign key is read directly in that case.
+    # configuration at that moment. An owner model configured afterwards
+    # (a test, or an initializer that ran late) has the column but either no
+    # association or one declared for another class, so the foreign key is
+    # read directly in that case.
     def owner
       association = self.class.owner_association
       return nil unless association
-      return public_send(association) if respond_to?(association)
+      return public_send(association) if owner_association_current?(association)
 
       owner_class = ActionAgent.public_send(CLASS_FOR.fetch(association)).safe_constantize
       owner_id = self[:"#{association}_id"]
@@ -87,13 +88,24 @@ module ActionAgent
     end
 
     # Assigns +owner+ to whichever association this install uses. A no-op
-    # when the host app configured no owner model.
+    # when the host app configured no owner model. Writes the foreign key
+    # directly when the association is missing or was declared for another
+    # class, as #owner reads it.
     def owner=(record)
       association = self.class.owner_association
       return unless association
-      return public_send(:"#{association}=", record) if respond_to?(:"#{association}=")
+      return public_send(:"#{association}=", record) if owner_association_current?(association)
 
       self[:"#{association}_id"] = record&.id
     end
+
+    private
+
+    # Whether +association+ was declared for the class the configuration
+    # names now.
+    def owner_association_current?(association)
+      reflection = self.class.reflect_on_association(association)
+      reflection.present? && reflection.class_name == ActionAgent.public_send(CLASS_FOR.fetch(association)).to_s
+    end
   end
 end

data/app/queries/action_agent/metrics_report.rb

@@ -440,7 +440,7 @@ module ActionAgent
       versions.filter_map do |version|
         agent = version.agent
         next if agent.nil?
-        next if @agent && agent.telemetry_agent_class != @agent
+        next if @agent && agent.reported_agent_class != @agent
 
         previous = predecessors[[ version.agent_id, version.version_number - 1 ]]
         instructions_changed = snapshot_of(version)["instructions"].to_s != snapshot_of(previous)["instructions"].to_s

data/app/services/action_agent/agent_execution_service.rb

@@ -500,6 +500,21 @@ module ActionAgent
       tool_definitions = tool_schemas
       service = self
 
+      # A dashboard-authored agent has no Ruby class — it is rows: a tool
+      # selection, instructions typed in the builder. That is the common case
+      # and the runtime below builds a class for it.
+      #
+      # An agent mirrored from host code is the other case: the class exists,
+      # already declares its own tools (SchemaTools rosters, delegations) and
+      # renders its own instructions, and none of that is reachable through
+      # `tools` + `instructions` columns. Running the real class keeps the
+      # dashboard evaluating what production runs, instead of a rebuilt
+      # lookalike. Both runtimes stay; which one applies is decided by whether
+      # the class resolves.
+      if (host_class = resolved_host_class)
+        return run_host_class(host_class, actor: actor, action: action, run_trace_id: run_trace_id)
+      end
+
       agent_class = Class.new(ActiveAgent::Base) do
         # SolidAgent persists contexts under self.class.name; anonymous
         # classes would fail its agent_name presence validation.
@@ -677,6 +692,40 @@ module ActionAgent
       end
     end
 
+    # The host class this agent mirrors, when it names one that resolves to a
+    # runnable ActiveAgent::Base subclass. Anything else — no class name, a
+    # class that no longer exists, a name that resolves to something else — is
+    # nil, and the dynamic runtime handles the record as before.
+    #
+    # @return [Class, nil]
+    def resolved_host_class
+      return nil unless ActionAgent.run_host_agent_classes
+
+      name = @agent_record.agent_class_name.presence
+      return nil if name.blank?
+
+      klass = name.safe_constantize
+      klass if klass.is_a?(Class) && klass < ActiveAgent::Base
+    end
+
+    # Runs the host's own class. Its tools, delegations and instructions come
+    # from the code, so the engine supplies only what is the run's business:
+    # the caller, and the trace to correlate against.
+    def run_host_class(klass, actor:, action:, run_trace_id:)
+      generation = klass.as(actor).public_send(action, **host_action_arguments(klass, action))
+      generation.prompt_options[:trace_id] = run_trace_id if generation.respond_to?(:prompt_options)
+      generation.generate_now
+    end
+
+    # A code agent's action takes named arguments (`ask(question:)`), so the
+    # run's message is passed under the action's own keyword rather than as a
+    # bare message the signature would reject.
+    def host_action_arguments(klass, action)
+      contract = klass.try(:delegation_contracts)&.dig(action.to_sym)
+      keyword = contract&.try(:parameters)&.keys&.first
+      keyword ? { keyword.to_sym => user_text } : {}
+    end
+
     def provider_available?(name)
       # The gem's mock provider is a test double: accepted only in the test
       # environment so app runs can never store fabricated output.

data/app/services/action_agent/agent_sync.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Mirrors host ActiveAgent classes into Agent records, so the dashboard can
+  # run, evaluate and release the agents an app already has in code.
+  #
+  # The engine reads an agent's identity from the class rather than asking the
+  # host to restate it: name, description and tool roster all come from the
+  # class, and re-running the sync updates each record in place. `AgentRelease`
+  # already expects `agent_class_name` to be set by "whatever syncs its
+  # ActiveAgent classes into Agent records" — this is that, so a host no longer
+  # has to write it.
+  #
+  # The split is deliberate and is the reason this is safe to run on deploy:
+  #
+  # * **The code owns what an agent is** — name, description, instructions,
+  #   tools. Rewritten on every sync, so it cannot drift from the class.
+  # * **The operator owns how it runs** — provider, model, status. Set once on
+  #   create and never touched again, so a model chosen in the dashboard
+  #   survives the next deploy.
+  #
+  #   ActionAgent::AgentSync.call(RecordAgent.all, owner: owner)
+  #
+  # @see AgentRelease which cuts a version per synced agent
+  class AgentSync
+    Row = Struct.new(:agent, :created, :skipped, keyword_init: true)
+    Result = Struct.new(:rows, :errors, keyword_init: true) do
+      def success? = errors.blank?
+      def agents = rows.filter_map(&:agent)
+      def created = rows.select(&:created)
+      def skipped = rows.select(&:skipped)
+    end
+
+    # @param agents [Array<Class>] ActiveAgent::Base subclasses
+    # @param owner [Object] the record agents and API keys scope to
+    # @param provider [String, Symbol, nil] defaults to the class's own
+    # @param model [String, nil] defaults to the class's own
+    def self.call(agents, owner:, provider: nil, model: nil)
+      new(agents, owner: owner, provider: provider, model: model).call
+    end
+
+    def initialize(agents, owner:, provider: nil, model: nil)
+      @agents = Array(agents)
+      @owner = owner
+      @provider = provider
+      @model = model
+    end
+
+    # @return [Result]
+    def call
+      return Result.new(rows: [], errors: "An owner is required: the engine scopes agents to one.") if @owner.nil?
+
+      rows = Agent.transaction { @agents.map { |klass| upsert(klass) } }
+      Result.new(rows: rows, errors: nil)
+    rescue ActiveRecord::RecordInvalid => e
+      Result.new(rows: [], errors: e.record.errors.full_messages.join(", "))
+    end
+
+    private
+
+    def upsert(klass)
+      unless klass.respond_to?(:prompt_options)
+        return Row.new(agent: nil, created: false, skipped: "#{klass} is not an ActiveAgent::Base subclass")
+      end
+
+      provider = resolved_provider(klass)
+      model = resolved_model(klass)
+      if provider.blank? || model.blank?
+        return Row.new(agent: nil, created: false, skipped: "#{klass} has no provider/model configured")
+      end
+
+      # Slugs are unique per owner, so the lookup is too: unscoped, a second
+      # owner's sync would find the first owner's record and rewrite it.
+      agent = Agent.for_owner(@owner).find_or_initialize_by(slug: self.class.slug_for(klass))
+      created = agent.new_record?
+      if created
+        agent.owner = @owner
+        agent.provider = provider
+        agent.model = model
+        agent.status = :active
+      end
+
+      agent.assign_attributes(
+        name: klass.name.titleize,
+        agent_class_name: klass.name,
+        description: description_for(klass),
+        instructions: instructions_for(klass),
+        tools: tool_names_for(klass)
+      )
+      agent.save!
+      Row.new(agent: agent, created: created, skipped: nil)
+    end
+
+    # "TicketAgent" -> "ticket-agent", the slug an MCP client sees as
+    # run_ticket-agent. A namespaced class flattens its separators, because
+    # Agent validates slugs as /\A[a-z0-9\-_]+\z/ — "Billing::TicketAgent"
+    # becomes "billing-ticket-agent".
+    def self.slug_for(klass)
+      klass.name.underscore.tr("/", "-").tr("_", "-")
+    end
+
+    # An agent's own description if it declares one (a delegation contract is
+    # where an agent says what it answers), else its titleized name.
+    def description_for(klass)
+      contract = klass.try(:delegation_contracts)&.values&.first
+      contract&.try(:description).presence || klass.name.titleize
+    end
+
+    # The rendered instructions, so the dashboard record runs on the same text
+    # the class does rather than a hand-maintained copy.
+    #
+    # An agent whose instructions are assembled rather than rendered straight
+    # from its own template — filled from assigns it computes, or falling back
+    # to a template it shares with sibling agents — says so by defining
+    # `dashboard_instructions_text`. That is asked first, because only the
+    # class knows how its own prompt is built.
+    def instructions_for(klass)
+      return klass.dashboard_instructions_text.presence if klass.respond_to?(:dashboard_instructions_text)
+
+      klass.try(:rendered_instructions).presence
+    end
+
+    def tool_names_for(klass)
+      names = klass.try(:tool_names)
+      Array(names).map(&:to_s)
+    end
+
+    def resolved_provider(klass)
+      (@provider || klass.prompt_options[:service]).to_s.downcase.presence
+    end
+
+    def resolved_model(klass)
+      (@model || klass.prompt_options[:model]).presence
+    end
+  end
+end

data/app/services/action_agent/agent_tool_roster.rb

@@ -48,7 +48,7 @@ module ActionAgent
     def initialize(agent:, traces:, hours: ToolDiscovery::DEFAULT_WINDOW_HOURS)
       @agent = agent
       @discovery = ToolDiscovery.new(
-        traces: traces.for_agent(agent.telemetry_agent_class),
+        traces: agent.telemetry_traces(traces),
         agents: Agent.where(id: agent.id),
         hours: hours
       )