flowchart TB
    subgraph "Agent 模块"
        AGENTBASE[AgentBase<TContext>]
        AGENT[Agent<TContext>]
        REALTIMEAGENT[RealtimeAgent<TContext>]
        
        subgraph "配置类型"
            MCPCONFIG[MCPConfig]
            STOPTOOLS[StopAtTools]
            TOOLSFINALOUT[ToolsToFinalOutputResult]
        end
        
        subgraph "核心方法"
            GETTOOLS[get_all_tools]
            GETMCPTOOLS[get_mcp_tools]
            GETSYSPROMPT[get_system_prompt]
            GETPROMPT[get_prompt]
            CLONE[clone]
            ASTOOL[as_tool]
        end
    end
    
    subgraph "外部依赖"
        TOOLS[Tool System]
        MCP[MCP Servers]
        GUARDRAILS[Guardrails]
        HANDOFFS[Handoffs]
        MODELS[Model Interface]
        PROMPTS[Prompt System]
        LIFECYCLE[Lifecycle Hooks]
    end
    
    AGENTBASE --> AGENT
    AGENTBASE --> REALTIMEAGENT
    
    AGENT --> GETTOOLS
    AGENT --> GETMCPTOOLS
    AGENT --> GETSYSPROMPT
    AGENT --> GETPROMPT
    AGENT --> CLONE
    AGENT --> ASTOOL
    
    AGENT --> MCPCONFIG
    AGENT --> STOPTOOLS
    AGENT --> TOOLSFINALOUT
    
    GETTOOLS --> TOOLS
    GETMCPTOOLS --> MCP
    AGENT --> GUARDRAILS
    AGENT --> HANDOFFS
    AGENT --> MODELS
    GETSYSPROMPT --> PROMPTS
    GETPROMPT --> PROMPTS
    AGENT --> LIFECYCLE
    
    style AGENT fill:#e1f5fe
    style AGENTBASE fill:#f3e5f5
    style REALTIMEAGENT fill:#e8f5e8

async def get_all_tools(self, run_context: RunContextWrapper[TContext]) -> list[Tool]:
    """聚合所有可用工具（MCP + Function Tools）"""
    # 1) 获取 MCP 工具
    mcp_tools = await self.get_mcp_tools(run_context)
    
    # 2) 检查函数工具启用状态
    async def _check_tool_enabled(tool: Tool) -> bool:
        if not isinstance(tool, FunctionTool):
            return True
            
        attr = tool.is_enabled
        if isinstance(attr, bool):
            return attr
        # 动态检查工具是否启用
        res = attr(run_context, self)
        if inspect.isawaitable(res):
            return bool(await res)
        return bool(res)
    
    # 3) 并发检查所有工具状态
    results = await asyncio.gather(*(_check_tool_enabled(t) for t in self.tools))
    enabled = [t for t, ok in zip(self.tools, results) if ok]
    
    # 4) 合并返回所有启用的工具
    return [*mcp_tools, *enabled]

async def get_system_prompt(self, run_context: RunContextWrapper[TContext]) -> str | None:
    """动态生成系统提示词"""
    if isinstance(self.instructions, str):
        # 静态指令直接返回
        return self.instructions
    elif callable(self.instructions):
        # 动态指令需要函数调用
        sig = inspect.signature(self.instructions)
        params = list(sig.parameters.values())
        
        # 参数数量校验
        if len(params) != 2:
            raise TypeError(
                f"'instructions' callable must accept exactly 2 arguments (context, agent)"
            )
        
        # 调用指令生成函数
        if inspect.iscoroutinefunction(self.instructions):
            return await cast(Awaitable[str], self.instructions(run_context, self))
        else:
            return cast(str, self.instructions(run_context, self))
    
    return None

def as_tool(self, tool_name: str | None, tool_description: str | None, ...) -> Tool:
    """将代理转换为可被其他代理调用的工具"""
    
    @function_tool(
        name_override=tool_name or _transforms.transform_string_function_style(self.name),
        description_override=tool_description or "",
        is_enabled=is_enabled,
    )
    async def run_agent(context: RunContextWrapper, input: str) -> str:
        # 使用独立的 Runner 执行代理
        output = await Runner.run(
            starting_agent=self,
            input=input,
            context=context.context,
            run_config=run_config,
            max_turns=resolved_max_turns,
            hooks=hooks,
            previous_response_id=previous_response_id,
            conversation_id=conversation_id,
            session=session,
        )
        
        # 提取输出结果
        if custom_output_extractor:
            return await custom_output_extractor(output)
        return ItemHelpers.text_message_outputs(output.new_items)
    
    return run_agent

