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: [], policies: [], policy: nil, 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
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/antigravity/agent.rb', line 10

def initialize(model: nil, system_instruction: nil, tools: [],
               skills: [], policies: [], policy: nil, 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 = []
  @policies = []
  @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?

  # Resolve policy: sugar (symbol → preset, Policy object → use directly)
  if policy
    resolved = policy.is_a?(Symbol) ? Policy.preset(policy) : policy
    enforce(resolved)
  end

  # Load policies
  policies.each { |p| enforce(p) }

  # 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



231
232
233
 
# File 'lib/antigravity/agent.rb', line 231

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.



61
62
63
64
65
66
67
68
69
 
# File 'lib/antigravity/agent.rb', line 61

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



222
223
224
225
226
 
# File 'lib/antigravity/agent.rb', line 222

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) 


194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/antigravity/agent.rb', line 194

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



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

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 



242
243
244
 
# File 'lib/antigravity/agent.rb', line 242

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

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



250
251
252
 
# File 'lib/antigravity/agent.rb', line 250

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

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



183
184
185
186
187
 
# File 'lib/antigravity/agent.rb', line 183

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 



178
179
180
181
 
# File 'lib/antigravity/agent.rb', line 178

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

#before_prompt(&block) ⇒ Object 



238
239
240
 
# File 'lib/antigravity/agent.rb', line 238

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

#before_tool_call(&block) ⇒ Object 



246
247
248
 
# File 'lib/antigravity/agent.rb', line 246

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

#close! ⇒ Object 



111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/antigravity/agent.rb', line 111

def close!
  # Emit session_end hook before teardown
  if @connected
    hooks.emit(:session_end, {
      turn_count: turn_count,
      conversation_id: conversation_id,
    })
  end

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

#connect! ⇒ Object

--- Connection Lifecycle ---



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/antigravity/agent.rb', line 73

def connect!
  return self if @connected

  # Auto-attach lifecycle logger if enabled via env
  if lifecycle_logger_enabled? && !@lifecycle_attached
    LifecycleLogger.attach!(self, verbose: ENV['ANTIGRAVITY_LIFECYCLE_VERBOSE'] == '1')
    @lifecycle_attached = true
  end

  @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

  # Emit session_start hook
  hooks.emit(:session_start, {
    model: @model,
    conversation_id: conversation_id,
    workspace: @workspace,
    skills_count: @skills.length,
    tools_count: @tools.length,
  })

  self
end

#connected? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

#conversation_id ⇒ Object

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



149
150
151
 
# File 'lib/antigravity/agent.rb', line 149

def conversation_id
  @conversation&.conversation_id
end

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



255
256
257
 
# File 'lib/antigravity/agent.rb', line 255

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

#enforce(policy) ⇒ Object 



51
52
53
54
55
56
 
# File 'lib/antigravity/agent.rb', line 51

def enforce(policy)
  @policies << policy
  before_tool_call do |tool_name, args|
    policy.evaluate(tool_name, args)
  end
end

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

--- Chat ---



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/antigravity/agent.rb', line 128

def prompt(message, timeout: Antigravity.config.timeout_llm, &block)
  connect! unless @connected
  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 ---



165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/antigravity/agent.rb', line 165

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 



157
158
159
160
161
 
# File 'lib/antigravity/agent.rb', line 157

def session_summary
  return {} unless @conversation

  @conversation.session_summary(model: @model)
end

#turn_count ⇒ Object 



153
154
155
 
# File 'lib/antigravity/agent.rb', line 153

def turn_count
  @conversation&.turn_count || 0
end