oz-agent-sdk 0.1.0

data/lib/oz/resources/agent.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Oz
+  module Resources
+    # Entry point for running and managing cloud agents, reachable via
+    # +client.agent+. Sub-resources hang off it: {#runs}, {#schedules},
+    # {#identities}, {#sessions}, and {#conversations}.
+    class Agent < Base
+      # Start a new agent run.
+      #
+      # @param prompt [String, nil] instruction for the agent. Required unless a
+      #   skill is supplied via +skill+, +config[:skill_spec]+, or
+      #   +config[:skills]+.
+      # @param config [Hash, nil] cloud run configuration (+AmbientAgentConfig+):
+      #   +:environment_id+, +:model_id+, +:name+, +:base_prompt+,
+      #   +:mcp_servers+, +:harness+, +:skills+, +:memory_stores+, ...
+      # @param conversation_id [String, nil] continue an existing conversation
+      # @param attachments [Array<Hash>, nil] file attachments (max 5), each
+      #   +{ data:, file_name:, mime_type: }+ with base64-encoded +data+
+      # @param interactive [Boolean, nil] whether the run is interactive
+      # @param mode [String, nil] "normal", "plan", or "orchestrate"
+      # @param parent_run_id [String, nil] parent run for orchestration trees
+      # @param skill [String, nil] skill spec used as the base prompt
+      # @param team [Boolean, nil] create a team-owned run
+      # @param title [String, nil] custom run title
+      # @param agent_identity_uid [String, nil] execution principal (team runs)
+      # @return [Oz::Model] +{ run_id, state, task_id, at_capacity }+
+      def run(prompt: nil, config: nil, conversation_id: nil, attachments: nil, interactive: nil,
+              mode: nil, parent_run_id: nil, skill: nil, team: nil, title: nil,
+              agent_identity_uid: nil, **extra)
+        body = compact(
+          prompt: prompt, config: config, conversation_id: conversation_id,
+          attachments: attachments, interactive: interactive, mode: mode,
+          parent_run_id: parent_run_id, skill: skill, team: team, title: title,
+          agent_identity_uid: agent_identity_uid
+        ).merge(extra)
+        model(@client.post('/agent/runs', body: body))
+      end
+
+      # List available agents (skills) across accessible environments.
+      # @param include_malformed_skills [Boolean, nil]
+      # @param refresh [Boolean, nil] clear the agent-list cache first
+      # @param repo [String, nil] restrict to a single "owner/repo"
+      # @param sort_by [String, nil] "name" (default) or "last_run"
+      # @return [Oz::Model] response with an +agents+ array
+      def list(include_malformed_skills: nil, refresh: nil, repo: nil, sort_by: nil, **extra)
+        query = compact(
+          include_malformed_skills: include_malformed_skills, refresh: refresh,
+          repo: repo, sort_by: sort_by
+        ).merge(extra)
+        model(@client.get('/agent', query: query))
+      end
+
+      # Retrieve an artifact produced by a run (plan, screenshot, or file).
+      # @param artifact_uid [String]
+      # @return [Oz::Model]
+      def get_artifact(artifact_uid)
+        model(@client.get("/agent/artifacts/#{enc(artifact_uid)}"))
+      end
+
+      # List cloud environments available to the caller.
+      # @param sort_by [String, nil] "last_updated" (default) or "name"
+      # @return [Oz::Model] response with an +environments+ array
+      def list_environments(sort_by: nil, **extra)
+        query = compact(sort_by: sort_by).merge(extra)
+        model(@client.get('/agent/environments', query: query))
+      end
+
+      # @return [Oz::Resources::Runs]
+      def runs
+        @runs ||= Runs.new(@client)
+      end
+
+      # @return [Oz::Resources::Schedules]
+      def schedules
+        @schedules ||= Schedules.new(@client)
+      end
+
+      # @return [Oz::Resources::Identities]
+      def identities
+        @identities ||= Identities.new(@client)
+      end
+
+      # @return [Oz::Resources::Sessions]
+      def sessions
+        @sessions ||= Sessions.new(@client)
+      end
+
+      # @return [Oz::Resources::Conversations]
+      def conversations
+        @conversations ||= Conversations.new(@client)
+      end
+    end
+  end
+end