# 推荐：明确的代理定义
agent = Agent(
    name="DataAnalyst",  # 使用描述性名称
    instructions="""
    你是一个专业的数据分析师。请：

    1. 分析用户提供的数据
    2. 识别关键趋势和模式
    3. 生成可视化图表
    4. 提供具体的业务建议
    """,
    tools=[data_analysis_tool, chart_generator_tool],  # 相关工具集合
    model_settings=ModelSettings(
        temperature=0.3,  # 分析任务需要较低随机性
        max_tokens=2000   # 预留足够输出空间
    ),
    output_guardrails=[content_safety_guardrail],  # 必要的安全检查

)

def generate_context_aware_instructions(
    context: RunContextWrapper,
    agent: Agent
) -> str:
    """根据上下文动态生成指令"""
    user_role = context.context.get("user_role", "general")
    task_type = context.context.get("task_type", "chat")
    
    base_instructions = "你是一个智能助手。"
    
    if user_role == "developer":
        base_instructions += "请使用技术术语，提供代码示例。"
    elif user_role == "business":
        base_instructions += "请使用商业语言，关注ROI和业务价值。"
    
    if task_type == "analysis":
        base_instructions += "请进行深入分析并提供数据支持。"
    
    return base_instructions

# 使用动态指令
agent = Agent(
    name="AdaptiveAssistant",
    instructions=generate_context_aware_instructions,  # 函数而非字符串
    # ... 其他配置
)

# 专业化代理
research_agent = Agent(
    name="Researcher",
    instructions="专注于信息收集和事实核查",
    tools=[web_search_tool, database_query_tool],
    handoff_description="负责信息研究和数据收集"
)

analysis_agent = Agent(
    name="Analyst",
    instructions="专注于数据分析和洞察提取",
    tools=[data_analysis_tool, visualization_tool],
    handoff_description="负责数据分析和可视化"
)

# 协调代理
coordinator = Agent(
    name="Coordinator",
    instructions="""
    你是一个任务协调者。根据用户需求：

    - 需要信息收集时，切换到 Researcher
    - 需要数据分析时，切换到 Analyst  
    - 最终整合结果并响应用户
    """,
    handoffs=[research_agent, analysis_agent]

)

# 将代理转换为工具
specialist_tool = specialist_agent.as_tool(
    tool_name="domain_expert",
    tool_description="专业领域专家，提供深度分析和建议",
    max_turns=5,  # 限制子代理执行轮次
    custom_output_extractor=lambda result: result.final_output
)

# 在主代理中使用
main_agent = Agent(
    name="MainAssistant",
    instructions="当遇到专业问题时，调用 domain_expert 工具获取专家意见",
    tools=[specialist_tool, other_tools...]
)

@dataclass
class Agent(AgentBase, Generic[TContext]):
    # 基础配置
    name: str                                    # 代理名称
    handoff_description: str | None = None       # 切换描述
    tools: list[Tool] = field(default_factory=list)
    mcp_servers: list[MCPServer] = field(default_factory=list)
    mcp_config: MCPConfig = field(default_factory=lambda: MCPConfig())
    
    # 指令与提示
    instructions: str | Callable[[RunContextWrapper[TContext], Agent[TContext]], MaybeAwaitable[str]] | None = None
    prompt: Prompt | DynamicPromptFunction | None = None
    
    # 协作与切换
    handoffs: list[Agent[Any] | Handoff[TContext, Any]] = field(default_factory=list)
    
    # 模型配置
    model: str | Model | None = None
    model_settings: ModelSettings = field(default_factory=get_default_model_settings)
    
    # 安全防护
    input_guardrails: list[InputGuardrail[TContext]] = field(default_factory=list)
    output_guardrails: list[OutputGuardrail[TContext]] = field(default_factory=list)
    
    # 输出控制
    output_type: type[Any] | AgentOutputSchemaBase | None = None
    
    # 行为控制
    tool_use_behavior: Literal["run_llm_again", "stop_on_first_tool"] | StopAtTools | ToolsToFinalOutputFunction = "run_llm_again"
    reset_tool_choice: bool = True
    
    # 生命周期
    hooks: AgentHooks[TContext] | None = None

