exa-ai 0.11.2 → 0.12.0

data/exe/exa-ai-agent-run-events

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse command-line arguments
+api_key = nil
+run_id = nil
+output_format = "json"
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--api-key"
+    api_key = args.shift
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai agent-run-events <run_id> [options]
+
+      Retrieve events for an agent run.
+
+      Arguments:
+        run_id                  ID of the agent run
+
+      Options:
+        --api-key KEY           Exa API key (or use EXA_API_KEY env var)
+        --output-format FORMAT  Output format: json, pretty, or text (default: json)
+        --help, -h              Show this help message
+
+      Examples:
+        exa-ai agent-run-events run_123
+        exa-ai agent-run-events run_123 --output-format pretty
+    HELP
+    exit 0
+  else
+    # First positional argument is the run_id
+    if run_id.nil?
+      run_id = arg
+    else
+      warn "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate required arguments
+if run_id.nil?
+  warn "Error: Run ID argument required"
+  warn "Usage: exa-ai agent-run-events <run_id> [options]"
+  warn "Try 'exa-ai agent-run-events --help' for more information"
+  exit 1
+end
+
+begin
+  # Resolve API key
+  api_key = Exa::CLI::Base.resolve_api_key(api_key)
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Call API
+  events = client.agent_run_events(run_id)
+
+  # Format output
+  items = events.respond_to?(:data) ? events.data : events
+  case output_format
+  when "json"
+    puts JSON.pretty_generate(events.respond_to?(:to_h) ? events.to_h : events)
+  when "pretty"
+    puts "Events for Agent Run: #{run_id}"
+    puts ""
+    items.each_with_index do |event, i|
+      puts "#{i + 1}. #{event.respond_to?(:to_h) ? event.to_h.inspect : event}"
+    end
+  when "text"
+    items.each do |event|
+      puts event.respond_to?(:to_h) ? event.to_h.inspect : event.to_s
+    end
+  else
+    puts JSON.pretty_generate(events.respond_to?(:to_h) ? events.to_h : events)
+  end
+
+rescue Exa::NotFound => e
+  warn "Agent run not found: #{e.message}"
+  exit 1
+rescue Exa::Unauthorized => e
+  warn "Authentication failed: #{e.message}"
+  warn "Please provide a valid API key via --api-key or EXA_API_KEY environment variable"
+  exit 1
+rescue Exa::ClientError => e
+  warn "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  warn "Server error: #{e.message}"
+  exit 1
+rescue Exa::Error => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  warn "Unexpected error: #{e.message}"
+  exit 1
+end

data/exe/exa-ai-agent-run-get

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse command-line arguments
+api_key = nil
+run_id = nil
+output_format = "json"
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--api-key"
+    api_key = args.shift
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai agent-run-get <run_id> [options]
+
+      Get the status and results of an agent run.
+
+      Arguments:
+        run_id                  ID of the agent run to retrieve
+
+      Options:
+        --api-key KEY           Exa API key (or use EXA_API_KEY env var)
+        --output-format FORMAT  Output format: json, pretty, or text (default: json)
+        --help, -h              Show this help message
+
+      Examples:
+        exa-ai agent-run-get run_123
+        exa-ai agent-run-get run_123 --output-format pretty
+    HELP
+    exit 0
+  else
+    # First positional argument is the run_id
+    if run_id.nil?
+      run_id = arg
+    else
+      warn "Unknown option: #{arg}"
+      exit 1
+    end
+  end
+end
+
+# Validate required arguments
+if run_id.nil?
+  warn "Error: Run ID argument required"
+  warn "Usage: exa-ai agent-run-get <run_id> [options]"
+  warn "Try 'exa-ai agent-run-get --help' for more information"
+  exit 1
+end
+
+begin
+  # Resolve API key
+  api_key = Exa::CLI::Base.resolve_api_key(api_key)
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Call API
+  result = client.agent_run_get(run_id)
+
+  # Format output
+  formatted = Exa::CLI::Formatters::AgentRunFormatter.format_run(result, output_format)
+  puts formatted
+
+rescue Exa::NotFound => e
+  warn "Agent run not found: #{e.message}"
+  exit 1
+rescue Exa::Unauthorized => e
+  warn "Authentication failed: #{e.message}"
+  warn "Please provide a valid API key via --api-key or EXA_API_KEY environment variable"
+  exit 1
+rescue Exa::ClientError => e
+  warn "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  warn "Server error: #{e.message}"
+  exit 1
+rescue Exa::Error => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  warn "Unexpected error: #{e.message}"
+  exit 1
+end

