Class: Antigravity::Agent

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

inherited

Methods included from Emojifiable

#emoji, included

Constructor Details

#initialize(model: nil, system_instruction: nil, tools: [], skills: [], workspace: nil, auto_logger: true, log_file: nil) {|_self| ... } ⇒ Agent

Returns a new instance of Agent.

Yields:

  • (_self)

Yield Parameters:



10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/antigravity/agent.rb', line 10

def initialize(model: nil, system_instruction: nil, tools: [],
               skills: [], workspace: nil, auto_logger: true, log_file: nil, &block)
  @model = model || Antigravity.config.default_model
  @api_key = Antigravity.config.api_key
  @system_instruction = system_instruction
  @workspace = workspace ? File.expand_path(workspace) : nil
  @tools = tools.dup
  @skills = []
  @sidecars = []
  @hooks = Hooks.new
  @client = Client.new
  @logger_guard = nil
  @connection = nil
  @conversation = nil
  @connected = false

  # Register pre-provided tools into the tool runner
  @tool_runner = ToolRunner.new
  @tools.each { |t| @tool_runner.register(t) }

  # Load skills provided at construction (local paths or GitHub URLs)
  add_skills(skills) unless Array(skills).empty?

  # Automagic Logger attachment unless disabled via ENV["ANTIGRAVITY_LOGGER"]=false or auto_logger: false
  if auto_logger && logger_enabled?
    attach_logger(log_file)
  end

  yield(self) if block_given?
end

Instance Attribute Details

#api_key ⇒ Object

Returns the value of attribute api_key.



6
7
8
 
# File 'lib/antigravity/agent.rb', line 6

def api_key
  @api_key
end

#client ⇒ Object (readonly)

Returns the value of attribute client.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def client
  @client
end

#connection ⇒ Object (readonly)

Returns the value of attribute connection.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def connection
  @connection
end

#conversation ⇒ Object (readonly)

Returns the value of attribute conversation.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def conversation
  @conversation
end

#hooks ⇒ Object (readonly)

Returns the value of attribute hooks.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def hooks
  @hooks
end

#logger_guard ⇒ Object (readonly)

Returns the value of attribute logger_guard.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def logger_guard
  @logger_guard
end

#model ⇒ Object

Returns the value of attribute model.



6
7
8
 
# File 'lib/antigravity/agent.rb', line 6

def model
  @model
end

#sidecars ⇒ Object (readonly)

Returns the value of attribute sidecars.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def sidecars
  @sidecars
end

#skills ⇒ Object (readonly)

Returns the value of attribute skills.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def skills
  @skills
end

#system_instruction ⇒ Object

Returns the value of attribute system_instruction.



6
7
8
 
# File 'lib/antigravity/agent.rb', line 6

def system_instruction
  @system_instruction
end

#tools ⇒ Object (readonly)

Returns the value of attribute tools.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def tools
  @tools
end

#workspace ⇒ Object (readonly)

Returns the value of attribute workspace.



7
8
9
 
# File 'lib/antigravity/agent.rb', line 7

def workspace
  @workspace
end

Class Method Details

.list_skills(path_or_url) ⇒ Array<String>

List discovered skills in a container path (without loading them).

Parameters:

  • path_or_url (String) —

    local path or GitHub URL

Returns:

  • (Array<String>) —

    skill directory paths



189
190
191
 
# File 'lib/antigravity/agent.rb', line 189

def self.list_skills(path_or_url)
  SkillResolver.resolve(path_or_url)
end

.open(**kwargs, &block) ⇒ Object

Block form: opens connection, yields agent, auto-closes.



44
45
46
47
48
49
50
51
52
 
# File 'lib/antigravity/agent.rb', line 44

def self.open(**kwargs, &block)
  agent = new(**kwargs)
  agent.connect!
  begin
    block.call(agent)
  ensure
    agent.close!
  end
end

Instance Method Details

#add_inline_skill(name:, description:, instructions:) ⇒ Skill

Create and add an inline skill (no file needed).

Parameters:

  • name (String) —

    skill name

  • description (String) —

    what the skill does

  • instructions (String) —

    the skill body (markdown)

Returns:

  • (Skill) —

    the inline skill



180
181
182
183
184
 
# File 'lib/antigravity/agent.rb', line 180

def add_inline_skill(name:, description:, instructions:)
  skill = Skill.inline(name: name, description: description, instructions: instructions)
  @skills << skill unless @skills.any? { |s| s.name == skill.name }
  skill
end

#add_skill(path_or_url, skill_name: nil) ⇒ Skill Also known as: load_skill

Add a single skill by path or GitHub URL. Raises if the path resolves to multiple skills (use add_skills instead).

Parameters:

  • path_or_url (String) —

    local path or GitHub URL

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

    optional specific skill name within a repo

Returns:

  • (Skill) —

    the loaded skill

Raises:

  • (ArgumentError) 


152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/antigravity/agent.rb', line 152

def add_skill(path_or_url, skill_name: nil)
  target = skill_name ? "#{path_or_url.to_s.chomp('/')}/#{skill_name}" : path_or_url.to_s
  paths = SkillResolver.resolve(target)
  if paths.size > 1
    raise ArgumentError,
          "add_skill resolved to #{paths.size} skills. Use add_skills instead, " \
          "or specify skill_name: to pick one."
  end
  raise ArgumentError, "No skill found at #{target}" if paths.empty?

  load_single_skill(paths.first)
