activeagent 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 867cf01603bb86b99c7abdbe6cc9e731264dc60bfdf3e89ca19a4d25fca5ea3d
-  data.tar.gz: c8b86f8988ff27931f4a82f8aa71aa04168bceae00f8f9cab6b98507dd3d2b94
+  metadata.gz: 45044ca9e6ddabcdfb1be0f32074149a3e9fb8fcaa9e7c8a79c02f81c73eb64b
+  data.tar.gz: 7f0a2489a68e01f0dd0e9a1fb96878bb900acaab173ba0a0157ad82a8a510fe6
 SHA512:
-  metadata.gz: 8c81f0537fddda60bbe3049cdb36b0478130d969ba0d35af408f3a5c527e2448d8e733638cd94b6c72c8f4b8d1ec13da32877baae3101e0373cc7d173253d06c
-  data.tar.gz: 6af0f6a1879a9e291581a51beb5b6b96ac2ec641a9ebc007cb2345c695e1f746741fbb667bd761f889591d15c7ffeb917e7ecb7c5d1151f4d6687af3f87a3930
+  metadata.gz: 7c4797fc3bc8e97be8624ef989abc1486fe0d357f5248353dd09bc9852de605e0b14cebb33f3fb35ba166f62e64f7ce5522f62da94ad25b5b188a771f1f8aeec
+  data.tar.gz: 72bc8b89a042c1d3fd2489de0eb452d2e95106eaf9a46ad4dc5e8f1378b3441345c0b652c123490804943064f16526a1baa67584ce4b2a4315255beb3783203e

data/CHANGELOG.md

@@ -5,7 +5,92 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.2.0] - Unreleased
+## [1.3.0] - 2026-08-18
+
+### Added
+
+- **Agent-as-tool delegation.** A tool is a Ruby method the model can call; a
+  delegation is another agent it can call. The callee keeps its own
+  instructions, templates, model and budget, so a specialist agent stays
+  specialist and the generalist orchestrating it never inherits its prompt.
+  Declared with `delegation :action, description:` on the sub-agent, with a
+  JSON Schema for the inputs and an optional `returns` schema that becomes the
+  sub-agent's response format. See `docs/actions/delegation.md`.
+
+### Fixed
+
+- **Streamed generations report their token usage.** A request with
+  `stream: true` recorded zero input and output tokens, and so zero cost and
+  no context-pressure estimate downstream — dashboards showed `Tokens 0` and
+  `$0.00` beside a run that had plainly called the API. Three things had to
+  hold at once for the usage to survive, and none did: the streaming path
+  returns `nil` rather than a response body to read usage from; Chat
+  Completions only emits its usage chunk when the request sets
+  `stream_options: {include_usage: true}`, which was never sent; and that
+  chunk arrives *after* `content.done`, where the response was already being
+  built. Completion now defers until the stream drains, and the usage chunk
+  is recorded on the way past. A provider hook (`api_stream_usage_parameters`,
+  empty by default) keeps providers that report unconditionally — or not at
+  all — unaffected.
+
+  Also fixed a silent conversion failure behind the same symptom:
+  `Usage.from_provider_usage` early-returns on anything that is not a Hash,
+  and the stainless gems hand back model objects, so usage was dropped even
+  when it did arrive.
+
+### Note on the 1.2.0 tag
+
+The `v1.2.0` tag had been moved to a commit later than the one published as
+`activeagent 1.2.0`, so the tag and the gem disagreed. It has been repointed
+to the commit that actually produced the release. If you fetched the tag
+between 2026-08-14 and 2026-08-18, re-fetch with `git fetch --tags --force`.
+
+## [1.2.2] - 2026-08-14
+
+### Fixed
+
+- **`actionagent`: every engine constant resolves under a host's
+  inflections.** 1.2.1 scoped its autoloader override to the basename `api`,
+  which covered the controllers under `app/controllers/action_agent/api` and
+  nothing else. Seven files camelize differently once a host registers an
+  acronym — `mcp_catalog.rb`, `mcp_recording_middleware.rb`,
+  `playwright_mcp_client.rb`, `api_key.rb`, and the `api_keys`, `mcp` and
+  `mcp_servers` controllers — and each raised `Zeitwerk::NameError` on first
+  reference. In a host declaring `inflect.acronym "MCP"` the **Tools view was
+  unreachable** (`uninitialized constant
+  ActionAgent::ToolDiscovery::McpCatalog`), as were the MCP endpoints and
+  anything touching an API key.
+
+  Every path under the engine now camelizes with Zeitwerk's default
+  inflector, ignoring the host's acronyms, scoped by path so the host's own
+  constants keep their spelling. The router half generalizes with it: an
+  all-caps run in a missing constant is retried in the relaxed spelling
+  (`API` → `Api`, `MCPServersController` → `McpServersController`) rather
+  than aliasing each pair by hand.
+
+## [1.2.1] - 2026-08-14
+
+### Fixed
+
+- **`actionagent`: the install migrations now run on MySQL.** Both templates
+  already chose the JSON column type per adapter, but kept `default: []` /
+  `default: {}` for every adapter, and MySQL rejects a default on a JSON
+  column outright — so `rails g action_agent:install && rails db:migrate`
+  aborted mid-`create_table` on any MySQL host. The default (and the paired
+  `null: false`, which without it would reject the inserts the default
+  existed to satisfy) is now PostgreSQL-only. Every JSON column is read
+  through `Array(...)` / `|| {}`, so a NULL reads as the empty value.
+- **`actionagent`: the mount works in a host that declares
+  `inflect.acronym "API"`.** An engine's files are autoloaded under the
+  host's inflections, so such a host made Zeitwerk expect
+  `ActionAgent::API::TracesController` from a file defining
+  `ActionAgent::Api::TracesController`, and every request to the mount
+  raised `Zeitwerk::NameError`. Rails separately camelizes a route's stored
+  controller path with the host's global inflections, which no engine-level
+  setting scopes. The autoloader is now pinned to `Api` for this engine's
+  own path, and the namespace answers to `API` as well.
+
+## [1.2.0] - 2026-08-14
 
 ### ⚠️ The dashboard has moved to its own gem
 
