PARAS MADAN
All writing

Latest in AI

How to upgrade a Rails app to OpenAI Ruby SDK 1.0

Check Ruby compatibility, replace retired Assistants bindings, and test saved conversations and Responses compaction before updating the openai gem.

Your Rails console can load a new gem while a queue worker still runs an older Ruby. It can also boot without touching a stale Assistants reference buried in a job. Those are two different upgrade failures, and OpenAI's Ruby SDK 1.0, released November 21, is a good reason to test for both before deploy.

The official openai gem now requires Ruby 3.3.0 or newer. The release removes the old Assistants, Threads and Videos bindings and changes the types returned by Responses compaction. If your app already uses Responses, the runtime and compaction checks may be all you need.

Check the Ruby that runs each process

Read the lockfile first to make sure your dependency is the official openai gem. Check the Ruby version in CI and in the images that run web processes, queue workers and scheduled jobs. A current version on your laptop doesn't help if one of those images still ships Ruby 3.2. The requirement is in the tagged gemspec.

Once you have updated the lockfile in a staging build, run this inside each distinct runtime image:

bundle exec ruby -ropenai -e 'puts RUBY_VERSION; puts Gem.loaded_specs.fetch("openai").version'

The command loads the installed library and prints both versions without constructing a client or making an API request. Also boot the application and workers in staging with external calls stubbed. The load check alone won't find method calls that only run when a job executes.

Find deleted calls, including in jobs

Search for beta.assistants, beta.threads, client.videos and /v1/videos. Include job code, tests and Batch payload templates. Search for wrapper names too: removing a direct call from a controller won't fix a scheduled job that still goes through the old wrapper. Don't miss old model constants referenced by config, such as GPT_4_VISION_PREVIEW. The versioned migration guide lists the removed paths and changed types.

The Assistants API sunset happened in August. The November release removes SDK methods for an API that already stopped working. Rolling back the gem won't bring that API back or recover a thread's contents.

Give retained conversations new IDs

For a chat flow that still depends on old thread IDs, start with one synthetic transcript from your app's storage format. Convert its retained messages and tool results to Conversation items in their original order. Create a new Conversation for each thread you migrate and store the new ID alongside the old ID. An old thread ID won't work as the new conversation: argument.

Put the old Assistant's instructions and tool definitions into your Responses configuration. Send a follow-up using the new conversation ID and check that it can answer a question about the retained transcript. If the application runs function tools, verify that each function_call_output matches the corresponding call_id. For a thread with no stored transcript, handle it as a fresh session instead of silently claiming to restore it. Existing thread IDs alone aren't enough.

Test compaction separately from ordinary responses

If you call client.responses.compact, add a fixture with both a retained input message and a compaction record. SDK 1.0 can return both in compacted history, so code that casts every item to ResponseOutputItem or expects assistant text can break even when responses.create still works. Check your Sorbet or RBS annotations if you use them.

The SDK guide recommends forwarding the full compacted output into the next request. Verify that your adapter doesn't discard unfamiliar records while extracting display text. A successful text-only response is a useful smoke test; it doesn't tell you whether your stored history survives compaction.

I'm Paras. I work across AI, engineering and distribution.

I help AI teams turn breaking releases into technical guides that show developers what to check before upgrading.

Book a 30-minute call.