flowchart TB
    subgraph "Models 模块"
        MODELINTERFACE[Model 接口]
        MODELPROVIDER[ModelProvider 接口]
        
        subgraph "抽象层"
            MODELTRACING[ModelTracing 枚举]
            MODELSETTINGS[ModelSettings 配置]
        end
        
        subgraph "OpenAI 提供商"
            OPENAIPROVIDER[OpenAIProvider]
            OPENAIRESPONSES[OpenAIResponsesModel]
            OPENAICHAT[OpenAIChatCompletionsModel]
            SHAREDCLIENT[共享HTTP客户端]
        end
        
        subgraph "多提供商支持"
            MULTIPROVIDER[MultiProvider]
            MULTIPROVIDERMAP[MultiProviderMap]
            LITELLMPROVIDER[LiteLLMProvider]
        end
        
        subgraph "默认模型管理"
            DEFAULTMODELS[get_default_model]
            MODELREGISTERY[模型注册表]
        end
        
        subgraph "协议转换"
            CHATCMPLCONVERTER[ChatCompletions转换器]
            RESPONSESCONVERTER[Responses转换器]
            STREAMHANDLER[流式处理器]
        end
    end
    
    subgraph "外部依赖"
        OPENAI[openai 客户端]
        HTTPX[httpx HTTP客户端]
        LITELLM[litellm 多模型代理]
        ITEMS[items 数据类型]
        TRACING[tracing 追踪系统]
    end
    
    MODELINTERFACE --> MODELPROVIDER
    MODELINTERFACE --> MODELTRACING
    
    MODELPROVIDER --> OPENAIPROVIDER
    MODELPROVIDER --> MULTIPROVIDER
    
    OPENAIPROVIDER --> OPENAIRESPONSES
    OPENAIPROVIDER --> OPENAICHAT
    OPENAIPROVIDER --> SHAREDCLIENT
    
    MULTIPROVIDER --> MULTIPROVIDERMAP
    MULTIPROVIDER --> OPENAIPROVIDER
    MULTIPROVIDER --> LITELLMPROVIDER
    
    OPENAIRESPONSES --> RESPONSESCONVERTER
    OPENAICHAT --> CHATCMPLCONVERTER
    OPENAIRESPONSES --> STREAMHANDLER
    OPENAICHAT --> STREAMHANDLER
    
    OPENAIPROVIDER --> DEFAULTMODELS
    MULTIPROVIDER --> MODELREGISTERY
    
    OPENAIRESPONSES --> OPENAI
    OPENAICHAT --> OPENAI
    SHAREDCLIENT --> HTTPX
    LITELLMPROVIDER --> LITELLM
    
    MODELINTERFACE --> ITEMS
    OPENAIRESPONSES --> TRACING
    OPENAICHAT --> TRACING
    
    style MODELINTERFACE fill:#e1f5fe
    style OPENAIPROVIDER fill:#f3e5f5
    style MULTIPROVIDER fill:#e8f5e8
    style DEFAULTMODELS fill:#fff3e0

class MultiProvider(ModelProvider):
    """多提供商路由的核心实现"""
    
    def _get_prefix_and_model_name(self, model_name: str | None) -> tuple[str | None, str | None]:
        """解析模型名称，提取提供商前缀和模型名"""
        if model_name is None:
            return None, None
        
        # 检查是否包含提供商前缀
        if "/" in model_name:
            prefix, name = model_name.split("/", 1)
            return prefix, name
        else:
            # 无前缀时默认使用 OpenAI
            return None, model_name
    
    def get_model(self, model_name: str | None) -> Model:
        """根据模型名称路由到合适的提供商"""
        prefix, actual_model_name = self._get_prefix_and_model_name(model_name)
        
        if prefix is None:
            # 默认使用 OpenAI 提供商
            return self.openai_provider.get_model(actual_model_name)
        
        # 检查自定义提供商映射
        if self.provider_map and self.provider_map.has_prefix(prefix):
            provider = self.provider_map.get_provider(prefix)
            return provider.get_model(actual_model_name)
        
        # 检查回退提供商
        if prefix in self._fallback_providers:
            provider = self._fallback_providers[prefix]
            return provider.get_model(actual_model_name)
        
        # 处理内置前缀
        if prefix == "openai":
            return self.openai_provider.get_model(actual_model_name)
        elif prefix == "litellm":
            return self._get_litellm_provider().get_model(actual_model_name)
        
        raise UserError(f"Unknown model provider: {prefix}")

_http_client: httpx.AsyncClient | None = None

def shared_http_client() -> httpx.AsyncClient:
    """全局共享HTTP客户端的单例实现"""
    global _http_client
    if _http_client is None:
        _http_client = DefaultAsyncHttpxClient(
            # 优化配置
            limits=httpx.Limits(
                max_keepalive_connections=100,  # 保持连接数
                max_connections=200,            # 最大连接数
                keepalive_expiry=30.0          # 连接保持时间
            ),
            timeout=httpx.Timeout(
                connect=10.0,    # 连接超时
                read=60.0,       # 读取超时
                write=10.0,      # 写入超时
                pool=5.0         # 连接池超时
            )
        )
    return _http_client

