Class: Oz::Resources::Agent

Inherits:
Base
  • Object
show all
Defined in:
lib/oz/resources/agent.rb

Overview

Entry point for running and managing cloud agents, reachable via client.agent. Sub-resources hang off it: #runs, #schedules, #identities, #sessions, and #conversations.

Instance Method Summary collapse

Methods inherited from Base

#initialize

Constructor Details

This class inherits a constructor from Oz::Resources::Base

Instance Method Details

#conversations ⇒ Oz::Resources::Conversations

Returns:



90
91
92
 
# File 'lib/oz/resources/agent.rb', line 90

def conversations
  @conversations ||= Conversations.new(@client)
end

#get_artifact(artifact_uid) ⇒ Oz::Model

Retrieve an artifact produced by a run (plan, screenshot, or file).

Parameters:

  • artifact_uid (String)

Returns:



57
58
59
 
# File 'lib/oz/resources/agent.rb', line 57

def get_artifact(artifact_uid)
  model(@client.get("/agent/artifacts/#{enc(artifact_uid)}"))
end

#identities ⇒ Oz::Resources::Identities

Returns:



80
81
82
 
# File 'lib/oz/resources/agent.rb', line 80

def identities
  @identities ||= Identities.new(@client)
end

#list(include_malformed_skills: nil, refresh: nil, repo: nil, sort_by: nil, **extra) ⇒ Oz::Model

List available agents (skills) across accessible environments.

Parameters:

  • include_malformed_skills (Boolean, nil) (defaults to: nil)
  • refresh (Boolean, nil) (defaults to: nil) —

    clear the agent-list cache first

  • repo (String, nil) (defaults to: nil) —

    restrict to a single “owner/repo”

  • sort_by (String, nil) (defaults to: nil) —

    “name” (default) or “last_run”

Returns:

  • (Oz::Model) —

    response with an agents array



46
47
48
49
50
51
52
 
# File 'lib/oz/resources/agent.rb', line 46

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

#list_environments(sort_by: nil, **extra) ⇒ Oz::Model

List cloud environments available to the caller.

Parameters:

  • sort_by (String, nil) (defaults to: nil) —

    “last_updated” (default) or “name”

Returns:

  • (Oz::Model) —

    response with an environments array



64
65
66
67
 
# File 'lib/oz/resources/agent.rb', line 64

def list_environments(sort_by: nil, **extra)
  query = compact(sort_by: sort_by).merge(extra)
  model(@client.get('/agent/environments', query: query))
end

#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) ⇒ Oz::Model

Start a new agent run.

Parameters:

  • prompt (String, nil) (defaults to: nil) —

    instruction for the agent. Required unless a skill is supplied via skill, config[:skill_spec], or config[:skills].

  • config (Hash, nil) (defaults to: nil) —

    cloud run configuration (AmbientAgentConfig): :environment_id, :model_id, :name, :base_prompt, :mcp_servers, :harness, :skills, :memory_stores, …

  • conversation_id (String, nil) (defaults to: nil) —

    continue an existing conversation

  • attachments (Array<Hash>, nil) (defaults to: nil) —

    file attachments (max 5), each { data:, file_name:, mime_type: } with base64-encoded data

  • interactive (Boolean, nil) (defaults to: nil) —

    whether the run is interactive

  • mode (String, nil) (defaults to: nil) —

    “normal”, “plan”, or “orchestrate”

  • parent_run_id (String, nil) (defaults to: nil) —

    parent run for orchestration trees

  • skill (String, nil) (defaults to: nil) —

    skill spec used as the base prompt

  • team (Boolean, nil) (defaults to: nil) —

    create a team-owned run

  • title (String, nil) (defaults to: nil) —

    custom run title

  • agent_identity_uid (String, nil) (defaults to: nil) —

    execution principal (team runs)

Returns:

  • (Oz::Model) —

    { run_id, state, task_id, at_capacity }



28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/oz/resources/agent.rb', line 28

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

#runs ⇒ Oz::Resources::Runs

Returns:



70
71
72
 
# File 'lib/oz/resources/agent.rb', line 70

def runs
  @runs ||= Runs.new(@client)
end

#schedules ⇒ Oz::Resources::Schedules

Returns:



75
76
77
 
# File 'lib/oz/resources/agent.rb', line 75

def schedules
  @schedules ||= Schedules.new(@client)
end

#sessions ⇒ Oz::Resources::Sessions

Returns:



85
86
87
 
# File 'lib/oz/resources/agent.rb', line 85

def sessions
  @sessions ||= Sessions.new(@client)
end