data/lib/oz/resources/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Oz
+  module Resources
+    # Shared behaviour for API resource wrappers. Holds the {Oz::Client} and
+    # provides small helpers for wrapping responses and encoding path segments.
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      # Wraps a decoded response body in {Oz::Model} (recursively).
+      def model(body)
+        Oz::Model.build(body)
+      end
+
+      # URL-encodes a single path segment (run ids, uids, ...).
+      def enc(segment)
+        CGI.escape(segment.to_s)
+      end
+
+      # Builds a params hash from keyword arguments, dropping +nil+ values so
+      # only explicitly provided options are sent.
+      def compact(hash)
+        hash.compact
+      end
+    end
+  end
+end

data/lib/oz/resources/conversations.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Oz
+  module Resources
+    # Look up redirects for agent conversations, reachable via
+    # +client.agent.conversations+.
+    class Conversations < Base
+      # Resolve where a conversation id should redirect to.
+      # @param conversation_id [String]
+      # @return [Oz::Model]
+      def check_redirect(conversation_id)
+        model(@client.get("/agent/conversations/#{enc(conversation_id)}/redirect"))
+      end
+    end
+  end
+end

data/lib/oz/resources/identities.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Oz
+  module Resources
+    # Manage agent identities (team-owned execution principals), reachable via
+    # +client.agent.identities+. These back the +/agent/identities+ endpoints.
+    class Identities < Base
+      # Create an agent identity.
+      # @param name [String] a name for the agent
+      # @param params [Hash] optional fields such as +description+, +prompt+,
+      #   +base_model+, +base_harness+, +environment_id+, +mcp_servers+,
+      #   +memory_stores+, +secrets+, +skills+, +inference_providers+,
+      #   +harness_auth_secrets+
+      # @return [Oz::Model] the created identity (+AgentResponse+)
+      def create(name:, **params)
+        model(@client.post('/agent/identities', body: { name: name }.merge(params)))
+      end
+
+      # Update an agent identity. Accepts the same fields as {#create}.
+      # @return [Oz::Model]
+      def update(uid, **params)
+        model(@client.put("/agent/identities/#{enc(uid)}", body: params))
+      end
+
+      # List all agent identities.
+      # @return [Oz::Model] response with an +agents+ array
+      def list
+        model(@client.get('/agent/identities'))
+      end
+
+      # Retrieve a single agent identity by uid.
+      # @return [Oz::Model]
+      def retrieve(uid)
+        model(@client.get("/agent/identities/#{enc(uid)}"))
+      end
+      alias get retrieve
+
+      # Delete an agent identity.
+      # @return [nil]
+      def delete(uid)
+        @client.delete("/agent/identities/#{enc(uid)}")
+        nil
+      end
+    end
+  end
+end

data/lib/oz/resources/runs.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Oz
+  module Resources
+    # Operations on individual agent runs, reachable via +client.agent.runs+.
+    class Runs < Base
+      # Retrieve a single run by id.
+      # @param run_id [String]
+      # @return [Oz::Model] the run (+RunItem+)
+      def retrieve(run_id)
+        model(@client.get("/agent/runs/#{enc(run_id)}"))
+      end
+
+      # List runs with optional filters. Returns a cursor-paginated page.
+      #
+      # Supported filters include: +ancestor_run_id+, +artifact_type+,
+      # +created_after+, +created_before+, +creator+, +cursor+, +environment_id+,
+      # +execution_location+, +executor+, +limit+, +model_id+, +name+, +q+,
+      # +schedule_id+, +skill+, +skill_spec+, +sort_by+, +sort_order+, +source+,
+      # +state+ (an Array of states), and +updated_after+.
+      #
+      # Time-like filters accept either an ISO-8601 String or a Time/Date.
+      # @return [Oz::CursorPage]
+      def list(**params)
+        body = @client.get('/agent/runs', query: params)
+        Oz::CursorPage.new(body, resource: self, params: params, items_key: 'runs')
+      end
+
+      # Cancel a run that is in progress.
+      # @param run_id [String]
+      # @return [String] confirmation message returned by the API
+      def cancel(run_id)
+        @client.post("/agent/runs/#{enc(run_id)}/cancel")
+      end
+
+      # List the attachments produced by a run's handoff.
+      # @param run_id [String]
+      # @return [Oz::Model]
+      def list_handoff_attachments(run_id)
+        model(@client.get("/agent/runs/#{enc(run_id)}/handoff/attachments"))
+      end
+
+      # Send a follow-up message to a run (e.g. to answer a blocking question or
+      # continue the conversation).
+      # @param run_id [String]
+      # @param message [String, nil] the follow-up message
+      # @param mode [String, nil] "normal", "plan", or "orchestrate"
+      # @return [Oz::Model]
+      def submit_followup(run_id, message: nil, mode: nil)
+        body = compact(message: message, mode: mode)
+        model(@client.post("/agent/runs/#{enc(run_id)}/followups", body: body))
+      end
+    end
+  end
+end

