class LittleGhost::Agent

Define reusable agents that can answer, stream, call tools, and delegate work. Each subclass describes one application role with an inheritable Ruby DSL.

A customer support agent can look up an account itself and give longer investigations to a research specialist:

class ResearchAgent < LittleGhost::Agent
  description "Researches transfer failures"
  model "customer_support.research"
  tools LedgerSearchTool
end

class CustomerSupportAgent < LittleGhost::Agent
  description "Handles support requests"
  model :customer_support
  limits max_turns: 40
  tools AccountLookupTool
  subagent ResearchAgent, kind: "research"
end

run = CustomerSupportAgent.ask("Why is transfer 481 pending?")
run.completed? # => true
run.response   # => "Transfer 481 is waiting for the receiving bank."

Class declarations are inherited. Prompts resolve by the agent’s logical path unless system_prompt or system_template supplies one explicitly; tools and prompt locals may also be selected dynamically for each run. Capabilities such as skills, context management, loop detection, and delegation remain inactive until their DSL methods are called.

The class-level ask helper creates a standalone entrypoint and returns a completed Run. Create a standalone instance explicitly to reuse one Runtime or call stream_ask for StreamEvent objects. Runtimes build bound instances internally; their call method returns a RunResult and their stream method follows the owning run’s single-execution lifecycle. Closing an agent closes owned tools and any standalone workspace and sandbox. LittleGhost::Agent.ask uses You are a helpful agent. as its system prompt. Subclasses continue to use their inline or conventional prompts.

Models can return ordinary text or a locally validated structured result. Tool failures are sanitized before returning to the model, diagnostic capture can be disabled for sensitive agents, and cancellation, deadlines, and cleanup failures remain framework control flow.

Attributes

Run-scoped model, tools, lifecycle, delegation, and execution resources available to agent extensions.

delegation_activity [R]

Run-scoped model, tools, lifecycle, delegation, and execution resources available to agent extensions.

max_tool_calls [R]

Run-scoped model, tools, lifecycle, delegation, and execution resources available to agent extensions.

Run-scoped model, tools, lifecycle, delegation, and execution resources available to agent extensions.

Run-scoped model, tools, lifecycle, delegation, and execution resources available to agent extensions.

Runtime used to build this agent’s model, tools, workspace, and sandbox.

Run-scoped model, tools, lifecycle, delegation, and execution resources available to agent extensions.

tool_registry [R]

Run-scoped model, tools, lifecycle, delegation, and execution resources available to agent extensions.

Run-scoped model, tools, lifecycle, delegation, and execution resources available to agent extensions.

Public Class Methods

after_initialize(callable = nil, prepend: false) { |agent| ... } → self

Source

# File lib/little_ghost/agent.rb, line 295

Prepares per-agent state after a run-scoped instance is initialized.

after_invocation(callable = nil, prepend: false) { |payload| ... } → self

Source

# File lib/little_ghost/agent.rb, line 312

Observes or transforms the terminal invocation payload.

after_model(callable = nil, prepend: false) { |payload| ... } → self

Source

# File lib/little_ghost/agent.rb, line 326

Observes or transforms a successful model response.

after_model_error(callable = nil, prepend: false) { |payload| ... } → self

Source

# File lib/little_ghost/agent.rb, line 333

Handles a model error before it leaves the agent loop.

after_tool(callable = nil, prepend: false) { |payload| ... } → self

Source

# File lib/little_ghost/agent.rb, line 351
private

Observes or transforms a completed tool result.

agent_id() → String

agent_id(value) → String

Source

# File lib/little_ghost/agent.rb, line 99
def agent_id(*values)
  return agent_id_value || default_agent_id if values.empty?

  self.agent_id_value = values.fetch(0).to_s
end

The stable identifier used in telemetry, delegation, and default tool names. Named subclasses derive it from their underscored class name without an Agent suffix; passing value replaces that default.

ask (message, **options)

Source

# File lib/little_ghost/agent.rb, line 88
def ask(message, **options)
  new.ask(message, **options)
end

