赛博小镇基于 HelloAgents 与 Godot 的多智能体 AI NPC 对话系统实战解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents本篇技术指南聚焦《从零开始构建智能体》教程第 15 章的配套开源案例——赛博小镇Helloagents-AI-Town一个将 HelloAgents 多智能体框架与 Godot 游戏引擎结合的 2D 像素风 AI 小镇模拟项目。文中将从项目架构、环境搭建、NPC 智能体构建、记忆与好感度系统、批量自主行为、日志体系到前后端通信完整还原每个模块的源码实现与配置细节读完你即可在本地跑起一个会记忆、有感情、能自主生活的 AI 小镇并掌握把多智能体系统接入游戏引擎的通用套路。项目概览三个会生活的 AI NPC赛博小镇基于 HelloAgents 框架构建展示多智能体系统在游戏中的落地应用。项目在 Datawhale 办公室场景中部署了3 个拥有独立人格的 AI NPCPython 工程师张三、产品经理李四和 UI 设计师王五。每个 NPC 都是一个独立的SimpleAgent实例具备以下核心能力智能对话系统玩家可以用自然语言与任意 NPC 交流NPC 根据角色设定与互动历史做出回应记忆系统短期工作记忆 长期情景记忆两级记忆能够记住与玩家的互动历史好感度系统5 个关系等级NPC 对玩家的态度随互动动态变化NPC 自主行为闲逛、工作等背景对话让小镇活起来完整日志系统所有对话与互动被完整记录便于调试与分析。项目的完整工程位于仓库 code/chapter15/Helloagents-AI-Town 目录其中backend/为 Python 后端helloagents-ai-town/为 Godot 游戏工程。技术栈与四层架构项目采用游戏引擎 后端服务的分离式架构技术栈如下层次技术选型职责前端层Godot 4.x推荐 4.2游戏渲染、玩家控制、NPC 显示、对话 UI后端层FastAPI Python 3.10API 路由、NPC 状态管理、对话处理、日志记录智能体层HelloAgents 框架NPC 智能、记忆管理、好感度计算外部服务层LLM API / Qdrant / SQLite对话生成、向量存储、数据持久化整体数据流转为玩家在 Godot 中按 E 键与 NPC 互动 → Godot 通过 HTTP API 将请求发送到 FastAPI 后端 → 后端调用 HelloAgents 的SimpleAgent处理对话先检索记忆再调用 LLM 生成回复→ 后端更新好感度并写日志 → 返回回复给前端展示。架构图如下前端 Godot 工程中的场景与脚本组织可参考 scripts 目录说明player.gd负责移动与交互、npc.gd负责巡逻与对话气泡、dialogue_ui.gd负责对话框、api_client.gd负责与后端通信、main.gd负责全局协调。环境准备与 5 分钟快速启动系统要求操作系统Windows 10/11、macOS、LinuxGodot4.2推荐 4.3Python3.10Git可选用于克隆仓库。步骤 1获取项目git clone https://gitcode.com/datawhalechina/hello-agents # 进入本章案例目录 cd hello-agents/code/chapter15/Helloagents-AI-Town也可以直接下载仓库 ZIP 包后解压到任意目录。步骤 2安装 Godot从 Godot 官网下载 4.2 版本Windows 提供.exe直开文件macOS 提供.dmg文件解压运行即可。之后在 Godot 中点击导入选择Helloagents-AI-Town/helloagents-ai-town/scenes/main.tscn点击导入并编辑。步骤 3配置 Python 环境cd backend python -m venv venv # Windows 激活虚拟环境 venv\Scripts\activate # macOS/Linux 激活虚拟环境 source venv/bin/activate # 安装依赖 pip install -r requirements.txt依赖文件 backend/requirements.txt 中关键依赖包括fastapi0.104.0、uvicorn[standard]0.24.0、pydantic2.0.0、python-dotenv以及 HelloAgents 框架hello-agents0.2.4,0.2.9。随后安装 HelloAgents 框架cd ../HelloAgents pip install -e . cd ../backend步骤 4配置环境变量cp .env.example .env仓库提供的 backend/.env.example 默认推荐使用 ModelScope 平台# HelloAgents LLM配置使用ModelScope API LLM_MODEL_IDQwen/Qwen2.5-72B-Instruct LLM_API_KEYyour-modelscope-api-key-here LLM_BASE_URLhttps://api-inference.modelscope.cn/v1/ # 其他可选模型 # LLM_MODEL_IDQwen/Qwen2.5-7B-Instruct # LLM_MODEL_IDdeepseek-ai/DeepSeek-V3 # 兼容 OpenAI 的服务也可用 # LLM_BASE_URLhttps://api.deepseek.com/v1 # LLM_MODEL_IDdeepseek-chat重要请务必将LLM_API_KEY替换为你自己的实际密钥。若使用其他 LLM 服务同时调整LLM_MODEL_ID与LLM_BASE_URL。此外 backend/config.py 会自动加载.env文件并提供以下配置项API_HOST 0.0.0.0、API_PORT 8000后端监听地址NPC_UPDATE_INTERVAL 30NPC 状态批量更新间隔秒LLM_MODEL_ID/LLM_API_KEY/LLM_BASE_URL从环境变量读取CORS_ORIGINS [*]跨域配置生产环境应限制具体域名。settings.validate()会在服务启动时检查LLM_API_KEY若未配置会给出警告——此时系统自动降级为预设对话模式基础功能仍可运行。步骤 5启动后端服务cd backend python main.py预期输出 对话日志文件: .../backend/logs/dialogue_2025-10-15.log 日志目录: .../backend/logs 赛博小镇后端服务启动中... ... ✅ 所有服务已启动! API地址: http://0.0.0.0:8000 API文档: http://0.0.0.0:8000/docs main.py中通过 FastAPI 的lifespan生命周期钩子完成初始化验证配置 → 初始化 NPC 管理器含记忆与好感度系统→ 启动状态管理器定时任务 → 打印 API 地址。也可以使用 uvicorn 直接启动uvicorn main:app --reload --host 0.0.0.0 --port 8000。步骤 6运行游戏在 Godot 编辑器中点击右上角运行按钮或按 F5游戏窗口打开后WASD移动玩家E与附近 NPC 交互出现按E交互提示时Enter发送消息ESC关闭对话框。游戏画面为一个像素风格的 Datawhale 办公室场景NPC 头顶会浮现对话气泡提示若游戏无法对话请确认后端服务正在运行、后端地址正确默认http://localhost:8000并查看 Godot 控制台错误信息。后端可通过http://localhost:8000/docs访问 Swagger 交互式 API 文档。NPC 智能体系统从角色设定到对话循环NPC 角色配置三个 NPC 的角色定义集中在 backend/agents.py 的NPC_ROLES字典中每个 NPC 包含职位、位置、活动、性格、专长、说话风格和爱好NPC_ROLES { 张三: { title: Python工程师, location: 工位区, activity: 写代码, personality: 技术宅,喜欢讨论算法和框架, expertise: 多智能体系统、HelloAgents框架、Python开发、代码优化, style: 简洁专业,喜欢用技术术语,偶尔吐槽bug, hobbies: 看技术博客、刷LeetCode、研究新框架 }, 李四: { title: 产品经理, location: 会议室, activity: 整理需求, personality: 外向健谈,善于沟通协调, ... }, 王五: { title: UI设计师, location: 休息区, activity: 喝咖啡, personality: 细腻敏感,注重美感, ... } }create_system_prompt()函数将这些配置渲染成结构化系统提示词包含角色设定、行为准则第一人称、30-50 字简洁回复、可表达情绪、不说我是 AI等和对话示例确保 NPC 扮演真实的办公室同事。NPCAgentManager 与对话流水线NPCAgentManager负责统一管理所有 NPC为每个 NPC 创建SimpleAgent实例与独立的MemoryManager并在 LLM 不可用时自动切换到模拟模式。其核心chat()方法完整串联了六大步骤日志系统全程埋点获取当前好感度从RelationshipManager读取关系等级与对话风格修饰词拼入上下文检索相关记忆调用memory_manager.retrieve_memories(querymessage, memory_types[working, episodic], limit5, min_importance0.3)构建增强提示词将好感度上下文、历史记忆与当前玩家消息拼装为enhanced_message生成回复agent.run(enhanced_message)调用 LLM分析并更新好感度调用analyze_and_update_affinity()将玩家消息与 NPC 回复交给情感分析 Agent保存对话到记忆将玩家消息importance0.5与 NPC 回复importance0.6以working类型写入记忆元数据中同时记录当时好感度、好感度变化量与情感倾向。# agents.py 中记忆检索与保存的关键代码 relevant_memories memory_manager.retrieve_memories( querymessage, memory_types[working, episodic], limit5, min_importance0.3 ) memory_manager.add_memory( contentf玩家说: {player_message}, memory_typeworking, importance0.5, metadata{ speaker: player, player_id: player_id, affinity: affinity, affinity_change: affinity_change, sentiment: sentiment, context: {interaction_type: dialogue, npc_name: npc_name} } )NPC 记忆系统短期 长期两级记忆核心功能工作记忆Working Memory短期存储最近 10 条对话约 2 小时后自动过期用于当前对话上下文检索快速情景记忆Episodic Memory长期持久化存储重要对话基于 Qdrant 向量数据库进行语义检索最多存 100 条记忆重要性低于 0.3 的记忆自动被遗忘记忆隔离每个 NPC 拥有独立记忆系统backend/memory_data/张三/、李四/、王五/三个目录NPC 之间互不干扰各玩家的对话也独立存储。记忆系统配置参数agents.py中_create_memory_manager()展示了完整的MemoryConfig配置memory_config MemoryConfig( storage_pathmemory_dir, # 存储路径按NPC隔离 working_memory_capacity10, # 工作记忆容量最近10条 working_memory_tokens2000, # 工作记忆token限制 max_capacity100, # 记忆总容量 importance_threshold0.3, # 重要性阈值 decay_factor0.95 # 时间衰减系数 ) memory_manager MemoryManager( configmemory_config, user_idnpc_name, # 以NPC名字作为user_id enable_workingTrue, # 启用短期工作记忆 enable_episodicTrue, # 启用长期情景记忆 enable_semanticFalse, # 不需要语义记忆 enable_perceptualFalse # 不需要感知记忆 )各参数含义与建议范围参数默认值建议范围说明working_memory_capacity105-20工作记忆容量越大越占内存working_memory_tokens20001000-4000Token 限制影响上下文长度max_capacity10050-500记忆总容量越大越占磁盘importance_threshold0.30.1-0.5重要性阈值越高越偏向保留重要记忆decay_factor0.950.8-0.99时间衰减系数越低越强调近期记忆记忆 API 接口POST /chat Content-Type: application/json {npc_name: 张三, message: 你好,你是做什么的?}GET /npcs/张三/memories?limit10 # 查看NPC记忆 DELETE /npcs/张三/memories?memory_typeworking # 清空记忆测试用其中GET响应返回记忆列表id、content、type、importance、timestamp、metadataDELETE支持按working/episodic类型定向清空不传则清空全部对应 backend/main.py 中clear_npc_memories的实现。NPC 好感度系统LLM 情感分析驱动的五级关系五级关系等级好感度值域为 0-100初始值为 50友好共分五个等级陌生0-20冷淡疏离不太愿意多说回答简短熟悉20-40礼貌但略显生疏回答简洁友好40-60礼貌友善正常交流保持专业亲密60-80友好热情愿意多聊会主动关心对方挚友80-100非常热情像老朋友一样亲切愿意分享私人话题。好感度变化规则好感度不靠固定加分而是由情感分析 Agent 根据对话内容动态判定对话类型变化量示例赞美、感谢、请教3 到 8你真棒! 谢谢你! 能教教我吗?友好问候、正常交流1 到 3你好! 最近怎么样?普通闲聊、中性话题0今天天气不错批评、质疑、不耐烦-3 到 -8这个不太好 真的吗?侮辱、攻击、恶意-8 到 -15你太烂了!好感度被严格限制在 0-100 区间等级跨越时会触发关系等级提升/降低事件如 56→64 时友好→亲密。RelationshipManager 源码实现backend/relationship_manager.py 中情感分析由一个独立的SimpleAgent(nameAffinityAnalyzer)承担其系统提示词明确规定了分析维度玩家态度、对话内容、互动质量、情感倾向与 JSON 输出格式# 情感分析Agent的输出格式 { should_change: true/false, change_amount: -15到10之间的整数, reason: 简短说明原因(10字以内), sentiment: positive/neutral/negative }analyze_and_update_affinity()的执行流程构建玩家消息 NPC 回复的分析提示 → 调用分析 Agent →_parse_analysis()解析 JSON依次尝试直接解析、截取大括号内容、正则提取三个回退策略→ 若should_change为 true 则更新好感度并判定新旧等级 → 返回包含old_affinity、new_affinity、change_amount、reason、sentiment、old_level、new_level的完整结果。若解析失败或分析异常系统会安全返回不改变的默认值不会中断对话流程。好感度最终通过get_affinity_modifier()生成的对话风格修饰词注入 NPC 的系统提示词实现好感度越高回复越热情的动态效果。好感度 API 接口GET /npcs/张三/affinity?player_idplayer # 获取单个NPC好感度 GET /affinities?player_idplayer # 获取所有NPC好感度 PUT /npcs/张三/affinity?affinity80player_idplayer # 设置好感度测试用PUT接口会校验好感度必须在 0-100 之间越界返回 400响应示例如{ message: 已设置张三对玩家的好感度, npc_name: 张三, player_id: player, affinity: 80.0, level: 挚友, modifier: 非常热情友好,像老朋友一样亲切,愿意分享私人话题 }若想调整好感度变化敏感度可修改 relationship_manager.py 中的情感分析提示词更敏感可将变化量范围调至 -20 到 15更保守可缩至 -5 到 5也可增加更多分析维度。NPC 自主行为批量生成 即时响应的混合模式批量对话生成器为了让 NPC 在无人交互时也活着闲逛、工作、自言自语项目实现了 backend/batch_generator.py。其核心思路是一次 LLM 调用生成全部 3 个 NPC 的对话并要求严格按 JSON 格式返回{张三: 这个bug真是见鬼了,已经调试两小时了..., 李四: 嗯,这个功能的优先级需要重新评估一下。, 王五: 这杯咖啡的拉花真不错,灵感来了!}提示词中会注入当前场景由_get_current_context()根据本地时间自动推断清晨/上午/午餐/下午/傍晚/夜晚以及每个 NPC 的职位、位置、活动与性格描述。相比逐个调用批量方式将每分钟 API 调用从 6 次降为 2 次3 NPC × 每 30 秒一次 → 1 次批量调用/30 秒成本降低约 66%见 backend/README.md。当 LLM 不可用时系统自动降级使用按时间段划分的preset_dialogues预设对话库。状态管理器backend/state_manager.py 的NPCStateManager负责定时调度启动时立即执行一次更新随后以NPC_UPDATE_INTERVAL默认 30 秒为间隔运行后台循环_auto_update_loop()将批量生成结果缓存到current_dialogues并通过以下接口暴露给前端GET /npcs/status # 获取所有NPC当前状态与更新倒计时 POST /npcs/status/refresh # 强制刷新一次混合模式的价值背景对话走批量生成玩家靠近 NPC 但未交互时NPC 显示正在调试代码...等背景对话成本低玩家交互走即时响应按 E 键后立即调用该 NPC 专属 Agent基于玩家的具体消息、历史记忆与好感度生成个性化回复质量高。这种预制菜 现炒的混合策略让 NPC 始终看起来生动同时保障交互质量与成本可控该思路可迁移到任何需要大量 AI 调用的场景。日志系统对话全程可视化双重输出与按日归档日志系统backend/logger.py使用 Pythonlogging标准库同时挂载文件 handler与控制台 handler实现双重输出日志按日期自动归档backend/logs/ ├── dialogue_2025-01-15.log ├── dialogue_2025-01-16.log └── dialogue_2025-01-17.log它自动记录对话开始/结束、玩家消息、当前好感度与关系等级、检索到的相关记忆、NPC 回复、好感度变化分析、关系等级变化、记忆保存确认。一次完整对话的日志形如14:30:25 - 14:30:25 - 对话开始: 张三 - 玩家 14:30:25 - 14:30:25 - 玩家消息: 你好,很高兴认识你! 14:30:25 - 当前好感度: 50.0/100 (友好) 14:30:25 - 检索到0条相关记忆 14:30:26 - 正在生成回复... 14:30:28 - 张三回复: 你好!我也很高兴认识你。我是Python工程师张三... 14:30:28 - 正在分析好感度变化... 14:30:30 - 好感度变化: 50.0 - 56.0 (6.0) 14:30:30 - 原因: 友好问候 14:30:30 - 情感: positive 14:30:30 - 对话已保存到张三的记忆中 14:30:30 - 14:30:30 - ✅ 对话完成日志查看工具backend/view_logs.py 提供三种子命令cd backend python view_logs.py tail # 实时查看类似 tail -fCtrlC 停止 python view_logs.py view # 查看今天完整日志 python view_logs.py list # 列出所有日志文件含大小与修改时间不传参数时默认进入tail实时查看模式。日志系统在教学与调试中的价值在于完整呈现玩家输入 → 记忆检索 → NPC 回复生成 → 好感度分析 → 记忆保存的对话流水线验证记忆与好感度系统是否按预期工作。后端 API 全景backend/main.py 使用 FastAPI Pydantic模型定义见 backend/models.py暴露了完整的 REST API方法路径说明GET/API 信息与端点列表GET/health健康检查POST/chat与 NPC 对话核心接口GET/npcs获取全部 NPC 列表GET/npcs/status获取 NPC 自主对话状态POST/npcs/status/refresh强制刷新 NPC 状态GET/npcs/{npc_name}获取单个 NPC 详情含当前对话GET/npcs/{npc_name}/memories查看 NPC 记忆DELETE/npcs/{npc_name}/memories清空 NPC 记忆GET/npcs/{npc_name}/affinity获取单个 NPC 好感度PUT/npcs/{npc_name}/affinity设置 NPC 好感度GET/affinities获取所有 NPC 好感度/chat接口的典型请求/响应POST /chat Content-Type: application/json {npc_name: 张三, message: 你好,你在做什么?}{ npc_name: 张三, npc_title: Python工程师, message: 你好!我正在写代码,调试一个多智能体系统的bug。, success: true, timestamp: 2024-01-15T10:30:00 }Godot 前端实现要点场景系统与脚本分工游戏采用 Godot 场景系统模块化组织main.tscn主场景、player.tscn玩家、npc.tscnNPC 通用模板三个 NPC 均为其实例通过export参数区分、dialogue_ui.tscn对话 UI。GDScript 语法与 Python 高度相似对 Python 开发者几乎零门槛。玩家控制与交互player.gd 使用CharacterBody2D实现 WASD 移动、四方向动画切换与碰撞检测通过add_to_group(player)注册到组NPC 的InteractionArea检测到玩家进出时调用set_nearby_npc()玩家按 E 键触发interact_with_npc()再通过get_tree().call_group(dialogue_system, start_dialogue, npc_name)通知对话系统。对话期间set_interacting(true)禁用移动。NPC 巡逻与对话气泡npc.gd 实现了 NPC 的自主巡逻在出生点wander_range默认 200 像素范围内随机选取目标每隔wander_interval_min~wander_interval_max3-8 秒更换一次目标点update_dialogue()接收主场景下发的背景对话并显示气泡10 秒后自动隐藏。API 客户端与对话 UIapi_client.gd 使用HTTPRequest节点异步通信为对话、状态、NPC 列表分别创建独立请求节点通过信号chat_response_received、npc_status_received等通知结果避免阻塞游戏主循环接口地址集中在 config.gdAPI_BASE_URL http://localhost:8000。dialogue_ui.gd 负责对话框的显示/隐藏、富文本对话渲染与发送逻辑并在对话框打开时屏蔽 WASD/E/空格等游戏按键防止误操作。main.gd 作为协调中枢每NPC_STATUS_UPDATE_INTERVAL30 秒拉取一次/npcs/status将各 NPC 的自主对话分发给对应节点更新气泡。配置 AutoLoad 单例在Project - Project Settings - AutoLoad中注册config.gd名称Config与api_client.gd名称APIClient即可在任何脚本中通过Config.API_CHAT、/root/APIClient访问。常见问题排查问题检查项后端启动失败Python 版本是否 ≥3.10、虚拟环境是否激活、依赖是否安装完整、.env是否配置正确Godot 无法打开项目Godot 版本是否 ≥4.2、project.godot是否存在、导入目录是否正确游戏运行但无法对话后端服务是否运行、地址是否默认http://localhost:8000、查看 Godot 控制台报错好感度没有变化对话是否过于中性、情感分析 Agent 是否判定无需改变、LLM 响应解析是否失败可用更明确的情感表达重试好感度变化过快/过慢修改relationship_manager.py中变化量范围、调整情感分析提示词、用PUT接口手动设置初始值NPC 记不住对话检查记忆系统初始化日志、memory_data目录是否存在、必要时调低importance_threshold总结与扩展方向赛博小镇完整演示了HelloAgents 多智能体框架 FastAPI 后端 Godot 前端的三层技术栈协作SimpleAgent提供 NPC 智能MemoryManagerSQLite Qdrant提供两级记忆RelationshipManager提供基于 LLM 情感分析的好感度系统NPCBatchGenerator与NPCStateManager提供低成本的自主行为logger.pyview_logs.py提供可视化调试。对应教材章节 docs/chapter15/第十五章 构建赛博小镇.md英文版见 Chapter15-Building-Cyber-Town.md给出了完整的逐步实现思路。项目本身具备清晰的可扩展空间接入 WebSocket 实现多人在线、为 NPC 设计基于好感度门槛的任务系统、增加 NPC 之间的互动对话、引入情绪系统、设计团队会议等动态事件或将世界从单一办公室扩展为多场景地图。本文所有源码均可在 code/chapter15/Helloagents-AI-Town 目录下直接查阅与运行配套的四份指南安装配置、对话日志、好感度系统、记忆系统可帮助你按模块逐步深入。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考