v0.4.7

Key Changes

Hosted container tool + Skills

This release includes the hosted shell runtime tool along with its native skills support. Developers now can pass a container-based shell runtime with skills this way:

import { Agent } from '@openai/agents';

const agent = new Agent({
  name: 'Container Shell Agent',
  model: 'gpt-5.2',
  instructions: 'Use the available container to answer user requests.',
  tools: [
    shellTool({
      environment: {
        type: 'container_auto',
        skills: [{type: 'skill_reference', skillId: "skill_698bbe879adc81918725cbc69dcae7960bc5613dadaed377", version: "1"}],
      },
    }),
  ],
});

Check the following examples for more details:

• https://github.com/openai/openai-agents-js/blob/main/examples/tools/container-shell-inline-skill.ts
• https://github.com/openai/openai-agents-js/blob/main/examples/tools/container-shell-skill-ref.ts

References:

• Hosted shell: https://developers.openai.com/api/docs/guides/tools-shell#hosted-runtime-details
• Skills API: https://developers.openai.com/api/docs/guides/tools-skills
• Skills Cookbook: https://developers.openai.com/cookbook/examples/skills_in_api

What's Changed

• feat: support shell tool environment + skills by @seratch in #950
• fix(agents-extensions): #945 map AI SDK cacheRead usage to cached_tokens by @seratch in #946
• fix(agents-openai): omit named tool_choice when prompt supplies tools by @seratch in #951
• fix(agents-core): preserve legacy ShellTool typing and strict shell pending statuses by @seratch in #952

Documents & Other Changes

• docs: clarify Codex run-context threading guidance and examples by @seratch in #942
• docs: update translated document pages by @github-actions[bot] in #943
• chore: upgrade pnpm to 10.29.2 by @seratch in #948
• chore: update versions by @github-actions[bot] in #947

Full Changelog: v0.4.6...v0.4.7

v0.4.6

What's Changed

• feat(extensions): add codex run-context thread reuse and same-thread workflow by @seratch in #940
• chore(deps): bump @modelcontextprotocol/sdk from 1.25.2 to 1.26.0 in the npm_and_yarn group across 1 directory by @dependabot[bot] in #939

Documents & Other Changes

• chore: upgrade dev deps by @seratch in #936
• chore(skills): migrate repository skill paths to .agents/skills by @seratch in #935
• docs(guides): add missing option coverage across runner, mcp, sessions, and extensions by @seratch in #937
• docs: update translated document pages by @github-actions[bot] in #938
• chore: update versions by @github-actions[bot] in #941

Full Changelog: v0.4.5...v0.4.6

v0.4.5

What's Changed

• feat: #921 add structured input builders for agent tools by @seratch in #924
• feat: add MCP server errorFunction support by @seratch in #926
• feat: add MCP tool meta resolver support by @seratch in #919
• feat: #663 add computer tool approvals and run context arg by @seratch in #920
• feat: #763 add onSafetyCheck hook for computer safety checks by @seratch in #925
• feat(core,realtime): add configurable approval-rejection tool error messages by @seratch in #932
• fix: #932 consider traceIncludeSensitiveData option by @seratch in #933
• fix: populate streamed chat completion choices in generation traces by @seratch in #934
• fix: preserve zod descriptions in json schema output by @seratch in #923

Documents & Other Changes

• chore(deps): bump the github-actions group with 2 updates by @dependabot[bot] in #928
• chore(deps): bump fastify from 5.3.3 to 5.7.3 in the npm_and_yarn group across 1 directory by @dependabot[bot] in #931
• chore(deps): bump the npm_and_yarn group across 4 directories with 1 update by @dependabot[bot] in #918
• chore: update versions by @github-actions[bot] in #922

Full Changelog: v0.4.4...v0.4.5

v0.4.4

What's Changed

• fix: #680 resume nested agent tool approvals after interruptions by @seratch in #916

Documents & Other Changes

• chore(deps): bump hono from 4.11.4 to 4.11.7 in the npm_and_yarn group across 1 directory by @dependabot[bot] in #913
• chore: upgrade pnpm to 10.28.2 by @seratch in #915
• chore: update versions by @github-actions[bot] in #917

Full Changelog: v0.4.3...v0.4.4

v0.4.3

What's Changed

• fix(agents-core): #905 detach abort listeners after streaming completion by @seratch in #908

Documents and other changes

• docs: #901 connectMcpServers & MCPServers ops by @seratch in #902
• docs: update translated document pages by @github-actions[bot] in #903
• test: silence expected MCP server error logs by @seratch in #909
• test: fail on unexpected stdout/stderr in Vitest by @seratch in #911
• chore: upgrade GitHub Actions to latest versions by @salmanmkc in #904
• chore: update versions by @github-actions[bot] in #910

Full Changelog: v0.4.2...v0.4.3

v0.4.2

Key Changes

New utility for multiple MCP server management