end

#add_skills(paths_or_urls) ⇒ Array<Skill>

Add one or more skills by path or GitHub URL. Accepts a single string or an array. Each entry is resolved (may expand to multiple).

Parameters:

  • paths_or_urls (String, Array<String>) —

    local paths or GitHub URLs

Returns:

  • (Array<Skill>) —

    all loaded skills



169
170
171
172
173
 
# File 'lib/antigravity/agent.rb', line 169

def add_skills(paths_or_urls)
  Array(paths_or_urls).flat_map do |p|
    SkillResolver.resolve(p).map { |skill_path| load_single_skill(skill_path) }
  end
end

#after_response(&block) ⇒ Object 



200
201
202
 
# File 'lib/antigravity/agent.rb', line 200

def after_response(&block)
  hooks.after_response(&block)
end

#after_tool_call(&block) ⇒ Object Also known as: on_tool_call 



208
209
210
 
# File 'lib/antigravity/agent.rb', line 208

def after_tool_call(&block)
  hooks.after_tool_call(&block)
end

#attach_logger(log_target = nil, level: :info, silent_notice: false) ⇒ Object 



141
142
143
144
145
 
# File 'lib/antigravity/agent.rb', line 141

def attach_logger(log_target = nil, level: :info, silent_notice: false)
  @logger_guard = Guards::AgentLogger.new(log_target, level: level, silent_notice: silent_notice)
  @logger_guard.attach_to(self)
  @logger_guard
end

#attach_sidecar(sidecar) ⇒ Object 



136
137
138
139
 
# File 'lib/antigravity/agent.rb', line 136

def attach_sidecar(sidecar)
  @sidecars << sidecar
  sidecar
end

#before_prompt(&block) ⇒ Object 



196
197
198
 
# File 'lib/antigravity/agent.rb', line 196

def before_prompt(&block)
  hooks.before_prompt(&block)
end

#before_tool_call(&block) ⇒ Object 



204
205
206
 
# File 'lib/antigravity/agent.rb', line 204

def before_tool_call(&block)
  hooks.before_tool_call(&block)
end

#close! ⇒ Object 



78
79
80
81
82
83
 
# File 'lib/antigravity/agent.rb', line 78

def close!
  @connected = false
  @connection&.disconnect!
  @connection = nil
  @conversation = nil
end

#connect! ⇒ Object

--- Connection Lifecycle ---



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/antigravity/agent.rb', line 56

def connect!
  return self if @connected

  @connection = Connection::LocalConnection.new
  @connection.connect!

  @conversation = Conversation.new(
    ws_client: @connection.ws_client,
    tool_runner: @tool_runner,
    hooks: @hooks
  )

  harness_config = build_harness_config
  @conversation.initialize_session!(harness_config: harness_config)
  @connected = true
  self
end

#connected? ⇒ Boolean

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/antigravity/agent.rb', line 74

def connected?
  @connected && @connection&.connected?
end

#conversation_id ⇒ Object

--- Metadata Accessors (mirrors Python SDK) ---



107
108
109
 
# File 'lib/antigravity/agent.rb', line 107

def conversation_id
  @conversation&.conversation_id
end

#emit_sidecar_event(event_type, payload = {}) ⇒ Object 



213
214
215
 
# File 'lib/antigravity/agent.rb', line 213

def emit_sidecar_event(event_type, payload = {})
  @sidecars.each { |sidecar| sidecar.emit(event_type, payload) }
end

#prompt(message, timeout: Antigravity.config.timeout_llm, &block) ⇒ Object Also known as: ask

--- Chat ---



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/antigravity/agent.rb', line 87

def prompt(message, timeout: Antigravity.config.timeout_llm, &block)
  emit_sidecar_event(:prompt_started, prompt: message)
  hooks.run_pre_prompt(message)

  if @connected && @conversation
    response = @conversation.chat(message, timeout: timeout, &block)
  else
    # Legacy mock-client path (unit tests, pre-connection)
    response = client.send_turn(self, message, &block)
  end

  hooks.run_post_response(response)
  emit_sidecar_event(:turn_completed, response: response.content, model: model)

  response
end

#register_tool(tool_or_name = nil, description: "", &block) ⇒ Object

--- Tool Registration ---



123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/antigravity/agent.rb', line 123

def register_tool(tool_or_name = nil, description: "", &block)
  if block_given? && tool_or_name
    tool = Tool::Dynamic.new(tool_or_name, description: description, &block)
  elsif tool_or_name.respond_to?(:to_json_schema)
    tool = tool_or_name
  else
    raise ArgumentError, "Invalid tool definition"
  end
  @tools << tool
  @tool_runner.register(tool) if @tool_runner
  tool
end

#session_summary ⇒ Object 



115
116
117
118
119
 
# File 'lib/antigravity/agent.rb', line 115

def session_summary
  return {} unless @conversation

  @conversation.session_summary(model: @model)
end

#turn_count ⇒ Object 



111
112
113
 
# File 'lib/antigravity/agent.rb', line 111

def turn_count
  @conversation&.turn_count || 0
end