Executes message through a fresh standalone entrypoint and returns the completed LittleGhost::Run. Invocation options are forwarded to ask.

Create an instance explicitly when reusing a Runtime or streaming events.

before_invocation(callable = nil, prepend: false) { |payload| ... } → self

Source

# File lib/little_ghost/agent.rb, line 305

Runs before one invocation begins.

The payload may be continued, replaced, or cancelled with a decision from Support::Callbacks.

before_model(callable = nil, prepend: false) { |payload| ... } → self

Source

# File lib/little_ghost/agent.rb, line 319

Runs before a model request is sent.

before_tool(callable = nil, prepend: false) { |payload| ... } → self

Source

# File lib/little_ghost/agent.rb, line 340

Runs after validation but before a tool call starts.

capture_diagnostics() → true or false

capture_diagnostics(value) → true or false

Source

# File lib/little_ghost/agent.rb, line 215
def capture_diagnostics(*values)
  return capture_diagnostics_value if values.empty?

  self.capture_diagnostics_value = values.fetch(0) == true
end

Whether agent-layer diagnostics may include model and tool content.

Capture defaults to true, and only a literal true enables it. This setting does not disable run-level input and output capture from an enabled process-wide Support::ContentCapture policy. For sensitive work, also install Support::ContentCapture.disabled or an appropriate scrubber through Instrumentation.capture_content.

description() → String

description(value) → String

Source

# File lib/little_ghost/agent.rb, line 117
def description(*values)
  return description_value.to_s if values.empty?

  self.description_value = values.fetch(0).to_s
end

The human-readable description shown when this agent is delegated.

limits() → Hash

limits(**values) → Hash

Source

# File lib/little_ghost/agent.rb, line 151
def limits(**values)
  return limits_value if values.empty?

  self.limits_value = limits.merge(values.transform_keys(&:to_sym))
end

Inherited execution limits for model turns, tool calls, and tool output.

Keyword arguments merge into the current limits and the zero-argument form returns them.

logical_path ()

Source

# File lib/little_ghost/agent.rb, line 106
def logical_path
  parts = name.to_s.split("::")
  parts[-1] = parts.last.sub(/Agent\z/, "") if parts.any?
  parts.reject(&:empty?).map { |part| underscore(part) }.join("/")
end

The underscored, namespace-aware path used for conventional prompt lookup.

model() → String, Proc, nil

model(role) → String

model { |invocation| ... } → Proc

Source

# File lib/little_ghost/agent.rb, line 131
def model(*values, &block)
  return model_value if values.empty? && !block

  self.model_value = block || values.fetch(0).to_s
end

The logical model role for this agent.

Pass a block to choose a role from each Invocation at run time.

new (model: nil, runtime: nil, tools: [], template_resolver: nil, template_paths: [], run: nil, executor: Support::Executor.new, delegation_activity: nil, agent_path: Subagents::AgentPath::ROOT, max_turns: 100, max_tool_calls: 1_000, max_tool_result_tokens: DEFAULT_MAX_TOOL_RESULT_TOKENS, model_settings: {}, workspace: nil, sandbox: nil)

Source

