class RubyLLM::MCP::Task
A tool call that an MCP server runs in the background, as the Tasks extension describes. Declare MCP.extension :tasks, and a server may answer a long call with a task instead of a result.
A chat never waits for a task. It pauses the tool call, and Chat#pending_tasks returns the tasks it waits on. refresh checks on a task once; Chat#complete checks on every one again and resumes the chat once they are done:
task = chat.pending_tasks.first task.refresh task.status # => :working task.status_message # => "Rendering page 3 of 12" task.poll_interval # => 5.0
MCP#call waits for the task of a tool you call directly.
Attributes
The task’s id on its server.
Public Instance Methods
Source
# File lib/ruby_llm/mcp/task.rb, line 93 def cancel connected.cancel_task(id) unless complete? self end
Asks the server to cancel the task, and returns self. The server may still finish it, so check with refresh.
Source
# File lib/ruby_llm/mcp/task.rb, line 59 def expires_at Time.iso8601(data['createdAt']) + (data['ttlMs'] / 1000.0) if data['ttlMs'] && data['createdAt'] end
When the server may forget the task, as a Time, or nil when it keeps the task for good.
Source
# File lib/ruby_llm/mcp/task.rb, line 53 def poll_interval data['pollIntervalMs'] / 1000.0 if data['pollIntervalMs'] end
How many seconds the server asks you to wait before checking on the task again, or nil.
Source
# File lib/ruby_llm/mcp/task.rb, line 74 def refresh @data = connected.poll_task(id) unless complete? self end
Source
# File lib/ruby_llm/mcp/task.rb, line 65 def result raise error if failed? || cancelled? Result.new(data['result']) if succeeded? end
Returns the MCP::Result once the task succeeded?, and nil until then. Raises MCP::Error when the task failed or was cancelled.
Source
# File lib/ruby_llm/mcp/task.rb, line 41 def status data['status'].to_sym end
The task’s state: :working, :input_required, :completed, :failed, or :cancelled.
Source
# File lib/ruby_llm/mcp/task.rb, line 47 def status_message data['statusMessage'] end
What the server says about the task’s state, such as how far it got, or nil.
# File lib/ruby_llm/mcp/task.rb, line 87 def wait(timeout: nil, interval: nil) connected.await_task(self, timeout:, interval:) end
Checks on the task until it is complete?, sleeping poll_interval seconds in between, and returns self. Answers the server’s requests for input with MCP.before_input_request callbacks. timeout defaults to the server’s MCP.timeout, and the task is cancelled when it runs out or the chat is cancelled.
Raises MCP::Error when the task fails or the time runs out, and MCP::InputRequiredError when no callback answers a request.