沉浸式角色扮演智能体实战基于 OpenAI 兼容 API 的角色设定与对话管理hello-agents 共创项目解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents本文围绕《从零开始构建智能体》共创项目中的 megg-ops-roleplay_agent 展开系统讲解一个纯 Python 实现的沉浸式角色扮演智能体如何通过环境变量接入任意兼容 OpenAI API 格式的模型服务、如何通过系统提示词工程塑造角色人格、如何管理多轮对话历史并支持角色切换与对话重置。读完本文你将掌握从零构建一个可运行、可扩展的对话式角色扮演 Agent 的完整方案并能直接复现仓库中的全部代码。项目定位与功能特性megg-ops-roleplay_agent是一个基于 Python 的沉浸式角色扮演智能体Roleplay Agent核心交互方式为用户在终端中输入角色名称、来源作品、性格特质可选开场白智能体随即化身该角色以不打破第四面墙的方式与用户进行多轮中文对话。从 README.md 与 roleplay_agent.py 可以确认其核心特性高度自定义的角色设定角色名称、来源作品、性格特质、开场白均可由用户逐项输入模型无关底层只依赖 OpenAI 官方 SDK因此任何兼容 OpenAI API 格式的服务OpenAI、Azure OpenAI、Anthropic Claude 兼容层、Ollama、LocalAI 等都可以直接接入沉浸式对话系统提示词明确要求永不打破第四面墙让模型完全以角色身份去反应、感受和说话多角色切换对话过程中输入new即可重新设定角色无需重启程序对话重置输入reset可清空当前对话历史但保留系统设定与开场白实现重新来过。环境要求与依赖安装根据 README 与 requirements.txt运行本项目需要Python 3.8 或更高版本一个兼容 OpenAI API 格式的模型服务 API 密钥仅两个第三方依赖openai1.0.0官方 OpenAI Python SDK1.x 版本注意 1.x 的客户端初始化方式与 0.x 差异较大python-dotenv1.0.0用于从.env文件加载环境变量。安装依赖pip install -r requirements.txt配置 API 信息.env环境变量项目通过python-dotenv加载.env文件中的配置在项目根目录创建.env并填入以下内容LLM_API_KEY你的实际API密钥 LLM_MODEL_ID模型ID (例如: gpt-3.5-turbo, claude-3-opus 等) LLM_BASE_URLAPI基础URL (可选如果是默认OpenAI则不需要)三个变量的含义如下表变量名是否必填说明源码中的默认值LLM_API_KEY必填AI 模型服务的 API 密钥无缺失时直接抛ValueErrorLLM_MODEL_ID必填要使用的模型 ID如gpt-4、claude-3-opusdefault-model未设置时使用占位值LLM_BASE_URL可选API 服务的基础 URL使用非标准 OpenAI 服务时必须配置None默认走 OpenAI 官方地址源码层面的配置加载逻辑在 roleplay_agent.py 的CharacterRoleplayAgent.__init__中可以看到具体实现load_dotenv() # 加载 .env 文件 api_key os.getenv(LLM_API_KEY) model_id os.getenv(LLM_MODEL_ID, default-model) base_url os.getenv(LLM_BASE_URL, None) if not api_key: raise ValueError(请设置 LLM_API_KEY 环境变量)值得注意的两个实现细节API 密钥缺失即快速失败构造函数中直接抛出ValueError避免带着空密钥继续运行这一设计保证了程序在启动阶段就能给出明确报错。base_url可选注入只有当LLM_BASE_URL被设置时才会把base_url传入OpenAI客户端。这正是兼容一切 OpenAI 格式服务的关键——只需把base_url指向自托管网关如 Ollama 的http://localhost:11434/v1、LocalAI 或 Azure 的 endpoint即可无缝切换后端模型而业务代码完全不用改动。使用指南从角色设定到沉浸式对话启动程序python roleplay_agent.py角色设定流程程序启动后会依次提示输入四项角色信息源码见 main 函数角色名称如孙悟空出自作品如西游记性格与特质如桀骜不驯机智勇敢嫉恶如仇……这段自由文本会原样注入系统提示词是决定角色说话风格的核心输入开场白可选直接回车则使用默认开场白*注视着你* 你是谁。对话中的控制命令对话循环支持以下内置命令对应 main 的 while 循环输入行为quit/exit/退出/退出对话退出程序并打印告别语new重新走一遍角色设定流程开始新的角色reset重置当前对话历史保留系统设定与开场白其他文本作为用户消息发给当前角色示例对话来自 README 欢迎使用沉浸式角色扮演智能体 首先让我们设置一个角色... 请输入角色名称 (例如孙悟空): 孙悟空 请输入角色出自作品 (例如西游记): 西游记 请输入角色性格与特质 (例如桀骜不驯机智勇敢嫉恶如仇...): 齐天大圣桀骜不驯机智勇敢嫉恶如仇。说话喜欢带俺老孙性格急躁但重情重义。拥有火眼金睛看不起凡夫俗子的繁文缛节。 请输入开场白 (可选直接回车使用默认): 嘿哪里来的小妖怪见到俺老孙还不快快报上名来 ✅ 成功初始化角色: 孙悟空 (来自 西游记) 孙悟空: 嘿哪里来的小妖怪见到俺老孙还不快快报上名来 开始对话吧输入 quit 或 exit 退出输入 new 开始新角色。 你: 你好大圣 孙悟空: *甩了甩金箍棒眯起火眼金睛打量着你* 哼看你倒有几分胆色敢跟俺老孙打招呼。说你是何方神圣来这花果山有何贵干俺老孙最近正愁没人陪我练练武艺呢源码级解析沉浸感从何而来系统提示词工程角色人格的骨架setup_character方法roleplay_agent.py是整份代码的灵魂。它把用户的四项输入组装成一段结构化的系统提示词其中包含六条关键指令这六条指令是保证沉浸式体验的核心 Prompt 设计保持角色设定永不打破第四面墙不要表现得像个 AI完全以角色身份反应、感受和说话积极主动不能只是被动回答用户的话必须主动推动对话发展提问引导几乎每次回复结尾都要包含相关问题、观察或行动引导用户继续回复、加深沉浸感语气风格调整词汇和句式以匹配角色的经典语气语境假设默认假设用户是在角色的世界里互动语言全程使用中文对话。从工程视角看这六条指令分别解决了角色扮演中常见的六大问题出戏、被动应答、对话枯竭、风格失真、语境错位与语言不一致堪称一套可复用的沉浸式角色扮演 Prompt 模板可以原样迁移到任何 Agent 框架中。对话历史的组织方式角色初始化时self.chat被构建为两条消息roleplay_agent.pyself.chat [ {role: system, content: system_instruction}, {role: assistant, content: self.character_config[opening_line]} ]设计要点开场白以assistant角色的身份预先放入历史这样用户看到的第一条消息就是角色自己的话而不是模型的空白等待——这是让对话第一眼就有沉浸感的巧妙细节。消息发送与生成参数send_message方法roleplay_agent.py负责真正的模型调用response self.client.chat.completions.create( modelself.model_id, messagesself.chat, temperature0.9, # 增加创造性 max_tokens1024 )两个生成参数的含义与调优建议temperature0.9高于默认值为角色回复注入更多随机性与创造性让同一角色面对同一句话时不会给出千篇一律的答案更接近活人的表现。若追求稳定可控如教学演示可调低至 0.60.7。max_tokens1024限制单次回复的最大 token 数防止角色长篇大论导致对话失去节奏也间接控制 API 调用成本。调用成功后用户的输入与模型的回复会依次 append 进self.chat形成完整的多轮上下文——这也是temperature之外决定角色记忆的另一关键整个对话历史始终随请求一起发送模型才能记得前面说过的话。异常处理上send_message捕获所有异常并打印错误、返回一句兜底回复抱歉我暂时无法回应请稍后再试。保证在 API 抖动时程序不崩溃、对话不断流。对话重置与角色切换的实现reset_conversationroleplay_agent.py将self.chat截断回[system 消息, 开场白消息]即清空记忆但保留人设。其前提条件是len(self.chat) 1避免在没有任何对话时误操作。角色切换new命令不创建新对象而是重新调用setup_character用新参数整体覆盖character_config并重建self.chat。CharacterRoleplayAgent实例全程复用因此只需一次 API 客户端初始化即可服务任意多个角色资源利用高效。支持的模型服务生态由于项目只依赖OpenAI官方 SDK 且base_url可配置理论上所有兼容 OpenAI Chat Completions 格式的服务均可开箱即用README 中明确列出的包括OpenAI GPT 系列直接使用官方地址.env中无需LLM_BASE_URLAzure OpenAI将LLM_BASE_URL指向 Azure 提供的 endpointAnthropic Claude通过 Anthropic 官方兼容层或第三方网关接入自托管模型如 Ollama、LocalAI 等本地推理服务把LLM_BASE_URL指向本机地址即可实现零成本离线角色扮演。这一设计意味着即使未来模型服务商更换只需修改.env三行配置角色设定代码与提示词模板完全无需变动。使用注意事项与调优建议来自 README 及代码实践的提醒请确保 API 密钥有效且具备相应模型的使用权限AI 生成内容可能包含虚构信息涉及事实性内容请理性对待注意 API 配额与费用长对话会因上下文累积而增大 token 消耗可定期使用reset控制成本根据所选模型服务的差异可调整temperature02 区间默认值越界时部分服务会报错、max_tokens等参数以获得最佳效果若使用本地模型如 Ollama模型本身的角色扮演能力参差不齐建议优先选择经过中文指令微调的模型LLM_MODEL_ID未设置时源码会回退到占位值default-model此值通常无法被真实服务识别生产使用请务必显式配置。技术栈与扩展方向本项目技术栈非常精简README 明示Python 3.8OpenAI Python SDK1.xpython-dotenv环境变量管理基于现有源码结构可以自然延伸出以下增强方向仅作思路参考不涉及对仓库的修改角色库持久化将角色配置序列化为 JSON 存档支持一键载入预设角色多轮记忆压缩当对话历史超过上下文窗口时用摘要替换早期消息角色声音与表情在send_message返回后追加 TTS 语音合成与表情标记渲染Web 化将终端交互迁移为 Gradio/Streamlit 界面或包装为 FastAPI 服务供上层 Agent 调用。许可证本项目仅供学习和研究使用见 README.md 末尾声明。整套代码仅约 170 行却完整覆盖了环境配置—角色建模—提示词工程—多轮对话管理—交互控制的 Agent 最小闭环非常适合作为学习 Agent 对话系统、OpenAI SDK 用法以及角色扮演 Prompt 设计的入门范本。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 沉浸式角色扮演智能体实战：基于 OpenAI 兼容 API 的角色设定与对话管理（hello-agents 共创项目解析）
沉浸式角色扮演智能体实战基于 OpenAI 兼容 API 的角色设定与对话管理hello-agents 共创项目解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents本文围绕《从零开始构建智能体》共创项目中的 megg-ops-roleplay_agent 展开系统讲解一个纯 Python 实现的沉浸式角色扮演智能体如何通过环境变量接入任意兼容 OpenAI API 格式的模型服务、如何通过系统提示词工程塑造角色人格、如何管理多轮对话历史并支持角色切换与对话重置。读完本文你将掌握从零构建一个可运行、可扩展的对话式角色扮演 Agent 的完整方案并能直接复现仓库中的全部代码。项目定位与功能特性megg-ops-roleplay_agent是一个基于 Python 的沉浸式角色扮演智能体Roleplay Agent核心交互方式为用户在终端中输入角色名称、来源作品、性格特质可选开场白智能体随即化身该角色以不打破第四面墙的方式与用户进行多轮中文对话。从 README.md 与 roleplay_agent.py 可以确认其核心特性高度自定义的角色设定角色名称、来源作品、性格特质、开场白均可由用户逐项输入模型无关底层只依赖 OpenAI 官方 SDK因此任何兼容 OpenAI API 格式的服务OpenAI、Azure OpenAI、Anthropic Claude 兼容层、Ollama、LocalAI 等都可以直接接入沉浸式对话系统提示词明确要求永不打破第四面墙让模型完全以角色身份去反应、感受和说话多角色切换对话过程中输入new即可重新设定角色无需重启程序对话重置输入reset可清空当前对话历史但保留系统设定与开场白实现重新来过。环境要求与依赖安装根据 README 与 requirements.txt运行本项目需要Python 3.8 或更高版本一个兼容 OpenAI API 格式的模型服务 API 密钥仅两个第三方依赖openai1.0.0官方 OpenAI Python SDK1.x 版本注意 1.x 的客户端初始化方式与 0.x 差异较大python-dotenv1.0.0用于从.env文件加载环境变量。安装依赖pip install -r requirements.txt配置 API 信息.env环境变量项目通过python-dotenv加载.env文件中的配置在项目根目录创建.env并填入以下内容LLM_API_KEY你的实际API密钥 LLM_MODEL_ID模型ID (例如: gpt-3.5-turbo, claude-3-opus 等) LLM_BASE_URLAPI基础URL (可选如果是默认OpenAI则不需要)三个变量的含义如下表变量名是否必填说明源码中的默认值LLM_API_KEY必填AI 模型服务的 API 密钥无缺失时直接抛ValueErrorLLM_MODEL_ID必填要使用的模型 ID如gpt-4、claude-3-opusdefault-model未设置时使用占位值LLM_BASE_URL可选API 服务的基础 URL使用非标准 OpenAI 服务时必须配置None默认走 OpenAI 官方地址源码层面的配置加载逻辑在 roleplay_agent.py 的CharacterRoleplayAgent.__init__中可以看到具体实现load_dotenv() # 加载 .env 文件 api_key os.getenv(LLM_API_KEY) model_id os.getenv(LLM_MODEL_ID, default-model) base_url os.getenv(LLM_BASE_URL, None) if not api_key: raise ValueError(请设置 LLM_API_KEY 环境变量)值得注意的两个实现细节API 密钥缺失即快速失败构造函数中直接抛出ValueError避免带着空密钥继续运行这一设计保证了程序在启动阶段就能给出明确报错。base_url可选注入只有当LLM_BASE_URL被设置时才会把base_url传入OpenAI客户端。这正是兼容一切 OpenAI 格式服务的关键——只需把base_url指向自托管网关如 Ollama 的http://localhost:11434/v1、LocalAI 或 Azure 的 endpoint即可无缝切换后端模型而业务代码完全不用改动。使用指南从角色设定到沉浸式对话启动程序python roleplay_agent.py角色设定流程程序启动后会依次提示输入四项角色信息源码见 main 函数角色名称如孙悟空出自作品如西游记性格与特质如桀骜不驯机智勇敢嫉恶如仇……这段自由文本会原样注入系统提示词是决定角色说话风格的核心输入开场白可选直接回车则使用默认开场白*注视着你* 你是谁。对话中的控制命令对话循环支持以下内置命令对应 main 的 while 循环输入行为quit/exit/退出/退出对话退出程序并打印告别语new重新走一遍角色设定流程开始新的角色reset重置当前对话历史保留系统设定与开场白其他文本作为用户消息发给当前角色示例对话来自 README 欢迎使用沉浸式角色扮演智能体 首先让我们设置一个角色... 请输入角色名称 (例如孙悟空): 孙悟空 请输入角色出自作品 (例如西游记): 西游记 请输入角色性格与特质 (例如桀骜不驯机智勇敢嫉恶如仇...): 齐天大圣桀骜不驯机智勇敢嫉恶如仇。说话喜欢带俺老孙性格急躁但重情重义。拥有火眼金睛看不起凡夫俗子的繁文缛节。 请输入开场白 (可选直接回车使用默认): 嘿哪里来的小妖怪见到俺老孙还不快快报上名来 ✅ 成功初始化角色: 孙悟空 (来自 西游记) 孙悟空: 嘿哪里来的小妖怪见到俺老孙还不快快报上名来 开始对话吧输入 quit 或 exit 退出输入 new 开始新角色。 你: 你好大圣 孙悟空: *甩了甩金箍棒眯起火眼金睛打量着你* 哼看你倒有几分胆色敢跟俺老孙打招呼。说你是何方神圣来这花果山有何贵干俺老孙最近正愁没人陪我练练武艺呢源码级解析沉浸感从何而来系统提示词工程角色人格的骨架setup_character方法roleplay_agent.py是整份代码的灵魂。它把用户的四项输入组装成一段结构化的系统提示词其中包含六条关键指令这六条指令是保证沉浸式体验的核心 Prompt 设计保持角色设定永不打破第四面墙不要表现得像个 AI完全以角色身份反应、感受和说话积极主动不能只是被动回答用户的话必须主动推动对话发展提问引导几乎每次回复结尾都要包含相关问题、观察或行动引导用户继续回复、加深沉浸感语气风格调整词汇和句式以匹配角色的经典语气语境假设默认假设用户是在角色的世界里互动语言全程使用中文对话。从工程视角看这六条指令分别解决了角色扮演中常见的六大问题出戏、被动应答、对话枯竭、风格失真、语境错位与语言不一致堪称一套可复用的沉浸式角色扮演 Prompt 模板可以原样迁移到任何 Agent 框架中。对话历史的组织方式角色初始化时self.chat被构建为两条消息roleplay_agent.pyself.chat [ {role: system, content: system_instruction}, {role: assistant, content: self.character_config[opening_line]} ]设计要点开场白以assistant角色的身份预先放入历史这样用户看到的第一条消息就是角色自己的话而不是模型的空白等待——这是让对话第一眼就有沉浸感的巧妙细节。消息发送与生成参数send_message方法roleplay_agent.py负责真正的模型调用response self.client.chat.completions.create( modelself.model_id, messagesself.chat, temperature0.9, # 增加创造性 max_tokens1024 )两个生成参数的含义与调优建议temperature0.9高于默认值为角色回复注入更多随机性与创造性让同一角色面对同一句话时不会给出千篇一律的答案更接近活人的表现。若追求稳定可控如教学演示可调低至 0.60.7。max_tokens1024限制单次回复的最大 token 数防止角色长篇大论导致对话失去节奏也间接控制 API 调用成本。调用成功后用户的输入与模型的回复会依次 append 进self.chat形成完整的多轮上下文——这也是temperature之外决定角色记忆的另一关键整个对话历史始终随请求一起发送模型才能记得前面说过的话。异常处理上send_message捕获所有异常并打印错误、返回一句兜底回复抱歉我暂时无法回应请稍后再试。保证在 API 抖动时程序不崩溃、对话不断流。对话重置与角色切换的实现reset_conversationroleplay_agent.py将self.chat截断回[system 消息, 开场白消息]即清空记忆但保留人设。其前提条件是len(self.chat) 1避免在没有任何对话时误操作。角色切换new命令不创建新对象而是重新调用setup_character用新参数整体覆盖character_config并重建self.chat。CharacterRoleplayAgent实例全程复用因此只需一次 API 客户端初始化即可服务任意多个角色资源利用高效。支持的模型服务生态由于项目只依赖OpenAI官方 SDK 且base_url可配置理论上所有兼容 OpenAI Chat Completions 格式的服务均可开箱即用README 中明确列出的包括OpenAI GPT 系列直接使用官方地址.env中无需LLM_BASE_URLAzure OpenAI将LLM_BASE_URL指向 Azure 提供的 endpointAnthropic Claude通过 Anthropic 官方兼容层或第三方网关接入自托管模型如 Ollama、LocalAI 等本地推理服务把LLM_BASE_URL指向本机地址即可实现零成本离线角色扮演。这一设计意味着即使未来模型服务商更换只需修改.env三行配置角色设定代码与提示词模板完全无需变动。使用注意事项与调优建议来自 README 及代码实践的提醒请确保 API 密钥有效且具备相应模型的使用权限AI 生成内容可能包含虚构信息涉及事实性内容请理性对待注意 API 配额与费用长对话会因上下文累积而增大 token 消耗可定期使用reset控制成本根据所选模型服务的差异可调整temperature02 区间默认值越界时部分服务会报错、max_tokens等参数以获得最佳效果若使用本地模型如 Ollama模型本身的角色扮演能力参差不齐建议优先选择经过中文指令微调的模型LLM_MODEL_ID未设置时源码会回退到占位值default-model此值通常无法被真实服务识别生产使用请务必显式配置。技术栈与扩展方向本项目技术栈非常精简README 明示Python 3.8OpenAI Python SDK1.xpython-dotenv环境变量管理基于现有源码结构可以自然延伸出以下增强方向仅作思路参考不涉及对仓库的修改角色库持久化将角色配置序列化为 JSON 存档支持一键载入预设角色多轮记忆压缩当对话历史超过上下文窗口时用摘要替换早期消息角色声音与表情在send_message返回后追加 TTS 语音合成与表情标记渲染Web 化将终端交互迁移为 Gradio/Streamlit 界面或包装为 FastAPI 服务供上层 Agent 调用。许可证本项目仅供学习和研究使用见 README.md 末尾声明。整套代码仅约 170 行却完整覆盖了环境配置—角色建模—提示词工程—多轮对话管理—交互控制的 Agent 最小闭环非常适合作为学习 Agent 对话系统、OpenAI SDK 用法以及角色扮演 Prompt 设计的入门范本。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考