activeagent 1.6.4 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0332669c4ffee1ccbea3e1645e126acac6b4e957b980000e5d96baedc908638
-  data.tar.gz: 1d6062b56a6e7fc0e76b965d308df706c3be563292344cdf68b500046e838784
+  metadata.gz: 4aee77fd4f67a50824b7153b66f31aa5f19293bad4397e032ec0a9e674a759d0
+  data.tar.gz: e261e8ca9d221edbc849791ed28c67bc491ccc31e1e18f5c4cbf7a9a96a806c5
 SHA512:
-  metadata.gz: c0a940227737d94497c19e8760cf1241ea02f6078987f8cd27f78b0b1a1fb22ac90c8b924dff87e85a4bf8f13c952f6a36eec388dd806f56d230f5b38c9fe59b
-  data.tar.gz: df01fdb757be0bcfa549086dfe0082db0ada892fc552600087d07fe9c1299a4aa4d4c897987cbda897832d11df50f19368261413647f63db4e636a4bb5bb98e5
+  metadata.gz: f5779f6207e07b1aec0ef14f72a5b010075b953c9025a12f6231ba164522c8b785cd9ca1bb297361abedc42aa535c468ef642978ec9fb439c79c9c0fe71ebd79
+  data.tar.gz: 1d2720a47e5e8c2a6c17a74cff893f1da2e89dd430b295bdcda4b9bdfb966afa8e75fbf95c0f063f5bca0bc8406d782e08b99fa6bed99b20230fb793ac3e518b

data/CHANGELOG.md

