Module: RubyPi::Agent

Defined in:

lib/ruby_pi/agent/core.rb,
lib/ruby_pi/agent/core.rb,
lib/ruby_pi/agent/loop.rb,
lib/ruby_pi/agent/state.rb,
lib/ruby_pi/agent/events.rb,
lib/ruby_pi/agent/result.rb

Overview

Module-level convenience method for creating Agent instances without referencing Agent::Core directly. Allows RubyPi::Agent.new(...).

Defined Under Namespace

Modules: EventEmitter Classes: Core, Loop, Result, State

Constant Summary

EVENTS =

Canonical event types emitted during the agent lifecycle. Each symbol represents a specific moment or occurrence:

• :text_delta — An incremental text chunk from the LLM stream.
• :tool_call_delta — An incremental tool call chunk from the LLM stream.
• :tool_execution_start — A tool is about to be executed.
• :tool_execution_end — A tool has finished executing.
• :turn_start — A new think-act-observe cycle is beginning.
• :turn_end — A think-act-observe cycle has completed.
• :agent_end — The agent has finished its run (final event).
• :error — A recoverable or fatal error occurred.
• :compaction — Context compaction was triggered.
• :provider_fallback — A Fallback provider switched from primary to backup mid-stream. Subscribers should discard any partial text_delta output that arrived before this event.
• :provider_retry — A provider discarded a failed streaming attempt and is retrying from the beginning.

%i[
  text_delta
  tool_call_delta
  tool_execution_start
  tool_execution_end
  turn_start
  turn_end
  agent_end
  error
  compaction
  provider_retry
  provider_fallback
].freeze

Class Method Summary

• .new(**args) ⇒ RubyPi::Agent::Core

  Creates a new Agent::Core instance.

Class Method Details

.new(**args) ⇒ RubyPi::Agent::Core

Creates a new Agent::Core instance. This is the recommended entry point for building agents.

Examples:

agent = RubyPi::Agent.new(
  system_prompt: "You are helpful.",
  model: model,
  tools: registry
)

Parameters:

• args (Hash) —

  constructor arguments forwarded to Agent::Core.new

Returns:

• (RubyPi::Agent::Core) —

  a new agent instance

# File 'lib/ruby_pi/agent/core.rb', line 240

def new(**args)
  Core.new(**args)
end