Wen-Tien Chang

This commit **enhances the documentation** by introducing a new example demonstrating the use of **local shell skills**. It specifically updates `docs/examples.md` to include a 'Local shell with local skills' entry, providing a practical guide for users. This is a **documentation update** that improves the discoverability and understanding of how to integrate local shell functionalities within the system.

This commit introduces **support for Gemini 3 Pro**, specifically handling its unique thought signatures, and significantly enhances **cross-model conversation compatibility**. It achieves this by **integrating provider-specific data handling** within the `litellm_model` and updating message conversion, streaming, and OpenAI API response processing to preserve and propagate this metadata. This **feature development** ensures that provider-specific details, like Gemini's thought signatures, are correctly managed across different model interactions and API conversions. Additionally, it includes **refactoring** to exclude provider-specific data from general transcripts and adds comprehensive **tests** to validate the new Gemini functionality and OpenAI API compatibility.

This commit **ensures compatibility with the OpenAI Chat Completions API** by explicitly setting the `content` field to `None` for assistant messages that contain tool calls. This **compatibility fix** primarily affects the **Chat Completions converter** within the `src/agents/models/chatcmpl_converter.py` module, specifically the `_get_current_assistant_message` function. By enforcing this explicit `content=None` for tool-call messages, the system prevents potential API parsing errors and ensures correct message formatting. A new test case has been added to `tests/test_openai_chatcompletions_converter.py` to verify this required behavior for API compliance.

This commit **fixes a bug** where **non-text tool outputs were not properly preserved** during message conversion, leading to potential data loss. The **LiteLLM model integration** (`litellm_model.py`) has been updated to explicitly request the preservation of all tool output content. Concurrently, the **chat completion message converter** (`chatcmpl_converter.py`) now accepts a new parameter to conditionally extract either all content or only text content from tool outputs. This enhancement ensures that **all types of tool output**, including structured data or other non-textual formats, are accurately retained and passed through the system, improving the fidelity of tool interactions.

This commit introduces a **new capability** to the **agent hook system** by defining and integrating the `AgentHookContext` class. This new context object, which extends `RunContextWrapper`, now includes the `turn_input`, making the original input available to both **agent start and end hooks**. The `AgentRunner` and `run_final_output_hooks` are updated to create and pass this enhanced context, allowing **custom agent hooks** to access crucial turn-level information for more sophisticated logic or logging. This change significantly improves the contextual awareness of the **`agents` module's lifecycle management** and is thoroughly tested.

This commit introduces a **new feature** to the **Agent Runner** that enables automatic `previous_response_id` chaining for internal calls on the first turn of an agent conversation. A new parameter, `auto_previous_response_id`, has been added to the `run` and `run_streamed` functions in `src/agents/run.py` to facilitate this. This enhancement streamlines **continuous conversation flow** by automating the linking of responses, improving the overall conversational experience for agents. Comprehensive tests have been added to verify this functionality, and the documentation in `docs/running_agents.md` has been updated to reflect its usage.

This commit provides a **bug fix** to prevent **streaming hangs** within the **agent execution path**. Specifically, it ensures that the event queue for streamed runs, managed by `_run_single_turn_streamed` in `src/agents/run.py`, is always marked complete in a `finally` block. This prevents the application from indefinitely waiting or hanging if an exception occurs during critical operations like `session.add_items` within a streamed turn. A new asynchronous test has been added to `tests/test_session.py` to verify that exceptions now propagate correctly without causing a hang, improving the robustness of **streamed agent interactions**.

This commit introduces a **bug fix** to the **`chatcmpl_stream_handler`** module, specifically within the `_handle_chunk` method in `src/agents/models/chatcmpl_stream_handler.py`. It **corrects the logic for processing streaming chat completion responses** to ensure that `usage` data from earlier stream chunks is properly preserved when subsequent chunks do not provide this information. This prevents potential data loss or inaccurate reporting of resource usage for streaming operations. A new test case has been added to `tests/test_reasoning_content.py` to validate the correct preservation of `usage` data across stream chunks.

This commit **clarifies documentation** for the `handoff()` and `realtime_handoff()` functions within the **`agents` module**. It specifically **removes the incorrect mention of callable support** for the `agent` parameter in the docstrings of `src/agents/handoffs/__init__.py` and `src/agents/realtime/handoffs.py`. This **documentation update** ensures that developers correctly understand that the `agent` parameter expects an agent object, not a function. The change **improves API clarity** and prevents potential confusion or misuse when integrating with these core agent handoff mechanisms.

This commit introduces a **bug fix** to the **agent tooling mechanism**, specifically addressing an issue where the `as_tool` decorator could return a blank string upon early tool termination. The `run_agent` method within `src/agents/agent.py` is modified to directly return `output.final_output`, ensuring consistent and meaningful output from agent tools. This change improves the **reliability and robustness of agent interactions** by preventing unexpected empty results. A corresponding **test update** in `tests/test_agent_as_tool.py` validates this corrected behavior.

