openai 0.89.0 → 0.90.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22667eb3ef088a2e9b2e2f6c0e50c55e11f490e51be0ba1b2281259585eb6334
-  data.tar.gz: 01dad883b9f759c0bc04b6dea9cb842beb86d8d0f85a1d6761da19695288d5ad
+  metadata.gz: ed1195dfde86772df82a57968852233c3a37680a78766331eda4daca5961a74c
+  data.tar.gz: be58d94437e2b61b07576d3dac3769897ac72dffdfffbe6895e2fe0b13fcd345
 SHA512:
-  metadata.gz: 49fbf5ecac0836f16994255c07cefcb7c1f5380447a381f37af18e9434cd61780c4a688573f0ebd4c166d7a343dc08577dc7348a94efe6d57b082a453a2ca68c
-  data.tar.gz: 9822b12136cf3322ade3babbbec1b2556d9bc3fa884aaa65277533c46eab7cc6d8abcd9bc82ca9e7264238576ccd34181cf8b4b0f0aa143c7d959b7ca7b06675
+  metadata.gz: 3b363e344db928b8523e320c1f623a6d6f479c62806031eb362eff88ac3322760e794ad0993e19a5bc65fdc95d7f5bc97d9ff4592e8a8b1b19edac07f1a1e03f
+  data.tar.gz: 9544d48b551ba4e9928025e0bec07c57fa35b5ce3c8f2afb7f1fad7d1700cb40576ff896bc65c05b90cd55ac2fd2edb491cd42d24d119bf07326bb85d2913b1f

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.90.0](https://github.com/openai/openai-ruby/compare/v0.89.0...v0.90.0) (2026-09-10)
+
+
+### Features
+
+* **api:** add Agents API ([#695](https://github.com/openai/openai-ruby/issues/695)) ([24324ed](https://github.com/openai/openai-ruby/commit/24324ed510a198d2f955668a231a63c46cf491c1))
+
 ## [0.89.0](https://github.com/openai/openai-ruby/compare/v0.88.0...v0.89.0) (2026-09-10)
 
 

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.89.0"
+gem "openai", "~> 0.90.0"
 ```
 
 <!-- x-release-please-end -->

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Beta
+      class AgentSessionMessage
+        # Concatenate output-text blocks in message order, without fetching or
+        # filtering by phase. Reading this method does not change serialization.
+        # @return [String]
+        def output_text
+          content
+            .filter_map do |part|
+              (part[:text] || part["text"]) if (part[:type] || part["type"]).to_s == "output_text"
+            end
+            .join
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "tools"
+
+module OpenAI
+  module Helpers
+    module Agents
+      # Stream one turn on an idle session. The caller must be its only input writer
+      # until iteration ends, because input submission does not return a turn ID.
+      # Use a block or ensure #close when abandoning external iteration.
+      # Closing the connection does not cancel the backend turn.
+      class SessionStream
+        include Enumerable
+
+        # @api private
+        def initialize(sessions:, session_id:, input:, tool_handlers: {}, idempotency_key: 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?
+
+          @sessions = sessions
+          @session_id = session_id
+          @handlers = tool_handlers.to_h.dup
+          @options = request_options.to_h.dup
+          headers = {"OpenAI-Beta" => "agents=v1"}.merge(@options[:extra_headers].to_h)
+          options_key = @options.delete(:idempotency_key)
+          input_key = idempotency_key || options_key || SecureRandom.uuid
+          headers.delete_if do |key, value|
+            match = key.to_s.casecmp?("idempotency-key")
+            input_key = value if match
+            match
+          end
+
+          @options[:extra_headers] = headers
+          @recent_events = {}
+          @handled_calls = {}
+          @closed = false
+          session = @sessions.retrieve(@session_id, request_options: @options)
+          unless session.status == :idle
+            raise(
+              ArgumentError,
+              "sessions.stream requires an idle session; use sessions.events.stream_streaming to follow an active session"
+            )
+          end
+
+          @raw_stream = @sessions.events.stream_streaming(@session_id, request_options: @options)
+          begin
+            @sessions.events.create(
+              @session_id,
+              events: [{type: :"agent.session.input.message", input: messages}],
+              idempotency_key: input_key,
+              request_options: @options
+            )
+            @iterator = iterator
+            submitted = true
+          ensure
+            close unless submitted
+          end
+        end
+
+        # Yields the original typed events. Registered handlers run sequentially after
+        # their function-call event is yielded; unknown tools remain caller-managed.
+        # @yieldparam event [OpenAI::Models::Beta::AgentSessionEvent]
+        # @return [Enumerator, self]
+        def each
+          return enum_for(:each) unless block_given?
+          return self if @closed
+          begin
+            loop do
+              break if @closed
+              yield @iterator.next
+            end
+
+          ensure
+            close
+          end
+
+          self
+        end
+
+        # Consume remaining events and registered tool calls.
+        # @return [self]
+        def until_done
+          each { |_event| nil }
+          self
+        end
+
+        # Close the event connection without cancelling the backend turn.
+        # @return [void]
+        def close
+          return if @closed
+
+          @closed = true
+          @raw_stream&.close
+        end
+
+        private
+
+        def iterator
+          Enumerator.new do |yielder|
+            begin
+              @raw_stream.each do |event|
+                next unless accept?(event)
+
+                terminal = event.type == :"agent.session.failed" ||
+                  (event.type == :"agent.session.idle" && @turn_ended)
+                invocation = prepare_call(event) unless terminal
+                close if terminal
+                yielder << event
+                break if terminal || @closed
+
+                dispatch(invocation.call) if invocation
+              end
+
+              raise RuntimeError, "Session event stream ended before the turn reached idle or failed" unless @closed
+            ensure
+              close
+            end
+          end
+        end
+
+        def accept?(event)
+          return false if @recent_events.key?(event.event_id)
+
+          @recent_events.shift if @recent_events.size == 1024
+          @recent_events[event.event_id] = true
+          case event.type
+          when :"agent.session.turn.created"
+            @turn_id ||= event.turn_id.dup if event.turn.subagent_id.nil?
+          when :"agent.session.turn.completed", :"agent.session.turn.failed", :"agent.session.turn.cancelled"
+            @turn_ended = true if @turn_id && event.turn_id == @turn_id
+          end
+
+          true
+        end
+
+        def prepare_call(event)
+          return unless event.type == :"agent.session.turn.item.added" && event.item.type == :function_call
+
+          call = event.item
+          key = [call.turn_id.dup, call.call_id.dup]
+          return if @handled_calls.key?(key)
+
+          @handled_calls[key] = true
+          handler = @handlers[call.name]
+          return unless handler
+
+          Tools.prepare(call, handler)
+        end
+
+        def dispatch(result)
+          idempotency_key = SecureRandom.uuid
+          delays = [0.1, 0.3, 0.6]
+          begin
+            @sessions
+              .events
+              .create(@session_id, events: [result], idempotency_key: idempotency_key, request_options: @options)
+          rescue OpenAI::Errors::BadRequestError => error
+            delay = delays.shift
+            raise unless delay && Tools.pending_call_race?(error, result[:call_id])
+
+            sleep(delay)
+            retry
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Helpers
+    module Agents
+      # @api private
+      module Tools
+        # Capture routing and detached arguments before caller code sees the event,
+        # but defer the application callback until iteration resumes after yielding it.
+        def self.prepare(call, handler)
+          base = {type: :"agent.session.input.tool_result", turn_id: call.turn_id.dup, call_id: call.call_id.dup}
+          arguments = begin
+            JSON.parse(call.arguments.is_a?(String) ? call.arguments : JSON.generate(call.arguments))
+          rescue StandardError
+            nil
+          end
+
+          lambda do
+            begin
+              raise ArgumentError, "Function arguments must be a JSON object" unless arguments.is_a?(Hash)
+
+              output = handler.call(arguments)
+              output = JSON.generate(output) if output.is_a?(Hash)
+              unless output.nil? || output.is_a?(String) || output.is_a?(Array)
+                raise ArgumentError, "Tool output must be a string, object, content array, or nil"
+              end
+
+              serialized = JSON.generate(output)
+              if output.is_a?(Array) && !content_output?(JSON.parse(serialized))
+                raise ArgumentError, "Tool output array must contain input text or image content"
+              end
+
+              base.merge(success: true, output: output)
+            rescue StandardError
+              base.merge(success: false, error: "Tool handler failed.")
+            end
+          end
+        end
+
+        def self.content_output?(parts)
+          parts.all? do |part|
+            next false unless part.is_a?(Hash)
+
+            case part["type"]
+            when "input_text"
+              part["text"].is_a?(String)
+            when "input_image"
+              part["image_url"].is_a?(String)
+            else
+              false
+            end
+          end
+        end
+
+        def self.pending_call_race?(error, call_id)
+          body = error.body
+          body = body[:error] if body.is_a?(Hash) && body[:error].is_a?(Hash)
+          body.is_a?(Hash) &&
+            body[:code] == "invalid_request_error" &&
+            body[:message] == "Unknown pending tool call: #{call_id}"
+        end
+      end
+    end
+  end
+end

data/lib/openai/internal/token_page.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if token_page.next_page?
+    #     token_page = token_page.next_page
+    #   end
+    #
+    # @example
+    #   token_page.auto_paging_each do |role|
+    #     puts(role)
+    #   end
+    class TokenPage
+      include OpenAI::Internal::Type::BasePage
+
+      # @return [Array<generic<Elem>>, nil]
+      attr_accessor :data
+
+      # @return [Boolean]
+      attr_accessor :has_more
+
+      # @return [String, nil]
+      attr_accessor :next_
+
+      # @return [Boolean]
+      def next_page?
+        has_more
+      end
+
+      # @raise [OpenAI::HTTP::Error]
+      # @return [self]
+      def next_page
+        unless next_page?
+          message = "No more pages available. Please check #next_page? before calling ##{__method__}"
+          raise message
+        end
+
+        req = OpenAI::Internal::Util.deep_merge(@req, {query: {page: next_}})
+        @client.request(req)
+      end
+
+      # @param blk [Proc]
+      #
+      # @yieldparam [generic<Elem>]
+      def auto_paging_each(&blk)
+        unless block_given?
+          raise ArgumentError.new("A block must be given to ##{__method__}")
+        end
+
+        page = self
+        loop do
+          page.data&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [OpenAI::Internal::Transport::BaseClient]
+      # @param req [Hash{Symbol=>Object}]
+      # @param response_metadata [OpenAI::ResponseMetadata]
+      # @param page_data [Hash{Symbol=>Object}]
+      def initialize(client:, req:, response_metadata:, page_data:)
+        super
+
+        case page_data
+        in {data: Array => data}
+          @data = data.map { OpenAI::Internal::Type::Converter.coerce(@model, _1) }
+        else
+        end
+
+        @has_more = page_data[:has_more]
+        @next_ = page_data[:next]
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        model = OpenAI::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)} has_more=#{has_more.inspect} next_=#{next_.inspect}>"
+      end
+    end
+  end
+end

data/lib/openai/models/beta/agent.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Beta
+      # @see OpenAI::Resources::Beta::Agents#create
+      class Agent < OpenAI::Internal::Type::BaseModel
+        # @!attribute id
+        #   The ID of the reusable agent.
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute created_at
+        #   The Unix timestamp, in seconds, when the agent was created.
+        #
+        #   @return [Integer]
+        required :created_at, Integer
+
+        # @!attribute instructions
+        #   Custom instructions appended to the agent's default base instructions.
+        #
+        #   @return [String, nil]
+        required :instructions, String, nil?: true
+
+        # @!attribute metadata
+        #   Custom string key-value pairs attached to the agent.
+        #
+        #   @return [Hash{Symbol=>String}]
+        required :metadata, OpenAI::Internal::Type::HashOf[String]
+
+        # @!attribute model
+        #   The requested model name used for inference.
+        #
+        #   @return [String]
+        required :model, String
+
+        # @!attribute multi_agent
+        #   The resolved configuration for creating and coordinating subagents.
+        #
+        #   @return [OpenAI::Models::Beta::MultiAgentConfig]
+        required :multi_agent, -> { OpenAI::Beta::MultiAgentConfig }
+
+        # @!attribute name
+        #   A human-readable name for the agent, or null if it is unnamed.
+        #
+        #   @return [String, nil]
+        required :name, String, nil?: true
+
+        # @!attribute object
+        #   The object type. Always `agent`.
+        #
+        #   @return [Symbol, :agent]
+        required :object, const: :agent
+
+        # @!attribute reasoning
+        #   The resolved reasoning configuration, including the model default for an omitted
+        #   effort.
+        #
+        #   @return [OpenAI::Models::Beta::AgentReasoning]
+        required :reasoning, -> { OpenAI::Beta::AgentReasoning }
+
+        # @!attribute service_tier
+        #   The resolved service-tier policy used for model requests.
+        #
+        #   @return [Symbol, OpenAI::Models::Beta::Agent::ServiceTier]
+        required :service_tier, enum: -> { OpenAI::Beta::Agent::ServiceTier }
+
+        # @!attribute text
+        #   The resolved configuration for text generated by the agent.
+        #
+        #   @return [OpenAI::Models::Beta::AgentText]
+        required :text, -> { OpenAI::Beta::AgentText }
+
+        # @!attribute tools
+        #   Tools available to the agent.
+        #
+        #   @return [Array<OpenAI::Models::Beta::PersistedAgentTool::Function, OpenAI::Models::Beta::PersistedAgentTool::ToolSearch, OpenAI::Models::Beta::PersistedAgentTool::ProgrammaticToolCalling, OpenAI::Models::Beta::PersistedAgentTool::Mcp, OpenAI::Models::Beta::PersistedAgentTool::WebSearch>]
+        required :tools, -> { OpenAI::Internal::Type::ArrayOf[union: OpenAI::Beta::PersistedAgentTool] }
+
+        # @!attribute updated_at
+        #   The Unix timestamp, in seconds, when the agent was last updated.
+        #
+        #   @return [Integer]
+        required :updated_at, Integer
+
+        # @!method initialize(id:, created_at:, instructions:, metadata:, model:, multi_agent:, name:, reasoning:, service_tier:, text:, tools:, updated_at:, object: :agent)
+        #   A reusable agent scoped to the caller's project.
+        #
+        #   @param id [String]
+        #     The ID of the reusable agent.
+        #
+        #   @param created_at [Integer]
+        #     The Unix timestamp, in seconds, when the agent was created.
+        #
+        #   @param instructions [String, nil]
+        #     Custom instructions appended to the agent's default base instructions.
+        #
+        #   @param metadata [Hash{Symbol=>String}]
+        #     Custom string key-value pairs attached to the agent.
+        #
+        #   @param model [String]
+        #     The requested model name used for inference.
+        #
+        #   @param multi_agent [OpenAI::Models::Beta::MultiAgentConfig]
+        #     The resolved configuration for creating and coordinating subagents.
+        #
+        #   @param name [String, nil]
+        #     A human-readable name for the agent, or null if it is unnamed.
+        #
+        #   @param reasoning [OpenAI::Models::Beta::AgentReasoning]
+        #     The resolved reasoning configuration, including the model default for an omitted
+        #     effort.
+        #
+        #   @param service_tier [Symbol, OpenAI::Models::Beta::Agent::ServiceTier]
+        #     The resolved service-tier policy used for model requests.
+        #
+        #   @param text [OpenAI::Models::Beta::AgentText]
+        #     The resolved configuration for text generated by the agent.
+        #
+        #   @param tools [Array<OpenAI::Models::Beta::PersistedAgentTool::Function, OpenAI::Models::Beta::PersistedAgentTool::ToolSearch, OpenAI::Models::Beta::PersistedAgentTool::ProgrammaticToolCalling, OpenAI::Models::Beta::PersistedAgentTool::Mcp, OpenAI::Models::Beta::PersistedAgentTool::WebSearch>]
+        #     Tools available to the agent.
+        #
+        #   @param updated_at [Integer]
+        #     The Unix timestamp, in seconds, when the agent was last updated.
+        #
+        #   @param object [Symbol, :agent]
+        #     The object type. Always `agent`.
+
+        # The resolved service-tier policy used for model requests.
+        #
+        # @see OpenAI::Models::Beta::Agent#service_tier
+        module ServiceTier
+          extend OpenAI::Internal::Type::Enum
+
+          AUTO = :auto
+          DEFAULT = :default
+          FLEX = :flex
+          PRIORITY = :priority
+          FAST = :fast
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+    end
+  end
+end

data/lib/openai/models/beta/agent_close_subagent_call_item.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Beta
+      class AgentCloseSubagentCallItem < OpenAI::Internal::Type::BaseModel
+        # @!attribute id
+        #   The ID of the tool call item.
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute recipient_agent_id
+        #   The ID of the agent to close.
+        #
+        #   @return [String]
+        required :recipient_agent_id, String
+
+        # @!attribute sender_agent_id
+        #   The ID of the agent requesting the close.
+        #
+        #   @return [String]
+        required :sender_agent_id, String
+
+        # @!attribute status
+        #   The status of the tool call.
+        #
+        #   @return [Symbol, OpenAI::Models::Beta::AgentFunctionCallStatus]
+        required :status, enum: -> { OpenAI::Beta::AgentFunctionCallStatus }
+
+        # @!attribute turn_id
+        #   The ID of the turn that contains this item.
+        #
+        #   @return [String]
+        required :turn_id, String
+
+        # @!attribute type
+        #   The item type. Always `close_subagent_call`.
+        #
+        #   @return [Symbol, :close_subagent_call]
+        required :type, const: :close_subagent_call
+
+        # @!method initialize(id:, recipient_agent_id:, sender_agent_id:, status:, turn_id:, type: :close_subagent_call)
+        #   A request to close a subagent.
+        #
+        #   @param id [String]
+        #     The ID of the tool call item.
+        #
+        #   @param recipient_agent_id [String]
+        #     The ID of the agent to close.
+        #
+        #   @param sender_agent_id [String]
+        #     The ID of the agent requesting the close.
+        #
+        #   @param status [Symbol, OpenAI::Models::Beta::AgentFunctionCallStatus]
+        #     The status of the tool call.
+        #
+        #   @param turn_id [String]
+        #     The ID of the turn that contains this item.
+        #
+        #   @param type [Symbol, :close_subagent_call]
+        #     The item type. Always `close_subagent_call`.
+      end
+    end
+  end
+end

data/lib/openai/models/beta/agent_command_execution_item.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Beta
+      class AgentCommandExecutionItem < OpenAI::Internal::Type::BaseModel
+        # @!attribute id
+        #   The ID of the command execution item.
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute command
+        #   The command that was executed.
+        #
+        #   @return [String]
+        required :command, String
+
+        # @!attribute cwd
+        #   The working directory used to execute the command.
+        #
+        #   @return [String, nil]
+        required :cwd, String, nil?: true
+
+        # @!attribute duration_ms
+        #   The command duration in milliseconds.
+        #
+        #   @return [Integer, nil]
+        required :duration_ms, Integer, nil?: true
+
+        # @!attribute exit_code
+        #   The process exit code, if the command completed.
+        #
+        #   @return [Integer, nil]
+        required :exit_code, Integer, nil?: true
+
+        # @!attribute output
+        #   The command output, if available.
+        #
+        #   @return [String, nil]
+        required :output, String, nil?: true
+
+        # @!attribute status
+        #   The status of the command execution.
+        #
+        #   @return [Symbol, OpenAI::Models::Beta::AgentFunctionCallStatus]
+        required :status, enum: -> { OpenAI::Beta::AgentFunctionCallStatus }
+
+        # @!attribute turn_id
+        #   The ID of the turn that contains this item.
+        #
+        #   @return [String]
+        required :turn_id, String
+
+        # @!attribute type
+        #   The item type. Always `command_execution`.
+        #
+        #   @return [Symbol, :command_execution]
+        required :type, const: :command_execution
+
+        # @!method initialize(id:, command:, cwd:, duration_ms:, exit_code:, output:, status:, turn_id:, type: :command_execution)
+        #   A command execution produced by the agent.
+        #
+        #   @param id [String]
+        #     The ID of the command execution item.
+        #
+        #   @param command [String]
+        #     The command that was executed.
+        #
+        #   @param cwd [String, nil]
+        #     The working directory used to execute the command.
+        #
+        #   @param duration_ms [Integer, nil]
+        #     The command duration in milliseconds.
+        #
+        #   @param exit_code [Integer, nil]
+        #     The process exit code, if the command completed.
+        #
+        #   @param output [String, nil]
+        #     The command output, if available.
+        #
+        #   @param status [Symbol, OpenAI::Models::Beta::AgentFunctionCallStatus]
+        #     The status of the command execution.
+        #
+        #   @param turn_id [String]
+        #     The ID of the turn that contains this item.
+        #
+        #   @param type [Symbol, :command_execution]
+        #     The item type. Always `command_execution`.
+      end
+    end
+  end
+end