# File lib/little_ghost/agent.rb, line 461
def initialize(
  model: nil,
  runtime: nil,
  tools: [],
  template_resolver: nil,
  template_paths: [],
  run: nil,
  executor: Support::Executor.new,
  delegation_activity: nil,
  agent_path: Subagents::AgentPath::ROOT,
  max_turns: 100,
  max_tool_calls: 1_000,
  max_tool_result_tokens: DEFAULT_MAX_TOOL_RESULT_TOKENS,
  model_settings: {},
  workspace: nil,
  sandbox: nil
)
  if model.nil? && run.nil?
    @standalone = true
    @runtime = runtime || Runtime.new(configuration: LittleGhost.configuration)
    @workspace = workspace
    @sandbox = sandbox
    @owns_resources = true
    @closed = false
    @close_mutex = Mutex.new
    @interruptions_mutex = Mutex.new
    @active_interruptions = []
    return
  end

  @model = model
  @runtime = runtime || run&.runtime
  @run = run
  @workspace = workspace || run&.workspace
  @sandbox = sandbox || run&.sandbox
  if @runtime.is_a?(Runtime) && !@workspace
    @workspace = @runtime.build_workspace
    @sandbox ||= @runtime.build_sandbox(workspace: @workspace)
  end
  @owns_resources = run.nil? && (@workspace || @sandbox)
  binding = Tool::Binding.new(agent: self, run:, runtime: @runtime, model:, workspace: @workspace, sandbox: @sandbox)
  @tool_registry = ToolRegistry.new(tools, binding:)
  self.class.tool_declarations.each do |declaration|
    @tool_registry.register(declaration, replace: true)
  end
  @structured_output_strategy = StructuredOutput.resolve(
    self.class.result_schema,
    model:,
    ordinary_tools: @tool_registry.specifications
  )
  @model_settings = model_settings.to_h.freeze
  @template_resolver = template_resolver || default_template_resolver(template_paths)
  @executor = executor
  @delegation_activity = delegation_activity
  @agent_path = Subagents::AgentPath.validate!(agent_path)
  @max_turns = Integer(max_turns)
  @max_tool_calls = Integer(max_tool_calls)
  @max_tool_result_tokens = Integer(max_tool_result_tokens)
  @closed = false
  @close_mutex = Mutex.new
  @exclusive_tools_mutex = Mutex.new
  @interruptions_mutex = Mutex.new
  @active_interruptions = []
  raise ArgumentError, "max_turns must be at least 1" if @max_turns < 1
  raise ArgumentError, "max_tool_calls must be at least 1" if @max_tool_calls < 1
  raise ArgumentError, "max_tool_result_tokens must be at least 1" if @max_tool_result_tokens < 1
  apply_cancellation_decision!(run_callbacks(:after_initialize, self))
rescue
  @tool_registry&.close
  raise
end

Creates either a standalone entrypoint or a run-scoped agent.

Calling new without model and run creates the console-friendly standalone form. Runtime builders supply the remaining dependencies and apply class-level limits and declarations.

prompt_local (name, *values, &resolver)

Source

# File lib/little_ghost/agent.rb, line 272
def prompt_local(name, *values, &resolver)
  raise ArgumentError, "Provide a prompt local value or block" if values.empty? && !resolver
  raise ArgumentError, "Provide a prompt local value or block, not both" unless values.empty? || !resolver

  self.prompt_local_values = prompt_local_values.merge(name.to_sym => resolver || values.fetch(0))
end

Adds a named value or resolver to every prompt rendered for the agent.

result_schema() → Hash, nil

result_schema(schema, name: nil, description: nil, strategy: :auto) → Hash

result_schema(name: nil, description: nil, strategy: :auto, **schema) → Hash

Source

# File lib/little_ghost/agent.rb, line 170
def result_schema(schema = nil, name: nil, description: nil, strategy: :auto, **schema_keywords)
  return result_schema_value if schema.nil? && schema_keywords.empty? && name.nil? && description.nil? && strategy == :auto

  if schema.nil?
    schema = schema_keywords
  elsif !schema_keywords.empty?
    raise ArgumentError, "Provide result_schema as a hash or keyword schema, not both"
  end

  raise ArgumentError, "result_schema must be a hash" unless schema.is_a?(Hash)

  normalized_schema = Class.new(Tool).tap { |tool| tool.input_schema(schema) }.input_schema
  validate_result_schema_keywords!(normalized_schema)
  unless normalized_schema["type"] == "object"
    raise ConfigurationError, "result_schema must describe a top-level object"
  end

  schema_name = (name || "#{agent_id}_result").to_s
  unless schema_name.match?(/\A[a-zA-Z0-9_-]{1,64}\z/)
    raise ConfigurationError, "result_schema name must contain 1-64 letters, numbers, underscores, or hyphens"
  end
  strategy = strategy.to_sym
  unless StructuredOutput::STRATEGIES.include?(strategy)
    raise ConfigurationError, "result_schema strategy must be auto, provider, or tool"
  end

  self.result_schema_value = {
    schema: normalized_schema,
    name: schema_name,
    description: description&.to_s,
    strategy:
  }