class OpenAIProvider(ModelProvider):
    """OpenAI提供商的连接管理"""
    
    def _get_client(self) -> AsyncOpenAI:
        """延迟加载和复用客户端实例"""
        if self._client is None:
            self._client = AsyncOpenAI(
                api_key=self._get_api_key(),
                base_url=self._stored_base_url,
                organization=self._stored_organization,
                project=self._stored_project,
                http_client=shared_http_client(),  # 使用共享客户端
            )
        return self._client

class OpenAIResponsesModel(Model):
    """OpenAI Responses API的流式处理"""
    
    def stream_response(
        self,
        system_instructions: str | None,
        input: str | list[TResponseInputItem],
        model_settings: ModelSettings,
        tools: list[Tool],
        output_schema: AgentOutputSchemaBase | None,
        handoffs: list[Handoff],
        tracing: ModelTracing,
        **kwargs
    ) -> AsyncIterator[TResponseStreamEvent]:
        """流式响应处理的核心实现"""
        
        async def _stream_generator():
            # 1) 构建请求参数
            request_data = self._build_request_data(
                system_instructions, input, model_settings,
                tools, output_schema, handoffs, **kwargs
            )
            
            # 2) 创建流式请求
            stream = await self._client.responses.create(
                **request_data,
                stream=True
            )
            
            # 3) 处理流式事件
            try:
                async for event in stream:
                    # 追踪记录
                    if tracing.include_data():
                        self._record_stream_event(event)
                    
                    # 事件转换和过滤
                    processed_event = self._process_stream_event(event)
                    if processed_event:
                        yield processed_event
                        
            except Exception as e:
                # 流式处理异常恢复
                logger.error(f"Stream processing error: {e}")
                yield self._create_error_event(e)
            finally:
                # 清理资源
                await stream.aclose()
        
        return _stream_generator()
    
    def _process_stream_event(self, raw_event) -> TResponseStreamEvent | None:
        """流式事件的处理和转换"""
        if raw_event.type == "response.output_item.added":
            # 输出项添加事件
            return self._convert_output_item_event(raw_event)
        elif raw_event.type == "response.content_part.added":
            # 内容片段添加事件  
            return self._convert_content_part_event(raw_event)
        elif raw_event.type == "response.done":
            # 响应完成事件
            return self._convert_completion_event(raw_event)
        else:
            # 跳过未知事件类型
            return None

class ChatCompletionsConverter:
    """Chat Completions API到统一格式的转换器"""
    
    @staticmethod
    def convert_to_model_response(
        chat_completion: ChatCompletion,
        tools: list[Tool],
        handoffs: list[Handoff]
    ) -> ModelResponse:
        """将ChatCompletion转换为统一的ModelResponse格式"""
        
        # 1) 提取基础信息
        choice = chat_completion.choices[0]
        message = choice.message
        
        # 2) 处理工具调用
        output_items = []
        if message.tool_calls:
            for tool_call in message.tool_calls:
                if tool_call.type == "function":
                    # 函数工具调用
                    output_item = ToolCallOutputItem(
                        tool_name=tool_call.function.name,
                        tool_call_id=tool_call.id,
                        input=tool_call.function.arguments
                    )
                    output_items.append(output_item)
        
        # 3) 处理文本输出
        if message.content:
            text_item = MessageOutputItem(
                content=message.content,
                role="assistant"
            )
            output_items.append(text_item)
        
        # 4) 处理使用统计
        usage_stats = None
        if chat_completion.usage:
            usage_stats = Usage(
                input_tokens=chat_completion.usage.prompt_tokens,
                output_tokens=chat_completion.usage.completion_tokens,
                total_tokens=chat_completion.usage.total_tokens
            )
        
        # 5) 构建统一响应
        return ModelResponse(
            output=output_items,
            usage=usage_stats,
            response_id=chat_completion.id,
            model=chat_completion.model,
            created_at=chat_completion.created
        )

