# 第 1-12 课课堂练习：Agent 文本处理工具箱
#
# 完成要求：
# 1. 根据注释定义和调用函数，练习参数与返回值。
# 2. 使用有意义的英文蛇形函数名和变量名。
# 3. 函数体使用四个空格缩进。
# 4. 不要删除题目注释。
# 5. 完成后运行本文件并核对预期结果。


# 练习一：定义并调用一个负责输出问候语的函数。
# 1. 定义 greet_user(name) 函数，参数 name 表示需要问候的姓名。
# 2. 函数内部使用 print() 输出“你好，{name}！”，本题不需要使用 return。
# 3. 调用函数时传入字符串“Python 学习者”。
# 4. 预期输出：你好，Python 学习者！
# 可参考 functions.py 中 greet_user(name) 的写法。


# 练习二：定义一个用于生成 Agent 描述文本的函数。
# 1. 定义 build_agent_description(name, model) 函数。
#    参数 name 表示 Agent 名称，参数 model 表示模型名称。
# 2. 函数内部不要直接输出，而是使用 return 返回字符串：
#    “Agent：{name}，模型：{model}”。
# 3. 使用“代码助手”和“gpt-5”作为参数调用函数。
# 4. 把返回值保存到变量 description，再使用 print(description) 输出。
# 5. 预期输出：Agent：代码助手，模型：gpt-5
# 可参考 functions.py 中 build_agent_description(name, model) 的写法。



# 练习三：定义一个计算两个数字之和的函数。
# 1. 定义 get_total(first_number, second_number) 函数，两个参数都接收数字。
# 2. 在函数内部计算 first_number + second_number，并使用 return 返回计算结果。
# 3. 调用函数计算 12 和 8，把返回值保存到变量 total。
# 4. 使用 print(total) 输出结果，预期输出：20。
# 注意：本题要练习返回值，因此不要只在函数内部 print() 计算结果。



# 练习四：定义一个带默认参数的 Agent 描述函数。
# 1. 定义 build_agent_description_with_default(name, model="gpt-5") 函数。
# 2. 函数使用 return 返回“Agent：{name}，模型：{model}”。
# 3. 第一次只传入 name="代码助手"，把返回值保存并输出；此时 model 自动使用“gpt-5”。
# 4. 第二次传入 name="代码助手"和关键字参数 model="o3"，再保存并输出返回值。
# 5. 两次预期输出分别为：
#    Agent：代码助手，模型：gpt-5
#    Agent：代码助手，模型：o3
# 可参考 functions.py 中默认参数和关键字参数的示例。



# 练习五：定义一个安全读取 Agent 工具列表的函数。
# 1. 定义 get_agent_tools(agent) 函数，参数 agent 接收一个字典。
# 2. 函数内部使用 return agent.get("tools", [])：
#    字典存在 tools 键时返回对应的列表，不存在时返回默认的空列表 []。
# 3. 创建第一个测试字典：
#    {"name": "代码助手", "tools": ["搜索", "计算器"]}
# 4. 创建第二个测试字典：{"name": "聊天助手"}，它没有 tools 键。
# 5. 分别调用函数并用 print() 输出返回值。
# 6. 两次预期输出分别为：["搜索", "计算器"] 和 []。
# 可参考 functions.py 中 get_available_tools(agent) 的写法。



# 练习六：定义一个统计已启用 Agent 数量的函数。
# 1. 定义 count_enabled_agents(agents) 函数，参数 agents 接收“由字典组成的列表”。
# 2. 在函数内先创建计数变量 enabled_count，并把初始值设为 0。
# 3. 遍历 agents；如果当前字典的 agent["enabled"] 为 True，就把计数加 1。
# 4. 遍历结束后，使用 return 返回 enabled_count。不要遇到 False 就提前结束循环。
# 5. 使用下面三条数据测试：
#    {"name": "代码助手", "enabled": True}
#    {"name": "聊天助手", "enabled": False}
#    {"name": "搜索助手", "enabled": True}
# 6. 保存并输出函数返回值，预期输出：2。
# 可参考 functions.py 中 count_enabled_agents(agents) 的写法。