end

Declares a strict JSON-object result contract. Every object must set additionalProperties: false and require each property. Automatic strategy selection prefers provider-native structured output and falls back to a terminal tool when supported.

A missing or invalid result receives one repair attempt before LittleGhost::StructuredResultError is raised. Invalid schemas and strategies raise LittleGhost::ConfigurationError immediately.

system_prompt() → String, Proc, nil

system_prompt(value) → String

system_prompt { |locals| ... } → Proc

Source

# File lib/little_ghost/agent.rb, line 241
def system_prompt(*values, &block)
  return system_prompt_builder_value || system_prompt_value if values.empty? && !block

  self.system_template_value = nil
  if block
    self.system_prompt_value = nil
    self.system_prompt_builder_value = block
  else
    self.system_prompt_value = values.fetch(0).to_s
    self.system_prompt_builder_value = nil
  end
end

The inline system prompt or prompt-building block.

Setting an inline prompt clears system_template so one source remains authoritative.

system_template() → String, nil

system_template(path) → String

Source

# File lib/little_ghost/agent.rb, line 226
def system_template(*values)
  return system_template_value if values.empty?

  self.system_template_value = values.fetch(0).to_s
end

The explicit system prompt template path, when conventional lookup is not used.

tools (*values)

Source

# File lib/little_ghost/agent.rb, line 258
def tools(*values)
  invalid = values.flatten.compact.find { |value| !value.is_a?(Class) }
  if invalid
    raise ConfigurationError, "Class-level tools must be classes"
  end

  declarations = tool_declarations_value + values
  self.tool_declarations_value = declarations
  tool_declarations
end

Adds tool or provider classes to the agent.

Every declaration must be a class. A provider class can supply tools dynamically by implementing tools(binding).

Public Instance Methods

as_tool (name: self.class.agent_id, description: self.class.description, preserve_context: false)

Source

# File lib/little_ghost/agent.rb, line 756
def as_tool(name: self.class.agent_id, description: self.class.description, preserve_context: false)
  agent = self
  description = "Delegate a task to #{name}." if description.to_s.empty?
  mutex = Mutex.new
  retained_history = []
  tool_class = Tool.define(
    name: name,
    description: description,
    input_schema: {
      type: "object",
      properties: {input: {type: "string"}},
      required: ["input"],
      additionalProperties: false
    }
  ) do |input, context: nil|
    invocation = lambda do
      result = agent.call(
        input.fetch("input"),
        history: preserve_context ? retained_history : [],
        context: context&.state || {},
        cancellation_token: context&.cancellation_token || Support::CancellationToken.new,
        interruption_metadata: context&.interruption_metadata,
        interruption_ids: context&.interruption_ids || [],
        deadline: context&.deadline,
        parent_operation_id: run&.operation_id
      )
      retained_history.replace(result.messages.reject { |message| message.role == :system }) if preserve_context
      result.structured? ? result.structured_result.value : result.text
    end
    preserve_context ? mutex.synchronize(&invocation) : invocation.call
  end
  tool_class.define_method(:close) { agent.close }
  binding = Tool::Binding.new(
    agent: self,
    run:,
    runtime:,
    model:,
    workspace:,
    sandbox:
  )
  tool_class.new(binding:)
end

Exposes this agent as a Tool instance.

By default, each call starts with empty conversational history. Set preserve_context: true to retain history serially between calls.

ask (message, **options)

Source

# File lib/little_ghost/agent.rb, line 567
def ask(message, **options)
  call(message, **options)
end

Console-friendly name for call.

call (input = nil, **options)

Source

# File lib/little_ghost/agent.rb, line 556
def call(input = nil, **options)
  return build_run(entrypoint_payload(input, options)).call if @standalone

  result = nil
  stream(input, **options).each do |event|
    result = event.data[:result] if event.type == :invocation_stop
  end
  result
end

Runs input to completion.

A standalone agent returns a LittleGhost::Run. An agent built inside a run returns its LittleGhost::RunResult.

