[FEATURE] Support function calling without automatically executing tools

[subelsky]

Scope check

• This is core LLM communication (not application logic)
• This benefits most users (not just my use case)
• This can't be solved in application code with current RubyLLM
• I read the Contributing Guide

Due diligence

• I searched existing issues
• I checked the documentation

What problem does this solve?

Right now the tool-calling feature cannot be used for pure function calling, because it automatically executes tools and returns the results to the model as part of the chat.

In many cases, such as multi-agent workflows, developers will want to pass the parameters returned by a function call to another agent, which can't be done without making an unnecessary chat request to the original model.

Proposed solution

I'd like to add a check to RubyLLM::Chat#handle_tool_calls that only sends a new message if the tool has defined an execute method. Any tools that do not implement execute can be treated as pure functions with no RubyLLM side effects.

Why this belongs in RubyLLM

This is core behavior for the RubyLLM::Chat class - it could theoretically be fixed by subclassing RubyLLM::Chat and overriding the private method, but that is not very maintainable.

I'm happy to fix this if there's an appetite for the change! thanks for making a great gem.

[crmne]

This isn't a core library concern and would break how tool calling fundamentally works.

Tool calls are expected to return results to the LLM - that's the entire point of function calling. The model requests a tool execution and expects a response to continue the conversation. Interrupting this flow breaks the standard tool calling contract.

You can solve this with existing functionality. Write a tool that coordinates with your other agents:

class AgentBridgeTool < RubyLLM::Tool
  def execute(params)
    OtherAgent.process(params)
    "Task forwarded to specialized agent"
  end
end

Or store the tool call data and return an appropriate response to keep the conversation flowing.

Won't fix.

[tpaulshippy]

can't be done without making an unnecessary chat request to the original model.

Is this true @crmne?

[subelsky]

Tool calls are expected to return results to the LLM - that's the entire point of function calling. The model requests a tool execution and expects a response to continue the conversation. Interrupting this flow breaks the standard tool calling contract.

Thanks for considering my proposal. I disagree with this statement: single-turn tool calling is a powerful pattern that I use in almost everything I've built. Sometimes you want to conditionally process tool results before returning them to the caller, and sometimes you want to interrupt the tool-calling sequence completely (like if the model calls a 'stop' function, or if the tool arguments include something that fails sanitization.).

Automatically executing a tool and invoking another request without a way for the application to check/validate/cancel that call feels like an antipattern to me. Your AgentBridgeTool doesn't look like it would solve this for me, unfortunately. Best of luck!

[tpaulshippy]

If you try your proposal in a fork, I'm interested @subelsky

[sritabh]

I have had similar use case where I want my model to execute a piece of code and not send the response back to the model. The following is the workaround I came up with.

Base class

Defines a class method interrupt_on_success_with_signal

class AI::Tools::Base < RubyLLM::Tool
  class << self
    attr_accessor :interrupt_on_success_with_signal

    def interrupt_on_success_with_signal
      @interrupt_on_success_with_signal = true
    end

    def signals_on_success?
      @interrupt_on_success_with_signal ||= false
    end
  end

  def self.method_added(method_name)
    return unless method_name == :execute
    return if @execute_wrapped

    @execute_wrapped = true
    original_execute = instance_method(:execute)

    define_method(:execute) do |**params|
      result = original_execute.bind(self).call(**params)
      handle_signal_on_success(result:, args: params)
    end

    @execute_wrapped = false
  end

  private

  def handle_signal_on_success(data)
    if self.class.signals_on_success?
      raise AI::Utils::SuccessfulCompletionSignal.new("Tool success signal: Execution completed successfully", data: data)
    end

    data[:result]
  end
end

Tool required to be just executed

class MyToolToExecuteCode < AI::Tools::Base
  interrupt_on_success_with_signal # Interrupt this tool call after executing with signal

  ...

  def execute(param1: , param2:)
    # Pass the response from model to another agent here
  end
