ruby_llm-ai_sdk

Stream RubyLLM chats to the AI SDK useChat hook.

The AI SDK's React hooks speak the UI message stream protocol: Server-Sent Events that carry text deltas, reasoning, tool calls, tool results and approval requests. This gem emits that protocol from a RubyLLM chat, so a React or Next.js front end talks to a Ruby backend the same way it talks to a Node one, tool calls and human approvals included.

RubyLLM::AiSdk::Stream.new(chat, response.stream).ask "Refund order 42"

gem "ruby_llm-ai_sdk"

Requires RubyLLM 1.16 or later. Approval requests need RubyLLM's requires_approval, unreleased at the time of writing, so point the ruby_llm gem at its main branch to use them.

Include the controller module and hand stream_chat a chat. It sets the headers the AI SDK expects, streams the turn over ActionController::Live, and closes the stream when the turn ends.

class MessagesController < ApplicationController
  include RubyLLM::AiSdk::Controller

  def create
    stream_chat SupportAgent.find(params[:chat_id])
  end
end

On the front end, point useChat at that action. Nothing else changes.

const { messages, sendMessage, addToolApprovalResponse } = useChat({
  transport: new DefaultChatTransport({ api: `/chats/${chatId}/messages` }),
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
});

stream_chat reads the body useChat posts. When the last message is from the user, it asks it, with any attached files passed to chat.ask as attachments. When the last assistant message carries approval decisions, it records them with chat.approve or chat.deny and continues the parked turn.

examples/ holds a complete pair, a Rails API app and a Next.js page, that exercises text, tools, approval and denial through a browser.

Stream writes to anything that responds to write, so it works with Rack hijacking, Sinatra streaming, or a file.

stream = RubyLLM::AiSdk::Stream.new(chat, io)
stream.ask "What is the weather in Paris?"   # one turn, streamed
stream.serve request_body                     # a full useChat body, as JSON or a Hash

RubyLLM::AiSdk::HEADERS holds the response headers to set.

Tool outputs that are valid JSON arrive parsed, so part.output on the client is the object your tool returned.

Declare a tool with requires_approval and the turn stops before it runs. The client receives tool-approval-request, renders it with the tool's input, and the person decides:

{part.state === "approval-requested" && (
  <button onClick={() => addToolApprovalResponse({ id: part.approval.id, approved: true })}>
    Approve
  </button>
)}

useChat posts the decision back, the gem records it, and the same stream format carries the tool's output and the model's reply. With acts_as_chat, the decision persists on the tool call record, so the parked turn can be resumed from another process.

• A Stream is one turn. It registers a callback on the chat it wraps and only writes while its own turn runs, so a chat can be streamed turn after turn, with one Stream per request.
• Tool results come from the transcript, not the callback. RubyLLM's after_tool_result does not carry the tool call id, so results are read from the tool messages appended to the chat. That also keeps concurrent tool execution correct.
• Steps follow model responses. Each assistant message closes a step; a text or reasoning chunk that arrives with no step open opens one.

useChat sends file parts as data URLs by default, or as hosted URLs when you upload them yourself. Both reach chat.ask through with:: hosted files as their URL, data URLs decoded into a RubyLLM::Attachment that keeps the filename, so RubyLLM detects the type and sends it the way the provider expects.

bundle install
bundle exec rake   # specs and RuboCop

The specs stub the provider and drive real RubyLLM::Chat objects through every path, including approvals. No API keys are needed.

MIT.