async def get_all_tools(self, run_context: RunContextWrapper[TContext]) -> list[Tool]:
    """聚合所有可用工具，包括 MCP 工具和启用的函数工具"""
    # 1) 异步获取 MCP 工具
    mcp_tools = await self.get_mcp_tools(run_context)
    
    # 2) 定义工具启用检查函数
    async def _check_tool_enabled(tool: Tool) -> bool:
        if not isinstance(tool, FunctionTool):
            return True  # 非函数工具默认启用
            
        attr = tool.is_enabled
        if isinstance(attr, bool):
            return attr  # 静态启用状态
        
        # 动态启用检查
        res = attr(run_context, self)
        if inspect.isawaitable(res):
            return bool(await res)
        return bool(res)
    
    # 3) 并发检查所有函数工具的启用状态
    results = await asyncio.gather(*(_check_tool_enabled(t) for t in self.tools))
    enabled = [t for t, ok in zip(self.tools, results) if ok]
    
    # 4) 合并 MCP 工具和启用的函数工具
    return [*mcp_tools, *enabled]

async def get_system_prompt(self, run_context: RunContextWrapper[TContext]) -> str | None:
    """获取系统提示词，支持静态字符串和动态函数生成"""
    if isinstance(self.instructions, str):
        # 静态指令直接返回
        return self.instructions
    elif callable(self.instructions):
        # 动态指令需要函数调用
        sig = inspect.signature(self.instructions)
        params = list(sig.parameters.values())
        
        # 强制要求两个参数：context 和 agent
        if len(params) != 2:
            raise TypeError(
                f"'instructions' callable must accept exactly 2 arguments (context, agent), "
                f"but got {len(params)}: {[p.name for p in params]}"
            )
        
        # 支持同步和异步指令函数
        if inspect.iscoroutinefunction(self.instructions):
            return await cast(Awaitable[str], self.instructions(run_context, self))
        else:
            return cast(str, self.instructions(run_context, self))
    
    return None  # 未设置指令时返回 None

def clone(self, **kwargs: Any) -> Agent[TContext]:
    """创建代理的浅拷贝，支持属性修改"""
    return dataclasses.replace(self, **kwargs)

# 原始代理
original_agent = Agent(
    name="Assistant",
    instructions="你是一个助手",
    tools=[tool1, tool2]
)

# 克隆并修改指令
modified_agent = original_agent.clone(
    instructions="你是一个专业的技术助手",
    model_settings=ModelSettings(temperature=0.3)
)

# 克隆并添加工具（需要提供完整列表）
enhanced_agent = original_agent.clone(
    tools=[tool1, tool2, tool3]  # 包含原有工具
)

def as_tool(self, tool_name: str | None, tool_description: str | None, ...) -> Tool:
    """将代理转换为工具，实现代理的递归调用"""
    
    @function_tool(
        name_override=tool_name or _transforms.transform_string_function_style(self.name),
        description_override=tool_description or "",
        is_enabled=is_enabled,
    )
    async def run_agent(context: RunContextWrapper, input: str) -> str:
        """工具化代理的执行函数"""
        resolved_max_turns = max_turns if max_turns is not None else DEFAULT_MAX_TURNS
        
        # 使用独立的 Runner 执行代理
        output = await Runner.run(
            starting_agent=self,
            input=input,
            context=context.context,
            run_config=run_config,
            max_turns=resolved_max_turns,
            hooks=hooks,
            previous_response_id=previous_response_id,
            conversation_id=conversation_id,
            session=session,
        )
        
        # 提取最终输出
        if custom_output_extractor:
            return await custom_output_extractor(output)
        
        # 默认提取文本消息输出
        return ItemHelpers.text_message_outputs(output.new_items)
    
    return run_agent

sequenceDiagram
    autonumber
    participant MainAgent as 主代理
    participant Tool as 代理工具
    participant Runner as Runner
    participant SubAgent as 子代理
    participant Model as 模型
    
    MainAgent->>Tool: 调用代理工具
    Tool->>Runner: Runner.run(子代理, 输入)
    Runner->>SubAgent: 配置子代理
    SubAgent->>Model: 发送指令和工具
    Model-->>SubAgent: 模型响应
    SubAgent-->>Runner: 执行结果
    Runner-->>Tool: RunResult
    Tool->>Tool: 提取输出文本
    Tool-->>MainAgent: 返回字符串结果

async def get_mcp_tools(self, run_context: RunContextWrapper[TContext]) -> list[Tool]:
    """从配置的 MCP 服务器获取工具列表"""
    convert_schemas_to_strict = self.mcp_config.get("convert_schemas_to_strict", False)
    return await MCPUtil.get_all_function_tools(
        self.mcp_servers, convert_schemas_to_strict, run_context, self
    )

@dataclass
class ToolsToFinalOutputResult:
    is_final_output: bool                # 是否为最终输出
    """是否终止代理执行。True 时代理停止，False 时继续执行"""
    
    final_output: Any | None = None      # 最终输出内容
    """最终输出内容。is_final_output 为 True 时必须提供，类型需匹配 agent.output_type"""

