基于HelloAgents框架构建智能故事生成器自定义Tool实现小说、剧本与诗歌的多文体生成实战【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents本指南以 Datawhale hello-agents 仓库中共创项目laoyouf-aistory为实例完整讲解如何基于 HelloAgents 框架hello-agents0.2.7从零构建一个可根据文体 主题 风格三元参数生成不同文本体裁内容的智能故事生成器。读者将掌握 HelloAgents 中SimpleAgent、Tool、ToolParameter、ToolRegistry、HelloAgentsLLM等核心抽象的正确用法并拿到一份可直接在 Jupyter Notebook 中运行的小说/剧本/诗歌生成实战方案。一、项目概览要解决什么问题laoyouf-aistory是一个面向娱乐场景的智能故事生成器其核心能力可以概括为一句话描述需求三参数决定产出解决什么问题根据用户输入的文体小说/剧本/诗歌、主题与风格三个维度生成与之一一对应的原创故事内容特色功能文体、主题、风格全部由用户自定义自由组合拒绝千篇一律的模板化输出适用场景娱乐快速构思故事点子、生成剧本初稿、创作诗歌等。项目的全部核心代码位于 main.ipynb它演示了使用 HelloAgents 框架构建智能故事生成助手StoryGeneratorAgent的完整流程。Notebook 本身也被划分为第0部分快速演示与第1~4部分完整版两条路径前者用最少的代码快速验证能力后者包含更精细的类型特定提示词与更完善的系统提示词设计。技术栈层面项目依赖极其轻量——requirements.txt中仅有一条核心依赖# 核心依赖 hello-agents[all]0.2.7也就是说除 HelloAgents 框架本体外不需要引入任何额外的 AI 编排库。二、环境准备Python 版本、依赖安装与 LLM 密钥配置1. 环境要求按项目 README.md 的说明运行环境需要满足Python 3.10Notebook 的language_info元数据中记录的运行环境为 3.10.19一个可访问的 OpenAI 兼容 LLM 服务本项目的默认配置指向 ModelScope 魔搭的推理 API2. 安装依赖进入项目目录后执行pip install -r requirements.txt该命令会安装hello-agents[all]0.2.7及其全部可选依赖。3. 配置 API 密钥README 中给出的是通用模板流程# 创建.env文件 cp .env.example .env # 编辑.env文件填入你的API密钥需要说明的是当前仓库该目录下Co-creation-projects/laoyouf-aistory/实际只包含README.md、main.ipynb、requirements.txt三个文件并未附带.env.example文件。因此本项目的实际密钥配置方式是直接在 Notebook 中通过环境变量完成见 main.ipynb 第1部分等价写法如下import os os.environ[LLM_MODEL_ID] Qwen/Qwen2.5-72B-Instruct os.environ[LLM_API_KEY] 你的 API Key os.environ[LLM_BASE_URL] https://api-inference.modelscope.cn/v1/ os.environ[LLM_TIMEOUT] 604. 运行项目# 启动Jupyter Notebook jupyter lab # 打开main.ipynb并运行也可以直接在本仓库中打开 main.ipynb按从上到下的顺序依次执行单元格。三、HelloAgents 核心抽象速览这篇文章用到的四件套在动手写代码之前先厘清本项目用到的 HelloAgents 框架核心组件。虽然仓库内 HelloAgents Optimized 版源码见 Co-creation-projects/lcyting-StockSage-agent/HelloAgents Optimized/hello_agents/与 pip 包hello-agents的公开 API 存在部分差异但其设计思想一脉相承可作为底层原理的参照组件职责参照实现Tool工具基类抽象出run()执行逻辑与get_parameters()参数元信息两个接口tools/base.pyToolParameter单个工具参数的声明式定义name/type/description/required/defaulttools/base.pyToolRegistry工具的注册、查询、执行与描述生成中心tools/registry.pyHelloAgentsLLM统一的 LLM 客户端负责从环境变量读取模型配置并调用 OpenAI 兼容接口core/llm.pySimpleAgent最简智能体形态持有 system_prompt llm tool_registry接收文本输入并返回结果框架顶层导出从框架源码可以确认三个对本项目至关重要的设计细节第一参数优先环境变量兜底的配置哲学。core/llm.py 中HelloAgentsLLM.__init__依次读取LLM_MODEL_ID、LLM_TIMEOUT、LLM_API_KEY、LLM_BASE_URL环境变量未显式传入参数时全部走环境变量这与本项目在 Notebook 里用os.environ配置四个变量的做法完全吻合。超时时间默认值为 60 秒os.getenv(LLM_TIMEOUT, 60)与本项目设置一致。第二自动检测 provider。框架会根据 API Key 前缀如ms-识别为 ModelScope、base_url 域名如api-inference.modelscope.cn自动判断服务商core/llm.py因此用户只需配好四个通用环境变量即可。第三工具参数的结构化描述。ToolParameter在框架中是一个 PydanticBaseModeltools/base.pyTool.to_openai_schema()会将其转换为标准的 OpenAI function calling schematools/base.py这正是 LLM 能够读懂工具参数并正确填写 JSON 的关键。而ToolRegistry则提供register_tool、get_tools_description、execute_tool等能力tools/registry.pyAgent 通过它管理自己的全部工具。四、第一步定义StoryGeneratorTool自定义工具故事生成的核心能力被封装为一个自定义工具StoryGeneratorTool它继承自Tool需要实现两个方法run()真正执行生成与get_parameters()声明工具参数。完整版第2部分的代码如下from hello_agents import SimpleAgent, HelloAgentsLLM from hello_agents.tools import Tool, ToolParameter from typing import Dict, Any, List import os class StoryGeneratorTool(Tool): def __init__(self): super().__init__(namestory_generator, description根据用户输入生成不同类型的故事内容) def run(self, parameters: Dict[str, Any]) - str: # 获取用户输入参数 story_type parameters.get(type, 小说) theme parameters.get(theme, 奇幻冒险) style parameters.get(style, 轻松幽默) # 构造提示词 prompt f生成一个{story_type}主题是{theme}风格为{style}。 # 添加类型特定的指导 if story_type 小说: prompt 请使用小说格式以第三人称叙述包含完整的情节发展和人物描写。 elif story_type 剧本: prompt 请使用剧本格式包含场景描述、角色对话和动作指示。 elif story_type 诗歌: prompt 请使用诗歌格式注意押韵和节奏感。 # 调用LLM生成故事 llm HelloAgentsLLM() response llm.generate_text(prompt, max_tokens1024) return response def get_parameters(self) - List[ToolParameter]: return [ ToolParameter(nametype, typestring, description故事类型小说/剧本/诗歌, requiredTrue), ToolParameter(nametheme, typestring, description故事主题, requiredTrue), ToolParameter(namestyle, typestring, description故事风格, requiredTrue) ]这段代码有三个值得展开的实战要点1. 参数默认值兜底。run()内使用parameters.get(type, 小说)的形式取参即使 LLM 或上游遗漏了某个字段也能退回到奇幻冒险、轻松幽默等合理默认值保证工具不会因缺参而崩溃。对应到框架层面Tool.validate_parameters()会用get_parameters()中requiredTrue的参数名做存在性校验tools/base.py双重保险。2. 按文体定制提示词分支。这是完整版相较快速演示版的核心增强——根据story_type追加不同的格式指导小说第三人称叙述完整的情节发展和人物描写剧本场景描述、角色对话、动作指示诗歌押韵和节奏感。这一设计直接回应了项目总结中提到的核心挑战——确保不同故事类型格式的准确性和合适的文本内容量。3. 统一调用 LLM。工具内部直接实例化HelloAgentsLLM()并调用generate_text(prompt, max_tokens1024)模型、密钥、地址全部复用第1部分设置的环境变量。max_tokens1024为故事生成预留了充足的输出长度。五、第二步设计系统提示词与创建智能体工具就绪后需要通过ToolRegistry注册再装配进SimpleAgent。第3部分给出了完整代码# 定义系统提示词 system_prompt 你是一位经验丰富的故事创作者能够根据用户提供的参数生成不同类型的故事内容。 你的任务是 1. 根据用户指定的故事类型小说/剧本/诗歌生成相应格式的内容 2. 确保故事符合用户指定的主题和风格 3. 保持故事的连贯性和创意性 4. 根据需要使用预设的故事元素库 生成故事时请注意 - 小说以第三人称叙述包含完整的情节发展和人物描写 - 剧本使用标准剧本格式包含场景描述、角色对话和动作指示 - 诗歌注意押韵和节奏感使用生动的意象和比喻 请直接输出生成的故事内容无需添加任何额外说明或解释。 # 导入工具注册表 from hello_agents import ToolRegistry # 创建工具注册表 tool_registry ToolRegistry() tool_registry.register_tool(StoryGeneratorTool()) # 创建智能体 agent SimpleAgent( name智能故事生成器, llmHelloAgentsLLM(), system_promptsystem_prompt, tool_registrytool_registry ) print(✅ 智能体创建完成) print(f智能体名称: {agent.name}) print(f可用工具: {list(tool_registry._tools.keys())})这段装配代码说明了一个清晰的分层结构system_prompt是智能体的人设与规则手册它不仅定义了经验丰富的故事创作者这一角色还通过你的任务是 1/2/3/4给出行动清单通过生成故事时请注意给出文体格式规范最后用请直接输出生成的故事内容无需添加任何额外说明约束输出纯净度——这一句对下游直接展示故事至关重要。ToolRegistry是工具的中转站register_tool()将story_generator注册进注册表。框架源码中注册表还提供了unregister、get_tool、execute_tool、list_tools、get_tools_description等接口tools/registry.py并内置了一个全局注册表global_registry供多智能体场景共享tools/registry.py。SimpleAgent是总装配线将名称、LLM、系统提示词、工具注册表四个要素组合起来。框架源码中Agent基类还会自动维护对话历史self._history并支持stream_run流式输出core/agent.py即每轮agent.run()都会把用户输入与智能体回复记入历史为多轮创作对话留出了扩展空间。六、第三步三种文体的生成实战第4部分封装了一个生成入口函数def generate_story(agent, parameters): # 生成故事 story agent.run(f请根据以下参数生成一个故事\n{, .join([f- {k}: {v} for k, v in parameters.items()])}) # 返回故事内容 return storyagent.run()接收一个自然语言指令智能体内部会结合system_prompt、工具注册表中的story_generator工具描述以及用户参数自主完成调用工具→生成故事的闭环。然后按文体分别构造参数并调用# 小说参数 novel_parameters { type: 小说, theme: 魔法森林中的冒险, style: 轻松幽默 } print( 生成小说示例 ) novelStory generate_story(agent, novel_parameters) print(novelStory)# 剧本参数 script_parameters { type: 剧本, theme: 拯救被困的朋友, style: 悬疑紧张 } print( 生成剧本示例 ) scriptStory generate_story(agent, script_parameters) print(scriptStory)# 诗歌参数 poem_parameters { type: 诗歌, theme: 彩虹山的美景, style: 浪漫温馨 } print( 生成诗歌示例 ) poemStory generate_story(agent, poem_parameters) print(poemStory)三个示例覆盖了三种文体 × 三种风格 × 三个主题的组合轻松幽默的小说冒险、悬疑紧张的剧本救援、浪漫温馨的诗歌美景。想尝试新的组合只需修改generate_story()的参数例如{type: 小说, theme: 赛博朋克都市, style: 冷峻暗黑}即可零代码改动地生成全新故事。七、第0部分三分钟快速演示版如果不关心工程细节、只想快速验证效果Notebook 的第0部分提供了精简路径先用input()交互式收集三个参数# 选择故事类型小说/剧本/诗歌 story_type input(请输入故事类型小说/剧本/诗歌: ) # 输入故事主题 theme input(请输入故事主题: ) # 选择故事风格 style input(请输入故事风格: )再复用相同的导入、工具定义与装配代码此处StoryGeneratorTool使用不携带类型特定指导分支的简化版最后直接把用户输入拼进指令print( 开始生成故事 ) story agent.run(f请根据以下参数生成一个故事\n- 类型{story_type}\n- 主题{theme}\n- 风格{style}) print(story) print(\n✅ 故事生成完成)快速版与完整版的差异点如下这也是理解本项目设计取舍的关键对比维度第0部分快速演示第1~4部分完整版参数来源input()交互式键盘输入代码中直接构造参数字典工具提示词基础版拼接一句话按文体追加格式指导分支系统提示词单行简版多段结构化完整版适用场景快速验证 / 演示正式使用 / 二次开发八、项目总结已实现功能、挑战与演进方向Notebook 第5部分对项目做了完整复盘这既是本项目的事实总结也是读者继续迭代的路线图。已实现的功能✅ 环境配置与 LLM 模型设置ModelScope 上以Qwen/Qwen2.5-72B-Instruct为默认模型✅ 小说/剧本/诗歌三种故事类型生成✅ 根据用户指定主题和风格定制故事内容✅ 交互式参数输入和故事生成开发中遇到的挑战确保不同故事类型格式的准确性和合适的文本内容量字数——解决手段就是上文按文体追加格式指导的提示词分支处理不同风格故事的语言特点——需要让模型在轻松幽默与悬疑紧张等风格间保持稳定输出。未来改进方向扩展故事元素库增加更多角色、地点和情节支持用户自定义故事元素添加故事优化功能如语法检查和风格统一实现多语言故事生成支持添加故事可视化功能如场景图或角色关系图。九、小结通过 laoyouf-aistory 这个共创项目可以清晰地看到 HelloAgents 框架以工具为中心的开发范式把领域能力生成故事封装为Tool用ToolParameter声明参数契约经ToolRegistry注册最终由SimpleAgent连同系统提示词一起编排执行。整个项目仅依赖hello-agents[all]0.2.7一个核心包却完整覆盖了环境配置、工具定义、智能体装配、多文体生成与交互式输入的全部环节是学习 HelloAgents 框架入门开发的最佳样例之一。读者可直接运行 main.ipynb 体验效果也可以参考仓库中其他共创项目的框架用法如 hello_agents 工具与注册表源码在此基础上进一步扩展自己的文体、元素库与可视化能力。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考