This commit introduces a **new feature** by adding the `prompt_cache_retention` field to the **`ModelSettings`** configuration, allowing users to specify the prompt cache retention policy. This new setting is now passed to both **OpenAI Chat Completions** and **OpenAI Responses API requests** via the `_build_request` function, enabling more granular control over how prompts are handled by OpenAI models. The change impacts the core `ModelSettings` data structure and its integration with the OpenAI API. Serialization tests for `ModelSettings` have also been updated to ensure proper handling of this new configuration option.

This commit performs a crucial **dependency upgrade**, advancing the **`openai-python` library** to version 2.8.0 to enable support for newer OpenAI API capabilities, including "GPT 5.1". The `uv.lock` file was updated to reflect this new package version and its associated hashes. Concurrently, minor **style adjustments** were applied to `src/agents/models/openai_responses.py`, specifically updating type ignore comments within the `_convert_tool_choice_to_openai_format` method. These changes ensure the system's **tool calling functionality**, particularly for **web search and mcp tool choices**, remains robust and compatible with the updated OpenAI API.

This commit provides a **documentation clarification** for the **agent lifecycle hooks** `on_tool_start` and `on_tool_end`. The docstrings for these methods, located in `src/agents/lifecycle.py` within `RunHooksBase` and `AgentHooksBase`, have been updated. The primary purpose is to explicitly state that these hooks are intended for **local tools only**, improving developer understanding and preventing misapplication to remote tool interactions. This **documentation update** ensures clearer guidance for users implementing custom agent behaviors.

This commit **improves the robustness and backward compatibility** of **tool output processing** within the **`agents` module**. It introduces stricter validation for dictionary tool outputs, now requiring an explicit `type` field in `src/agents/items.py` before conversion to a structured `ToolOutput` object. Furthermore, Pydantic validators were added to `ToolOutputImage` and `ToolOutputFileContent` in `src/agents/tool.py` to ensure essential identifier fields are always present. This **maintenance and improvement** prevents ambiguous conversions and ensures consistent, reliable parsing of `ToolOutput` results, enhancing the overall stability of agent interactions.

This commit **fixes a bug** in the **`LitellmModel`** where the `tool_choice` parameter failed to be correctly applied when a specific function name was provided and streaming was enabled. It addresses issue #1846 by ensuring the `tool_choice` parameter is properly converted and applied within `src/agents/extensions/models/litellm_model.py` using the `OpenAIResponsesConverter`. This **bug fix** improves the reliability of **tool-use capabilities** for agents utilizing Litellm, ensuring correct function selection even when streaming responses.

This commit performs **maintenance cleanup** by **removing the unused example file** `ui.py` from the repository. This file was identified as dead code, likely a leftover from a previous demonstration or development phase, and no longer serves any active purpose within the project's **user interface components**. The removal helps to **reduce repository clutter** and improve code hygiene without impacting any active features or functionality.

This commit delivers a **bug fix** for the **Local shell tool**, enabling it to **correctly return tool output to the LLM**. The changes primarily affect the **agent's execution pipeline** within `src/agents/_run_impl.py`, where the integration of local shell call execution into the `_run_step` method and the output format for tool results have been corrected. This ensures that agents can now reliably receive and process the results of shell commands, significantly improving their interaction with the local environment. Additionally, new tests in `tests/test_local_shell_tool.py` were introduced to verify this corrected functionality.

This commit **fixes** an issue within the **`OpenAIConversationsSession` memory agent** where its `get_items` method was incorrectly including unset fields during the serialization of conversation items. The `get_items` method in `src/agents/memory/openai_conversations_session.py` has been modified to utilize `model_dump()` with the `exclude_unset=True` parameter. This **bug fix** ensures that only explicitly set fields are included in the serialized output, improving the **robustness and correctness of conversation data serialization** for downstream consumption and preventing potential data inconsistencies.

This commit **fixes a bug** in the **agent streaming mechanism** by correcting the emission order of `ReasoningItem` and `RawResponsesStreamEvent` events. The core change in `src/agents/run.py` **reorders the streaming of raw response events** and ensures `ReasoningItem` events are emitted immediately, providing a logical and accurate sequence of events to consumers. This **improves the reliability and interpretability of streamed agent outputs**, particularly for detailed reasoning steps. To validate this fix, the `FakeModel` was expanded to simulate a comprehensive event sequence, and new, rigorous **test cases** were added, including `test_complete_streaming_events`, to verify the exact order and types of all streaming events.

This commit **fixes a bug** in the **multi-turn conversation handling** within the `agents` module, specifically addressing an issue where redundant input items might be sent when `conversation_id` or `previous_response_id` were provided. A new `_ServerConversationTracker` is introduced in `src/agents/run.py` to manage server-side conversation state, ensuring that only *new* input items are transmitted during subsequent turns. This **bug fix** significantly improves the reliability and efficiency of **server-managed conversations** by preventing unnecessary data processing. The change is thoroughly validated with new test cases in `tests/test_agent_runner.py` and accompanied by updated documentation in `docs/running_agents.md` to guide users on proper multi-turn agent execution.