class StopAtTools(TypedDict):
    stop_at_tool_names: list[str]
    """工具名称列表。当调用列表中任一工具时，代理停止执行"""

class MCPConfig(TypedDict):
    convert_schemas_to_strict: NotRequired[bool]
    """是否将 MCP 模式转换为严格模式。默认 False，最佳努力转换"""

from agents import Agent, Runner

# 创建基础代理
agent = Agent(
    name="CustomerService",
    instructions="你是一个客服助手，请礼貌专业地回答用户问题。",
    model="gpt-4o",
    model_settings=ModelSettings(temperature=0.7)
)

# 执行对话
result = await Runner.run(agent, "我想了解退货政策")
print(result.final_output)

from agents import Agent, function_tool

@function_tool
def query_order(order_id: str) -> str:
    """查询订单状态"""
    # 实际查询逻辑
    return f"订单 {order_id} 状态：已发货"

@function_tool  
def process_refund(order_id: str, reason: str) -> str:
    """处理退款申请"""
    # 实际退款逻辑
    return f"订单 {order_id} 退款申请已提交，理由：{reason}"

# 创建带工具的代理
service_agent = Agent(
    name="ServiceAgent",
    instructions="使用提供的工具帮助用户处理订单问题。",
    tools=[query_order, process_refund]
)

# 专业代理
technical_agent = Agent(
    name="TechnicalSupport",
    instructions="处理技术问题，提供详细的技术解决方案。",
    handoff_description="技术支持专家"
)

# 主代理
main_agent = Agent(
    name="MainService",
    instructions="""
    根据用户问题类型进行分类：

    - 技术问题：切换到 TechnicalSupport
    - 其他问题：直接处理
    """,
    handoffs=[technical_agent]

)

def adaptive_instructions(context: RunContextWrapper, agent: Agent) -> str:
    """根据上下文自适应生成指令"""
    user_level = context.context.get("user_level", "beginner")
    
    base = "你是一个编程助手。"
    if user_level == "beginner":
        return base + "请使用简单的语言，提供详细的解释。"
    elif user_level == "expert":
        return base + "可以使用专业术语，关注高级特性。"
    return base

adaptive_agent = Agent(
    name="AdaptiveTutor",
    instructions=adaptive_instructions  # 函数而非字符串
)

classDiagram
    class Generic~TContext~ {
        <<abstract>>
    }
    
    class AgentBase~TContext~ {
        +str name
        +str|None handoff_description
        +list[Tool] tools
        +list[MCPServer] mcp_servers
        +MCPConfig mcp_config
        +get_mcp_tools(RunContextWrapper) list[Tool]
        +get_all_tools(RunContextWrapper) list[Tool]
    }
    
    class Agent~TContext~ {
        +str|Callable|None instructions
        +Prompt|DynamicPromptFunction|None prompt
        +list[Agent|Handoff] handoffs
        +str|Model|None model
        +ModelSettings model_settings
        +list[InputGuardrail] input_guardrails
        +list[OutputGuardrail] output_guardrails
        +type|AgentOutputSchemaBase|None output_type
        +str|StopAtTools|ToolsToFinalOutputFunction tool_use_behavior
        +bool reset_tool_choice
        +AgentHooks|None hooks
        +clone(**kwargs) Agent[TContext]
        +as_tool(...) Tool
        +get_system_prompt(RunContextWrapper) str|None
        +get_prompt(RunContextWrapper) ResponsePromptParam|None
    }
    
    class RealtimeAgent~TContext~ {
        +str|Callable|None instructions
        +Prompt|None prompt
        +list[RealtimeAgent|Handoff] handoffs
        +list[OutputGuardrail] output_guardrails
        +RealtimeAgentHooks|None hooks
        +clone(**kwargs) RealtimeAgent[TContext]
        +get_system_prompt(RunContextWrapper) str|None
    }
    
    class ToolsToFinalOutputResult {
        +bool is_final_output
        +Any|None final_output
    }
    
    class MCPConfig {
        +bool convert_schemas_to_strict
    }
    
    class StopAtTools {
        +list[str] stop_at_tool_names
    }
    
    Generic~TContext~ <|-- AgentBase~TContext~
    AgentBase~TContext~ <|-- Agent~TContext~
    AgentBase~TContext~ <|-- RealtimeAgent~TContext~
    
    Agent~TContext~ --> ToolsToFinalOutputResult : uses
    Agent~TContext~ --> MCPConfig : contains
    Agent~TContext~ --> StopAtTools : uses
    
    AgentBase~TContext~ --> MCPConfig : contains

