docs: update docs to reflect recent changes (#960)

Author: seratch

docs/src/content/docs/extensions/ai-sdk.mdx

@@ -35,7 +35,7 @@ Out of the box the Agents SDK works with OpenAI models through the Responses API
 
    ```typescript
    import { openai } from '@ai-sdk/openai';
-   import { aisdk } from '@openai/agents-extensions';
+   import { aisdk } from '@openai/agents-extensions/ai-sdk';
    ```
 
 4. Initialize an instance of the model to be used by the agent:
@@ -47,9 +47,9 @@ Out of the box the Agents SDK works with OpenAI models through the Responses API
 </Steps>
 
 <Aside type="caution">
-  We currently support ai-sdk's model provider v2 modules, which are compatible
-  with Vercel AI SDK v5. If you have a specific reason to continue using the v1
-  model providers, you can copy the module from
+  We support AI SDK providers that expose `specificationVersion` `v2` or `v3`.
+  If you have a specific reason to continue using the older v1 provider style,
+  you can copy the module from
   [examples/ai-sdk-v1](https://github.com/openai/openai-agents-js/tree/main/examples/ai-sdk-v1)
   and include it in your project.
 </Aside>

docs/src/content/docs/guides/mcp.mdx

@@ -206,6 +206,9 @@ await using mcpServers = await connectMcpServers(servers);
 For **Streamable HTTP** and **Stdio** servers, each time an `Agent` runs it may call `list_tools()` to discover available tools. Because that round‑trip can add latency—especially to remote servers—you can cache the results in memory by passing `cacheToolsList: true` to `MCPServerStdio` or `MCPServerStreamableHttp`.
 
 Only enable this if you're confident the tool list won't change. To invalidate the cache later, call `invalidateToolsCache()` on the server instance.
+If you are using shared MCP tool caching via `getAllMcpTools(...)`, you can also invalidate by server name with `invalidateServerToolsCache(serverName)`.
+
+For advanced cases, `getAllMcpTools({ generateMCPToolCacheKey })` lets you customize cache partitioning (for example, by server + agent + run context).
 
 ### Tool filtering
 

docs/src/content/docs/guides/sessions.mdx

@@ -46,6 +46,9 @@ Reusing the same session instance ensures the agent receives the full conversati
 | `organization`   | `string` | OpenAI organization ID for requests.                           |
 | `project`        | `string` | OpenAI project ID for requests.                                |
 
+If you need to pre-create a conversation ID before constructing the session, use
+`startOpenAIConversationsSession(client?)` and pass the returned ID as `conversationId`.
+
 ---
 
 ## How the runner uses sessions

docs/src/content/docs/guides/tools.mdx

@@ -49,19 +49,28 @@ for advanced options like `rankingOptions` or semantic filters.
 Local built-in tools run in your own environment and require you to supply implementations:
 
 - **Computer use** – implement the `Computer` interface and pass it to `computerTool()`.
-- **Shell** – implement the `Shell` interface and pass it to `shellTool()`.
+- **Shell** – either provide a local `Shell` implementation, or configure a hosted container environment.
 - **Apply patch** – implement the `Editor` interface and pass it to `applyPatchTool()`.
 
-These tools execute locally and are **not** hosted by OpenAI. Use them when you need direct access
-to files, terminals, or GUI automation in your runtime. The tool calls are still requested by the
-OpenAI model’s responses, but your application is expected to execute them locally.
+Computer and apply-patch tools execute locally and are **not** hosted by OpenAI. Shell tools can run
+locally or in hosted container environments, depending on `shellTool()` configuration.
+The tool calls are still requested by the model’s responses, but your application controls how those
+calls are executed.
 
 <Code
   lang="typescript"
   code={localBuiltInToolsExample}
   title="Local built-in tools"
 />
 
+For hosted shell environments, configure `shellTool({ environment })` with either:
+
+- `type: 'container_auto'` to create a managed container for the run (supports network policy, memory limit, and skills).
+- `type: 'container_reference'` to reuse an existing container by `containerId`.
+
+See `examples/tools/container-shell-skill-ref.ts` and `examples/tools/container-shell-inline-skill.ts`
+for end-to-end usage.
+
 ---
 
 ## 3. Function tools

docs/src/content/docs/guides/voice-agents/build.mdx

@@ -84,6 +84,9 @@ Hosted MCP tools can be configured with `hostedMcpTool` and are executed remotel
 
 While the tool is executing the agent will not be able to process new requests from the user. One way to improve the experience is by telling your agent to announce when it is about to execute a tool or say specific phrases to buy the agent some time to execute the tool.
 
+If a function tool should finish without immediately triggering another model response, return `backgroundResult(output)` from `@openai/agents/realtime`.
+This sends the tool output back to the session while leaving response triggering under your control.
+
 ### Accessing the conversation history
 
 Additionally to the arguments that the agent called a particular tool with, you can also access a snapshot of the current conversation history that is tracked by the Realtime Session. This can be useful if you need to perform a more complex action based on the current state of the conversation or are planning to use [tools for delegation](#delegation-through-tools).