classDiagram
    class Model {
        <<Interface>>
        +get_response(instructions, input, settings, ...) ModelResponse
        +stream_response(instructions, input, settings, ...) AsyncIterator[TResponseStreamEvent]
    }
    
    class ModelProvider {
        <<Interface>>
        +get_model(model_name) Model
    }
    
    class ModelTracing {
        <<Enumeration>>
        DISABLED
        ENABLED
        ENABLED_WITHOUT_DATA
        +is_disabled() bool
        +include_data() bool
    }
    
    class OpenAIProvider {
        -AsyncOpenAI _client
        -str _stored_api_key
        -str _stored_base_url
        -bool _use_responses
        
        +__init__(api_key?, base_url?, client?, ...)
        +get_model(model_name) Model
        -_get_client() AsyncOpenAI
    }
    
    class MultiProvider {
        +MultiProviderMap provider_map
        +OpenAIProvider openai_provider
        -dict[str, ModelProvider] _fallback_providers
        
        +__init__(provider_map?, openai_*, ...)
        +get_model(model_name) Model
        -_get_prefix_and_model_name(name) tuple[str?, str?]
        -_get_litellm_provider() ModelProvider
    }
    
    class MultiProviderMap {
        -dict[str, ModelProvider] _mapping
        
        +has_prefix(prefix) bool
        +get_provider(prefix) ModelProvider?
        +add_provider(prefix, provider) void
        +remove_provider(prefix) void
        +get_mapping() dict[str, ModelProvider]
        +set_mapping(mapping) void
    }
    
    class OpenAIResponsesModel {
        -AsyncOpenAI _client
        -str _model_name
        
        +get_response(...) ModelResponse
        +stream_response(...) AsyncIterator[TResponseStreamEvent]
        -_build_request_data(...) dict
        -_process_stream_event(event) TResponseStreamEvent?
    }
    
    class OpenAIChatCompletionsModel {
        -AsyncOpenAI _client
        -str _model_name
        
        +get_response(...) ModelResponse
        +stream_response(...) AsyncIterator[TResponseStreamEvent]
        -_convert_to_responses_format(...) dict
        -_convert_from_chat_completion(...) ModelResponse
    }
    
    class LiteLLMProvider {
        +get_model(model_name) Model
        -_create_litellm_model(name) Model
    }
    
    Model <|.. OpenAIResponsesModel : implements
    Model <|.. OpenAIChatCompletionsModel : implements
    
    ModelProvider <|.. OpenAIProvider : implements
    ModelProvider <|.. MultiProvider : implements
    ModelProvider <|.. LiteLLMProvider : implements
    
    MultiProvider --> MultiProviderMap : uses
    MultiProvider --> OpenAIProvider : contains
    MultiProvider --> LiteLLMProvider : creates
    
    OpenAIProvider --> OpenAIResponsesModel : creates
    OpenAIProvider --> OpenAIChatCompletionsModel : creates
    
    OpenAIResponsesModel --> ModelTracing : uses
    OpenAIChatCompletionsModel --> ModelTracing : uses
    
    note for Model "统一的模型调用接口\n支持同步和流式响应"
    note for MultiProvider "前缀路由的多提供商管理\n支持动态提供商注册"
    note for OpenAIProvider "OpenAI官方API集成\n支持Responses和Chat Completions"

sequenceDiagram
    autonumber
    participant App as 应用
    participant Multi as MultiProvider
    participant Map as MultiProviderMap
    participant OpenAI as OpenAIProvider
    participant Model as OpenAIResponsesModel
    participant Client as AsyncOpenAI
    
    App->>Multi: get_model("openai/gpt-4o")
    Multi->>Multi: _get_prefix_and_model_name("openai/gpt-4o")
    Multi->>Multi: 解析得到 prefix="openai", name="gpt-4o"
    
    Multi->>Map: has_prefix("openai")
    Map-->>Multi: False (不在自定义映射中)
    
    Multi->>Multi: 检查内置前缀 "openai"
    Multi->>OpenAI: get_model("gpt-4o")
    
    OpenAI->>OpenAI: _get_client()
    OpenAI->>Client: 创建或复用AsyncOpenAI客户端
    Client-->>OpenAI: 客户端实例
    
    OpenAI->>Model: 创建OpenAIResponsesModel("gpt-4o", client)
    Model-->>OpenAI: 模型实例
    OpenAI-->>Multi: 返回模型
    Multi-->>App: 返回配置好的模型

sequenceDiagram
    autonumber
    participant Runner as 执行引擎
    participant Model as OpenAIResponsesModel
    participant Client as AsyncOpenAI
    participant Stream as 流式响应
    participant Tracing as 追踪系统
    
    Runner->>Model: stream_response(instructions, input, settings, ...)
    Model->>Model: _build_request_data() 构建请求
    
    Model->>Client: responses.create(stream=True)
    Client->>Stream: 建立流式连接
    Stream-->>Client: 流式响应对象
    Client-->>Model: stream对象
    
    loop 处理流式事件
        Stream->>Model: 流式事件 (response.content_part.added)
        Model->>Model: _process_stream_event() 处理事件
        
        alt 追踪启用
            Model->>Tracing: 记录流式事件
            Tracing-->>Model: 记录完成
        end
        
        Model->>Model: 转换为统一格式
        Model-->>Runner: yield 处理后的事件
        Runner->>Runner: 处理增量内容
    end
    
    Stream->>Model: 流式完成事件 (response.done)
    Model->>Model: _convert_completion_event()
    Model-->>Runner: yield 完成事件
    
    Model->>Stream: aclose() 关闭流
    Stream-->>Model: 资源释放完成

sequenceDiagram
    autonumber
    participant Runner as 执行引擎
    participant ChatModel as OpenAIChatCompletionsModel  
    participant Converter as ChatCompletionsConverter
    participant Client as AsyncOpenAI
    participant Tracing as 追踪系统
    
    Runner->>ChatModel: get_response(instructions, input, settings, ...)
    ChatModel->>ChatModel: _convert_to_chat_format() 转换输入格式
    
    ChatModel->>Client: chat.completions.create(messages, tools, ...)
    Client-->>ChatModel: ChatCompletion响应
    
    ChatModel->>Tracing: 记录模型调用
    Tracing-->>ChatModel: 记录完成
    
    ChatModel->>Converter: convert_to_model_response(chat_completion, tools, handoffs)
    
    Converter->>Converter: 提取基础信息 (choice, message)
    Converter->>Converter: 处理工具调用 (tool_calls)
    Converter->>Converter: 处理文本输出 (content)  
    Converter->>Converter: 处理使用统计 (usage)
    Converter->>Converter: 构建统一响应格式
    
    Converter-->>ChatModel: ModelResponse
    ChatModel-->>Runner: 统一格式的响应