Starting with this version, there is a new, convenient way to manage multiple MCP server instances. See #901 and examples/mcp/mcp-servers-example.ts

New import path for aisdk() from @openai/agents-extensions

If you've been using the @openai/agents-extensions package for aisdk() helper, we now recommend importing it from @openai/agents-extensions/ai-sdk. Both import paths still work for now, but the top-level import is deprecated and will be removed in v0.5.0.

AI SDK's useChat compatibility utility under @openai/agents-extensions/ai-sdk-ui

createAiSdkUiMessageStreamResponse from @openai/agents-extensions/ai-sdk-ui enables server routes in React/Next.js apps to stream data that can be consumed by useChat on the frontend. See #899 and examples/ai-sdk-ui.

What's Changed

• feat: add MCPServers lifecycle helper by @seratch in #901
• feat: add AI SDK data/text stream response adapters for streamed runs by @seratch in #899
• feat(agents-core): add maxTurns error handlers with runData snapshots by @seratch in #896, #900
• fix(agents-core): prefer run tracing config when resuming run state by @seratch in #895
• test(realtime,core,extensions): add coverage for approvals, tracing, MCP, and codex helpers by @seratch in #890

Documents & Other Changes

• chore(deps): bump the github-actions group with 2 updates by @dependabot[bot] in #889
• docs(sessions): add manual compaction guidance for streaming by @seratch in #892
• docs: update translated document pages by @github-actions[bot] in #893
• chore(deps): bump hono from 4.11.3 to 4.11.4 in the npm_and_yarn group across 1 directory by @dependabot[bot] in #898
• chore: update versions by @github-actions[bot] in #891

Full Changelog: v0.4.1...v0.4.2

v0.4.1

What's Changed

• fix(openai): keep compaction auto mode aligned with store=false by @seratch in #886
• fix(agents-core): handle invalid JSON in tool call arguments gracefully by @OlegHQ in #887
• fix: handle legacy fileId fallback and expand coverage by @seratch in #883

Documents & Others

• ci: add coverage job with thresholds by @seratch in #885
• ci: sync package labels and milestones after changeset validation by @seratch in #888
• chore(examples): update ai-sdk-v1 example deps by @seratch in #880
• docs: #860 dropping zod v3 support by @seratch in #861
• docs: update a few pages to include more details by @seratch in #881
• Update all translated document pages by @github-actions[bot] in #879
• Update translated document pages by @github-actions[bot] in #882
• chore: update versions by @github-actions[bot] in #884

Full Changelog: v0.4.0...v0.4.1

v0.4.0

Key Changes

Drop Zod v3 support and require Zod v4 for schema-based tools and outputs

Starting with this version, we have dropped support for Zod v3 and now require Zod v4 for schema-based tools and outputs. Please use zod@4 instead of zod@3. If you use this SDK in vanilla JavaScript and do not rely on the TypeScript compiler, the SDK will still work with the Zod v3 runtime.

Make @ai-sdk/provider an optional peer dependency to support v2 and v3 formats

The @ai-sdk/provider dependency was previously a required dependency of the openai/agents-extensions package, but it is now an optional peer dependency. This breaking change is primarily intended to support both v2 and v3 formats. In addition, changing how the dependency is loaded allows developers to use the latest major version without waiting for this SDK to migrate.

Update gpt-5.1/5.2 defaults and reasoning effort types

This change is more minor than the two above. We updated the default reasoning effort for gpt-5.1 and gpt-5.2 to "none". When you use gpt-5.1 or gpt-5.2, the default reasoning effort is now "none", which is better suited for interactive agent apps. If you intentionally relied on "low" effort (the default in v0.3), please explicitly pass your own ModelSettings with reasoning.effort="low".

What's Changed

• feat: #561 Drop Zod v3 support and require Zod v4 for schema-based tools and outputs by @seratch in #860
• chore: #868 make @ai-sdk/provider an optional peer dependency to support v2 and v3 formats by @seratch in #872
• feat(agents-core): update gpt-5.1/5.2 defaults and reasoning effort types by @seratch in #876

Documents & Others

• docs: experimental codex tool document by @seratch in #870
• docs: update a few document pages by @seratch in #874
• Update all translated document pages by @github-actions[bot] in #875
• Update all translated document pages by @github-actions[bot] in #877
• Update all translated document pages by @github-actions[bot] in #871
• ci: optimize doc translation workflow by @seratch in #873
• chore: update versions by @github-actions[bot] in #869

Full Changelog: v0.3.9...v0.4.0

v0.3.9

What's Changed

• feat: Add experimental codex tool module by @seratch in #867
• fix(agents-core): #670 set subclass error names by @seratch in #862

Experimental: Codex Tool Support

Starting with this version, we have added a new experimental Codex extension (@openai/agents-extensions/experimental/codex). This extension allows you to use Codex as a tool within your agents. Since this module is still experimental, its behavior and implementation details may change in future releases.

