Class: Agents::ToolContext

Inherits:
Object
  • Object
show all
Defined in:
lib/agents/tool_context.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(run_context:, retry_count: 0) ⇒ ToolContext

Initialize a new ToolContext wrapping a RunContext

Parameters:

  • run_context (Agents::RunContext) —

    The run context containing shared execution state

  • retry_count (Integer) (defaults to: 0) —

    Number of times this tool execution has been retried (default: 0)



61
62
63
64
 
# File 'lib/agents/tool_context.rb', line 61

def initialize(run_context:, retry_count: 0)
  @run_context = run_context
  @retry_count = retry_count
end

Instance Attribute Details

#retry_count ⇒ Object (readonly)

Returns the value of attribute retry_count.



55
56
57
 
# File 'lib/agents/tool_context.rb', line 55

def retry_count
  @retry_count
end

#run_context ⇒ Object (readonly)

Returns the value of attribute run_context.



55
56
57
 
# File 'lib/agents/tool_context.rb', line 55

def run_context
  @run_context
end

Instance Method Details

#context ⇒ Hash

Convenient access to the shared context hash from the RunContext. This delegation makes it easier for tools to access context data without having to navigate through run_context.context.

Examples:

Accessing context data in a tool

def perform(tool_context, **params)
  user_id = tool_context.context[:user_id]
  session = tool_context.context[:session]
  # ...
end

Returns:

  • (Hash) —

    The shared context hash from the RunContext



77
78
79
 
# File 'lib/agents/tool_context.rb', line 77

def context
  @run_context.context
end

#state ⇒ Hash

Convenient access to the shared state hash within the context. This provides tools with a dedicated space to store and retrieve state that persists across agent interactions within a conversation.

State is automatically initialized as an empty hash if it doesn’t exist. All state modifications are automatically included in context serialization, making it persist across process boundaries (e.g., Rails with ActiveRecord).

Examples:

Tool storing customer information in state

def perform(tool_context, customer_id:)
  customer = Customer.find(customer_id)

  # Store in shared state for other tools/agents to access
  tool_context.state[:customer_id] = customer_id
  tool_context.state[:customer_name] = customer.name
  tool_context.state[:plan_type] = customer.plan

  "Found customer #{customer.name}"
end

Tool reading from shared state

def perform(tool_context)
  customer_id = tool_context.state[:customer_id]
  plan_type = tool_context.state[:plan_type]

  if customer_id && plan_type
    "Current plan: #{plan_type} for customer #{customer_id}"
  else
    "No customer information available"
  end
end

Returns:

  • (Hash) —

    The shared state hash



130
131
132
 
# File 'lib/agents/tool_context.rb', line 130

def state
  context[:state] ||= {}
end

#usage ⇒ Agents::RunContext::Usage

Convenient access to the usage tracking object from the RunContext. Tools can use this to add their own usage metrics if they make additional LLM calls.

Examples:

Tool tracking additional LLM usage

def perform(tool_context, **params)
  # Tool makes its own LLM call
  response = llm.complete("Analyze: #{params[:data]}")
  tool_context.usage.add(response.usage)

  response.content
end

Returns:



94
95
96
 
# File 'lib/agents/tool_context.rb', line 94

def usage
  @run_context.usage
end