from agents import Agent, Runner
from agents.models import MultiProvider, MultiProviderMap
from agents.extensions.models import LiteLLMProvider

async def multi_provider_setup():
    """多提供商配置的最佳实践"""
    
    # 1. 创建自定义提供商映射
    provider_map = MultiProviderMap()
    
    # 2. 添加LiteLLM提供商支持更多模型
    litellm_provider = LiteLLMProvider()
    provider_map.add_provider("litellm", litellm_provider)
    
    # 3. 添加自定义模型提供商
    custom_provider = CustomModelProvider(api_endpoint="https://api.custom.com")
    provider_map.add_provider("custom", custom_provider)
    
    # 4. 创建多提供商实例
    multi_provider = MultiProvider(
        provider_map=provider_map,
        openai_api_key="your-openai-key",
        openai_use_responses=True  # 优先使用Responses API
    )
    
    # 5. 创建使用不同模型的代理
    agents = {
        "openai": Agent(
            name="OpenAIAgent",
            model="gpt-4o",  # 默认使用OpenAI
            instructions="使用OpenAI GPT-4o模型"
        ),
        "claude": Agent(
            name="ClaudeAgent",
            model="litellm/anthropic/claude-3-sonnet",
            instructions="使用Anthropic Claude模型"
        ),
        "custom": Agent(
            name="CustomAgent",
            model="custom/my-model-v1",
            instructions="使用自定义模型"
        )
    }
    
    # 6. 使用全局配置
    from agents.run import RunConfig
    run_config = RunConfig(model_provider=multi_provider)
    
    # 7. 执行不同模型的对话
    for name, agent in agents.items():
        try:
            result = await Runner.run(
                agent,
                f"介绍一下你使用的模型特点",
                run_config=run_config
            )
            print(f"{name}: {result.final_output}\n")
        except Exception as e:
            print(f"{name} 调用失败: {e}")

asyncio.run(multi_provider_setup())

import httpx
from openai import AsyncOpenAI
from agents.models import OpenAIProvider

def create_optimized_provider():
    """创建性能优化的模型提供商"""
    
    # 1. 自定义HTTP客户端配置
    http_client = httpx.AsyncClient(
        limits=httpx.Limits(
            max_keepalive_connections=50,   # 保持连接数
            max_connections=100,            # 最大连接数
            keepalive_expiry=60.0          # 连接保持时间
        ),
        timeout=httpx.Timeout(
            connect=5.0,     # 连接超时
            read=30.0,       # 读取超时
            write=5.0,       # 写入超时
            pool=2.0         # 连接池超时
        ),
        http2=True,         # 启用HTTP/2
        retries=3           # 自动重试
    )
    
    # 2. 创建优化的OpenAI客户端
    openai_client = AsyncOpenAI(
        api_key="your-api-key",
        http_client=http_client,
        max_retries=3,
        timeout=30.0
    )
    
    # 3. 创建提供商实例
    provider = OpenAIProvider(
        openai_client=openai_client,
        use_responses=True  # 使用更高效的Responses API
    )
    
    return provider

# 使用优化后的提供商
optimized_provider = create_optimized_provider()

from agents import Agent, Runner

async def streaming_response_example():
    """流式响应处理的最佳实践"""
    
    agent = Agent(
        name="StreamingAgent",
        instructions="详细解释复杂概念，分步骤回答",
        model="gpt-4o"
    )
    
    # 1. 启动流式执行
    result = Runner.run_streamed(
        agent,
        "详细解释机器学习的工作原理，包括训练和推理过程"
    )
    
    # 2. 实时处理流式事件
    accumulated_content = ""
    
    try:
        async for event in result.stream_events():
            if event.type == "run_item":
                item = event.data.item
                
                if item.type == "message_output":
                    # 处理消息输出事件
                    new_content = item.content
                    if new_content not in accumulated_content:
                        delta = new_content[len(accumulated_content):]
                        print(delta, end="", flush=True)
                        accumulated_content = new_content
                
                elif item.type == "tool_call":
                    # 处理工具调用事件
                    print(f"\n[工具调用: {item.tool_name}]")
                
                elif item.type == "tool_call_output":
                    # 处理工具输出事件
                    print(f"[工具结果: {item.output[:100]}...]")
            
            elif event.type == "raw_responses":
                # 处理原始响应事件（用于调试）
                response_count = len(event.data.responses)
                print(f"[收到 {response_count} 个原始响应]")
        
        print(f"\n\n最终结果: {result.final_output}")
        
    except Exception as e:
        print(f"流式处理错误: {e}")
        # 仍然可以获取部分结果
        if hasattr(result, 'final_output'):
            print(f"部分结果: {result.final_output}")

asyncio.run(streaming_response_example())

from agents.models import Model, ModelProvider
from agents.items import ModelResponse, TResponseInputItem