# 练习七：定义一个获取所有已启用 Agent 名称的函数。
# 1. 定义 get_enabled_agent_names(agents) 函数，agents 的数据结构与练习六相同。
# 2. 在函数内创建空列表 enabled_names，用于保存符合条件的名称。
# 3. 遍历 agents；当 agent["enabled"] 为 True 时，把 agent["name"] 添加到列表。
# 4. 遍历结束后，使用 return 返回 enabled_names。
# 5. 使用练习六给出的三条 Agent 数据调用函数，并使用 print() 输出返回值。
# 6. 预期输出：["代码助手", "搜索助手"]，停用的“聊天助手”不应出现在结果中。

# 练习八：定义一个判断 Agent 是否具备全部必需工具的函数。
# 1. 定义 has_required_tools(agent, required_tools) 函数：
#    agent 接收 Agent 字典，required_tools 接收“必需工具集合”。
# 2. 使用 agent.get("tools", []) 读取工具列表，再用 set() 转换为集合，
#    并把这个集合保存到局部变量 agent_tools。
# 3. 使用 required_tools <= agent_tools 判断“必需工具集合是否为 Agent 工具集合的子集”。
#    只有每一个必需工具都存在时，表达式才会得到 True。
# 4. 使用 return 返回判断结果，不要只在函数内部输出。
# 5. 创建测试 Agent：
#    {"name": "代码助手", "tools": ["搜索", "计算器", "终端"]}
# 6. 第一次传入必需工具集合 {"搜索", "终端"}，保存并输出结果，预期为 True。
# 7. 第二次传入必需工具集合 {"搜索", "数据库"}，保存并输出结果，预期为 False。
# 可回顾上一课“集合”中的子集判断，也可参考本课练习五的字典读取方式。


# 练习九：定义一个逐行输出 Agent 报告的函数。
# 1. 定义 print_agent_report(agents) 函数，agents 接收“由字典组成的列表”。
# 2. 每个字典都包含 name、enabled 和 tools 三个键，例如：
#    {"name": "代码助手", "enabled": True, "tools": ["搜索", "终端"]}
#    {"name": "聊天助手", "enabled": False, "tools": []}
# 3. 遍历 agents，根据 enabled 的布尔值生成中文状态：True 对应“启用”，False 对应“停用”。
# 4. 使用 len(agent["tools"]) 取得工具数量。
# 5. 在函数内部使用 print() 输出每个 Agent，本题只负责显示报告，不需要 return。
# 6. 调用函数后，预期输出：
#    代码助手：启用，工具数量：2
#    聊天助手：停用，工具数量：0


# 练习十：定义一个对模型使用记录去重并排序的函数。
# 1. 定义 normalize_model_history(model_history) 函数，参数接收模型名称列表。
# 2. 先使用 set(model_history) 去除重复名称。
# 3. 再把去重后的集合传给 sorted()；sorted() 会返回一个排好序的新列表。
# 4. 使用 return 返回这个新列表，不要只在函数内部输出。
# 5. 使用 ["gpt-5", "o3", "gpt-5", "claude"] 调用函数，保存并输出返回值。
# 6. 预期输出：["claude", "gpt-5", "o3"]。
# 可回顾上一课“集合”中的去重方式和 sorted() 的用法。


# 预期核心结果：
# greet_user() 能输出问候语；
# build_agent_description() 能返回可保存的字符串；
# get_total(12, 8) 返回 20；
# 默认参数调用时使用 gpt-5，关键字参数调用时使用 o3；
# 没有 tools 的 Agent 返回空列表；
# count_enabled_agents() 返回 2；
# get_enabled_agent_names() 只返回启用 Agent 的名称；
# 权限满足判断返回 True；
# 报告函数能正确输出每个 Agent 的状态和工具数量；
# 模型记录去重后按排序结果返回。


# 完成后进行自查：
# 1. 是否使用 def 定义函数；
# 2. 是否正确传递位置参数和关键字参数；
# 3. 需要继续使用的结果是否使用 return；
# 4. 是否区分 print() 和 return；
# 5. 默认参数是否放在普通参数后面；
# 6. 函数内的局部变量是否没有误当作全局变量；
# 7. 函数是否尽量只负责一个清晰的任务。