openai 0.97.0 → 0.98.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad027591f42a7f1aed3f0ac973b22b81f8d4a1171e30d311845b8ece12b0cc30
-  data.tar.gz: 70db67b389fe4053242e587dad3ea8a7fb9477f160278e213c4206cbe03d6289
+  metadata.gz: 490515bf12013414fe683641c2357dc16e15a26354bbc9436fef0dc7b901589f
+  data.tar.gz: db7eeb1fb9efa3745ac7d8bc37789450aac6212eee254d5a25d6d63c1f59fcfa
 SHA512:
-  metadata.gz: e14a2a0287715824fe9271eed406677661ac595d8b3851f2e24480b3c6d365362f067ad8e207e99cff2246cedd247f6d82a7007a487a37bd8c381dce3b8479d3
-  data.tar.gz: 647c42ecf4d655d2148e23c42253d057ffc569189541fd58333144b73663c3b4cf3adf9d9cfb51b0d98123cdabcd9c8458c2d3f8c169347e3e70a0bcc1978571
+  metadata.gz: b09e97bdd9d0589478bb3d68a31212e431e0ff1b691de4c54849fd993222ed14b9116417ddf31c1e7b9050478422305c86e314b2f28b8b587ddc81be13481250
+  data.tar.gz: 78664445a99113c083afbc48295d7e6a11bfcbdef798b69eb97e9283c8f77fc4477367895bf583a9c390af53925dd1fcb323c860e79c127b12edcc13b442c323

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.98.0](https://github.com/openai/openai-ruby/compare/v0.97.0...v0.98.0) (2026-10-01)
+
+
+### Features
+
+* **agents:** [1/n] parse typed output into Ruby models ([#796](https://github.com/openai/openai-ruby/issues/796)) ([49b8b70](https://github.com/openai/openai-ruby/commit/49b8b70763db318134f0eedd82bd91a7bd269943))
+* **agents:** prepare hosted files and download result artifacts ([#798](https://github.com/openai/openai-ruby/issues/798)) ([9853389](https://github.com/openai/openai-ruby/commit/9853389e6c5a428c836d8ac2e4af991519e9630d))
+* **api:** Add session traces and translation secrets ([#789](https://github.com/openai/openai-ruby/issues/789)) ([79e3e0c](https://github.com/openai/openai-ruby/commit/79e3e0c550e3630253bd79423a04fb108cbaa642))
+* bind typed application actions to beta agent tools ([#795](https://github.com/openai/openai-ruby/issues/795)) ([c8cab4a](https://github.com/openai/openai-ruby/commit/c8cab4aa699f8563946991f6b949f4ae73b212d7))
+* collect final output from beta Agents streams ([#793](https://github.com/openai/openai-ruby/issues/793)) ([35aaa3a](https://github.com/openai/openai-ruby/commit/35aaa3a881a13583bc28e25240bc86e2312ae647))
+
+
+### Bug Fixes
+
+* **api:** allow original image detail in Chat Completions ([#794](https://github.com/openai/openai-ruby/issues/794)) ([8bb025d](https://github.com/openai/openai-ruby/commit/8bb025dac3f0336309a6e12764d7520959fda0fd))
+* **api:** correct the eval run cancellation endpoint ([#791](https://github.com/openai/openai-ruby/issues/791)) ([6a99f63](https://github.com/openai/openai-ruby/commit/6a99f632f0c3a9009b90b671380a8840a4c68cd1))
+* enforce decoded WebSocket budget on inflater tails ([#792](https://github.com/openai/openai-ruby/issues/792)) ([2acfaf8](https://github.com/openai/openai-ruby/commit/2acfaf87c702b4ddc61ff7506f857c98ef8aa27d))
+* retire canceled Responses and Live websocket writes ([#787](https://github.com/openai/openai-ruby/issues/787)) ([de62191](https://github.com/openai/openai-ruby/commit/de621915ed28f5dcc8434a61e83a976a103f2fa6))
+
+
+### Chores
+
+* **api:** retain WebRTC Live session transport types ([#790](https://github.com/openai/openai-ruby/issues/790)) ([1f15936](https://github.com/openai/openai-ruby/commit/1f159369caa98861eb45ba6c614635b9cf39a16f))
+
 ## [0.97.0](https://github.com/openai/openai-ruby/compare/v0.96.0...v0.97.0) (2026-09-29)
 
 

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openai", "~> 0.97.0"
+gem "openai", "~> 0.98.0"
 ```
 
 <!-- x-release-please-end -->
@@ -50,6 +50,81 @@ stream.each do |event|
 end
 ```
 
+### Agents final output (beta)
+
+Collect final output from an Agents creation stream:
+
+```ruby
+stream = openai.beta.agents.sessions.create_streaming(
+  agent: {model: "gpt-5.2", instructions: "Explain the supplied policy clearly."},
+  environment: {type: :none},
+  input: "Explain this policy: ..."
+)
+result = stream.get_final_result
+puts(result.output_text)
+```
+
+Use the same getter for follow-ups; to display progress first, call
+`stream.with_result_collection` before iterating:
+
+```ruby
+openai.beta.agents.sessions.stream(result.session_id, input: "Give an example.") do |stream|
+  puts(stream.get_final_result.output_text)
+end
+```
+
+The beta result includes `turn` metadata and final `messages`; unsuccessful or
+incomplete collection raises `OpenAI::Helpers::Beta::Agents::ResultError`.
+
+### Typed Agents output (beta)
+
+Use an `OpenAI::BaseModel` with `output_type` to configure and parse a structured answer:
+
+```ruby
+class Report < OpenAI::BaseModel
+  required :summary, String
+  required :findings, OpenAI::ArrayOf[String]
+end
+
+result = openai.beta.agents.sessions.create_streaming(
+  agent: {model: "gpt-5.2"}, environment: {type: :none},
+  input: "Summarize these notes: ...", output_type: Report
+).get_final_result
+puts(result.output_parsed.summary)
+
+openai.beta.agents.sessions.stream(result.session_id, input: "Update the report.", output_type: Report) do |stream|
+  puts(stream.get_final_result.output_parsed.summary)
+end
+```
+
+Parsing follows the SDK’s existing `BaseModel` conventions. Each output-text item is parsed separately; `output_parsed` returns the first. Follow-up `output_type` only parses the answer; it does not change the session's schema.
+`OutputParseError#raw_result` preserves the completed answer if parsing fails.
+
+### Hosted files and artifacts
+
+Prepare selected local files before creating a hosted session, or use `upload` to stage one in an existing environment. Keep `upload_ids` for explicit cleanup through the Files API.
+
+```ruby
+prepared = openai.beta.agents.environments.files.prepare({
+  "/workspace/source.pdf" => Pathname("source.pdf")
+})
+stream = openai.beta.agents.sessions.create_streaming(
+  agent: {model: "gpt-6-astra"},
+  environment: {type: :openai_hosted, files: prepared.files},
+  input: "Read source.pdf and write /workspace/outputs/report.md"
+)
+result = stream.get_final_result
+artifacts = openai.beta.agents.sessions.artifacts.for_result(result)
+artifacts.download(path: "/workspace/outputs/report.md", to: Pathname("report.md"))
+
+# Or keep the downloaded bytes in memory:
+buffer = StringIO.new
+artifacts.download(path: "/workspace/outputs/report.md", to: buffer)
+puts(buffer.string)
+```
+
+`prepare_directory(directory, destination:, include:)` stages an explicitly selected snapshot. Local path and directory helpers assume stable, application-owned source paths; they are not a filesystem sandbox for arbitrary user-supplied paths or hostile local writers. Downloads select the exact result turn and stream to an application-owned local path or the writer you supply. An interrupted transfer may leave partial contents.
+
 ### Local audio
 
 Record a clip and play generated speech with optional FFmpeg/FFplay helpers.

data/lib/openai/helpers/agents/session_stream.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "tools"
+require_relative "../beta/agents/result"
 
 module OpenAI
   module Helpers
@@ -13,13 +14,26 @@ module OpenAI
         include Enumerable
 
         # @api private
-        def initialize(sessions:, session_id:, input:, tool_handlers: {}, idempotency_key: nil, request_options: {})
+        def initialize(
+          sessions:,
+          session_id:,
+          input:,
+          tool_handlers: {},
+          idempotency_key: nil,
+          output_type: nil,
+          request_options: {}
+        )
           messages = input.is_a?(String) ? [{role: :user, content: [{type: :input_text, text: input}]}] : input.to_a
           raise ArgumentError, "input must not be empty" if input == "" || messages.empty?
 
+          @output_parser = OpenAI::Helpers::Beta::Agents::OutputParser.new(output_type) unless output_type.nil?
           @sessions = sessions
           @session_id = session_id
           @handlers = tool_handlers.to_h.dup
+          @collector = OpenAI::Helpers::Beta::Agents::ResultCollector.new(
+            session_id: session_id,
+            handler_names: @handlers.keys
+          )
           @options = request_options.to_h.dup
           headers = {"OpenAI-Beta" => "agents=v1"}.merge(@options[:extra_headers].to_h)
           options_key = @options.delete(:idempotency_key)
@@ -84,6 +98,36 @@ module OpenAI
           self
         end
 
+        # @beta
+        # Consume the remaining events and handlers, then return this turn's final
+        # answer. Failed, blocked, or incomplete observation raises ResultError.
+        # @return [OpenAI::Helpers::Beta::Agents::TurnResult]
+        def get_final_result
+          with_result_collection
+          raise @result_error if @result_error
+          begin
+            each { |_event| break if @collector.stopped? } unless @collector.stopped?
+          rescue StandardError => error
+            @collector.observe_error(error)
+          end
+
+          result = @collector.result
+          @output_parser ? @output_parser.parse(result) : result
+        rescue OpenAI::Helpers::Beta::Agents::ResultError => error
+          @result_error = error
+          raise
+        ensure
+          close
+        end
+
+        # @beta
+        # Enable result collection before iterating to display progress.
+        # @return [self]
+        def with_result_collection
+          @collector.enable
+          self
+        end
+
         # Close the event connection without cancelling the backend turn.
         # @return [void]
         def close
@@ -99,7 +143,14 @@ module OpenAI
           Enumerator.new do |yielder|
             begin
               @raw_stream.each do |event|
-                next unless accept?(event)
+                known = event.is_a?(OpenAI::Internal::Type::BaseModel)
+                next if known && !accept?(event)
+
+                @collector.observe(event)
+                unless known
+                  yielder << event
+                  next
+                end
 
                 terminal = event.type == :"agent.session.failed" ||
                   (event.type == :"agent.session.idle" && @turn_ended)
@@ -112,6 +163,9 @@ module OpenAI
               end
 
               raise RuntimeError, "Session event stream ended before the turn reached idle or failed" unless @closed
+            rescue StandardError => error
+              @collector.observe_error(error)
+              raise
             ensure
               close
             end
@@ -134,7 +188,10 @@ module OpenAI
         end
 
         def prepare_call(event)
-          return unless event.type == :"agent.session.turn.item.added" && event.item.type == :function_call
+          unless event.type == :"agent.session.turn.item.added" &&
+              event.item.is_a?(OpenAI::Models::Beta::AgentFunctionCallItem)
+            return
+          end
 
           call = event.item
           key = [call.turn_id.dup, call.call_id.dup]

data/lib/openai/helpers/beta/agents/artifacts.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Beta
+      module Agents
+        # Artifact downloads scoped to one completed result (beta).
+        class ResultArtifacts
+          # @api private
+          def initialize(artifacts:, client:, result:)
+            @artifacts = artifacts
+            @client = client
+            @session_id = result.session_id.dup.freeze
+            @turn_id = result.turn_id.dup.freeze
+          end
+
+          # Download the exact turn/path to a caller-selected local path or writer.
+          # Returns the immutable artifact record that supplied the bytes.
+          def download(path:, to:, request_options: {})
+            request_options = request_options
+              .to_h
+              .merge(extra_headers: {"OpenAI-Beta" => "agents=v1"}.merge(request_options.to_h[:extra_headers].to_h))
+            match = nil
+            @artifacts
+              .list(@session_id, order: :asc, limit: 100, request_options: request_options)
+              .auto_paging_each do |artifact|
+                next unless artifact.turn_id == @turn_id && artifact.path == path
+                raise ArgumentError, "More than one artifact matches the result turn and path" if match
+                match = artifact
+              end
+
+            raise ArgumentError, "No artifact matches the result turn and path" unless match
+
+            transfer(match, to, request_options)
+
+            match
+          end
+
+          private
+
+          def transfer(artifact, destination, options)
+            writer = nil
+            opened = lambda do
+              writer = if destination.is_a?(String) || destination.is_a?(Pathname)
+                File.open(destination, "wb")
+              else
+                destination
+              end
+            end
+
+            request = {
+              method: :get,
+              path: ["agents/sessions/%1$s/artifacts/%2$s/content", @session_id, artifact.id],
+              headers: {"accept" => "application/octet-stream"},
+              security: {bearer_auth: true},
+              options: options
+            }
+            received = 0
+            @client.request_streaming_body(request, opened) do |chunk|
+              writer.write(chunk)
+              received += chunk.bytesize
+            end
+
+            raise IOError, "Artifact content size does not match its metadata" unless received == artifact.size_bytes
+          ensure
+            writer.close if writer && !writer.equal?(destination)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/beta/agents/creation_stream.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+module OpenAI
+  module Helpers
+    module Beta
+      module Agents
+        # A typed creation event stream with beta turn-result collection.
+        # Existing event iteration and HTTP metadata access remain available.
+        class CreationStream < OpenAI::Internal::Stream
+          # Requires initial input in create_streaming.
+          # Consume events through the initial root turn's terminal/idle boundary.
+          # Calling this again returns the same result without making requests.
+          # @return [OpenAI::Helpers::Beta::Agents::TurnResult]
+          def get_final_result
+            with_result_collection
+            raise @result_error if @result_error
+            begin
+              @iterator.next until @collector.stopped?
+            rescue StopIteration
+              # EOF alone does not establish a completed turn.
+            rescue StandardError => error
+              @collector.observe_error(error)
+            end
+
+            result = @collector.result
+            @output_parser ? @output_parser.parse(result) : result
+          rescue ResultError => error
+            @result_error = error
+            raise
+          ensure
+            close
+          end
+
+          # Enable result collection before iterating to display progress.
+          # @return [self]
+          def with_result_collection
+            @collector.enable
+            self
+          end
+
+          # @api private
+          def configure_output_parser(parser)
+            @output_parser = parser
+            self
+          end
+
+          private
+
+          def iterator
+            @collector = ResultCollector.new
+            source = super
+            @iterator = OpenAI::Internal::Util.chain_fused(source) do |yielder|
+              source.each do |event|
+                @collector.observe(event)
+                yielder << event
+              end
+
+            rescue StandardError => error
+              @collector.observe_error(error)
+              raise
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/beta/agents/files.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module OpenAI
+  module Helpers
+    module Beta
+      module Agents
+        # Uploaded file references ready for a hosted environment (beta).
+        # Delete upload_ids explicitly through the Files API when no longer needed.
+        class PreparedFiles
+          attr_reader :files, :upload_ids
+
+          # @api private
+          def initialize(files)
+            @files = files
+              .map do |file|
+                OpenAI::Models::Beta::HostedEnvironmentFileParam::FileID
+                  .new(
+                    file_id: file.fetch(:file_id).dup.freeze,
+                    path: file.fetch(:path).dup.freeze
+                  )
+                  .freeze
+              end
+              .freeze
+            @upload_ids = @files.map(&:file_id).freeze
+          end
+        end
+
+        # A preparation failed after uploads may have been created (beta).
+        class FilePreparationError < OpenAI::Errors::Error
+          attr_reader :prepared
+
+          # @api private
+          def initialize(prepared:)
+            @prepared = prepared
+            super("Agent file preparation failed; prepared contains the uploaded file references")
+          end
+        end
+
+        # @api private
+        class FilePreparation
+          def initialize(client:, environment_files:)
+            @client = client
+            @environment_files = environment_files
+          end
+
+          def prepare(files, request_options: {})
+            prepare_sources(files, request_options: request_options)
+          end
+
+          private def prepare_sources(files, request_options:, directory_root: nil)
+            entries = files.map do |destination, source|
+              path = local_file(source)
+              stat = path.lstat
+              check_directory_source(path, directory_root) if directory_root
+              [destination_path(destination), path, stat]
+            end
+
+            if entries.length > 1 && explicit_idempotency_key?(request_options)
+              raise ArgumentError, "Use separate uploads when supplying an Idempotency-Key for multiple files"
+            end
+
+            paths = entries.map(&:first).sort_by { _1.split("/") }
+            if paths.each_cons(2).any? { |a, b| a == b || b.start_with?("#{a}/") }
+              raise ArgumentError, "Destination file paths must not collide"
+            end
+
+            upload_options = entries.one? ? request_options_scope(request_options).child("file-upload") : request_options
+            uploaded = []
+            begin
+              Dir.mktmpdir("openai-agent-files") do |directory|
+                snapshots = entries.each_with_index.map do |(destination, source, stat), index|
+                  target = Pathname(directory).join(index.to_s)
+                  snapshot(source, target, stat, directory_root)
+                  [destination, OpenAI::FilePart.new(target, filename: source.basename.to_s)]
+                end
+
+                snapshots.each do |destination, source|
+                  file = @client.files.create(file: source, purpose: :user_data, request_options: upload_options)
+                  uploaded << {type: :file_id, file_id: file.id, path: destination}
+                end
+              end
+
+              PreparedFiles.new(uploaded)
+            rescue StandardError
+              raise FilePreparationError.new(prepared: PreparedFiles.new(uploaded))
+            end
+          end
+
+          def prepare_directory(directory, destination:, include:, request_options: {})
+            root = Pathname(directory).expand_path
+            identity = root.lstat
+            unless identity.directory?
+              raise ArgumentError, "directory must be an existing directory, not a symlink"
+            end
+
+            canonical = root.realpath
+            unless [root.lstat, canonical.lstat].all? {
+                _1.directory? && _1.dev == identity.dev && _1.ino == identity.ino
+              }
+              raise ArgumentError, "Selected directory changed while preparing files"
+            end
+
+            root = canonical
+            directory_root = [root, identity.dev, identity.ino]
+            patterns = Array(include)
+            if patterns.empty? ||
+                patterns.any? { !_1.is_a?(String) || _1.start_with?("/") || _1.split("/").include?("..") }
+              raise ArgumentError, "include must contain relative selection patterns"
+            end
+
+            base = destination_path(destination, directory: true)
+            selected = Dir
+              .glob(patterns, base: root)
+              .map { Pathname(_1).cleanpath.to_s }
+              .uniq
+              .reject { root.join(_1).directory? && !root.join(_1).symlink? }
+
+            prepare_sources(
+              selected.to_h { |relative| ["#{base}/#{relative}", root.join(relative)] },
+              request_options: request_options,
+              directory_root: directory_root
+            )
+          end
+
+          def upload(environment_id, file:, path:, request_options: {})
+            scope = request_options_scope(request_options)
+            prepared = prepare({path => file}, request_options: request_options)
+            stage_options = scope.child("environment-file")
+            begin
+              @environment_files.create(
+                environment_id,
+                hosted_environment_file_param: prepared.files.first,
+                request_options: stage_options.merge(
+                  extra_headers: {"OpenAI-Beta" => "agents=v1"}.merge(stage_options[:extra_headers].to_h)
+                )
+              )
+              prepared
+            rescue StandardError
+              raise FilePreparationError.new(prepared: prepared)
+            end
+          end
+
+          private
+
+          def request_options_scope(request_options)
+            options = request_options.to_h
+            headers = OpenAI::Internal::Util.normalized_headers(@client.headers, options[:extra_headers].to_h)
+            if headers.key?("idempotency-key")
+              options = options.merge(
+                extra_headers: options[:extra_headers].to_h.merge("idempotency-key" => headers["idempotency-key"])
+              )
+            end
+
+            OpenAI::Internal::RequestOptionsScope.new(options)
+          end
+
+          def snapshot(source, target, expected, directory_root)
+            flags = File::RDONLY | File::NONBLOCK | File::BINARY
+            flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+            File.open(source, flags) do |input|
+              unless input.stat.file? && file_identity(input.stat) == file_identity(expected)
+                raise ArgumentError, "Source changed after file preflight"
+              end
+
+              check_directory_source(source, directory_root) if directory_root
+              copied = File.open(target, "wb") { |output| IO.copy_stream(input, output, expected.size + 1) }
+              unless copied == expected.size && file_identity(input.stat) == file_identity(expected)
+                raise ArgumentError, "Source changed while preparing files"
+              end
+            end
+          end
+
+          def check_directory_source(source, boundary)
+            root, device, inode = boundary
+            current = root.lstat
+            unless current.directory? &&
+                current.dev == device &&
+                current.ino == inode &&
+                source.to_s.start_with?(File.join(root, "")) &&
+                source.realpath == source
+              raise ArgumentError, "Selected directory changed or contains a symlink"
+            end
+          end
+
+          def file_identity(stat) = [stat.dev, stat.ino, stat.size, stat.mtime, stat.ctime]
+
+          def destination_path(path, directory: false)
+            if path.is_a?(String)
+              path = path.encoding == Encoding::BINARY ? path.dup.force_encoding(Encoding::UTF_8) : path.encode(
+                Encoding::UTF_8
+              )
+              raise ArgumentError, "Destination must be valid UTF-8 text" unless path.valid_encoding?
+            end
+
+            parts = path.is_a?(String) ? path.split("/", -1) : []
+            relative = parts.drop(2)
+            root = relative.first
+            unless path.is_a?(String) &&
+                !path.include?("\0") &&
+                !path.include?("\\") &&
+                parts.first == "" &&
+                parts[1] == "workspace" &&
+                relative.none? { ["", ".", ".."].include?(_1) } &&
+                (directory || !relative.empty?) &&
+                ![".codex", ".managed-agents"].include?(root) &&
+                !root.to_s.start_with?(".managed-agents-") &&
+                (directory || relative != ["outputs"])
+              raise ArgumentError, "Destination must be a normalized file path under /workspace"
+            end
+
+            path
+          rescue EncodingError
+            raise ArgumentError, "Destination must be valid UTF-8 text"
+          end
+
+          def local_file(source)
+            path = Pathname(source).expand_path
+            unless path.file? && !path.symlink?
+              raise ArgumentError, "Sources must be regular files, not symlinks"
+            end
+
+            path
+          end
+
+          def explicit_idempotency_key?(options)
+            opts = options.to_h
+            headers = OpenAI::Internal::Util.normalized_headers(@client.headers, opts[:extra_headers].to_h)
+            headers.key?("idempotency-key") ? headers["idempotency-key"] : opts[:idempotency_key]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/beta/agents/function_tool.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "model_adapter"
+
+module OpenAI
+  module Helpers
+    module Beta
+      module Agents
+        # Beta binding between an application's argument model and local callback.
+        class FunctionTool
+          # @return [String]
+          attr_reader :name
+
+          # @param name [String]
+          # @param arguments [Class<OpenAI::BaseModel>]
+          # @param description [String]
+          # @yieldparam arguments [OpenAI::BaseModel]
+          def initialize(name:, arguments:, description: "", &handler)
+            ModelAdapter.validate!(arguments, parameter: "arguments")
+
+            raise ArgumentError, "a callback is required" unless handler
+            raise ArgumentError, "name must be a nonempty string" unless name.is_a?(String) && !name.empty?
+
+            @name = name.dup.freeze
+            @arguments = arguments
+            @handler = handler
+            @definition = JSON
+              .generate(
+                type: :function,
+                name: @name,
+                parameters: arguments.to_json_schema,
+                description: description
+              )
+              .freeze
+          end
+
+          # Supply this definition in the agent's tools at creation.
+          # @return [Hash{Symbol=>Object}]
+          def definition = JSON.parse(@definition, symbolize_names: true)
+
+          # Pass these local bindings to sessions.stream(tool_handlers: ...).
+          # @return [Hash{String=>Proc}]
+          def handlers = {name => method(:call).to_proc}
+
+          # Parse using the SDK's BaseModel conventions, then invoke the callback.
+          # This is not JSON Schema validation; validate application constraints
+          # and authorization in the callback before performing side effects.
+          # @param arguments [Hash{String=>Object}, String]
+          # @return [Object]
+          def call(arguments)
+            values = JSON.parse(arguments.is_a?(String) ? arguments : JSON.generate(arguments), symbolize_names: true)
+            raise ArgumentError, "Tool arguments must be a JSON object" unless values.is_a?(Hash)
+            parsed = ModelAdapter.coerce(@arguments, values)
+            unless parsed
+              raise ArgumentError, "Tool arguments cannot be parsed into the argument model"
+            end
+
+            @handler.call(parsed)
+          end
+
+        end
+      end
+    end
+  end
+end