@@ -7,6 +7,223 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-09-24
+
+Releases `activeagent` and `actionagent` 1.7.0 from one tag. A minor release:
+a mounted engine collects the evaluation reports applications publish with
+`ActiveAgent::Evals::Publisher`, whose failures now say what the collector
+refused and whether to retry; observed agents read their own traces in
+evaluation criteria, the Tools and Traces tabs and deploy markers; host apps
+extend the engine's models and controllers through concerns and mirror their
+agent classes into the dashboard; and the Evaluations page is rebuilt around
+runs. Run the install generator after upgrading (see Upgrading below).
+
+Upgrading: the install generator emits two new migrations, both guarded
+column by column: `ensure_agent_release_columns`, which adds the agent release
+columns an install generated fresh on 1.6.2-1.6.4 never got (and those on
+tables with a custom `table_name_prefix`), and `add_evaluation_report_identity`
+for the evaluation report collector. Re-run
+`bin/rails generate action_agent:install --skip` (`--skip` keeps your
+initializer) and `bin/rails db:migrate`. A traces-only install needs neither;
+if you re-run the generator there, pass `--traces_only` again, or it emits the
+whole dashboard schema. Nothing else changes until an application publishes a
+report to the mount.
+
+### Added
+
+- **Host concerns for the engine's models and controllers** (`actionagent`).
+  `ActionAgent.model_concerns` is included into
+  `ActionAgent::ApplicationRecord` as it loads, and so into every engine
+  model; `ActionAgent.controller_concerns` into
+  `ActionAgent::ApplicationController`, ahead of its own callbacks, and so
+  into every dashboard controller. (The ingest endpoint,
+  `Api::TracesController`, inherits `ActionController::API` and keeps its
+  own bearer-token authentication; it is not touched.) Entries are modules
+  or their names, resolved
+  when the class loads. A host that pins the engine's tables to one database
+  connection, or carries its session helpers onto the dashboard's
+  controllers, configures that here instead of reopening the classes from a
+  `to_prepare` block.
+- **The Evaluations page is rebuilt around runs** (`actionagent`). Evaluations
+  are the top level; every run is kept and listed with its movement against
+  the run before it (`+3 passed vs #2`, `partial run`, `#1 failed`), and a
+  sampling evaluation's run opens to a page of its own at
+  `<mount>/evaluations/:id/runs/:run_id` — a scorecard per model cohort, the
+  judge's verdict, the criteria × models matrix and what the run asks to fix.
+  A scenario suite's runs are the same full-width list; a row selects the run
+  the suite's model scorecards, fix items and scenario matrix show.
+- **What a run cost is two figures, not one.** The agent's spend — what the
+  replayed or sampled interactions cost to serve, with a `per_interaction`
+  rate, the operating cost a per-conversation budget is set against — is
+  reported apart from the judge's, the judge model's own calls, which run
+  agent-to-agent and offline. Every judge call is metered under what it was
+  for (`scores["_judge_usage"]`: calls, tokens, estimated cost and how many
+  calls scored, recommended, ruled or authored KPIs), and `EvaluationRun#usage`
+  carries both sides. The page shows them on every run row, on the run, on a
+  page tile and in the footer, so the cost of operating an agent is never
+  inflated by the cost of checking it.
+- A generation-sampling run records `scores["_cohorts"]`: per model, how many
+  generations were sampled, how many cleared every criterion, their latency
+  and tokens, and what those interactions cost to serve.
+- `GET /api/evaluations` carries `run_count` and a `previous_run` summary per
+  evaluation, and every serialized run its `number` in the evaluation's
+  history, oldest first.
+- The dashboard's object lists hold their metric columns in place: a trace,
+  interaction or evaluation run with nothing in a column prints a dash there
+  rather than sliding its neighbours over (`MetaStrip`).
+- `ActiveAgent::Base.rendered_instructions` renders an agent's instructions
+  outside a generation, for a dashboard mirroring the class and for tests
+  asserting what a model is told. Both otherwise reached a private renderer
+  through `send`.
+- `ActionAgent::AgentSync` mirrors host agent classes into dashboard `Agent`
+  records, setting the `agent_class_name` that `AgentRelease` already expects a
+  host to have written. The code owns what an agent is (name, description,
+  instructions, tools — rewritten every sync); the operator owns how it runs
+  (provider, model, status — set on create and preserved), so a model chosen in
+  the dashboard survives the next deploy.
+- `ActionAgent.run_host_agent_classes` (default `false`) runs an agent that
+  mirrors a host class as that class, rather than as one rebuilt from the
+  record's `tools` and `instructions` columns. Dashboard-authored agents, which
+  name no class, keep using the dynamic runtime either way; a class name that no
+  longer resolves falls back to it rather than failing the run.
+- MCP servers take `allowed_tools` and `require_approval` in the common
+  format. OpenAI's Responses API receives both as given; Anthropic receives
+  `allowed_tools` as an `mcp_toolset` entry in `tools` (every other tool of
+  the server disabled), beside any tools the request already declares
+  (#328, by @dark-panda).
+- **A mounted engine collects published evaluation reports** (`actionagent`).
+  An application that runs its agents itself and evaluates them in-process
+  publishes the finished report with `ActiveAgent::Evals::Publisher`; until
+  now a self-hosted install had nowhere to receive it. On a full install (not
+  one generated with `--traces_only`, which answers 501),
+  `POST <mount>/api/evaluation_reports` takes the version-1 envelope and
+  returns the receipt the publisher checks, and
+  `ActionAgent::EvaluationReportImport` stores it as the engine's own rows:
+  the observed agent for the report's `source` and `agent_name`, an evaluation
+  named for its suite and scope (`orders (eu, support)`), its scenarios, and a
+  complete run with a result per scenario and model. The Evaluations page
+  shows it the way it shows a run the dashboard executed, with the summary
+  recomputed from the stored results. The endpoint authenticates exactly as
+  trace ingest does (`ingest_api_key`, or the tenant's key in multi-tenant
+  mode), takes only `application/json`, and places a report's agent wherever
+  `trace_owner_resolver` puts that tenant's traced agents. A `run_id` is
+  stored once per tenant, or once per install, and compared exactly: 201 for a
+  new report, 200 for an identical retry, 409 for different content. Invalid
+  reports, and an evaluation name the report does not own, are 422; a cap an
+  operator has to lift (observed agents per owner, 100 evaluations per agent,
+  2,000 scenarios per evaluation) is 403; a new report over the new
+  `:evaluation_report` quota kind or past 30 new reports a minute from a key
+  is 429. An identical retry is never refused by the quota or the rate limit.
+  Bodies over 2 MiB are 413, and Rails never parses the body into params, so
+  nothing past the limit is read. `usage_recorder` is told
+  `:evaluation_report` for each stored report. Evaluation runs gain
+  `external_tenant`, `external_run_id` and `external_report_digest`, unique on
+  the first two (binary on MySQL); see Upgrading above.
+  `docs/evals/publication.md` documents the endpoint.
+
+### Changed
+
+- The engine's judge blocks take `ActiveAgent::Evals::Judge`'s `kind:`, so a
+  scenario run's score, recommendation and verdict calls are metered apart.
+- `ActionAgent::TelemetryTrace` inherits `ActionAgent::ApplicationRecord`
+  like every other engine model (`actionagent`), so it carries the model
+  concerns above, `AdapterAware` and the ownership API (`owner_association`,
+  `for_owner`) from the same place. Its table name is unchanged.
+- `Api::TracesController`'s bearer authentication and its 429 quota body
+  live in `ActionAgent::Api::IngestAuthentication` (`actionagent`), which the
+  evaluation report collector shares. A host subclass that overrides
+  `authenticate_api_key!` is unaffected. The tenant's
+  `increment_telemetry_usage!` is still called for each trace ingest request,
+  and not for a report post.
+- `add_agent_releases` reads `ActionAgent.table_name_prefix` for the tables
+  it alters (`actionagent`), so a newly generated copy works on an install
+  with a custom prefix. The trace table keeps its fixed name.
+- A collector's rejection of `ActiveAgent::Evals::Publisher` says what it
+  refused and whether to retry. The message carries the `error` string of a
+  JSON object response body beside the HTTP status — control characters and
+  runs of whitespace collapsed to one space, the API key replaced with
+  `[FILTERED]`, cut to 200 characters; nothing else from the body — and what
+  to do next: never retry the report under the same `run_id` on a 409,
+  publish a smaller selection on a 413, correct the report on a 422, retry
+  later on a 408, 429 or 5xx, and resolve the cause first on anything else,
+  such as a 401 or 403. `Publisher::Error` carries `status`, `detail` and
+  `retryable?`.
+
+### Deprecated
+
+- Assigning `ActionAgent.base_controller_class`, which has never been
+  consumed, warns through `ActionAgent.deprecator` and points at
+  `controller_concerns`. The accessor is removed in 2.0.
+
+### Fixed
+
+- Telemetry criteria (`trace_error_rate`, `trace_latency`) score an observed
+  agent from its own traces (`actionagent`). They selected traces by
+  `Agent#telemetry_agent_class`, which appends `Agent` to a class name
+  lacking it, so an agent observed from an application reporting `SupportBot`
+  found no traces and scored nothing, and observed agents of one class ending
+  in `Agent` read each other's actions. `Agent#telemetry_traces` selects the
+  traces `AgentRegistrar` attributed to the agent, plus unattributed ones with
+  its service, class and action. Deleting an observed agent leaves its traces
+  unattributed, so the agent registered again for them still reads them. The
+  agent's Traces tab, its Tools tab usage
+  columns and the Interactions list filtered to it use the same selection. The
+  Traces tab asks for it with `GET /api/traces?agent_id=`, which answers 404
+  for an agent the caller cannot see; `agent=` still filters by class. On the
+  Metrics page filtered to a class, an observed agent's deploy markers now
+  show under the class its traces report (`Agent#reported_agent_class`).
+  Authored and mirrored agents read the traces they did before.
+- `Agent.prompt(...).generate_later` and `Agent.embed(...).embed_later` run
+  their job instead of raising `ArgumentError: unknown keywords` in the
+  worker (#346).
+- The agent builder and editor can reach every model a provider serves: the
+  OpenRouter catalog is no longer cut to its first 100 ids, and the model
+  field is a type-ahead over the catalog that also takes an unlisted id
+  (`actionagent`, #427).
+- A rejected Create Agent shows its validation errors on the builder — a
+  summary and a message under each field — instead of leaving the form
+  silently in place. `POST`/`PATCH /api/agents` 422s carry `field_errors`
+  beside `errors` (`actionagent`, #426).
+- An engine agent is refused a provider whose client gem the host has not
+  installed (`openai` for OpenAI, Ollama and OpenRouter; `anthropic` for
+  Anthropic) when the provider is chosen, with a validation error naming
+  the gem, instead of failing on its first run (`actionagent`, #416).
+- A fresh `action_agent:install` creates the agent release columns with the
+  dashboard tables (`actionagent`): `release_digest` on agents,
+  `release_digest` and `revision` on agent versions, and `agent_version_id`
+  on agent runs and evaluation runs. The generator emits `add_agent_releases`
+  before the create-table migration, so on a fresh install it found none of
+  those tables and added nothing, and creating an agent run or an evaluation
+run raised `NoMethodError` on `agent_version_id`. An install generated
+that way on 1.6.2-1.6.4 gets the columns from the new
+`ensure_agent_release_columns` migration (see Upgrading above).
+- Every failure of `ActiveAgent::Evals::Publisher` to deliver a report
+  raises `Publisher::Error`. A malformed response (`Net::HTTPBadResponse`,
+  `Net::HTTPHeaderSyntaxError`, or a `Zlib::Error` from corrupt compression)
+  escaped as its own class and is now a retryable `Publisher::Error`. A
+  report that cannot be encoded as JSON (invalid UTF-8, `NaN`, nesting too
+  deep) is now a non-retryable one raised before anything is sent: it escaped
+  as `JSON::GeneratorError`, or was blamed on the collector as invalid JSON.
+  Only a network failure keeps its underlying error as `cause`, so a response
+  body or report content never reaches a log through the exception chain.
+  Invalid arguments raise `ArgumentError`, now also for a `report` that does
+  not convert to a hash (a string raised `NoMethodError` and `nil` published
+  an empty report) and a `nil` timeout (`TypeError`).
+- The publisher strips whitespace around its API key, so the key it sends is
+  the one it filters from a collector's explanation, and refuses a key with
+  characters other than visible ASCII.
+
+### Security
+
+- The dashboard's JSON API verifies the CSRF token (`actionagent`, #461). It
+  authenticates with the host's session cookie but had opted out of forgery
+  protection. The dashboard now sends the page's token with every mutating
+  request from one fetch shim; the MCP facade and trace ingest, which
+  authenticate by bearer token, stay exempt. A rejected request answers
+  `422` with `code: "invalid_csrf_token"`. Hosts that re-enabled protection
+  themselves (`ActionAgent::Api::BaseController.protect_from_forgery`) can
+  drop that line.
+
 ## [1.6.4] - 2026-09-22
 
 Releases `activeagent` and `actionagent` 1.6.4 from one tag. A patch on 1.6.3

data/lib/active_agent/concerns/view.rb

@@ -12,6 +12,29 @@ module ActiveAgent
       include ActionView::Layouts
     end
 
+    class_methods do
+      # The agent's rendered instructions, outside a generation.
+      #
+      # Two surfaces need the text an agent would run on without running it: a
+      # dashboard that mirrors the class (ActionAgent::AgentSync) and a test
+      # asserting what the model is told. Both otherwise reach a private
+      # renderer through `send`, which couples them to internals that can move
+      # without notice.
+      #
+      #   TicketAgent.rendered_instructions  # => "You are the Ticket agent..."
+      #
+      #   TicketAgent.rendered_instructions(topic: "tickets")
+      #
+      # @param template [String] template name, default "instructions"
+      # @param assigns [Hash] instance variables the template reads
+      # @return [String, nil] nil when the agent has no such template
+      def rendered_instructions(template: "instructions", **assigns)
+        agent = new
+        assigns.each { |name, value| agent.instance_variable_set(:"@#{name}", value) }
+        agent.send(:view_render_template, template)
+      end
+    end
+
     # Builds template lookup paths supporting both flat and nested directory structures.
     #
     # Templates are searched in priority order:

data/lib/active_agent/evals/publisher.rb

@@ -4,6 +4,7 @@ require "json"
 require "net/http"
 require "openssl"
 require "uri"
+require "zlib"
 
 module ActiveAgent
   module Evals
@@ -11,11 +12,51 @@ module ActiveAgent
     # retain run_id when retrying: compatible collectors treat that identity as
     # immutable within the authenticated account. Delivery is blocking and does
     # not follow redirects with the account's bearer credential.
+    #
+    # Every failure to deliver raises Error. Invalid arguments raise
+    # ArgumentError before anything is sent.
     class Publisher
       DEFAULT_ENDPOINT = "https://api.activeagents.ai/v1/evaluations"
       MAX_BYTES = 2 * 1024 * 1024
-      class Error < StandardError; end
+      DETAIL_LIMIT = 200
 
+      # Raised for every failed delivery. Only a network failure keeps the
+      # underlying error as its +cause+, so neither the response nor the
+      # report reaches a log through the exception chain.
+      #
+      # @!attribute [r] status
+      #   @return [Integer, nil] the collector's HTTP status for a rejection, nil otherwise
+      # @!attribute [r] detail
+      #   @return [String, nil] the collector's sanitized explanation of a rejection, if it gave one
+      class Error < StandardError
+        attr_reader :status, :detail
+
+        def initialize(message = nil, status: nil, detail: nil, retryable: false)
+          super(message)
+          @status = status
+          @detail = detail
+          @retryable = retryable
+        end
+
+        # Returns true when delivering the same report under the same run_id
+        # again may succeed.
+        def retryable?
+          @retryable
+        end
+      end
+
+      # Whether each rejection status is retryable, and what the caller should
+      # do about it. Other statuses fall back to the rules in +rejection+.
+      REJECTIONS = {
+        409 => [ false, "the collector already holds a different report under this run_id; never retry this report with the same run_id" ],
+        413 => [ false, "the report exceeds the collector's size limit; publish a smaller selection" ],
+        422 => [ false, "correct what the collector refused before retrying" ],
+        429 => [ true, "the account is over its quota or rate limit; retain the report and run_id and retry later" ]
+      }.freeze
+
+      # The key is sent as a bearer token and filtered from the collector's
+      # explanation, so it is limited to visible ASCII: the sanitizer in
+      # +collector_detail+ never alters it, and an echo of it always matches.
       def initialize(api_key:, endpoint: DEFAULT_ENDPOINT, timeout: 10, open_timeout: 10)
         @uri = URI.parse(endpoint.to_s)
         unless @uri.is_a?(URI::HTTP) && @uri.host && !@uri.userinfo && !@uri.query && !@uri.fragment
@@ -24,12 +65,16 @@ module ActiveAgent
         unless @uri.scheme == "https" || %w[localhost 127.0.0.1 ::1].include?(@uri.hostname)
           raise ArgumentError, "Evaluation endpoint requires HTTPS except on loopback hosts"
         end
-        raise ArgumentError, "Evaluation API key is required" if api_key.to_s.strip.empty?
 
-        @api_key = api_key.to_s
-        @timeout = Float(timeout)
-        @open_timeout = Float(open_timeout)
-        unless [ @timeout, @open_timeout ].all? { |value| value.finite? && value.positive? }
+        @api_key = api_key.to_s.strip
+        raise ArgumentError, "Evaluation API key is required" if @api_key.empty?
+        unless @api_key.match?(/\A[\x21-\x7E]+\z/)
+          raise ArgumentError, "Evaluation API key must contain only visible ASCII characters"
+        end
+
+        @timeout = Float(timeout, exception: false)
+        @open_timeout = Float(open_timeout, exception: false)
+        unless [ @timeout, @open_timeout ].all? { |value| value&.finite? && value.positive? }
           raise ArgumentError, "Evaluation delivery timeouts must be positive and finite"
         end
       rescue URI::InvalidURIError
@@ -43,7 +88,7 @@ module ActiveAgent
         identities.each do |key, value|
           raise ArgumentError, "#{key} must be a nonempty string" unless value.is_a?(String) && !value.strip.empty?
         end
-        body = JSON.generate(identities.merge("version" => 1, "report" => report.to_h))
+        body = encode(identities.merge("version" => 1, "report" => report_hash(report)))
         raise Error, "Evaluation report exceeds the 2 MiB delivery limit; publish a smaller selection" if body.bytesize > MAX_BYTES
 
         http = Net::HTTP.new(@uri.hostname, @uri.port)
@@ -57,19 +102,70 @@ module ActiveAgent
         request["Accept"] = "application/json"
         request.body = body
         response = http.request(request)
-        unless %w[200 201].include?(response.code)
-          raise Error, "Evaluation delivery rejected (HTTP #{response.code}); retain the report and run_id for retry"
-        end
+        raise rejection(response) unless %w[200 201].include?(response.code)
 
-        receipt = JSON.parse(response.body)
+        receipt = JSON.parse(response.body.to_s)
         unless receipt.is_a?(Hash) && receipt["run_id"] == run_id && receipt["status"] == "complete" && receipt["id"] && receipt["evaluation_id"]
-          raise Error, "Evaluation collector returned an invalid completion receipt; retain the report and run_id for retry"
+          raise Error.new("Evaluation collector returned an invalid completion receipt; retain the report and run_id for retry", retryable: true)
         end
         receipt
       rescue JSON::ParserError
-        raise Error, "Evaluation collector returned invalid JSON; retain the report and run_id for retry"
+        # The parser's message quotes the body.
+        raise Error.new("Evaluation collector returned invalid JSON; retain the report and run_id for retry", retryable: true), cause: nil
+      rescue Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Zlib::Error => e
+        # These messages can quote the response's status line, headers or body.
+        raise Error.new("Evaluation collector returned a malformed response (#{e.class}); retain the report and run_id for retry", retryable: true), cause: nil
       rescue IOError, SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError => e
-        raise Error, "Evaluation delivery failed (#{e.class}); retain the report and run_id for retry"
+        raise Error.new("Evaluation delivery failed (#{e.class}); retain the report and run_id for retry", retryable: true)
+      end
+
+      private
+
+      def report_hash(report)
+        hash = report.to_h if report.respond_to?(:to_h) && !report.nil? && !report.is_a?(Array)
+        raise ArgumentError, "report must be a Report or its saved JSON hash" unless hash.is_a?(Hash)
+
+        hash
+      end
+
+      # Returns the envelope as JSON. A report holding invalid UTF-8, NaN,
+      # Infinity or nesting over JSON's depth limit raises a non-retryable
+      # Error, without the generator's message, which can quote the report.
+      def encode(envelope)
+        JSON.generate(envelope)
+      rescue JSON::JSONError, EncodingError => e
+        raise Error.new("Evaluation report cannot be encoded as JSON (#{e.class}); correct the report before publishing"), cause: nil
+      end
+
+      def rejection(response)
+        status = response.code.to_i
+        retryable, guidance = REJECTIONS.fetch(status) do
+          if status == 408 || (500..599).cover?(status)
+            [ true, "retain the report and run_id for retry" ]
+          else
+            [ false, "retain the report and run_id, and resolve the rejection before retrying" ]
+          end
+        end
+        detail = collector_detail(response.body)
+        reason = detail ? "HTTP #{status}: #{detail}" : "HTTP #{status}"
+        Error.new("Evaluation delivery rejected (#{reason}); #{guidance}", status: status, detail: detail, retryable: retryable)
+      end
+
+      # Returns the +error+ string of a JSON object body, or nil for any other
+      # body. Control characters and runs of whitespace become one space, the
+      # API key becomes [FILTERED], and the result is cut to DETAIL_LIMIT
+      # characters: `"answer\n\tis required"` → `"answer is required"`.
+      def collector_detail(body)
+        parsed = JSON.parse(body.to_s)
+        message = parsed["error"] if parsed.is_a?(Hash)
+        return unless message.is_a?(String)
+
+        detail = message.scrub.gsub(/[[:space:]\p{C}]+/, " ").strip.gsub(@api_key, "[FILTERED]")
+        return if detail.empty?
+
+        detail.length > DETAIL_LIMIT ? "#{detail[0, DETAIL_LIMIT - 1].rstrip}…" : detail
+      rescue JSON::ParserError, EncodingError
+        nil
       end
     end
   end

data/lib/active_agent/generation_job.rb

@@ -23,7 +23,21 @@ module ActiveAgent
     # argument, so a record arrives as the same record the caller passed and
     # the agent's authorization callbacks decide against a real user rather
     # than against nil.
-    def perform(agent, agent_method, generation_method, args:, kwargs: nil, params: nil, actor: nil)
+    #
+    # +direct_generation_type+ marks a job enqueued by Agent.prompt(...) or
+    # Agent.embed(...), which have no action to call: +agent_method+ is then
+    # the synthetic +__direct_*__+ name, so the generation is rebuilt from
+    # +direct_args+ and +direct_options+ instead.
+    def perform(agent, agent_method, generation_method, args:, kwargs: nil, params: nil, actor: nil,
+                direct_generation_type: nil, direct_args: nil, direct_options: nil)
+      if direct_generation_type
+        generation = ActiveAgent::Parameterized::DirectGeneration.new(
+          agent.constantize, direct_generation_type.to_sym, params || {},
+          *Array(direct_args), **(direct_options || {}).symbolize_keys
+        )
+        return generation.public_send(generation_method)
+      end
+
       agent_class = params ? agent.constantize.with(params) : agent.constantize
       agent_class = agent_class.as(actor) if actor
       prompt = if kwargs

data/lib/active_agent/providers/anthropic/transforms.rb

@@ -38,10 +38,20 @@ module ActiveAgent
             end
 
             # Handle mcps parameter (common format) -> transforms to mcp_servers (provider format)
-            if params[:mcps]
-              params[:mcp_servers] = normalize_mcp_servers(params.delete(:mcps))
-            elsif params[:mcp_servers]
-              params[:mcp_servers] = normalize_mcp_servers(params[:mcp_servers])
+            if params[:mcps] || params[:mcp_servers]
+              mcps = if params[:mcps]
+                params.delete(:mcps)
+              else
+                params[:mcp_servers]
+              end
+
+              params[:mcp_servers] = normalize_mcp_servers(mcps)
+
+              # A server's allowed_tools become an mcp_toolset entry beside the
+              # request's own tools. Added only when there is one: an empty
+              # list would send `"tools": null` on every MCP request.
+              mcp_tools = normalize_mcp_tools(mcps)
+              params[:tools] = Array(params[:tools]) + mcp_tools if mcp_tools.present?
             end
 
             params
@@ -111,6 +121,49 @@ module ActiveAgent
             end
           end
 
+          # Builds Anthropic mcp_toolset tool entries from MCP server allowed_tools.
+          #
+          # Accepts allowed_tools entries as tool-name strings/symbols or hashes
+          # with a :name key; entries in any other format are ignored.
+          #
+          # @param mcp_servers [Array<Hash>]
+          # @return [Array<Hash>, nil] toolset entries, or nil when none were extracted
+          def normalize_mcp_tools(mcp_servers)
+            return nil unless mcp_servers.is_a?(Array)
+
+            result = mcp_servers.filter_map do |server|
+              next unless server.is_a?(Hash)
+
+              server_hash = server.deep_symbolize_keys
+              allowed_tools = server_hash[:allowed_tools]
+              next unless allowed_tools.is_a?(Array)
+
+              configs = allowed_tools.filter_map { |tool|
+                name = case tool
+                when String, Symbol
+                  tool.to_s
+                when Hash
+                  (tool[:name] || tool["name"]).to_s
+                end
+
+                [ name, { enabled: true } ] if name.present?
+              }.to_h
+
+              next if configs.empty?
+
+              {
+                type: "mcp_toolset",
+                mcp_server_name: server_hash[:name],
+                default_config: {
+                  enabled: false
+                },
+                configs: configs
+              }
+            end
+
+            result.presence
+          end
+
           # Normalizes tool_choice from common format to Anthropic gem model objects.
           #
           # The Anthropic gem expects tool_choice to be a model object (ToolChoiceAuto,

data/lib/active_agent/providers/open_ai/responses/transforms.rb

@@ -96,6 +96,14 @@ module ActiveAgent
                   server_url: server_hash[:url] || server_hash[:server_url]
                 }
 
+                if server_hash[:require_approval]
+                  result[:require_approval] = server_hash[:require_approval]
+                end
+
+                if server_hash[:allowed_tools]
+                  result[:allowed_tools] = server_hash[:allowed_tools]
+                end
+
                 # Keep authorization field (OpenAI uses 'authorization', not 'authorization_token')
                 if server_hash[:authorization]
                   result[:authorization] = server_hash[:authorization]

data/lib/active_agent/version.rb

@@ -1,3 +1,3 @@
 module ActiveAgent
-  VERSION = "1.6.4"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activeagent
 version: !ruby/object:Gem::Version
-  version: 1.6.4
+  version: 1.7.0
 platform: ruby
 authors:
 - Justin Bowen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack