…into feat/draw_graph

…into feat/draw_graph

…ions

Run the tests with `coverage`, and make sure the min coverage is 95%.

As titled. Test plan: unit tests/docs.

## Context
By default, the outputs of tools are sent to the LLM again. The LLM gets
to read the outputs, and produce a new response. There are cases where
this is not desired:
1. Every tool results in another round trip, and sometimes the output of
the tool is enough.
2. If you force tool use (via model settings `tool_choice=required`),
then the agent will just infinite loop.

This enables you to have different behavior, e.g. use the first tool
output as the final output, or write a custom function to process tool
results and potentially produce an output.

## Test plan
Added new tests and ran existing tests
Also added examples.


Closes #117

Fix for #574 

@rm-openai I'm not sure how to add a test within the repo but I have
pasted a test script below that seems to work

```python
import asyncio
from openai.types.responses import ResponseTextDeltaEvent
from agents import Agent, Runner

async def main():
    agent = Agent(
        name="Joker",
        instructions="You are a helpful assistant.",
    )

    result = Runner.run_streamed(agent, input="Please tell me 5 jokes.")
    num_visible_event = 0
    async for event in result.stream_events():
        if event.type == "raw_response_event" and isinstance(event.data, ResponseTextDeltaEvent):
            print(event.data.delta, end="", flush=True)
            num_visible_event += 1
            print(num_visible_event)
            if num_visible_event == 3:
                result.cancel()


if __name__ == "__main__":
    asyncio.run(main())
````

Now that `ModelSettings` has `Reasoning`, a non-primitive object,
`dataclasses.as_dict()` wont work. It will raise an error when you try
to serialize (e.g. for tracing). This ensures the object is actually
serializable.

Per
https://modelcontextprotocol.io/specification/draft/basic/lifecycle#timeouts

"Implementations SHOULD establish timeouts for all sent requests, to
prevent hung connections and resource exhaustion. When the request has
not received a success or error response within the timeout period, the
sender SHOULD issue a cancellation notification for that request and
stop waiting for a response.

SDKs and other middleware SHOULD allow these timeouts to be configured
on a per-request basis."

I picked 5 seconds since that's the default for SSE

In response to issue #587 , I implemented a solution to first check if
`refusal` and `usage` attributes exist in the `delta` object.

I added a unit test similar to `test_openai_chatcompletions_stream.py`.

Let me know if I should change something.

---------

Co-authored-by: Rohan Mehta <[email protected]>

When using the voice agent in typed code, it is suboptimal and error
prone to type the TTS voice variables in your code independently.

With this commit we are making the type exportable so that developers
can just use that and be future-proof.

Example of usage in code:

```
DEFAULT_TTS_VOICE: TTSModelSettings.TTSVoice = "alloy"

...

tts_voice: TTSModelSettings.TTSVoice = DEFAULT_TTS_VOICE 

...

output = await VoicePipeline(
  workflow=workflow,
  config=VoicePipelineConfig(
  tts_settings=TTSModelSettings(
    buffer_size=512,
    transform_data=transform_data,
    voice=tts_voice,
    instructions=tts_instructions,
  ))
).run(audio_input)
```

---------

Co-authored-by: Rohan Mehta <[email protected]>

Hi Team! 

This PR adds FutureAGI to the tracing documentation as one of the
automatic tracing processors for OpenAI agents SDK.


![image](https://github.com/user-attachments/assets/4de3aadc-5efa-4712-8b02-decdedf8f8ef)

Addresses #614

When an input image is given as input, the code tries to access the
'detail' key, that may not be present as noted in #159.

With this pull request, now it tries to access the key, otherwise set
the value to `None`.
@pakrym-oai  or @rm-openai let me know if you want any changes.

**Purpose**  
Allow arbitrary `extra_body` parameters (e.g. `cached_content`) to be
forwarded into the LiteLLM call. Useful for context caching in Gemini
models
([docs](https://ai.google.dev/gemini-api/docs/caching?lang=python)).

**Example usage**  
```python
import os
from agents import Agent, ModelSettings
from agents.extensions.models.litellm_model import LitellmModel

cache_name = "cachedContents/34jopukfx5di"  # previously stored context

gemini_model = LitellmModel(
    model="gemini/gemini-1.5-flash-002",
    api_key=os.getenv("GOOGLE_API_KEY")
)

agent = Agent(
    name="Cached Gemini Agent",
    model=gemini_model,
    model_settings=ModelSettings(
        extra_body={"cached_content": cache_name}
    )
)

Added missing word "be" in prompt instructions.

This is unlikely to change the agent functionality in most cases, but
optimal clarity in prompt language is a best practice.

Co-authored-by: aagarwal25 <[email protected]>

Adding an AGENTS.md file for Codex use

Added the `instructions` attribute to the MCP servers to solve #704 .

Let me know if you want to add an example to the documentation.

PR to enhance the `Usage` object and related logic, to support more
granular token accounting, matching the details available in the [OpenAI
Responses API](https://platform.openai.com/docs/api-reference/responses)
. Specifically, it:

- Adds `input_tokens_details` and `output_tokens_details` fields to the
`Usage` dataclass, storing detailed token breakdowns (e.g.,
`cached_tokens`, `reasoning_tokens`).
- Flows this change through
- Updates and extends tests to match
- Adds a test for the Usage.add method

### Motivation
- Aligns the SDK’s usage with the latest OpenAI responses API Usage
object
- Supports downstream use cases that require fine-grained token usage
data (e.g., billing, analytics, optimization) requested by startups

---------

Co-authored-by: Wulfie Bain <[email protected]>

---
[//]: # (BEGIN SAPLING FOOTER)
* #732
* #731
* __->__ #730

---
[//]: # (BEGIN SAPLING FOOTER)
* #732
* __->__ #731

…732)

Fix for #734

## Summary
- avoid infinite recursion in visualization by tracking visited agents
- test cycle detection in graph utility

## Testing
- `make mypy`
- `make tests` 

Resolves #668

## Summary
- mention MCPServerStreamableHttp in MCP server docs
- document CodeInterpreterTool, HostedMCPTool, ImageGenerationTool and
LocalShellTool
- update Japanese translations

## Summary
- avoid AttributeError when Gemini API returns `None` for chat message
- return empty output if message is filtered
- add regression test

## Testing
- `make format`
- `make lint`
- `make mypy`
- `make tests`

Towards #744