Skip to content
shimmer/docs
Integrations

OpenAI

Prepare OpenAI requests with recorded tool results during a test run.

On this page

The Python SDK includes shim_openai, a wrapper that prepares OpenAI inputs through Shimmer during a case run. Use it when a test needs recorded tool results inserted into the next model request.

Wrap a traced client

Apply the Shimmer shim after LangSmith’s tracing wrapper:

python
from langsmith.wrappers import wrap_openai
from openai import OpenAI
from shimmer.openai import shim_openai

client = shim_openai(wrap_openai(OpenAI()))

Use this client inside an agent invoked by your Shimmer harness. The runner provides the active case-run context that the shim needs, whether you run locally or through GitHub Actions.

How preparation works

Before forwarding a request to OpenAI, the shim asks Shimmer to prepare tool results against the case’s baseline trace. Your OpenAI client still handles the model request and response using your own provider credentials.

For recorded-result replacement, a tool can return the SHIMMER_REPLACE placeholder. The preparer searches recorded calls with the same tool name and uses matching to select a result. This is useful for reproducing external tool responses during a test.

Supported calls

The synchronous OpenAI client wrapper prepares inputs for:

  • client.chat.completions.create(...)
  • client.chat.completions.parse(...)
  • client.responses.create(...)
  • client.responses.parse(...)

Chat Completions sends messages; Responses sends input. Other request options, including streaming settings, remain with the OpenAI client.

Run locally or in CI

Run your harness through the CLI or the Shimmer GitHub Action. The Action authenticates to Shimmer with GitHub OIDC. Provide your agent’s OPENAI_API_KEY in the environment where its harness executes.

Recorded tool-result preparation is managed by Shimmer. Use a normal traced OpenAI client outside test runs; the shim requires an active case-run context.