class CustomModel(Model):
    """自定义模型实现示例"""
    
    def __init__(self, model_name: str, api_endpoint: str, api_key: str):
        self.model_name = model_name
        self.api_endpoint = api_endpoint
        self.api_key = api_key
        self._client = httpx.AsyncClient()
    
    async def get_response(
        self,
        system_instructions: str | None,
        input: str | list[TResponseInputItem],
        model_settings,
        tools,
        output_schema,
        handoffs,
        tracing,
        **kwargs
    ) -> ModelResponse:
        """自定义模型调用实现"""
        
        # 1. 构建请求
        request_data = {
            "model": self.model_name,
            "messages": self._convert_input_to_messages(system_instructions, input),
            "temperature": model_settings.temperature,
            "max_tokens": model_settings.max_tokens,
        }
        
        # 2. 调用自定义API
        response = await self._client.post(
            f"{self.api_endpoint}/chat/completions",
            json=request_data,
            headers={"Authorization": f"Bearer {self.api_key}"}
        )
        response.raise_for_status()
        
        # 3. 转换响应格式
        api_response = response.json()
        return self._convert_to_model_response(api_response)
    
    def stream_response(self, **kwargs):
        """流式响应实现（可选）"""
        # 实现流式处理逻辑
        raise NotImplementedError("流式响应暂未实现")
    
    def _convert_input_to_messages(self, system_instructions, input):
        """输入格式转换"""
        messages = []
        if system_instructions:
            messages.append({"role": "system", "content": system_instructions})
        
        if isinstance(input, str):
            messages.append({"role": "user", "content": input})
        else:
            # 处理复杂输入格式
            for item in input:
                messages.append({
                    "role": item.get("role", "user"),
                    "content": item.get("content", "")
                })
        
        return messages
    
    def _convert_to_model_response(self, api_response) -> ModelResponse:
        """响应格式转换"""
        choice = api_response["choices"][0]
        message = choice["message"]
        
        return ModelResponse(
            output=[{
                "type": "message_output",
                "content": message["content"],
                "role": "assistant"
            }],
            usage={
                "input_tokens": api_response.get("usage", {}).get("prompt_tokens", 0),
                "output_tokens": api_response.get("usage", {}).get("completion_tokens", 0),
                "total_tokens": api_response.get("usage", {}).get("total_tokens", 0)
            },
            response_id=api_response.get("id"),
            model=api_response.get("model")
        )

class CustomModelProvider(ModelProvider):
    """自定义模型提供商"""
    
    def __init__(self, api_endpoint: str, api_key: str):
        self.api_endpoint = api_endpoint
        self.api_key = api_key
    
    def get_model(self, model_name: str | None) -> Model:
        """创建自定义模型实例"""
        if model_name is None:
            model_name = "default-model"
        
        return CustomModel(
            model_name=model_name,
            api_endpoint=self.api_endpoint,
            api_key=self.api_key
        )

# 使用自定义提供商
custom_provider = CustomModelProvider(
    api_endpoint="https://api.mycompany.com",
    api_key="your-custom-api-key"
)

agent = Agent(
    name="CustomAgent",
    model="my-custom-model-v1",
    instructions="使用自定义模型提供服务"
)

# 配置自定义提供商
from agents.run import RunConfig
config = RunConfig(model_provider=custom_provider)

result = await Runner.run(agent, "测试自定义模型", run_config=config)

ModelProvider (提供商接口)
    ├── MultiProvider (多提供商路由)
    ├── OpenAIProvider (OpenAI实现)
    └── 自定义Provider (可扩展)

Model (模型接口)
    ├── get_response() (标准响应)
    └── stream_response() (流式响应)

ModelSettings (模型配置)
    └── 温度、token限制等参数

@abc.abstractmethod
async def get_response(
    self,
    system_instructions: str | None,
    input: str | list[TResponseInputItem],
    model_settings: ModelSettings,
    tools: list[Tool],
    output_schema: AgentOutputSchemaBase | None,
    handoffs: list[Handoff],
    tracing: ModelTracing,
    *,
    previous_response_id: str | None,
    conversation_id: str | None,
    prompt: ResponsePromptParam | None,
) -> ModelResponse

@dataclass
class ModelResponse:
    response_id: str | None  # 响应ID
    output: list  # 输出项列表（消息、工具调用等）
    usage: Usage  # Token使用统计
    raw_response: dict  # 原始响应数据

from agents.models import Model, ModelResponse
from agents import Usage

class CustomModel(Model):
    """自定义模型实现"""
    
    async def get_response(
        self,
        system_instructions: str | None,
        input: str | list[TResponseInputItem],
        model_settings: ModelSettings,
        tools: list[Tool],
        output_schema: AgentOutputSchemaBase | None,
        handoffs: list[Handoff],
        tracing: ModelTracing,
        *,
        previous_response_id: str | None = None,
        conversation_id: str | None = None,
        prompt: ResponsePromptParam | None = None,
    ) -> ModelResponse:
        """实现模型调用逻辑"""
        
        # 1. 准备请求数据
        request_data = {
            "messages": self._prepare_messages(system_instructions, input),
            "temperature": model_settings.temperature,
            "max_tokens": model_settings.max_tokens,
            "tools": self._convert_tools(tools),
        }
        
        # 2. 调用实际的LLM API
        response = await self._call_llm_api(request_data)
        
        # 3. 解析响应
        output_items = self._parse_output(response)
        
        # 4. 统计Token使用
        usage = Usage(
            input_tokens=response.get("usage", {}).get("prompt_tokens", 0),
            output_tokens=response.get("usage", {}).get("completion_tokens", 0),
            total_tokens=response.get("usage", {}).get("total_tokens", 0)
        )
        
        # 5. 返回标准化响应
        return ModelResponse(
            response_id=response.get("id"),
            output=output_items,
            usage=usage,
            raw_response=response
        )