@@ -106,6 +191,45 @@ observability surface (see `docs/framework/self-hosted-observability.md`):
   it remains a no-op accessor with its historical default so existing
   initializers keep booting, and will be removed in the next major.
 
+### Agent-as-tool delegation
+
+Sub-agents are now a first-class primitive. A tool is a Ruby method your
+model can call; a delegation is another agent your model can call — with
+its own instructions, templates, model and budget.
+
+- **`delegation :action, description:`** declares what a sub-agent exposes:
+  a description for the calling model, a JSON Schema for its inputs (block
+  DSL, a plain hash, or any class responding to `to_json_schema`), and
+  optionally a `returns` schema. A declared `returns` becomes the
+  sub-agent's `response_format`, and its answer is parsed and checked
+  before the caller sees it.
+- **`delegate_to AgentClass`** exposes those contracts to the calling model
+  as tools, with `only:`/`except:`/`as:` for scoping and renaming,
+  `params:` for forwarding, and `action:` for declaring a contract at the
+  call site when you don't own the sub-agent. Per-action scoping via the
+  `delegations:` prompt option.
+- **Cost and latency budgets**: `max_calls`, `max_tokens`, `max_cost`,
+  `max_duration` and a per-call `timeout`, set per delegation and/or
+  agent-wide with `delegation_budget`. Exhausting one returns a structured
+  result the model can act on (`on_exceeded: :stop`, the default) instead
+  of raising mid-conversation; `:raise` is available. Budgets are scoped
+  to a single generation, and spend is readable afterwards via
+  `delegation_ledger`.
+- **Swappable backends**: `backend: :ollama` or
+  `backend: { provider: :anthropic, model: "claude-haiku-4-5" }` moves a
+  delegation to different silicon without touching the sub-agent. Provider
+  swaps rebuild provider configuration rather than merging over it, and
+  template lookup still resolves to the original agent's views.
+- **Cost registry**: `ActiveAgent::Delegation::Pricing.register` records
+  token rates in USD per 1M tokens (no built-in price list, so `max_cost`
+  never fires on stale numbers); rates can also be stated inline on a budget.
+- **Instrumentation**: `delegate.active_agent` (agent, sub-agent, action,
+  model, duration, usage, cost, ledger) and
+  `delegation_refused.active_agent` (violated limit).
+- **New docs** (`docs/actions/delegation.md`) with a worked support-triage
+  example, plus test coverage in `test/features/delegation_test.rb` and
+  `test/docs/actions/delegation_examples_test.rb`.
+
 ### Dashboard & Telemetry — dev console readiness
 
 The dashboard engine — Active Agent's local dev console — now works out of