Source

# File lib/little_ghost/agent.rb, line 816
def close
  resources, interruptions = @close_mutex.synchronize do
    return if @closed

    @closed = true
    [
      [tool_registry, (@sandbox if @owns_resources), (@workspace if @owns_resources)],
      @interruptions_mutex.synchronize { @active_interruptions.dup }
    ]
  end
  first_error = nil
  interruptions.each do |active|
    active.close(AgentInterruptError.new("Agent was closed"))
  end
  resources.each do |resource|
    resource.close if resource.respond_to?(:close)
  rescue => error
    first_error ||= error
  end
  raise first_error if first_error
end

Closes owned tools, interruptions, sandbox, and workspace resources. The operation is idempotent and re-raises the first cleanup failure.

interrupt (message, cancellation_token: Support::CancellationToken.new, deadline: nil, target_operation_id: nil, interruption_id: nil, batch_key: nil, metadata: {})

Source

# File lib/little_ghost/agent.rb, line 576
def interrupt(
  message,
  cancellation_token: Support::CancellationToken.new,
  deadline: nil,
  target_operation_id: nil,
  interruption_id: nil,
  batch_key: nil,
  metadata: {}
)
  interrupt_response(
    message,
    cancellation_token:,
    deadline:,
    target_operation_id:,
    interruption_id:,
    batch_key:,
    metadata:
  ).text
end

Adds message to one active invocation and waits for its ordinary text reply.

The response may continue into tool calls; delivery does not stop the original invocation. Raises LittleGhost::AgentInterruptError when there is no unambiguous active target.

interrupt_response (message, cancellation_token: Support::CancellationToken.new, deadline: nil, target_operation_id: nil, interruption_id: nil, batch_key: nil, metadata: {})

Source

# File lib/little_ghost/agent.rb, line 603
def interrupt_response(
  message,
  cancellation_token: Support::CancellationToken.new,
  deadline: nil,
  target_operation_id: nil,
  interruption_id: nil,
  batch_key: nil,
  metadata: {}
)
  message = Message.new(role: :user, content: message) if message.is_a?(String)
  raise ArgumentError, "interrupt message must be a String or LittleGhost::Message" unless message.is_a?(Message)
  safe_content = message.content.all? do |content|
    content.is_a?(Content::Text) ||
      content.is_a?(Content::Image) ||
      content.is_a?(Content::Document)
  end
  unless safe_content
    raise ArgumentError, "interrupt message content must contain only text, images, or documents"
  end

  interruptions = @interruptions_mutex.synchronize do
    active = if target_operation_id
      @active_interruptions.select { |candidate| candidate.target_operation_id == target_operation_id }
    else
      @active_interruptions
    end
    if active.empty?
      raise AgentInterruptError, "Agent is not currently running"
    end
    if active.length > 1
      raise AgentInterruptError, "Agent has multiple active invocations; the interruption target is ambiguous"
    end

    active.first
  end
  options = {batch_key:, metadata:}
  options[:id] = interruption_id unless interruption_id.nil?
  ticket = interruptions.enqueue(message, **options)
  instrument(
    :agent_interrupt_queued,
    parent_operation_id: interruptions.operation_id,
    interruption_id: ticket.id,
    event_kind: :interrupt,
    diagnostic: {input: diagnostic_message(message)}
  )
  begin
    response = ticket.value(cancellation_token:, deadline:)
    interruptions.release(ticket)
    response
  rescue => error
    interruptions.release(ticket, withdraw: true)
    instrument(
      :agent_interrupt_failed,
      parent_operation_id: interruptions.operation_id,
      interruption_id: ticket.id,
      event_kind: :interrupt,
      error_type: error.class.name,
      diagnostic: {exception: diagnostic_exception(error)}
    )
    raise
  end
end

Adds an interruption and returns the model’s immediate response details.

Use target_operation_id when an agent has multiple active invocations. Messages may contain only text, image, or document content. The returned response value exposes text, tool_calls?, interruption_ids, and batch_key; tool calls may continue after this response. Depend on these methods rather than the response’s concrete class.