data/lib/oz/resources/schedules.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Oz
+  module Resources
+    # Manage scheduled agents (cron-triggered runs), reachable via
+    # +client.agent.schedules+.
+    class Schedules < Base
+      # Create a scheduled agent.
+      # @param cron_schedule [String] cron expression (e.g. "0 9 * * *")
+      # @param name [String] human-readable schedule name
+      # @param agent_config [Hash, nil] cloud agent run configuration
+      # @param agent_uid [String, nil] execution principal for team schedules
+      # @param enabled [Boolean, nil] whether the schedule is active immediately
+      # @param mode [String, nil] "normal", "plan", or "orchestrate"
+      # @param prompt [String, nil] instruction for the agent
+      # @param team [Boolean, nil] whether to create a team-owned schedule
+      # @return [Oz::Model] the created schedule (+ScheduledAgentItem+)
+      def create(cron_schedule:, name:, agent_config: nil, agent_uid: nil, enabled: nil,
+                 mode: nil, prompt: nil, team: nil, **extra)
+        body = compact(
+          cron_schedule: cron_schedule, name: name, agent_config: agent_config,
+          agent_uid: agent_uid, enabled: enabled, mode: mode, prompt: prompt, team: team
+        ).merge(extra)
+        model(@client.post('/agent/schedules', body: body))
+      end
+
+      # Retrieve a schedule by id.
+      # @return [Oz::Model]
+      def retrieve(schedule_id)
+        model(@client.get("/agent/schedules/#{enc(schedule_id)}"))
+      end
+
+      # Update a schedule. Accepts the same fields as {#create}.
+      # @return [Oz::Model]
+      def update(schedule_id, **params)
+        model(@client.put("/agent/schedules/#{enc(schedule_id)}", body: params))
+      end
+
+      # List all scheduled agents.
+      # @return [Oz::Model] response with a +schedules+ array
+      def list
+        model(@client.get('/agent/schedules'))
+      end
+
+      # Delete a schedule.
+      # @return [Oz::Model] response with a +success+ flag
+      def delete(schedule_id)
+        model(@client.delete("/agent/schedules/#{enc(schedule_id)}"))
+      end
+
+      # Pause a schedule (stops triggering new runs).
+      # @return [Oz::Model]
+      def pause(schedule_id)
+        model(@client.post("/agent/schedules/#{enc(schedule_id)}/pause"))
+      end
+
+      # Resume a paused schedule.
+      # @return [Oz::Model]
+      def resume(schedule_id)
+        model(@client.post("/agent/schedules/#{enc(schedule_id)}/resume"))
+      end
+    end
+  end
+end

data/lib/oz/resources/sessions.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Oz
+  module Resources
+    # Look up redirects for agent sessions, reachable via
+    # +client.agent.sessions+.
+    class Sessions < Base
+      # Resolve where a session UUID should redirect to.
+      # @param session_uuid [String]
+      # @return [Oz::Model]
+      def check_redirect(session_uuid)
+        model(@client.get("/agent/sessions/#{enc(session_uuid)}/redirect"))
+      end
+    end
+  end
+end

data/lib/oz/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Oz
+  VERSION = '0.1.0'
+end