end

You can then rescue from AI::Utils::SuccessfulCompletionSignal to track the request

[aamatte]

I have a similar but slightly different use case. In my agent system, I have a complete_task tool that signals the
conversation should end. However, after the tool executes and returns [TASK_COMPLETED], Ruby LLM automatically calls
complete again, resulting in:

1. Agent calls complete_task tool
2. Tool executes and returns result
3. Ruby LLM automatically calls complete → extra LLM request
4. LLM generates a final message like "¡Hasta la próxima!"
5. My code detects task completion and has to ignore this final message

This extra LLM call consumes tokens unnecessarily. My use case differs from pure function calling. I do want the tool
executed, but I'd like control over whether to continue the conversation afterward.

@sritabh's workaround with the signal approach is interesting, but it feels like we're working around the framework rather
than with it.

For my case, a simpler solution would be having the option to prevent the automatic complete call after tool execution,
perhaps:

# In handle_tool_calls
def handle_tool_calls(response, &)
  response.tool_calls.each_value do |tool_call|
    @on[:new_message]&.call
    result = execute_tool tool_call
    message = add_tool_result tool_call.id, result
    @on[:end_message]&.call(message)
  end

  # Check if we should continue
  unless @halt_after_tools || should_halt_after_tools?(response.tool_calls)
    complete(&)
  end
end

This would allow tools to signal completion without the extra round trip. Would this be a more acceptable approach than
the pure function calling proposal?

[subelsky]

I ended up writing my code to use a different gem after the wont-fix, so I won't be able to contribute code. But maybe execute_tool could be made to yield in the case where the tool requests halting further tool calls, to provide an early exit from handle_tool_calls. Somewhat similar to how raix-rails does it: https://github.com/OlympiaAI/raix-rails?tab=readme-ov-file#manually-stopping-a-loop

[joshforbes]

Tool calls are expected to return results to the LLM - that's the entire point of function calling. The model requests a tool execution and expects a response to continue the conversation. Interrupting this flow breaks the standard tool calling contract.

@crmne, in my case, I do want to return the result of the tool call to the LLM. I just don't want to do it right now.

I want to implement approve/deny functionality that the user is allowed to respond to on their own time (minutes/hours/days/whatever). I would want to stop the tool call from returning, wait for user approval, perform multiple actions upon approval, and finally reinstantiate the chat to return the output of those actions to the LLM.

Like @sritabh, I was also thinking of implementing this by raising, but it seems not quite right.

[joshforbes]

I'm not sure if it holds any weight, but "12 factor agents" recommend exactly this under their suggestion to "own your control flow":

https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-08-own-your-control-flow.md

This pattern allows you to interrupt and resume your agent's flow as needed, creating more natural conversations and workflows.

Example - the number one feature request I have for every AI framework out there is we need to be able to interrupt a working agent and resume later, ESPECIALLY between the moment of tool selection and the moment of tool invocation.

Without this level of resumability/granularity, there's no way to review/approve the tool call before it runs, which means you're forced to either:

Pause the task in memory while waiting for the long-running thing to complete (think while...sleep) and restart it from the beginning if the process is interrupted
Restrict the agent to only low-stakes, low-risk calls like research and summarization
Give the agent access to do bigger, more useful things, and just yolo hope it doesn't screw up

If you weren't interested in implementing it at the tool-level, maybe you would be interested in something like Langchainrb, where you can:

assistant.run(auto_tool_execution: false)

Or Raix where you can:

chat_completion(loop: false)

Then the user can implement their own loop, with whatever logic they need.

[crmne]

Just committed halt in 1721a00

class HandoffTool < RubyLLM::Tool
  def execute(query:)
    response = RubyLLM.chat
      .with_instructions("You are a Ruby expert...")
      .ask(query)
    
    halt response.content
  end
end

Tools can now stop continuation cleanly.

@subelsky @aamatte @sritabh @joshforbes