prompt_locals ()

Source

# File lib/little_ghost/agent.rb, line 800
def prompt_locals
  self.class.prompt_local_resolvers.to_h do |name, resolver|
    value = if resolver.respond_to?(:call)
      resolver.parameters.empty? ? instance_exec(&resolver) : resolver.call(self)
    else
      resolver
    end
    [name, value]
  end.freeze
end

Materializes and freezes the prompt locals declared on the agent class.

stream (input = nil, history: nil, context: nil, cancellation_token: Support::CancellationToken.new, deadline: nil, settings: nil, template_locals: nil, template_paths: nil, parent_operation_id: nil, checkpoint: nil, conversation_id: nil, interruption_metadata: nil, interruption_ids: [], interrupt_ready: nil)

Source

# File lib/little_ghost/agent.rb, line 674
def stream(
  input = nil,
  history: nil,
  context: nil,
  cancellation_token: Support::CancellationToken.new,
  deadline: nil,
  settings: nil,
  template_locals: nil,
  template_paths: nil,
  parent_operation_id: nil,
  checkpoint: nil,
  conversation_id: nil,
  interruption_metadata: nil,
  interruption_ids: [],
  interrupt_ready: nil
)
  if @standalone
    raise ArgumentError, "input is required" if input.nil?

    return build_run(entrypoint_payload(input, {})).each
  end

  raise ArgumentError, "input is required" if input.nil?

  history ||= []
  context ||= {}
  settings ||= {}
  template_locals ||= {}
  template_paths ||= []
  invocation_paths = Array(template_paths).map do |path|
    unless path.is_a?(LittleGhost::TrustedPath)
      raise ArgumentError, "invocation template paths must be LittleGhost::TrustedPath values"
    end
    path
  end
  settings = @model_settings.merge(settings)
  Enumerator.new do |events|
    interruptions = AgentInterruptions.new
    run_context = RunContext.new(
      state: context,
      cancellation_token: cancellation_token,
      deadline: deadline,
      metadata: {agent_id: self.class.agent_id},
      checkpoint:,
      conversation_id:,
      interruption_metadata:,
      interruption_ids:
    )
    begin
      with_invocation(run_context) do
        execute(
          input,
          history: history,
          context: run_context,
          settings: settings,
          template_locals: template_locals,
          template_paths: invocation_paths,
          events: events,
          parent_operation_id:,
          interruptions:,
          interrupt_ready:
        )
      end
    rescue => error
      interruptions.close(error)
      raise
    ensure
      interruptions.close(AgentInterruptError.new("Agent finished before the interruption was delivered"))
      unregister_interruptions(interruptions)
    end
  end
end

Streams one invocation as StreamEvent objects.

Agents built inside a run accept history, JSON-like context, cancellation, deadlines, settings, and trusted invocation template paths. An agent instance may be streamed only according to the lifecycle managed by its owning run. Every template path must be an application-created TrustedPath; the wrapper records a trust decision and must never contain unchecked request or model input.

stream_ask (message, **options)

Source

# File lib/little_ghost/agent.rb, line 748
def stream_ask(message, **options)
  stream(message, **options)
end

Console-friendly name for stream.

Source

# File lib/little_ghost/agent.rb, line 812
def tools = tool_registry

The materialized tools available during this agent run.

Protected Instance Methods

model_tools (tools, context:, turn:)

Source

# File lib/little_ghost/agent.rb, line 850
def model_tools(tools, context:, turn:)
  tools
end

Returns the tools exposed to the model for turn. Subclasses may override this hook to filter the already-authorized tool list.

with_invocation (_context) { || ... }

Source

# File lib/little_ghost/agent.rb, line 843
def with_invocation(_context)
  yield
end

Yields around one invocation. Subclasses may override this hook to install invocation-scoped state and must yield exactly once.

with_tool_execution (_execution) { || ... }

Source

# File lib/little_ghost/agent.rb, line 857
def with_tool_execution(_execution)
  yield
end

Yields around one tool execution. Subclasses may override this hook for execution-scoped behavior and must yield exactly once.