data/README.md

@@ -10,6 +10,16 @@
 >
 > *Makes code [TonsOfFun](https://tonsoffun.github.io)!*
 
+[![Gem Version](https://img.shields.io/gem/v/activeagent?label=activeagent&logo=rubygems&color=CC342D)](https://rubygems.org/gems/activeagent)
+[![actionagent](https://img.shields.io/gem/v/actionagent?label=actionagent&logo=rubygems&color=CC342D)](https://rubygems.org/gems/actionagent)
+[![Downloads](https://img.shields.io/gem/dt/activeagent?label=downloads)](https://rubygems.org/gems/activeagent)
+[![CI](https://github.com/activeagents/activeagent/actions/workflows/ci.yml/badge.svg)](https://github.com/activeagents/activeagent/actions/workflows/ci.yml)
+[![Cross-repo integration](https://github.com/activeagents/activeagent/actions/workflows/integration.yml/badge.svg)](https://github.com/activeagents/activeagent/actions/workflows/integration.yml)
+[![Docs](https://img.shields.io/badge/docs-docs.activeagents.ai-2563eb)](https://docs.activeagents.ai)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-CC342D)](https://www.ruby-lang.org)
+[![Rails](https://img.shields.io/badge/rails-7.2%20%7C%208.0%20%7C%208.1-D30001)](https://rubyonrails.org)
+[![License](https://img.shields.io/github/license/activeagents/activeagent)](LICENSE)
+
 # Active Agent
 Active Agent provides that missing AI layer in the Rails framework, offering a structured approach to building AI-powered applications through Agent Oriented Programming. **Now Agents are Controllers!** Designing applications using agents allows developers to create modular, reusable components that can be easily integrated into existing systems. This approach promotes code reusability, maintainability, and scalability, making it easier to build complex AI-driven applications with the Object Oriented Ruby code you already use today.
 
@@ -171,6 +181,7 @@ a free low-volume trial.
 - **View Templates**: Use ERB templates for prompts (text, JSON, HTML)
 - **Streaming Support**: Real-time response streaming with ActionCable
 - **Tool/Function Calling**: Agents can use tools to interact with external services
+- **Agent-as-Tool Delegation**: Hand work to sub-agents with declared schemas, cost/latency budgets, and swappable backends
 - **Context Management**: Maintain conversation history across interactions
 - **Structured Output**: Define JSON schemas for predictable responses
 
@@ -205,6 +216,29 @@ response = prompt.generate_now
 # Response includes tool call results
 ```
 
+### Delegation
+Hand part of a job to a sub-agent, under a declared contract and a budget:
+
+```ruby
+class SummarizerAgent < ApplicationAgent
+  generate_with :openai, model: "gpt-4o-mini"
+
+  delegation :summarize, description: "Condense a document into key points" do
+    string :text, required: true, description: "Full document text"
+  end
+
+  def summarize(text:) = prompt(message: text)
+end
+
+class ResearchAgent < ApplicationAgent
+  generate_with :openai, model: "gpt-4o"
+
+  delegate_to SummarizerAgent, budget: { max_calls: 3, timeout: 20 }
+
+  def research(topic:) = prompt(message: "Research #{topic}")
+end
+```
+
 ## Learn More
 
 - [Documentation](https://docs.activeagents.ai)

data/lib/active_agent/base.rb

@@ -5,6 +5,7 @@ require "active_support/core_ext/module/anonymous"
 require "active_support/core_ext/string/inflections"
 
 require "active_agent/concerns/callbacks"
+require "active_agent/concerns/delegation"
 require "active_agent/concerns/observers"
 require "active_agent/concerns/parameterized"
 require "active_agent/concerns/preview"
@@ -42,6 +43,7 @@ module ActiveAgent
     include AbstractController::Caching
 
     include Callbacks
+    include Delegation
     include Parameterized
     include Provider
     include Queueing
@@ -299,18 +301,25 @@ module ActiveAgent
 
     # @api private
     def prepare_prompt_parameters
-      parameters = prompt_options.deep_dup.except(:locals, *PROTECTED_OPTIONS)
+      parameters = prompt_options.deep_dup.except(:locals, :delegations, *PROTECTED_OPTIONS)
 
       # Render out proc/lamda attributes before rendering templates
       parameters.deep_transform_values! { _1.respond_to?(:call) ? _1.call : _1 }
 
+      # Expose declared sub-agents (agent-as-tool) alongside the action's own tools
+      parameters = apply_delegated_tools(parameters, prompt_options)
+
       # Strip parameters the target model rejects (e.g. temperature/top_p
       # on thinking-first models) before they reach the provider.
       ModelCapabilities.sanitize!(parameters)
 
       # Apply Callbacks
+      #
+      # The trace id is written back so it stays stable for the generation and
+      # readable from prompt_options — delegated sub-agents inherit it, which
+      # is what lets a delegation tree show up as one trace.
       parameters.merge!(
-        trace_id: prompt_options[:trace_id] || SecureRandom.uuid,
+        trace_id: prompt_options[:trace_id] ||= SecureRandom.uuid,
         exception_handler:,
         stream_broadcaster:,
         tools_function:,

data/lib/active_agent/concerns/delegation.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+require "active_agent/delegation/schema"
+require "active_agent/delegation/pricing"
+require "active_agent/delegation/budget"
+require "active_agent/delegation/ledger"
+require "active_agent/delegation/backend"
+require "active_agent/delegation/contract"
+require "active_agent/delegation/definition"
+require "active_agent/delegation/runner"
+
+module ActiveAgent
+  # Agent-as-tool delegation: hand part of a job to another agent.
+  #
+  # A tool is a Ruby method the model can call. A *delegation* is another agent
+  # the model can call — same mechanism, but the callee has its own
+  # instructions, its own templates, its own model, and its own budget. That
+  # separation is what makes the pattern worth having as a primitive: a
+  # specialist agent stays specialist, and the generalist orchestrating it
+  # never inherits its prompt.
+  #
+  # Delegation has three moving parts, each declared where it belongs:
+  #
+  # * **The contract** lives on the sub-agent, next to the action it describes.
+  #   Callers say which agent they want; they never restate its parameters.
+  # * **The budget** lives at the call site, because only the caller knows what
+  #   the work is worth. Exceeding it returns a structured result the model can
+  #   reason about, not an exception that ends the conversation.
+  # * **The backend** lives at the call site too, so the same sub-agent can run
+  #   on a cheap local model in one parent and a frontier model in another
+  #   without either agent's code changing.
+  #
+  # @example Declaring a sub-agent's contract
+  #   class SummarizerAgent < ApplicationAgent
+  #     generate_with :openai, model: "gpt-4o-mini"
+  #
+  #     delegation :summarize, description: "Condense a document into key points" do
+  #       string  :text, required: true, description: "Full document text"
+  #       integer :limit, description: "Maximum number of key points to return"
+  #
+  #       returns do
+  #         string :summary, required: true, description: "One-paragraph summary"
+  #         array  :points, of: :string, required: true, description: "The key points"
+  #       end
+  #     end
+  #
+  #     def summarize(text:, limit: 5)
+  #       prompt(message: text, limit: limit)
+  #     end
+  #   end
+  #
+  # @example Delegating to it
+  #   class ResearchAgent < ApplicationAgent
+  #     generate_with :openai, model: "gpt-4o"
+  #
+  #     delegation_budget max_calls: 8, max_duration: 60
+  #
+  #     delegate_to SummarizerAgent, budget: { max_calls: 3, timeout: 20 }
+  #     delegate_to FactCheckAgent, as: :verify, backend: { provider: :anthropic, model: "claude-haiku-4-5" }
+  #
+  #     def research(topic:)
+  #       prompt(message: "Research #{topic}. Summarize sources before citing them.")
+  #     end
+  #   end
+  #
+  # @see ActiveAgent::Delegation::Contract
+  # @see ActiveAgent::Delegation::Budget
+  # @see ActiveAgent::Delegation::Backend
+  module Delegation
+    extend ActiveSupport::Concern
+
+    # Raised when a delegation budget is exhausted and the policy is +:raise+.
+    class BudgetExceededError < StandardError
+      # @return [Budget::Violation]
+      attr_reader :violation
+      # @return [Definition]
+      attr_reader :definition
+
+      def initialize(violation, definition:)
+        @violation  = violation
+        @definition = definition
+
+        super("#{definition.agent_class}##{definition.action} exceeded its delegation budget " \
+              "(#{violation.limit}: #{violation.used} of #{violation.allowed} used)")
+      end
+    end
+
+    # Raised when a delegated call exceeds its timeout and the policy is +:raise+.
+    class TimeoutError < StandardError; end
+
+    # Raised when a sub-agent's output does not satisfy its declared +returns+
+    # schema and the policy is +:raise+.
+    class InvalidResultError < StandardError; end
+
+    included do
+      # Contracts this agent exposes to callers, keyed by action.
+      class_attribute :delegation_contracts, instance_accessor: false, default: {}.freeze
+
+      # Sub-agents this agent delegates to, keyed by tool name.
+      class_attribute :delegations, instance_accessor: false, default: {}.freeze
+
+      # Budget covering *all* delegated work in one generation.
+      class_attribute :_delegation_budget, instance_accessor: false, default: Budget.new
+    end
+
+    class_methods do
+      # Declares what this agent exposes to callers: one action, its inputs,
+      # and optionally the shape of what it returns.
+      #
+      # The description is the only thing a calling model reads before deciding
+      # whether to hand work over — write it for someone who has never seen the
+      # code.
+      #
+      # @param action [Symbol, String] the action a caller invokes
+      # @param description [String] what the action does
+      # @param schema [Hash, Class, Delegation::Schema, nil] inputs, when not using the block DSL
+      # @param returns [Hash, Class, Delegation::Schema, nil] declared output shape
+      # @param budget [Hash, Delegation::Budget, nil] default budget callers inherit
+      # @param on_invalid [Symbol] +:error+ (default) or +:raise+ when output misses required keys
+      # @yield input DSL; call +returns+ inside it to declare the output shape
+      # @return [Delegation::Contract]
+      #
+      # @example
+      #   delegation :translate, description: "Translate text into a target language" do
+      #     string :text, required: true, description: "Text to translate"
+      #     string :locale, required: true, description: "BCP 47 target locale, e.g. pt-BR"
+      #   end
+      def delegation(action, description: nil, schema: nil, returns: nil, budget: nil, on_invalid: :error, &block)
+        contract = Delegation::Contract.new(
+          action: action, description: description, schema: schema,
+          returns: returns, budget: budget, on_invalid: on_invalid, &block
+        )
+
+        self.delegation_contracts = delegation_contracts.merge(contract.action => contract).freeze
+
+        contract
+      end
+
+      # Exposes another agent to this agent's model as a tool.
+      #
+      # With no options, every contract the sub-agent declares becomes a tool.
+      # Narrow that with +only:+/+except:+, rename with +as:+, or declare a
+      # contract inline with +action:+ when you don't own the sub-agent.
+      #
+      # @param agent_class [Class] the sub-agent
+      # @param only [Symbol, Array<Symbol>, nil] expose just these actions
+      # @param except [Symbol, Array<Symbol>, nil] expose everything but these actions
+      # @param as [Symbol, String, nil] tool name (defaults to the action name)
+      # @param action [Symbol, String, nil] declare a contract inline for this action
+      # @param description [String, nil] overrides the contract's description
+      # @param schema [Hash, Class, Delegation::Schema, nil] inline contract inputs
+      # @param returns [Hash, Class, Delegation::Schema, nil] inline contract outputs
+      # @param backend [Symbol, Hash, Delegation::Backend, nil] provider/model to run this delegation on
+      # @param budget [Hash, Delegation::Budget, nil] limits for this delegation
+      # @param params [Hash, Symbol, Proc, nil] params forwarded to the sub-agent
+      # @yield inline contract input DSL
+      # @return [Array<Delegation::Definition>]
+      # @raise [ArgumentError] on an unknown action, a name collision, or a sub-agent with no contracts
+      #
+      # @example Everything the sub-agent declares
+      #   delegate_to SummarizerAgent
+      #
+      # @example One action, renamed, on a different backend, with a budget
+      #   delegate_to SummarizerAgent, only: :summarize, as: :condense,
+      #               backend: { model: "gpt-4o-mini" }, budget: { max_calls: 3 }
+      #
+      # @example An agent you don't own, described from here
+      #   delegate_to Vendor::ClassifierAgent, action: :classify,
+      #               description: "Classify a support ticket" do
+      #     string :body, required: true, description: "Ticket body"
+      #   end
+      def delegate_to(agent_class, only: nil, except: nil, as: nil, action: nil, description: nil,
+                      schema: nil, returns: nil, backend: nil, budget: nil, params: nil, &block)
+        contracts = delegation_contracts_for(agent_class, action:, only:, except:, description:, schema:, returns:, &block)
+
+        if (as || description) && contracts.size > 1
+          raise ArgumentError, "`as:` and `description:` describe a single delegation, but #{agent_class} exposes " \
+            "#{contracts.size} (#{contracts.map(&:action).join(", ")}). Narrow it with `only:` first."
+        end
+
+        contracts.map do |contract|
+          define_delegation Delegation::Definition.new(
+            agent_class: agent_class, contract: contract, tool_name: as,
+            description: description, backend: backend, budget: budget, params: params
+          )
+        end
+      end
+
+      # Budget covering every delegation this agent makes in one generation.
+      #
+      # Per-delegation budgets still apply; a call has to clear both. Called
+      # without arguments it reads the current budget.
+      #
+      # @param limits [Hash] see {Delegation::Budget}
+      # @return [Delegation::Budget]
+      #
+      # @example
+      #   delegation_budget max_calls: 10, max_duration: 60, max_cost: 0.25
+      def delegation_budget(**limits)
+        self._delegation_budget = _delegation_budget.merge(Delegation::Budget.build(limits)) if limits.any?
+
+        _delegation_budget
+      end
+
+      # Tool definitions for this agent's delegations, in the common tools format.
+      #
+      # @param filter [nil, true, false, Symbol, Array<Symbol>] which delegations to include
+      # @return [Array<Hash>]
+      def delegated_tools(filter = nil)
+        delegations_for(filter).map(&:to_tool)
+      end
+
+      # @param filter [nil, true, false, Symbol, Array<Symbol>]
+      # @return [Array<Delegation::Definition>]
+      def delegations_for(filter = nil)
+        case filter
+        when nil, true then delegations.values
+        when false     then []
+        else
+          names = Array(filter).map(&:to_sym)
+          unknown = names - delegations.keys
+          raise ArgumentError, "Unknown #{"delegation".pluralize(unknown.size)}: #{unknown.join(", ")}. " \
+            "This agent delegates to: #{delegations.keys.join(", ").presence || "(none)"}" if unknown.any?
+
+          delegations.values_at(*names)
+        end
+      end
+
+      private
+
+      # Registers a definition and the tool method the provider routes to.
+      #
+      # @param definition [Delegation::Definition]
+      # @return [Delegation::Definition]
+      def define_delegation(definition)
+        assert_available_tool_name!(definition)
+
+        self.delegations = delegations.merge(definition.tool_name => definition).freeze
+
+        tool_name = definition.tool_name
+        define_method(tool_name) do |**arguments|
+          perform_delegation(tool_name, **arguments)
+        end
+
+        definition
+      end
+
+      # @param definition [Delegation::Definition]
+      # @raise [ArgumentError]
+      def assert_available_tool_name!(definition)
+        name = definition.tool_name
+        return if delegations.key?(name) # re-declaring a delegation is a deliberate override
+
+        if method_defined?(name) || private_method_defined?(name)
+          raise ArgumentError, "#{self} already responds to ##{name}, so it cannot also be the tool name for " \
+            "#{definition.agent_class}##{definition.action}. Rename it with `as:`."
+        end
+      end
+
+      # @return [Array<Delegation::Contract>]
+      def delegation_contracts_for(agent_class, action:, only:, except:, description:, schema:, returns:, &block)
+        assert_agent_class!(agent_class)
+
+        if action
+          assert_action!(agent_class, action)
+
+          return [ Delegation::Contract.new(
+            action: action, description: description, schema: schema, returns: returns, &block
+          ) ]
+        end
+
+        contracts = agent_class.delegation_contracts.values
+
+        if contracts.empty?
+          raise ArgumentError, "#{agent_class} does not declare any delegations. Add " \
+            "`delegation :action_name, description: \"...\"` to it, or declare one here with " \
+            "`delegate_to #{agent_class}, action: :action_name, description: \"...\"`."
+        end
+
+        contracts = filter_contracts(contracts, only: only, except: except, agent_class: agent_class)
+        contracts.each { |contract| assert_action!(agent_class, contract.action) }
+        contracts
+      end
+
+      # @return [Array<Delegation::Contract>]
+      def filter_contracts(contracts, only:, except:, agent_class:)
+        selected = contracts
+
+        if only
+          names = Array(only).map(&:to_sym)
+          assert_declared!(agent_class, names, contracts)
+          selected = selected.select { |contract| names.include?(contract.action) }
+        end
+
+        if except
+          names = Array(except).map(&:to_sym)
+          assert_declared!(agent_class, names, contracts)
+          selected = selected.reject { |contract| names.include?(contract.action) }
+        end
+
+        raise ArgumentError, "No delegations left on #{agent_class} after applying only:/except:" if selected.empty?
+
+        selected
+      end
+
+      # @raise [ArgumentError]
+      def assert_declared!(agent_class, names, contracts)
+        unknown = names - contracts.map(&:action)
+        return if unknown.empty?
+
+        raise ArgumentError, "#{agent_class} does not declare #{"delegation".pluralize(unknown.size)} " \
+          "#{unknown.join(", ")}. It declares: #{contracts.map(&:action).join(", ")}"
+      end
+
+      # @raise [ArgumentError]
+      def assert_agent_class!(agent_class)
+        return if agent_class.is_a?(Class) && agent_class < ActiveAgent::Base
+
+        raise ArgumentError, "delegate_to expects an ActiveAgent::Base subclass, got #{agent_class.inspect}"
+      end
+
+      # @raise [ArgumentError]
+      def assert_action!(agent_class, action)
+        return if agent_class.method_defined?(action) || agent_class.private_method_defined?(action)
+
+        raise ArgumentError, "#{agent_class} does not define ##{action}, so it cannot be delegated to."
+      end
+    end
+
+    # Ledger covering every delegation made during this generation.
+    #
+    # @return [Delegation::Ledger]
+    def delegation_ledger
+      @_delegation_ledger ||= Delegation::Ledger.new
+    end
+
+    # Ledger for a single delegation during this generation.
+    #
+    # @param tool_name [Symbol, String]
+    # @return [Delegation::Ledger]
+    def delegation_ledger_for(tool_name)
+      delegation_ledgers[tool_name.to_sym] ||= Delegation::Ledger.new
+    end
+
+    # @return [Hash{Symbol => Delegation::Ledger}] per-delegation ledgers
+    def delegation_ledgers
+      @_delegation_ledgers ||= {}
+    end
+
+    # Runs a delegated call. Providers reach this through the tool method
+    # {ClassMethods#delegate_to} defines.
+    #
+    # @param tool_name [Symbol, String]
+    # @param arguments [Hash]
+    # @return [Object]
+    def perform_delegation(tool_name, **arguments)
+      definition = self.class.delegations[tool_name.to_sym]
+      raise ArgumentError, "#{self.class} has no delegation named #{tool_name}" unless definition
+
+      Delegation::Runner.new(definition, owner: self).call(**arguments)
+    end
+
+    private
+
+    # Merges declared delegations into the tools the provider is given.
+    #
+    # Scope them per action with the +delegations:+ prompt option: +false+ for
+    # none, or a name/list for a subset.
+    #
+    # @param parameters [Hash]
+    # @param prompt_options [Hash]
+    # @return [Hash]
+    # @api private
+    def apply_delegated_tools(parameters, prompt_options)
+      tools = self.class.delegated_tools(prompt_options[:delegations])
+      return parameters if tools.empty?
+
+      declared = Array(parameters[:tools])
+      names    = declared.filter_map { |tool| (tool[:name] || tool["name"]).to_s if tool.is_a?(Hash) }
+
+      parameters[:tools] = declared + tools.reject { |tool| names.include?(tool[:name]) }
+      parameters
+    end
+  end
+end