data/lib/oz.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'oz/version'
+require_relative 'oz/errors'
+require_relative 'oz/configuration'
+require_relative 'oz/model'
+require_relative 'oz/cursor_page'
+require_relative 'oz/resources/base'
+require_relative 'oz/resources/runs'
+require_relative 'oz/resources/schedules'
+require_relative 'oz/resources/identities'
+require_relative 'oz/resources/sessions'
+require_relative 'oz/resources/conversations'
+require_relative 'oz/resources/agent'
+require_relative 'oz/client'
+
+# Ruby SDK for the Oz API — Warp's cloud agent platform.
+#
+#   require "oz"
+#
+#   client = Oz::Client.new(api_key: ENV["WARP_API_KEY"])
+#   run = client.agent.run(prompt: "Fix the bug in auth.rb")
+#   puts run.run_id
+#
+# Or configure once and use the shared client:
+#
+#   Oz.configure { |c| c.api_key = ENV["WARP_API_KEY"] }
+#   Oz.client.agent.runs.list(limit: 20).each { |r| puts r.title }
+module Oz
+  # Alias matching the Python/TypeScript SDKs' +OzAPI+ class name.
+  OzAPI = Client
+
+  class << self
+    # Yields the global {Configuration} for mutation.
+    # @yieldparam config [Oz::Configuration]
+    # @return [Oz::Configuration]
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # @return [Oz::Configuration] the global configuration singleton.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Resets global configuration (mainly for tests).
+    # @return [Oz::Configuration]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Builds a new {Client}. Accepts the same keyword arguments as
+    # {Oz::Client#initialize}.
+    # @return [Oz::Client]
+    def new(**kwargs)
+      Client.new(**kwargs)
+    end
+
+    # A lazily-built shared client using the global configuration / environment.
+    # @return [Oz::Client]
+    def client
+      @client ||= Client.new
+    end
+
+    # Replaces the shared client (mainly for tests).
+    # @return [nil]
+    def reset_client!
+      @client = nil
+    end
+  end
+end

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0.2"

data/oz-agent-sdk.gemspec

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'lib/oz/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'oz-agent-sdk'
+  spec.version       = Oz::VERSION
+  spec.authors       = ['lagents']
+  spec.email         = ['sunny@lagents.ai']
+  spec.summary       = 'Ruby SDK for the Oz API — Warp\'s cloud agent platform'
+  spec.description   = 'Ruby client library for the Oz API, providing convenient access to run and ' \
+                       'manage cloud agents: runs, schedules, agent identities, environments, and artifacts.'
+  spec.homepage      = 'https://github.com/warpdotdev/oz-sdk-ruby'
+  spec.license       = 'Apache-2.0'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['source_code_uri'] = 'https://github.com/warpdotdev/oz-sdk-ruby'
+  spec.metadata['changelog_uri'] = 'https://github.com/warpdotdev/oz-sdk-ruby/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://rubydoc.info/gems/oz-agent-sdk'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/warpdotdev/oz-sdk-ruby/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    if File.exist?('.git')
+      `git ls-files -z`.split("\x0").reject do |f|
+        f.match(%r{\A(?:test|spec|features)/}) || f.match(/\A\./)
+      end
+    else
+      Dir.glob('**/*').reject do |f|
+        File.directory?(f) ||
+          f.match(%r{\A(?:test|spec|features)/}) ||
+          f.match(/\A\./) ||
+          f.match(/\.gem$/)
+      end
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'faraday', '>= 2.0', '< 3.0'
+
+  # Development dependencies
+  # NB: bundler is intentionally not listed here — it is the build tool, not a
+  # library dependency, and pinning it breaks under Ruby 4 (bundler < 2.7 calls
+  # the removed CGI.parse). The environment / CI provides a compatible bundler.
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'webmock', '~> 3.0'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification
+name: oz-agent-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- lagents
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 'Ruby client library for the Oz API, providing convenient access to run
+  and manage cloud agents: runs, schedules, agent identities, environments, and artifacts.'
+email:
+- sunny@lagents.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CHANGELOG.md
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE
+- Makefile
+- README.md
+- Rakefile
+- docs/api_reference.md
+- docs/configuration.md
+- docs/error_handling.md
+- docs/getting_started.md
+- docs/index.md
+- examples/identities.rb
+- examples/list_runs.rb
+- examples/run_agent.rb
+- examples/schedules.rb
+- lib/oz.rb
+- lib/oz/client.rb
+- lib/oz/configuration.rb
+- lib/oz/cursor_page.rb
+- lib/oz/errors.rb
+- lib/oz/model.rb
+- lib/oz/resources/agent.rb
+- lib/oz/resources/base.rb
+- lib/oz/resources/conversations.rb
+- lib/oz/resources/identities.rb
+- lib/oz/resources/runs.rb
+- lib/oz/resources/schedules.rb
+- lib/oz/resources/sessions.rb
+- lib/oz/version.rb
+- mise.toml
+- oz-agent-sdk.gemspec
+homepage: https://github.com/warpdotdev/oz-sdk-ruby
+licenses:
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/warpdotdev/oz-sdk-ruby
+  changelog_uri: https://github.com/warpdotdev/oz-sdk-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/oz-agent-sdk
+  bug_tracker_uri: https://github.com/warpdotdev/oz-sdk-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby SDK for the Oz API — Warp's cloud agent platform
+test_files: []