@dataclass
class Agent(AgentBase, Generic[TContext]):
    """智能代理的完整数据结构定义"""
    
    # === 基础标识信息 ===
    name: str
    """代理名称，用于标识和日志记录"""
    
    handoff_description: str | None = None
    """代理描述，用于多代理切换时的选择依据"""
    
    # === 工具与能力配置 ===
    tools: list[Tool] = field(default_factory=list)
    """函数工具列表，代理可调用的本地功能"""
    
    mcp_servers: list[MCPServer] = field(default_factory=list)
    """MCP 服务器列表，提供远程工具和资源"""
    
    mcp_config: MCPConfig = field(default_factory=lambda: MCPConfig())
    """MCP 服务器配置选项"""
    
    # === 指令与提示配置 ===
    instructions: (
        str
        | Callable[[RunContextWrapper[TContext], Agent[TContext]], MaybeAwaitable[str]]
        | None
    ) = None
    """系统指令，可以是静态字符串或动态生成函数"""
    
    prompt: Prompt | DynamicPromptFunction | None = None
    """提示对象，支持外部配置管理"""
    
    # === 协作与切换配置 ===
    handoffs: list[Agent[Any] | Handoff[TContext, Any]] = field(default_factory=list)
    """可切换的子代理列表，实现多代理协作"""
    
    # === 模型与生成配置 ===
    model: str | Model | None = None
    """使用的语言模型，字符串名称或模型实例"""
    
    model_settings: ModelSettings = field(default_factory=get_default_model_settings)
    """模型参数设置，如温度、最大令牌数等"""
    
    # === 安全与防护配置 ===
    input_guardrails: list[InputGuardrail[TContext]] = field(default_factory=list)
    """输入安全检查列表"""
    
    output_guardrails: list[OutputGuardrail[TContext]] = field(default_factory=list)
    """输出安全检查列表"""
    
    # === 输出与结果配置 ===
    output_type: type[Any] | AgentOutputSchemaBase | None = None
    """结构化输出类型定义"""
    
    # === 行为控制配置 ===
    tool_use_behavior: (
        Literal["run_llm_again", "stop_on_first_tool"]
        | StopAtTools
        | ToolsToFinalOutputFunction
    ) = "run_llm_again"
    """工具使用行为策略"""
    
    reset_tool_choice: bool = True
    """工具调用后是否重置工具选择"""
    
    # === 生命周期配置 ===
    hooks: AgentHooks[TContext] | None = None
    """生命周期事件钩子"""

# 指令字段的联合类型定义
instructions: (
    str                                                    # 静态字符串指令
    | Callable[                                           # 动态指令生成函数
        [RunContextWrapper[TContext], Agent[TContext]],   # 函数参数类型
        MaybeAwaitable[str]                               # 返回值类型（支持异步）
    ]
    | None                                                # 未设置指令
) = None

# 复杂的工具行为配置类型
tool_use_behavior: (
    Literal["run_llm_again", "stop_on_first_tool"]       # 预定义行为策略
    | StopAtTools                                         # 条件停止配置
    | ToolsToFinalOutputFunction                          # 自定义处理函数
) = "run_llm_again"

class MCPConfig(TypedDict):
    """MCP（Model Context Protocol）服务器配置"""
    
    convert_schemas_to_strict: NotRequired[bool]
    """是否将 MCP 模式转换为严格模式
    
    默认值：False
    说明：严格模式提供更强的类型检查，但可能导致某些模式不兼容
    使用场景：需要严格类型验证的生产环境
    """

class StopAtTools(TypedDict):
    """工具执行停止条件配置"""
    
    stop_at_tool_names: list[str]
    """停止工具名称列表
    
    行为：当执行列表中任一工具时，代理立即停止执行
    用途：实现精确的工具链控制
    示例：["save_file", "send_email"] - 执行保存或发送操作后停止
    """

# 文件操作后停止
file_agent = Agent(
    name="FileProcessor",
    tool_use_behavior=StopAtTools(stop_at_tool_names=["save_file", "delete_file"]),
    tools=[save_file_tool, delete_file_tool, read_file_tool]
)

# 通信操作后停止  
communication_agent = Agent(
    name="Communicator",
    tool_use_behavior=StopAtTools(stop_at_tool_names=["send_email", "send_sms"]),
    tools=[send_email_tool, send_sms_tool, draft_message_tool]
)