data/exe/exa-ai-agent-run-list

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exa-ai"
+
+# Parse command-line arguments
+api_key = nil
+cursor = nil
+limit = 10
+output_format = "json"
+
+args = ARGV.dup
+while args.any?
+  arg = args.shift
+  case arg
+  when "--api-key"
+    api_key = args.shift
+  when "--cursor"
+    cursor = args.shift
+  when "--limit"
+    limit = args.shift.to_i
+  when "--output-format"
+    output_format = args.shift
+  when "--help", "-h"
+    puts <<~HELP
+      Usage: exa-ai agent-run-list [options]
+
+      List agent runs with cursor-based pagination.
+
+      Options:
+        --api-key KEY           Exa API key (or use EXA_API_KEY env var)
+        --cursor CURSOR         Pagination cursor for next page
+        --limit LIMIT           Number of results per page (default: 10)
+        --output-format FORMAT  Output format: json, pretty, or text (default: json)
+        --help, -h              Show this help message
+
+      Examples:
+        exa-ai agent-run-list
+        exa-ai agent-run-list --limit 20
+        exa-ai agent-run-list --cursor next_page_cursor
+        exa-ai agent-run-list --output-format pretty
+    HELP
+    exit 0
+  else
+    warn "Unknown option: #{arg}"
+    exit 1
+  end
+end
+
+begin
+  # Resolve API key
+  api_key = Exa::CLI::Base.resolve_api_key(api_key)
+
+  # Build client
+  client = Exa::CLI::Base.build_client(api_key)
+
+  # Build parameters
+  params = { limit: limit }
+  params[:cursor] = cursor if cursor
+
+  # Call API
+  result = client.agent_run_list(**params)
+
+  # Format output
+  formatted = Exa::CLI::Formatters::AgentRunFormatter.format_list(result, output_format)
+  puts formatted
+
+  # Show pagination info if there are more results
+  if result.has_more && result.next_cursor
+    if output_format == "pretty"
+      puts "\n" + "=" * 80
+      puts "More results available. Use --cursor #{result.next_cursor} to get next page."
+    else
+      warn "More results available. Use --cursor #{result.next_cursor} to get next page."
+    end
+  end
+
+rescue Exa::Unauthorized => e
+  warn "Authentication failed: #{e.message}"
+  warn "Please provide a valid API key via --api-key or EXA_API_KEY environment variable"
+  exit 1
+rescue Exa::ClientError => e
+  warn "Client error: #{e.message}"
+  exit 1
+rescue Exa::ServerError => e
+  warn "Server error: #{e.message}"
+  exit 1
+rescue Exa::Error => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue StandardError => e
+  warn "Unexpected error: #{e.message}"
+  exit 1
+end

data/lib/exa/cli/formatters/agent_run_formatter.rb

