0.12.8

@openai/agents 0.20 and 0.21 on the 0.12 line

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/agents 0.20 or 0.21. 0.12.8’s @silverprotocol/openai-agents accepts both: its peer range widens from <0.20 to <0.22. Read “Moving to @openai/agents 0.20 and 0.21” below first.
  • You use an OpenAI-compatible provider through @openai/agents that reports usage detail counters beyond the ones the OpenAI client’s types define.
  • You use tool search over hosted MCP tools with @openai/agents 0.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 maxTurns from 0.20. Resolving an approval doesn’t use a turn, but the model call that follows does, so a run with maxTurns: 1 that resumes after an approval throws the SDK’s MaxTurnsExceededError on 0.20 and 0.21, where 0.19 completed it. The same run with maxTurns: 2 completes 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 Usage object, inputTokensDetails and outputTokensDetails are now records whose values are numbers or further records, so narrow each value to a number before you do arithmetic with it. The AgJSON usage this 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/agents 0.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/agents 0.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’s tool.done providerMetadata, beside toolSearchAgentName. 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_tokens and reasoning_tokens from a response’s input and output token details, and dropped every other key. The OpenAI client’s types (openai 7.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 one ext.openai.unparsed event 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’s null) now sets no usage counter, where 0.12.7 put that null in usage, 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-sdk 0.3.292;
  • @openai/agents 0.21.0;
  • @google/adk 2.2.1;
  • ai 7.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.