@dataclass
class ToolsToFinalOutputResult:
    """工具执行结果和终止控制"""
    
    is_final_output: bool
    """是否为最终输出
    
    True：代理停止执行，使用 final_output 作为最终结果
    False：代理继续执行，将工具结果发送给模型进行进一步处理
    """
    
    final_output: Any | None = None
    """最终输出内容
    
    约束：当 is_final_output 为 True 时，此字段不能为 None
    类型：必须与代理的 output_type 配置兼容
    用途：作为代理执行的最终返回值
    """

# 有效的结果配置示例
valid_results = [
    ToolsToFinalOutputResult(is_final_output=False),                    # 继续执行
    ToolsToFinalOutputResult(is_final_output=False, final_output=None), # 继续执行
    ToolsToFinalOutputResult(is_final_output=True, final_output="完成"), # 停止执行
]

# 无效的结果配置
invalid_result = ToolsToFinalOutputResult(is_final_output=True, final_output=None)  # 错误：缺少最终输出

ToolsToFinalOutputFunction: TypeAlias = Callable[
    [RunContextWrapper[TContext], list[FunctionToolResult]],  # 输入参数类型
    MaybeAwaitable[ToolsToFinalOutputResult],                 # 返回值类型
]
"""工具结果处理函数类型定义

参数说明：

- run_context: 运行上下文包装器，包含执行环境信息
- tool_results: 工具执行结果列表，包含所有工具调用的输出

返回值：

- ToolsToFinalOutputResult: 处理结果，控制代理是否继续执行

支持特性：

- 同步和异步函数实现
- 复杂的工具结果分析逻辑
- 条件化的执行控制策略

"""

async def smart_tool_processor(
    context: RunContextWrapper[dict],
    results: list[FunctionToolResult]
) -> ToolsToFinalOutputResult:
    """智能工具结果处理器"""
    
    # 检查是否有错误结果
    error_results = [r for r in results if r.is_error]
    if error_results:
        return ToolsToFinalOutputResult(
            is_final_output=True,
            final_output=f"工具执行失败：{error_results[0].error}"
        )
    
    # 检查是否包含最终操作
    final_tools = ["save_document", "send_notification"]
    for result in results:
        if result.tool_name in final_tools:
            return ToolsToFinalOutputResult(
                is_final_output=True,
                final_output=f"操作完成：{result.output}"
            )
    
    # 默认继续执行
    return ToolsToFinalOutputResult(is_final_output=False)

# 应用到代理配置
smart_agent = Agent(
    name="SmartProcessor",
    tool_use_behavior=smart_tool_processor,  # 使用自定义处理器
    tools=[save_document_tool, send_notification_tool, analyze_tool]
)

import json
from dataclasses import asdict
import pickle

# JSON 序列化（需要处理复杂对象）
agent_dict = asdict(agent)
# 注意：函数、模型实例等不能直接 JSON 序列化

# Pickle 序列化（完整对象序列化）
agent_bytes = pickle.dumps(agent)
restored_agent = pickle.loads(agent_bytes)

# 配置导出（仅可序列化字段）
config_dict = {
    "name": agent.name,
    "instructions": agent.instructions if isinstance(agent.instructions, str) else None,
    "model": agent.model if isinstance(agent.model, str) else None,
    # ... 其他可序列化字段
}

# 版本兼容的配置结构
class AgentConfigV1(TypedDict):
    """代理配置 V1 版本"""
    name: str
    instructions: str | None
    model: str | None
    tools: list[str]  # 工具名称列表

class AgentConfigV2(AgentConfigV1):
    """代理配置 V2 版本，向后兼容"""
    model_settings: dict[str, Any]
    guardrails: dict[str, list[str]]
    
# 配置迁移函数
def migrate_config_v1_to_v2(v1_config: AgentConfigV1) -> AgentConfigV2:
    """从 V1 配置迁移到 V2"""
    return {
        **v1_config,
        "model_settings": {},
        "guardrails": {"input": [], "output": []}
    }

import sys
from dataclasses import fields

def analyze_agent_memory(agent: Agent) -> dict[str, int]:
    """分析代理实例的内存占用"""
    memory_usage = {}
    
    for field in fields(agent):
        field_value = getattr(agent, field.name)
        memory_usage[field.name] = sys.getsizeof(field_value)
    
    return memory_usage

# 示例分析结果
typical_memory = {
    "name": 64,                    # 字符串
    "instructions": 256,           # 长字符串
    "tools": 80 + len(tools) * 32, # 列表 + 引用
    "model_settings": 200,         # 配置对象
    # 总计通常 < 1KB
}