@abc.abstractmethod
def stream_response(
    self,
    system_instructions: str | None,
    input: str | list[TResponseInputItem],
    model_settings: ModelSettings,
    tools: list[Tool],
    output_schema: AgentOutputSchemaBase | None,
    handoffs: list[Handoff],
    tracing: ModelTracing,
    *,
    previous_response_id: str | None,
    conversation_id: str | None,
    prompt: ResponsePromptParam | None,
) -> AsyncIterator[TResponseStreamEvent]

AsyncIterator[TResponseStreamEvent]  # 异步生成器，产生流式事件

class CustomModel(Model):
    """支持流式响应的模型"""
    
    async def stream_response(
        self,
        system_instructions: str | None,
        input: str | list[TResponseInputItem],
        model_settings: ModelSettings,
        tools: list[Tool],
        output_schema: AgentOutputSchemaBase | None,
        handoffs: list[Handoff],
        tracing: ModelTracing,
        *,
        previous_response_id: str | None = None,
        conversation_id: str | None = None,
        prompt: ResponsePromptParam | None = None,
    ) -> AsyncIterator[TResponseStreamEvent]:
        """实现流式响应"""
        
        # 准备请求
        request_data = self._prepare_request(
            system_instructions, input, model_settings, tools
        )
        request_data["stream"] = True
        
        # 调用流式API
        async for chunk in self._call_llm_stream_api(request_data):
            # 转换为标准事件格式
            event = self._convert_to_response_event(chunk)
            yield event

@abc.abstractmethod
def get_model(self, model_name: str | None) -> Model

Model  # 实现了Model接口的实例

from agents.models import ModelProvider, Model

class CustomProvider(ModelProvider):
    """自定义模型提供商"""
    
    def __init__(self, api_key: str, base_url: str):
        self.api_key = api_key
        self.base_url = base_url
        self._model_cache = {}
    
    def get_model(self, model_name: str | None) -> Model:
        """根据名称返回模型实例"""
        
        # 默认模型
        if model_name is None:
            model_name = "default-model"
        
        # 缓存模型实例
        if model_name not in self._model_cache:
            self._model_cache[model_name] = CustomModel(
                name=model_name,
                api_key=self.api_key,
                base_url=self.base_url
            )
        
        return self._model_cache[model_name]

def __init__(
    self,
    *,
    provider_map: MultiProviderMap | None = None,
    openai_api_key: str | None = None,
    openai_base_url: str | None = None,
    openai_client: AsyncOpenAI | None = None,
    openai_organization: str | None = None,
    openai_project: str | None = None,
    openai_use_responses: bool | None = None,
)

# 无前缀或"openai/"前缀 -> OpenAIProvider
"gpt-4o" -> OpenAIProvider
"openai/gpt-4o" -> OpenAIProvider

# "litellm/"前缀 -> LitellmProvider
"litellm/claude-3-opus" -> LitellmProvider

# 自定义前缀 -> 自定义Provider
"custom/my-model" -> CustomProvider (需要在provider_map中配置)

from agents.models import MultiProvider
from openai import AsyncOpenAI

# 基础用法（默认OpenAI）
provider = MultiProvider()

# 自定义OpenAI配置
provider = MultiProvider(
    openai_api_key="your-api-key",
    openai_base_url="https://api.openai.com/v1"
)

# 使用自定义客户端
custom_client = AsyncOpenAI(
    api_key="your-key",
    base_url="https://custom.api.com"
)
provider = MultiProvider(openai_client=custom_client)

# 获取模型
model = provider.get_model("gpt-4o")
model_litellm = provider.get_model("litellm/claude-3-opus")

def get_model(self, model_name: str | None) -> Model

# 解析前缀
"openai/gpt-4o" -> prefix="openai", name="gpt-4o"
"litellm/claude" -> prefix="litellm", name="claude"
"gpt-4o" -> prefix=None, name="gpt-4o"

# 查找提供商
if prefix in provider_map:
    return provider_map[prefix].get_model(name)
else:
    return fallback_provider.get_model(name)

provider = MultiProvider()

# OpenAI模型
gpt4 = provider.get_model("gpt-4o")
gpt4_explicit = provider.get_model("openai/gpt-4o")

# LiteLLM模型
claude = provider.get_model("litellm/claude-3-opus")
gemini = provider.get_model("litellm/gemini-pro")

# 使用模型
response = await gpt4.get_response(
    system_instructions="你是一个助手",
    input="Hello",
    model_settings=ModelSettings(),
    tools=[],
    output_schema=None,
    handoffs=[],
    tracing=ModelTracing.ENABLED
)