@@ -0,0 +1,149 @@
+module Exa
+  module CLI
+    module Formatters
+      class AgentRunFormatter
+        def self.format_run(run, format)
+          case format
+          when "json"
+            JSON.pretty_generate(run.to_h)
+          when "pretty"
+            format_run_pretty(run)
+          when "text"
+            format_run_text(run)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(run.to_h)
+          else
+            JSON.pretty_generate(run.to_h)
+          end
+        end
+
+        def self.format_list(list, format)
+          case format
+          when "json"
+            JSON.pretty_generate(list.to_h)
+          when "pretty"
+            format_list_pretty(list)
+          when "text"
+            format_list_text(list)
+          when "toon"
+            Exa::CLI::Base.encode_as_toon(list.to_h)
+          else
+            JSON.pretty_generate(list.to_h)
+          end
+        end
+
+        private
+
+        def self.format_run_pretty(run)
+          output = []
+          output << "Agent Run: #{run.id}"
+          output << "Status: #{run.status.upcase}"
+          output << "Created: #{run.created_at}"
+          output << ""
+
+          case run.status
+          when "queued"
+            output << "Run is queued..."
+          when "running"
+            output << "Run is running... ⚙️"
+          when "completed"
+            output << "Output:"
+            output << "--------"
+            if run.output.is_a?(Hash)
+              output << (run.output[:text] || run.output["text"] || run.output.inspect)
+            else
+              output << run.output.to_s
+            end
+            if run.output.is_a?(Hash) && (structured = run.output["structured"] || run.output[:structured])
+              output << ""
+              output << "Structured:"
+              output << JSON.pretty_generate(structured)
+            end
+            sources = grounding_sources(run)
+            unless sources.empty?
+              output << ""
+              output << "Grounding:"
+              sources.each { |s| output << "  - #{s}" }
+            end
+            output << ""
+            if run.cost_dollars
+              total = run.cost_dollars.is_a?(Hash) ? (run.cost_dollars["total"] || run.cost_dollars[:total]) : run.cost_dollars
+              output << "Cost: $#{total}"
+            end
+            output << "Completed: #{run.completed_at}" if run.completed_at
+          when "failed"
+            output << "Run failed"
+            output << "Stop reason: #{run.stop_reason}" if run.stop_reason
+          when "cancelled"
+            output << "Run was cancelled"
+            output << "Completed: #{run.completed_at}" if run.completed_at
+          end
+
+          output.join("\n")
+        end
+
+        def self.format_list_pretty(list)
+          output = []
+          output << "Agent Runs (#{list.data.length}):"
+          output << ""
+
+          if list.data.empty?
+            output << "No runs found."
+          else
+            output << "%-40s %-15s %s" % ["Run ID", "Status", "Created"]
+            output << "-" * 70
+
+            list.data.each do |run|
+              run_id = run.id.to_s[0..38]
+              status = run.status.upcase[0..14]
+              created = run.created_at.to_s[0..19]
+              output << "%-40s %-15s %s" % [run_id, status, created]
+            end
+          end
+
+          output << ""
+          if list.has_more
+            output << "More results available. Use --cursor #{list.next_cursor} for next page."
+          else
+            output << "End of results."
+          end
+
+          output.join("\n")
+        end
+
+        def self.format_run_text(run)
+          output = []
+          output << "#{run.id} #{run.status.upcase} #{run.created_at}"
+          if run.status == "completed" && run.output
+            text = run.output.is_a?(Hash) ? (run.output[:text] || run.output["text"]) : run.output.to_s
+            output << text.to_s
+            if run.output.is_a?(Hash) && (structured = run.output["structured"] || run.output[:structured])
+              output << JSON.generate(structured)
+            end
+          elsif run.status == "failed"
+            output << "Stop reason: #{run.stop_reason}"
+          end
+          output.join("\n")
+        end
+
+        # Flattens an output.grounding array into displayable source strings,
+        # tolerating both shapes seen from the API: flat {url,title} items and
+        # nested {citations:[{url,title}]} items.
+        def self.grounding_sources(run)
+          grounding = run.output.is_a?(Hash) ? (run.output["grounding"] || run.output[:grounding]) : nil
+          Array(grounding).flat_map do |item|
+            citations = item.is_a?(Hash) && item["citations"] ? item["citations"] : [item]
+            citations.map { |c| c.is_a?(Hash) ? (c["title"] || c["url"]) : c }
+          end.compact
+        end
+
+        def self.format_list_text(list)
+          output = list.data.map do |run|
+            "#{run.id} #{run.status.upcase} #{run.created_at}"
+          end
+          output.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/exa/client.rb

@@ -112,6 +112,83 @@ module Exa
       Services::ResearchGet.new(connection, research_id: research_id, **params).call
     end
 