sequenceDiagram
    autonumber
    participant User as 用户代码
    participant Agent as Agent 实例
    participant DataClass as dataclass 系统
    participant Validator as 参数验证器
    participant ModelUtil as 模型工具类
    
    User->>Agent: Agent(name="Assistant", ...)
    Agent->>DataClass: 调用 __init__
    DataClass->>Agent: 设置字段值
    Agent->>Agent: __post_init__()
    
    Agent->>Validator: 验证 name 类型
    Validator-->>Agent: 验证通过
    
    Agent->>Validator: 验证 instructions 类型
    Validator-->>Agent: 验证通过
    
    Agent->>Validator: 验证 tools 列表
    Validator-->>Agent: 验证通过
    
    Agent->>ModelUtil: 检查模型设置兼容性
    ModelUtil->>ModelUtil: is_gpt_5_default()
    ModelUtil->>ModelUtil: gpt_5_reasoning_settings_required()
    
    alt 模型不兼容
        ModelUtil->>Agent: 使用通用模型设置
        Agent->>Agent: self.model_settings = ModelSettings()
    else 模型兼容
        ModelUtil-->>Agent: 保持原有设置
    end
    
    Agent->>Validator: 验证其他配置字段
    Validator-->>Agent: 所有验证通过
    
    Agent-->>User: 返回初始化完成的代理实例

sequenceDiagram
    autonumber
    participant Runner as Runner
    participant Agent as Agent 实例
    participant MCPUtil as MCP 工具类
    participant MCPServer as MCP 服务器
    participant AsyncPool as 异步任务池
    participant Tool as 工具实例
    
    Runner->>Agent: get_all_tools(run_context)
    
    Agent->>Agent: get_mcp_tools(run_context)
    Agent->>MCPUtil: get_all_function_tools(servers, config, context, agent)
    
    loop 遍历每个 MCP 服务器
        MCPUtil->>MCPServer: 连接并获取工具列表
        MCPServer-->>MCPUtil: 返回工具定义
        MCPUtil->>MCPUtil: 转换为 Tool 对象
    end
    
    MCPUtil-->>Agent: 返回 MCP 工具列表
    
    Agent->>Agent: 检查函数工具启用状态
    
    loop 并发检查所有函数工具
        Agent->>AsyncPool: 提交 _check_tool_enabled 任务
        AsyncPool->>Tool: 检查 is_enabled 属性
        
        alt 工具启用检查是函数
            Tool->>Tool: 调用启用检查函数
            Tool->>Tool: 处理同步/异步结果
        else 工具启用检查是布尔值
            Tool->>Tool: 直接返回布尔结果
        end
        
        Tool-->>AsyncPool: 返回启用状态
        AsyncPool-->>Agent: 收集检查结果
    end
    
    Agent->>Agent: 过滤启用的工具
    Agent->>Agent: 合并 MCP 工具和函数工具
    Agent-->>Runner: 返回完整工具列表

sequenceDiagram
    autonumber
    participant RunImpl as 执行引擎
    participant Agent as Agent 实例
    participant Inspector as 函数检查器
    participant UserFunc as 用户指令函数
    participant Context as 运行上下文
    
    RunImpl->>Agent: get_system_prompt(run_context)
    
    Agent->>Agent: 检查 instructions 类型
    
    alt instructions 是字符串
        Agent-->>RunImpl: 直接返回字符串指令
    else instructions 是函数
        Agent->>Inspector: inspect.signature(self.instructions)
        Inspector-->>Agent: 返回函数签名
        
        Agent->>Agent: 检查参数数量
        
        alt 参数数量不等于 2
            Agent->>Agent: 抛出 TypeError
            Agent-->>RunImpl: 异常：参数数量错误
        else 参数数量正确
            Agent->>Inspector: inspect.iscoroutinefunction()
            Inspector-->>Agent: 返回是否为协程函数
            
            alt 是协程函数
                Agent->>UserFunc: await instructions(run_context, self)
                UserFunc->>Context: 访问上下文数据
                Context-->>UserFunc: 返回上下文信息
                UserFunc->>UserFunc: 生成动态指令
                UserFunc-->>Agent: 返回生成的指令字符串
            else 是同步函数
                Agent->>UserFunc: instructions(run_context, self)
                UserFunc->>Context: 访问上下文数据
                Context-->>UserFunc: 返回上下文信息
                UserFunc->>UserFunc: 生成动态指令
                UserFunc-->>Agent: 返回生成的指令字符串
            end
        end
    else instructions 是 None
        Agent-->>RunImpl: 返回 None
    end
    
    Agent-->>RunImpl: 返回最终指令结果