If you run an agent with codexTool() on a host where Codex is installed, the agent will use Codex as a tool to answer the question. The tool simply runs the Codex CLI as a subprocess, so all existing Codex configuration, skills, and capabilities are available without any additional setup.

See the example code and #862 for more details.

Documents & Others

• docs: add docs-sync skill guidance by @seratch in #857
• docs: align agent guides after $docs-sync audit by @seratch in #858
• ci: fix changeset milestone selection for patch bumps by @seratch in #863
• ci: Add pnpm-upgrade skill and automated job by @seratch in #865
• chore(deps): bump the npm_and_yarn group across 0 directory with 3 updates by @dependabot[bot] in #866
• Update all translated document pages by @github-actions[bot] in #859
• chore: update versions by @github-actions[bot] in #864

Full Changelog: v0.3.8...v0.3.9

v0.3.8

What's Changed

• fix: stabilize run resumption and tool execution pipeline by @seratch in #827
• feat: Add tool input/output guardrails to TS SDK by @seratch in #812
• feat: Add per-run tracing API key support by @seratch in #813
• feat: Add ai-sdk v3 support and improve other provider compatibility; fix #770 #791 by @seratch in #814
• feat: #794 Expose ToolInputParameters and ToolOptions from the top-level exports so wrappers can import the tool types by @seratch in #795
• fix: opt-in run state enhancement for #813 by @seratch in #834
• fix: Skip response_format when "text" in Chat Completions calls by @seratch in #835
• fix: #709 Share tracing context across runtimes to prevent Deno + ai-sdk context loss by @seratch in #828
• fix: #799 Expose raw input and validation error in tool parsing failures by @shrirajh in #800
• fix: Fix #809 chat completions tool calls when content is present by @seratch in #817
• fix(realtime): #820 null values for noise_reduction / transcription / turn_detection are ignored by @seratch in #822
• fix: #816 preserve falsy turn detection config values by @seratch in #819
• fix: sanitize conversation items for non-OpenAI models in HITL flow by @seratch in #845
• fix: whitelist realtime session tool payload to documented fields by @seratch in #849
• fix(agents-extensions): #802 handle object based token usage in ai-sdk wrapper by @ArpitMishra17 in #805
• fix: Fix streaming cancellation to abort promptly and resolve completion on cancel by @seratch in #818
• fix: Add content: null when having tool calls for Chat Completions by @seratch in #815
• fix: terminate streamable HTTP MCP sessions safely with typed guard by @seratch in #837
• refactor: #275 simplify streaming state by removing unused index tracking by @nexo-tech in #841
• fix: #829 Ensure generated declarations are type-checked and expose PreparedInputWithSessionResult by @seratch in #830
• chore(deps): bump @modelcontextprotocol/sdk from 1.24.0 to 1.25.1 in the npm_and_yarn group across 1 directory by @dependabot[bot] in #811
• chore(deps): bump @modelcontextprotocol/sdk from 1.25.1 to 1.25.2 in the npm_and_yarn group across 1 directory by @dependabot[bot] in #821

Documents

• docs: #804 improve the retry document section to be accurate by @seratch in #823
• Update all translated document pages by @github-actions[bot] in #824
• Improve guardrail tripwire logic in examples by @RajKKapadia in #803
• feat(examples): add HITL session scenario coverage with rehydration and rejections by @seratch in #842

Misc

• Upgrade pnpm to the latest patch version and dev deps as well by @seratch in #797
• chore(deps): bump the npm_and_yarn group across 3 directories with 1 update by @dependabot[bot] in #798
• Upgrade pnpm to 10.27.0; dev/docs dependencies too by @seratch in #810
• misc: Add verify-changes skill for project maintainers by @seratch in #826
• Add regression tests covering agent scenarios by @seratch in #832
• Add example runner script by @seratch in #833
• chore: Rename verify-changes and tweak its behavior, add MCP server skills by @seratch in #836
• docs: clarify completion report guidance in AGENTS.md by @seratch in #838
• docs: add pr-draft-summary skill instructions by @seratch in #839
• feat: expand example runner filtering and refresh sample images by @seratch in #840
• docs: move exec plan guide to repo root by @seratch in #846
• feat: add examples auto-run helper and refresh example workflows by @seratch in #848
• Upgrade pnpm, dev, and docs deps by @seratch in #850
• misc: add integration-tests skill guide by @seratch in #851
• Add two more agent skills by @seratch in #852
• Add unit tests using $test-coverage-improver by @seratch in #853
• ci: add Codex changeset validation workflow by @seratch in #854
• ci: add release PR review automation by @seratch in #856
• chore: update versions by @github-actions[bot] in #796

New Contributors

• @shrirajh made their first contribution in #800
• @RajKKapadia made their first contribution in #803
• @ArpitMishra17 made their first contribution in #805
• @nexo-tech made their first contribution in #841

Full Changelog: v0.3.7...v0.3.8