+    # Create a new agent run
+    #
+    # @param query [String] The query or task for the agent to execute (required)
+    # @param params [Hash] Additional run parameters
+    # @option params [Hash] :input Input data for the agent run. Multi-word keys inside
+    #   +input+, +data_sources+ items, and +metadata+ must be supplied in the exact shape
+    #   the API expects — the parameter converter does not recurse into nested values
+    #   (same contract as +output_schema+).
+    # @option params [Array<Hash>] :data_sources Data sources for the agent run
+    # @option params [Hash] :metadata Custom metadata
+    # @return [Resources::AgentRun] The newly created agent run
+    def agent_run_create(query:, **params)
+      Services::AgentRunCreate.new(connection, query: query, **params).call
+    end
+
+    # Stream an agent run, yielding chunks as they arrive
+    #
+    # @param query [String] The query or task for the agent to execute (required)
+    # @param params [Hash] Additional run parameters
+    # @option params [Hash] :input Input data for the agent run. Multi-word keys inside
+    #   +input+, +data_sources+ items, and +metadata+ must be supplied in the exact shape
+    #   the API expects — the parameter converter does not recurse into nested values
+    #   (same contract as +output_schema+).
+    # @option params [Array<Hash>] :data_sources Data sources for the agent run
+    # @option params [Hash] :metadata Custom metadata
+    # @yield [chunk] Yields each streamed event chunk as it arrives
+    # @yieldparam chunk [Hash] Partial agent run event data
+    # @return [void]
+    def agent_run_stream(query:, **params, &block)
+      Services::AgentRunStream.new(connection, query: query, **params).call(&block)
+    end
+
+    # Get the status and results of an agent run
+    #
+    # @param run_id [String] Agent run ID
+    # @return [Resources::AgentRun] Agent run with current status and results
+    def agent_run_get(run_id)
+      Services::AgentRunGet.new(connection, run_id: run_id).call
+    end
+
+    # List all agent runs
+    #
+    # @param params [Hash] Listing parameters
+    # @option params [Integer] :limit Maximum number of runs to return
+    # @option params [String] :cursor Cursor for pagination
+    # @return [Resources::AgentRunList] List of agent runs
+    def agent_run_list(**params)
+      Services::AgentRunList.new(connection, **params).call
+    end
+
+    # Cancel an in-progress agent run
+    #
+    # @param run_id [String] Agent run ID
+    # @return [Resources::AgentRun] The cancelled agent run
+    def agent_run_cancel(run_id)
+      Services::AgentRunCancel.new(connection, run_id: run_id).call
+    end
+
+    # Delete an agent run
+    #
+    # @param run_id [String] Agent run ID
+    # @return [Resources::AgentRun] The deleted agent run
+    def agent_run_delete(run_id)
+      Services::AgentRunDelete.new(connection, run_id: run_id).call
+    end
+
+    # List events for an agent run
+    #
+    # @param run_id [String] Agent run ID
+    # @param params [Hash] Listing parameters
+    # @option params [Integer] :limit Maximum number of events to return
+    # @option params [String] :cursor Cursor for pagination
+    # @return [Array<Hash>] List of agent run events
+    def agent_run_events(run_id, **params)
+      Services::AgentRunEvents.new(connection, run_id: run_id, **params).call
+    end
+
     # Search code repositories
     #
     # @param query [String] Code search query

data/lib/exa/resources/agent_run.rb