def adaptive_instructions(context: RunContextWrapper, agent: Agent) -> str:
    """示例：根据用户角色生成不同指令"""
    user_role = context.context.get("user_role", "general")
    task_type = context.context.get("task_type", "chat")
    
    base = f"你是 {agent.name}，一个智能助手。"
    
    if user_role == "developer":
        base += "请提供技术性回答，包含代码示例。"
    elif user_role == "business":
        base += "请关注商业价值和实际应用。"
    
    return base

sequenceDiagram
    autonumber
    participant User as 用户代码
    participant Agent as 源代理
    participant FuncTool as function_tool 装饰器
    participant Transform as 名称转换器
    participant ToolAgent as 工具化代理函数
    participant Runner as 独立 Runner
    participant TargetAgent as 目标代理实例
    participant ItemHelper as 输出提取器
    
    User->>Agent: as_tool(tool_name, description, ...)
    
    Agent->>Transform: transform_string_function_style(self.name)
    Transform-->>Agent: 返回转换后的工具名称
    
    Agent->>FuncTool: 创建 @function_tool 装饰器
    FuncTool->>FuncTool: 设置工具元数据
    
    Agent->>Agent: 定义内部 run_agent 函数
    
    User->>ToolAgent: 调用工具化代理("用户输入")
    ToolAgent->>ToolAgent: 解析执行参数
    
    ToolAgent->>Runner: Runner.run(starting_agent=源代理, ...)
    Runner->>TargetAgent: 创建独立执行环境
    
    TargetAgent->>TargetAgent: 处理用户输入
    
    loop 代理执行循环
        TargetAgent->>TargetAgent: 模型推理
        
        alt 需要工具调用
            TargetAgent->>TargetAgent: 执行工具
            TargetAgent->>TargetAgent: 处理工具结果
        else 产生最终输出
            TargetAgent->>TargetAgent: 生成最终结果
        end
    end
    
    TargetAgent-->>Runner: 返回 RunResult
    Runner-->>ToolAgent: 返回执行结果
    
    ToolAgent->>ToolAgent: 检查自定义输出提取器
    
    alt 有自定义提取器
        ToolAgent->>User: 调用 custom_output_extractor(result)
        User-->>ToolAgent: 返回提取的输出
    else 使用默认提取器
        ToolAgent->>ItemHelper: text_message_outputs(result.new_items)
        ItemHelper-->>ToolAgent: 返回文本输出
    end
    
    ToolAgent-->>User: 返回最终工具执行结果

# 默认输出提取：从所有新增项目中提取文本消息
default_output = ItemHelpers.text_message_outputs(result.new_items)

# 自定义输出提取：用户定义的提取逻辑
async def custom_extractor(result: RunResult) -> str:
    # 提取结构化数据
    if hasattr(result.final_output, 'summary'):
        return result.final_output.summary
    # 提取最后一条消息
    return result.new_items[-1].content if result.new_items else ""

sequenceDiagram
    autonumber
    participant MainAgent as 主代理
    participant HandoffSystem as 切换系统
    participant TargetAgent as 目标代理
    participant Session as 会话管理
    participant Context as 上下文传递
    participant Model as 语言模型
    
    MainAgent->>Model: 处理用户请求
    Model-->>MainAgent: 决定需要切换代理
    
    MainAgent->>HandoffSystem: 选择目标代理
    HandoffSystem->>HandoffSystem: 评估可用代理列表
    HandoffSystem->>HandoffSystem: 根据描述匹配合适代理
    
    HandoffSystem->>Session: 保存当前会话状态
    Session-->>HandoffSystem: 确认状态已保存
    
    HandoffSystem->>Context: 构建切换上下文
    Context->>Context: 收集切换原因和参数
    Context->>Context: 整理对话历史
    
    HandoffSystem->>TargetAgent: 启动目标代理
    TargetAgent->>Session: 加载会话历史
    Session-->>TargetAgent: 返回完整对话记录
    
    TargetAgent->>Context: 获取切换上下文
    Context-->>TargetAgent: 提供切换信息
    
    TargetAgent->>TargetAgent: 生成切换确认消息
    TargetAgent->>Model: 基于历史和上下文处理请求
    Model-->>TargetAgent: 生成响应
    
    TargetAgent->>Session: 更新会话状态
    Session-->>TargetAgent: 确认更新完成
    
    TargetAgent-->>HandoffSystem: 返回处理结果
    HandoffSystem-->>MainAgent: 完成代理切换

# 主代理的切换决策示例
if "技术问题" in user_input:
    return handoff_to_tech_support
elif "法律咨询" in user_input:
    return handoff_to_legal_advisor
else:
    return continue_main_agent