def add_provider(self, prefix: str, provider: ModelProvider)
def get_provider(self, prefix: str) -> ModelProvider | None
def has_prefix(self, prefix: str) -> bool
def remove_provider(self, prefix: str)

from agents.models import MultiProvider, MultiProviderMap, ModelProvider

# 创建自定义提供商
class MyCustomProvider(ModelProvider):
    def get_model(self, model_name: str | None) -> Model:
        return MyCustomModel(model_name)

# 创建提供商映射
provider_map = MultiProviderMap()
provider_map.add_provider("custom", MyCustomProvider())
provider_map.add_provider("azure", AzureProvider())

# 使用自定义映射创建MultiProvider
provider = MultiProvider(provider_map=provider_map)

# 现在可以使用自定义前缀
custom_model = provider.get_model("custom/my-model")
azure_model = provider.get_model("azure/gpt-4")

from agents.models import ModelProvider, Model, MultiProvider, MultiProviderMap
from agents import ModelResponse, Usage, ModelSettings
import httpx

class HuggingFaceModel(Model):
    """Hugging Face模型实现"""
    
    def __init__(self, model_name: str, api_key: str):
        self.model_name = model_name
        self.api_key = api_key
        self.base_url = "https://api-inference.huggingface.co/models"
    
    async def get_response(
        self,
        system_instructions: str | None,
        input: str | list,
        model_settings: ModelSettings,
        tools: list,
        output_schema,
        handoffs: list,
        tracing,
        **kwargs
    ) -> ModelResponse:
        """调用Hugging Face API"""
        
        # 准备请求
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/{self.model_name}",
                headers={"Authorization": f"Bearer {self.api_key}"},
                json={
                    "inputs": self._format_input(system_instructions, input),
                    "parameters": {
                        "temperature": model_settings.temperature,
                        "max_new_tokens": model_settings.max_tokens,
                    }
                }
            )
        
        # 解析响应
        data = response.json()
        output_text = data[0]["generated_text"]
        
        return ModelResponse(
            response_id=None,
            output=[{"type": "message", "content": output_text}],
            usage=Usage(input_tokens=0, output_tokens=0, total_tokens=0),
            raw_response=data
        )
    
    async def stream_response(self, **kwargs):
        """流式响应（简化版）"""
        response = await self.get_response(**kwargs)
        yield response.output[0]

