0.12.8
A patch release. All six packages move to 0.12.8 together. Only @silverprotocol/openai-agents changes. The spec revision stays 1.0.0-draft.8.
Who should upgrade
- You stay on the 0.12 line and want
@openai/agents0.20 or 0.21. 0.12.8’s@silverprotocol/openai-agentsaccepts both: its peer range widens from<0.20to<0.22. Read “Moving to @openai/agents 0.20 and 0.21” below first. - You use an OpenAI-compatible provider through
@openai/agentsthat reports usage detail counters beyond the ones the OpenAI client’s types define. - You use tool search over hosted MCP tools with
@openai/agents0.20 or later, and want the tool names a search established. - Anyone else gets the same output as from 0.12.7: every one of 125 replayed runs is byte-identical (see Wire version).
Moving to @openai/agents 0.20 and 0.21
These are changes in @openai/agents itself. They reach a host that upgrades, whichever version of this package it runs:
- A model call after an approval resume counts toward
maxTurnsfrom 0.20. Resolving an approval doesn’t use a turn, but the model call that follows does, so a run withmaxTurns: 1that resumes after an approval throws the SDK’sMaxTurnsExceededErroron 0.20 and 0.21, where 0.19 completed it. The same run withmaxTurns: 2completes on all three versions. - A run paused and saved on 0.21 can’t be resumed on 0.20. 0.21 saves run state at schema version 1.23, and 0.20 rejects it on resume with a
UserError: “Run state schema version 1.23 is not supported. Please use version 1.22.” A run saved on 0.19 or 0.20 resumes on 0.21. Upgrade every process that resumes saved runs before any process saves one on a newer version. - Usage token details can be nested from 0.21. In the SDK’s own
Usageobject,inputTokensDetailsandoutputTokensDetailsare now records whose values are numbers or further records, so narrow each value to a number before you do arithmetic with it. The AgJSONusagethis package emits doesn’t change shape. - The Runloop sandbox provider is removed in 0.21, with its public API. OpenAI’s migration guide lists the supported alternatives. This package never touches the sandbox.
OpenAI Agents SDK
- The package accepts
@openai/agents0.20 and 0.21: its peer range widens to>=0.2.0 <0.22. - A tool search’s hosted MCP tool names are carried. From
@openai/agents0.20, a tool-search output item can list the hosted MCP tool names a server-executed search established (toolSearchMcpToolNames). The package carries that array as received on the search’stool.doneproviderMetadata, besidetoolSearchAgentName. A value that isn’t an array of strings isn’t carried, and an output without the field gives the same events as before. - Usage detail counters the package doesn’t map are no longer dropped. The package maps
cached_tokens,cache_write_tokensandreasoning_tokensfrom a response’s input and output token details, and dropped every other key. The OpenAI client’s types (openai7.43.0) define no other key; an OpenAI-compatible provider can send flat counters or a nested breakdown, and 0.21 keeps them through a streamed run. They now ride oneext.openai.unparsedevent per response,name: "usage-details", before the round’s terminal, holding the unmapped entries as received. Nothing is emitted when every key is mapped. A mapped key whose value isn’t a number (a provider’snull) now sets no usage counter, where 0.12.7 put thatnullinusage, and rides the same event.
The other five packages change only their version.
Verified versions
Each framework package is verified end to end, tool calls included, against a live run at:
@anthropic-ai/claude-agent-sdk0.3.292;@openai/agents0.21.0;@google/adk2.2.1;ai7.0.130.
Wire version
1.0.0-draft.8, unchanged. Replaying every recorded stream and fixture through the 0.12.7 and 0.12.8 packages, all 125 runs give byte-identical events, among them the Claude Agent SDK (31), OpenAI Agents SDK (16), Google ADK (24) and Vercel AI SDK (9) streams, the Google ADK pause fixtures (22) and the engine-built OpenAI hosted-tool streams (22). No recorded stream triggers either OpenAI change. With an unmapped audio_tokens count added to each response’s input token details in one recorded OpenAI stream, 0.12.7 drops it, and 0.12.8 emits one usage-details event per response that holds it.
npm’s provenance for all six 0.12.8 packages attests typescript-sdk commit 9530fe48.