@@ -0,0 +1,54 @@
+module Exa
+  module Resources
+    class AgentRun < Struct.new(
+      :id, :object, :status, :stop_reason, :created_at, :completed_at,
+      :request, :output, :usage, :cost_dollars, keyword_init: true
+    )
+      def initialize(id:, object:, status:, stop_reason: nil, created_at: nil, completed_at: nil, request: nil, output: nil, usage: nil, cost_dollars: nil)
+        super
+        freeze
+      end
+
+      # Build from a raw API response body (camelCase keys), e.g. a GET payload
+      # or the data of a terminal agent_run.* stream event.
+      def self.from_response(body)
+        new(
+          id: body["id"],
+          object: body["object"] || "agent_run",
+          status: body["status"],
+          stop_reason: body["stopReason"],
+          created_at: body["createdAt"],
+          completed_at: body["completedAt"],
+          request: body["request"],
+          output: body["output"],
+          usage: body["usage"],
+          cost_dollars: body["costDollars"]
+        )
+      end
+
+      def queued?    = status == 'queued'
+      def running?   = status == 'running'
+      def completed? = status == 'completed'
+      def failed?    = status == 'failed'
+      def cancelled? = status == 'cancelled'
+
+      def finished? = completed? || failed? || cancelled?
+
+      def to_h
+        result = {
+          id: id,
+          object: object,
+          status: status
+        }
+        result[:stop_reason]  = stop_reason  if stop_reason
+        result[:created_at]   = created_at   if created_at
+        result[:completed_at] = completed_at if completed_at
+        result[:request]      = request      if request
+        result[:output]       = output       if output
+        result[:usage]        = usage        if usage
+        result[:cost_dollars] = cost_dollars if cost_dollars
+        result
+      end
+    end
+  end
+end

data/lib/exa/resources/agent_run_event_list.rb

@@ -0,0 +1,21 @@
+module Exa
+  module Resources
+    # Paginated collection of agent run events.
+    # Mirrors AgentRunList's data/has_more/next_cursor shape; event items are
+    # kept as plain hashes (the API returns {id, event, data, createdAt} per event).
+    class AgentRunEventList < Struct.new(:data, :has_more, :next_cursor, keyword_init: true)
+      def initialize(data:, has_more: false, next_cursor: nil)
+        super
+        freeze
+      end
+
+      def to_h
+        {
+          data: data.map { |item| item.respond_to?(:to_h) ? item.to_h : item },
+          has_more: has_more,
+          next_cursor: next_cursor
+        }
+      end
+    end
+  end
+end

data/lib/exa/resources/agent_run_list.rb

@@ -0,0 +1,18 @@
+module Exa
+  module Resources
+    class AgentRunList < Struct.new(:data, :has_more, :next_cursor, keyword_init: true)
+      def initialize(data:, has_more:, next_cursor: nil)
+        super
+        freeze
+      end
+
+      def to_h
+        {
+          data: data.map { |item| item.respond_to?(:to_h) ? item.to_h : item },
+          has_more: has_more,
+          next_cursor: next_cursor
+        }
+      end
+    end
+  end
+end

data/lib/exa/services/agent_run_cancel.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../resources/agent_run"
+
+module Exa
+  module Services
+    class AgentRunCancel
+      def initialize(connection, run_id:)
+        @connection = connection
+        @run_id = run_id
+      end
+
+      def call
+        response = @connection.post("/agent/runs/#{@run_id}/cancel", {})
+        body = response.body
+
+        Resources::AgentRun.new(
+          id: body["id"],
+          object: body["object"],
+          status: body["status"],
+          stop_reason: body["stopReason"],
+          created_at: body["createdAt"],
+          completed_at: body["completedAt"],
+          request: body["request"],
+          output: body["output"],
+          usage: body["usage"],
+          cost_dollars: body["costDollars"]
+        )
+      end
+    end
+  end
+end

data/lib/exa/services/agent_run_create.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "parameter_converter"
+require_relative "../resources/agent_run"
+
+module Exa
+  module Services
+    class AgentRunCreate
+      def initialize(connection, query:, **params)
+        @connection = connection
+        @params = params.merge(query: query)
+      end
+
+      def call
+        response = @connection.post("/agent/runs", ParameterConverter.convert(@params))
+        body = response.body
+
+        Resources::AgentRun.new(
+          id: body["id"],
+          object: body["object"],
+          status: body["status"],
+          stop_reason: body["stopReason"],
+          created_at: body["createdAt"],
+          completed_at: body["completedAt"],
+          request: body["request"],
+          output: body["output"],
+          usage: body["usage"],
+          cost_dollars: body["costDollars"]
+        )
+      end
+    end
+  end
+end