class HuggingFaceProvider(ModelProvider):
    """Hugging Face提供商"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
    
    def get_model(self, model_name: str | None) -> Model:
        """返回Hugging Face模型"""
        if model_name is None:
            model_name = "gpt2"
        return HuggingFaceModel(model_name, self.api_key)

# 注册到MultiProvider
provider_map = MultiProviderMap()
provider_map.add_provider("hf", HuggingFaceProvider(api_key="your-key"))

provider = MultiProvider(provider_map=provider_map)

# 使用Hugging Face模型
agent = Agent(
    name="HFAgent",
    model="hf/gpt2",  # 使用自定义前缀
    instructions="你是一个助手"
)

class ModelTracing(enum.Enum):
    DISABLED = 0              # 完全禁用追踪
    ENABLED = 1               # 启用追踪，包含所有数据
    ENABLED_WITHOUT_DATA = 2  # 启用追踪，但不包含输入输出数据

def is_disabled(self) -> bool:
    """是否禁用追踪"""
    return self == ModelTracing.DISABLED

def include_data(self) -> bool:
    """是否包含数据"""
    return self == ModelTracing.ENABLED

from agents.models import ModelTracing

# 完全启用追踪
tracing = ModelTracing.ENABLED

# 启用追踪但不记录敏感数据
tracing = ModelTracing.ENABLED_WITHOUT_DATA

# 禁用追踪
tracing = ModelTracing.DISABLED

# 在模型调用中使用
response = await model.get_response(
    ...,
    tracing=tracing
)

from agents import Agent, RunConfig
from agents.models import MultiProvider

# 创建支持多模型的提供商
provider = MultiProvider()

# 为不同任务使用不同模型
fast_agent = Agent(
    name="FastAgent",
    model="gpt-4o-mini",
    instructions="快速响应"
)

smart_agent = Agent(
    name="SmartAgent",
    model="gpt-4o",
    instructions="深度思考"
)

# 在运行时切换模型
config = RunConfig(
    model="gpt-4o",  # 覆盖代理的模型
    model_provider=provider
)

class FallbackModel(Model):
    """支持回退的模型"""
    
    def __init__(self, primary: Model, fallback: Model):
        self.primary = primary
        self.fallback = fallback
    
    async def get_response(self, **kwargs) -> ModelResponse:
        """尝试主模型，失败时使用备用模型"""
        try:
            return await self.primary.get_response(**kwargs)
        except Exception as e:
            logger.warning(f"Primary model failed: {e}, using fallback")
            return await self.fallback.get_response(**kwargs)

Model Interface (模型接口)
    ├── get_response() -> ModelResponse
    └── stream_response() -> AsyncIterator[StreamEvent]

ModelProvider (提供商接口)
    ├── MultiProvider (多提供商)
    └── OpenAIProvider (OpenAI实现)

ModelResponse (响应对象)
    ├── response_id
    ├── output
    ├── usage
    └── raw_response

ModelTracing (追踪配置)

classDiagram
    class Model {
        <<abstract>>
        +get_response(system_instructions, input, model_settings, tools, ...) ModelResponse
        +stream_response(system_instructions, input, model_settings, tools, ...) AsyncIterator
    }
    
    class ModelProvider {
        <<abstract>>
        +get_model(model_name: str) Model
    }
    
    class MultiProvider {
        -provider_map: MultiProviderMap
        -openai_provider: OpenAIProvider
        -_fallback_providers: dict
        +__init__(provider_map, openai_api_key, ...)
        +get_model(model_name: str) Model
        -_get_prefix_and_model_name(model_name) tuple
        -_get_fallback_provider(prefix) ModelProvider
    }
    
    class OpenAIProvider {
        -client: AsyncOpenAI
        -use_responses: bool
        -_models: dict
        +__init__(api_key, base_url, ...)
        +get_model(model_name: str) Model
    }
    
    class OpenAIResponsesModel {
        -client: AsyncOpenAI
        -model_name: str
        +get_response(...) ModelResponse
        +stream_response(...) AsyncIterator
    }
    
    class OpenAIChatCompletionsModel {
        -client: AsyncOpenAI
        -model_name: str
        +get_response(...) ModelResponse
        +stream_response(...) AsyncIterator
    }
    
    ModelProvider <|-- MultiProvider
    ModelProvider <|-- OpenAIProvider
    Model <|-- OpenAIResponsesModel
    Model <|-- OpenAIChatCompletionsModel
    MultiProvider --> OpenAIProvider : 持有
    OpenAIProvider --> OpenAIResponsesModel : 创建
    OpenAIProvider --> OpenAIChatCompletionsModel : 创建

classDiagram
    class MultiProviderMap {
        -_mapping: dict[str, ModelProvider]
        +__init__()
        +has_prefix(prefix: str) bool
        +get_mapping() dict
        +set_mapping(mapping: dict)
        +get_provider(prefix: str) ModelProvider | None
        +add_provider(prefix: str, provider: ModelProvider)
        +remove_provider(prefix: str)
    }
    
    class MultiProvider {
        +provider_map: MultiProviderMap | None
        +openai_provider: OpenAIProvider
        +get_model(model_name: str) Model
    }
    
    class ModelProvider {
        <<abstract>>
        +get_model(model_name: str) Model
    }
    
    MultiProvider --> MultiProviderMap : 使用
    MultiProviderMap --> ModelProvider : 映射

classDiagram
    class ModelResponse {
        +response_id: str | None
        +output: list[ResponseOutputItem]
        +usage: Usage
        +raw_response: dict
    }
    
    class ResponseOutputItem {
        <<union>>
        ResponseTextItem
        ResponseFunctionCallItem
        ResponseAudioItem
    }
    
    class ResponseTextItem {
        +type: "message"
        +content: str
        +role: str
    }
    
    class ResponseFunctionCallItem {
        +type: "function_call"
        +call_id: str
        +name: str
        +arguments: str
    }
    
    class Usage {
        +input_tokens: int
        +output_tokens: int
        +total_tokens: int
        +input_token_details: dict | None
        +output_token_details: dict | None
    }
    
    ModelResponse --> ResponseOutputItem : 包含多个
    ModelResponse --> Usage : 包含
    ResponseOutputItem <|-- ResponseTextItem
    ResponseOutputItem <|-- ResponseFunctionCallItem

@dataclass
class Usage:
    """Token使用统计"""
    
    input_tokens: int
    """输入Token数量"""
    
    output_tokens: int
    """输出Token数量"""
    
    total_tokens: int
    """总Token数量"""
    
    input_token_details: dict | None = None
    """输入Token详细信息（如缓存命中等）"""
    
    output_token_details: dict | None = None
    """输出Token详细信息（如推理Token等）"""

usage = Usage(
    input_tokens=150,
    output_tokens=50,
    total_tokens=200,
    input_token_details={
        "cached_tokens": 100,  # 缓存命中的Token
        "text_tokens": 50
    },
    output_token_details={
        "reasoning_tokens": 20,  # 推理Token（o1模型）
        "text_tokens": 30
    }
)

classDiagram
    class ModelSettings {
        +temperature: float | None
        +max_tokens: int | None
        +top_p: float | None
        +frequency_penalty: float | None
        +presence_penalty: float | None
        +response_format: dict | None
        +seed: int | None
        +stop: list[str] | None
        +logprobs: bool | None
        +top_logprobs: int | None
        +parallel_tool_calls: bool | None
    }

from agents import ModelSettings

# 创造性任务配置
creative_settings = ModelSettings(
    temperature=0.9,
    top_p=0.95,
    max_tokens=2000,
    presence_penalty=0.6
)

# 精确任务配置
precise_settings = ModelSettings(
    temperature=0.1,
    max_tokens=500,
    seed=42,  # 可重复的结果
    stop=["\n\n"]
)

# JSON模式配置
json_settings = ModelSettings(
    temperature=0.5,
    response_format={"type": "json_object"}
)

classDiagram
    class ModelTracing {
        <<enumeration>>
        DISABLED = 0
        ENABLED = 1
        ENABLED_WITHOUT_DATA = 2
        +is_disabled() bool
        +include_data() bool
    }