多Agent协作实战：6个AI Agent联手打造GTA风格开放世界沙盒原型

先从一段真实经历说起：年前我想在项目里做一个“GTA 风格”的开放世界小 DEMO——有小镇地图、有可以对话的 NPC、有任务、有载具刷出。传统做法是手动写地图数据、手动设计 NPC 行为、手动编排任务脚本，光是一个街区的手工资源就够写两周。后来我换了一个思路：把游戏内容生成拆成多个独立 AI Agent，让 6 个“AI 员工”各自负责一块，再用一个调度器统一协调，结果花了两天就把一个能跑起来的小镇 demo 搭出来了。这篇文章就用这个思路，完整拆解如何用 6 个 AI Agent 联手从零打造一个 GTA 风格的开放世界沙盒原型。

文章会覆盖以下核心内容：多 Agent 协作的架构设计、6 个 Agent 的分工与接口定义、具体到可运行的 Python 代码、本地无 Key 也能跑的 Mock 模式、常见报错排查、以及工程落地时的注意事项。无论你是刚接触 AI Agent 开发，还是已经做过一些 LLM 应用，都能从里面拿到可复用的套路。

1. 背景与核心概念

1.1 GTA 风格的开放世界游戏，复杂在哪里

GTA 类游戏的核心体验可以概括为：一张较大的可探索地图，一群行为各异的 NPC，一套能引导玩家持续游玩的任务系统，以及一些随机触发的事件。看起来简单，但要把这套东西用传统方式做出来，工作量非常惊人。

地图不是一张静态图片，而是分区域的街区、建筑、道路、室内场景。NPC 不是一段固定台词，而要根据时间、地点、玩家行为做出反应。任务也不是一条线写完就结束，而是需要设计前置条件、分支选择、失败判定、奖励发放。

这也是为什么传统开放世界项目的策划文档动辄上百页，程序侧还需要大量数据表、状态机、行为树。对于个人开发者或小型团队来说，这类项目的初期成本高到几乎无法启动。

如果把思路换一下：地图场景由 AI 根据 Prompt 生成，NPC 的人格和行为由 AI 动态推理，任务流程由 AI 根据玩家状态实时编排，那我们就能用极低的前期成本，快速搭出一个“看着像开放世界”的沙盒原型。这就是这篇文章要做的核心实验。

1.2 什么是 AI Agent，为什么需要多个 AI 联手

AI Agent 可以理解为一个“有目标、能调用工具、能循环处理任务”的智能体。它和单纯的 LLM 接口调用不同：调用一次 LLM 只是得到一段文本，而 Agent 是把大模型放进一个循环里，根据结果决定下一步动作，直到完成整个目标。

但一个 Agent 很难同时做好所有事情。场景生成需要较强的结构化输出能力，NPC 对话需要更自然的人设约束，任务编排需要记住玩家历史，资产筛选需要准确匹配本地资源文件。把这些职责都塞进同一个 Agent 里，提示词会越来越长，状态越来越混乱，最后生成的脚本经常互相矛盾。

所以更合理的做法是拆分：让每个 Agent 只负责一个专业领域，再用一个调度器管理它们的协作关系。这就像游戏工作室里有策划、美术、程序、测试一样，各司其职，才能稳定交付。

1.3 6 个 Agent 的分工总览

本文示例项目里，6 个 AI Agent 分别承担以下角色：

DirectorAgent 是“导演”，它不直接生成内容，而是根据当前游戏局面决定让哪个 Agent 输出什么。其余 5 个 Agent 是“执行者”，各自处理自己领域的生成任务。这样设计的好处是：每个 Agent 的 Prompt 都保持短小、稳定、可测试，单个 Agent 出错时也不影响整体流程。

2. 环境准备与版本说明

在开始写代码前，先把环境说明清楚。这里不会写死某个特定版本，因为 AI 相关库更新较快，不同机器上的环境差异也比较大。你只需要按你的实际环境微调即可。

2.1 基础环境

本文示例以 Python 3.10+ 常见环境为例，需要安装以下依赖：

pip install openai pyyaml rich

• openai：用于调用 OpenAI 兼容的大模型接口。
• pyyaml：用于读取 YAML 配置文件。
• rich：用于在终端中美化输出，方便演示运行结果。

如果你本地没有 OpenAI API Key，也可以使用 Mock 模式运行，示例代码里会内置一个MockLLM类，返回模拟结果。这样你可以不花一分钱也能完整跑通整个 Agent 调度流程。

2.2 大模型 API 配置

在项目根目录创建.env文件（注意生产项目中不要把.env提交到 Git）：

OPENAI_API_KEY=sk-xxxx OPENAI_API_BASE=https://api.openai.com/v1 OPENAI_MODEL=gpt-4o-mini

如果你使用的是国产大模型或开源模型部署的 OpenAI 兼容接口，只需要把OPENAI_API_BASE改成对应地址即可。代码里统一通过环境变量读取配置，不会写死模型地址。

2.3 项目结构规划

为了方便演示，我把项目设计成一个单机可运行的 Python 工程。目录结构如下：

my_ai_town/ ├── main.py # 入口程序 ├── config.yaml # 全局配置 ├── core/ │ ├── __init__.py │ ├── agent_manager.py # Agent 调度器 │ ├── base_agent.py # Agent 基础类 │ └── llm.py # LLM 调用封装与 Mock ├── agents/ │ ├── __init__.py │ ├── scene_agent.py │ ├── npc_agent.py │ ├── dialogue_agent.py │ ├── quest_agent.py │ ├── asset_agent.py │ └── director_agent.py ├── data/ │ ├── town_map.json # 场景 Agent 生成的输出 │ └── resources.json # 本地资源清单 └── output/ └── run_result.json # 运行结果

这个结构可以根据你自己的项目调整，但建议在开始写代码前先建立目录骨架，避免后面代码到处散落。

3. 核心架构与分工设计

3.1 调度器：Agent Manager

Agent Manager 是整个系统的中枢。它负责三件事：注册所有 Agent、初始化 LLM、根据事件调用对应 Agent。

我们可以设计一个简单的事件派发机制：Agent 之间不直接互相调用，而是把任务产出放进一个共享的事件队列，由调度器决定下一步执行哪个 Agent。这样各个 Agent 之间的耦合度低，新增一个 Agent 也不需要改动太多已有代码。

先来看 BaseAgent 这个基础类：

# 文件路径：core/base_agent.py from abc import ABC, abstractmethod class BaseAgent(ABC): def __init__(self, name: str, llm): self.name = name self.llm = llm @abstractmethod def run(self, context: dict) -> dict: """ 每个 Agent 子类都需要实现该方法。 context 是当前游戏上下文，包含地图数据、玩家状态、NPC 状态等。 返回值是一个 dict，调度器会将结果合并到全局状态中。 """ pass

每个 Agent 都是一个继承BaseAgent的类，只需要实现run方法。context里面存着游戏当前的全部状态，比如城镇地图、NPC 列表、玩家任务进度等。

3.2 六个 Agent 的职责与接口设计

接下来把每个 Agent 的职责和输入输出定义清楚。这一步非常重要，因为如果 Agent 的输入输出没有统一规范，后面的调度器会变得难以维护。

SceneAgent：输入是场景 Prompt（例如“生成一个海滨小镇”），输出是一个 JSON，包含城镇名称、区域列表、建筑列表和街道连接关系。

NPCAgent：输入是场景 Agent 生成的地图数据，输出是 NPC 列表。每个 NPC 包含姓名、年龄、职业、性格、日程模板。

DialogueAgent：输入是玩家当前所在场景、目标 NPC 的基本信息和历史对话，输出是 NPC 的下一句回复。

QuestAgent：输入是玩家当前状态和已完成任务，输出是当前可用的任务列表。

AssetAgent：输入是场景 Agent 的地图数据，输出是一个资源映射表，把“住宅楼”“便利店”“警局”等建筑类型映射到本地资源 ID。

DirectorAgent：输入是全局状态，输出是下一帧要触发的游戏事件，比如“在新手区刷出一辆载具”“引导玩家去便利店进货”。

3.3 全局状态与事件循环

为了让多个 Agent 协同工作，我们需要一个全局状态对象。它负责维护：

• 地图数据
• NPC 列表
• 玩家信息
• 任务列表
• 资源映射表
• 事件队列

调度器每次运行都会执行以下几个步骤：

1. 从事件队列中取出一个事件。
2. 根据事件类型决定调用哪个 Agent。
3. Agent 执行后返回结果，更新全局状态。
4. 判断是否继续循环。

整个过程用代码表达出来就是：

# 文件路径：core/agent_manager.py from rich.console import Console from core.base_agent import BaseAgent console = Console() class AgentManager: def __init__(self, global_state: dict): self.global_state = global_state self.agents = {} self.event_queue = [] def register_agent(self, agent: BaseAgent): self.agents[agent.name] = agent console.print(f"[bold green]注册 Agent: {agent.name}[/bold green]") def push_event(self, event: dict): self.event_queue.append(event) def run(self): while self.event_queue: event = self.event_queue.pop(0) agent_name = event["agent"] context = { "state": self.global_state, "event": event, } if agent_name in self.agents: result = self.agents[agent_name].run(context) self.global_state.update(result) console.print(f"[bold yellow]{agent_name} 执行完成[/bold yellow]") console.print(result)

需要注意，这里没有使用复杂的消息队列或异步框架，因为对于单机 demo 来说，同步执行已经足够清晰。后续如果要扩展为服务端架构，可以把event_queue替换成 Redis Stream 或 RabbitMQ。

4. 完整实战案例：6 个 Agent 联手打造 AI 小镇

4.1 创建项目结构与配置

首先建立项目目录，并创建config.yaml：

# 文件路径：config.yaml app: name: my_ai_town description: 6 个 AI Agent 联手生成的 GTA 风格沙盒小镇 agent: # 是否使用 Mock 模式，不需要真实 API Key mock: true # 每个 Agent 的生成轮次 max_rounds: 3 llm: temperature: 0.8 max_tokens: 1024

把mock设置为true时，程序不会调用真实大模型，而是使用内置规则生成结果。这样做的目的是让读者在没有 API Key 的情况下也能先跑通整个调度流程，再替换成真实模型。

4.2 编写 LLM 封装与 Mock 模式

在core/llm.py中，我们把模型调用封装起来。核心思路是：如果配置文件里mock为 true，就调用 mock 类返回固定结构的模拟数据；否则调用 OpenAI 客户端。

# 文件路径：core/llm.py import json import os from openai import OpenAI class MockLLM: def chat(self, messages, temperature=0.8, max_tokens=1024): # 模拟返回，方便无 Key 环境运行 content = """ { "status": "mock", "message": "这是 Mock 模式生成的模拟回复", "data": {} } """ return content class LLMClient: def __init__(self, mock: bool = True): self.mock = mock if not mock: self.client = OpenAI( api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_API_BASE"), ) else: self.mock_llm = MockLLM() def chat(self, system_prompt: str, user_prompt: str, temperature=0.8, max_tokens=1024): if self.mock: return self.mock_llm.chat( messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}, ], temperature=temperature, max_tokens=max_tokens, ) response = self.client.chat.completions.create( model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"), messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}, ], temperature=temperature, max_tokens=max_tokens, ) return response.choices[0].message.content

这个设计模式是 AI 工程实践里的常见套路：先做一层本地模拟，再逐步替换成真实模型。开发阶段用 Mock，联调阶段切真实 API，成本低且不容易阻塞开发。

4.3 实现 SceneAgent：生成小镇地图

SceneAgent 是整个项目的第一个执行者。它的目标是生成一份结构化的小镇地图配置。先用大白话解释一下为什么需要结构化输出：游戏引擎无法直接执行“生成一个漂亮的小镇”这样的自然语言指令，它需要的是具体的区域名称、建筑列表、坐标点。所以 SceneAgent 的 Prompt 必须强调输出 JSON 格式。

# 文件路径：agents/scene_agent.py import json from core.base_agent import BaseAgent class SceneAgent(BaseAgent): def run(self, context: dict) -> dict: state = context["state"] event = context["event"] town_name = event.get("town_name", "洛圣都小镇") scene_prompt = ( f"你是一个开放世界游戏地图策划师。请为名为 {town_name} 的小镇生成地图配置。" "要求包含 5 个区域，每个区域包含 3 个建筑，并描述建筑之间的道路连接。" "严格输出 JSON，不要输出多余文本。" "JSON 结构如下：" '{"town_name":"","areas":[{"name":"","description":"","buildings":[{"name":"","type":"","position":[x,y]}]}]}' ) result_text = self.llm.chat( system_prompt="你只负责输出 JSON，不输出任何解释。", user_prompt=scene_prompt, ) # 去掉可能出现的 markdown 代码块标记 cleaned = result_text.strip().replace("```json", "").replace("```", "") try: scene_data = json.loads(cleaned) except json.JSONDecodeError: # Mock 或模型输出不合法时的兜底数据 scene_data = self._fallback_scene(town_name) return {"scene": scene_data, "current_area": scene_data["areas"][0]["name"]} def _fallback_scene(self, town_name): return { "town_name": town_name, "areas": [ { "name": "中央广场", "description": "小镇最热闹的区域，周围是商店和餐馆。", "buildings": [ {"name": "市政厅", "type": "government", "position": [0, 0]}, {"name": "便利店", "type": "shop", "position": [1, 0]}, {"name": "咖啡馆", "type": "cafe", "position": [0, 1]}, ], }, { "name": "住宅区", "description": "安静的居民区，适合休息。", "buildings": [ {"name": "住宅楼 A", "type": "house", "position": [3, 3]}, {"name": "住宅楼 B", "type": "house", "position": [4, 3]}, {"name": "小公园", "type": "park", "position": [3, 4]}, ], }, ], }

这里有一个重要细节：cleaned处理是把模型的输出规范化。实际开发中，大模型经常会在 JSON 前后加上 ````json标记，如果不处理直接json.loads` 一定会报错。很多初学者在这里卡住，其实去掉后就能解决。

4.4 实现 NPCAgent：生成 NPC 人格与日程

有了地图之后，NPCAgent 才能发挥价值。NPC 是开放世界游戏里最影响真实感的元素。如果 NPC 只会站在原地重复一句台词，玩家的沉浸感会瞬间消失。这里我们让 NPCAgent 生成每个 NPC 的姓名、职业、性格和日程模板。

# 文件路径：agents/npc_agent.py import json from core.base_agent import BaseAgent class NPCAgent(BaseAgent): def run(self, context: dict) -> dict: state = context["state"] scene = state.get("scene", {}) npc_prompt = ( f"当前小镇是 {scene.get('town_name', 'AI小镇')}。" "请生成 3 个有生活感的 NPC，每个 NPC 需要包含姓名、年龄、职业、性格、每日日程。" "严格输出 JSON 数组，不要输出多余文本。" '示例格式：[{"name":"","age":0,"job":"","personality":"","daily_schedule":""}]' ) result_text = self.llm.chat( system_prompt="你只负责输出 JSON 数组。", user_prompt=npc_prompt, ) cleaned = result_text.strip().replace("```json", "").replace("```", "") try: npc_data = json.loads(cleaned) except json.JSONDecodeError: npc_data = self._fallback_npcs() return {"npcs": npc_data} def _fallback_npcs(self): return [ { "name": "迈克", "age": 30, "job": "修车工", "personality": "直爽、爱帮忙", "daily_schedule": "上午修车，下午去咖啡馆，晚上回家", }, { "name": "露西", "age": 25, "job": "咖啡师", "personality": "热情、健谈", "daily_schedule": "上午开店，下午休息，晚上去健身房", }, { "name": "老周", "age": 52, "job": "杂货店老板", "personality": "精打细算、消息灵通", "daily_schedule": "上午进货，下午看店，晚上数钱", }, ]

你可能会问：直接用_fallback_npcs()不就行了，为什么还要调用 LLM？答案很简单：Mock 数据是死的，大模型生成的数据每一次都有变化，这才是 AI Agent 系统的价值所在。真实项目中，你应该用大量生成的 NPC 来填充小镇，而不是手工维护一份 JSON。

4.5 实现 DialogueAgent：让 NPC 会根据上下文回复

DialogueAgent 是玩家感知最明显的一个 Agent。玩家进入游戏后，想要和一个 NPC 对话，传统做法是给 NPC 配置几段静态台词。这里我们把对话生成交给大模型，让它根据 NPC 人设、当前地点、玩家说的话来生成回复。

# 文件路径：agents/dialogue_agent.py import json from core.base_agent import BaseAgent class DialogueAgent(BaseAgent): def run(self, context: dict) -> dict: state = context["state"] event = context["event"] npc_name = event.get("npc_name", "迈克") player_message = event.get("player_message", "你好，这里有什么任务吗？") npcs = state.get("npcs", []) npc_info = None for npc in npcs: if npc["name"] == npc_name: npc_info = npc break if npc_info is None: npc_info = {"name": npc_name, "job": "路人", "personality": "普通"} dialogue_prompt = ( f"你是 {npc_info['name']}，职业是 {npc_info['job']}，性格是 {npc_info['personality']}。" f"玩家对你说：{player_message}。请用符合你人设的语气回复一句话，不要超过 50 字。" ) reply_text = self.llm.chat( system_prompt="你是一个虚构游戏里的 NPC，只能回复符合人设的台词。", user_prompt=dialogue_prompt, ) return { "last_dialogue": { "npc": npc_name, "player_message": player_message, "reply": reply_text, } }

DialogueAgent 的输入是当前状态和事件，输出并不修改全局 NPC 数据，而是把最近一轮对话写入状态。这样调度器可以随时读取state["last_dialogue"]，用于界面展示或日志记录。

4.6 实现 QuestAgent：生成任务链

任务系统是 GTA 类游戏的灵魂。要让 AI 自动生成任务，我们需要告诉它玩家的当前状态和已完成的进度。QuestAgent 接收全局状态后，会返回一个包含“任务名称、目标描述、奖励、是否完成”的任务列表。

# 文件路径：agents/quest_agent.py import json from core.base_agent import BaseAgent class QuestAgent(BaseAgent): def run(self, context: dict) -> dict: state = context["state"] player = state.get("player", {"name": "玩家", "level": 1, "completed_quests": []}) quest_prompt = ( f"玩家当前等级 {player['level']}，已完成任务：{player['completed_quests']}。" "请生成 2 个适合当前等级的开放世界支线任务。" "严格输出 JSON 数组，每个任务包含 title、description、reward、target_npc。" "不要生成重复任务。" ) result_text = self.llm.chat( system_prompt="你是开放世界游戏的剧情策划，善于生成有趣的任务。", user_prompt=quest_prompt, ) cleaned = result_text.strip().replace("```json", "").replace("```", "") try: quest_data = json.loads(cleaned) except json.JSONDecodeError: quest_data = self._fallback_quests() return {"quests": quest_data} def _fallback_quests(self): return [ { "title": "帮忙修车", "description": "迈克的车在广场抛锚了，去帮他拿工具。", "reward": "100 金币", "target_npc": "迈克", }, { "title": "送咖啡", "description": "露西需要把咖啡送到住宅区的公园，但她走不开。", "reward": "50 金币", "target_npc": "露西", }, ]

从工程角度来看，任务生成不能每次都生成完全不同的任务，否则玩家会觉得游戏没有连续性。所以实战中一定要把completed_quests传给 Prompt，让模型知道哪些任务已经做过，从而生成有递进感的任务链。

4.7 实现 AssetAgent：把 AI 生成的建筑匹配到本地资源

大模型生成的建筑名称是文本，但游戏引擎需要的是资源 ID。AssetAgent 的作用就是建一道“翻译层”，把“市政厅”“便利店”“住宅楼”这类文本映射到本地资源清单里的具体 ID。

# 文件路径：agents/asset_agent.py import json from core.base_agent import BaseAgent class AssetAgent(BaseAgent): def run(self, context: dict) -> dict: state = context["state"] scene = state.get("scene", {}) resource_list = state.get("resources", []) asset_map = {} for area in scene.get("areas", []): for building in area.get("buildings", []): building_type = building["type"] asset_id = self._match_asset(building_type, resource_list) asset_map[building["name"]] = { "building_type": building_type, "asset_id": asset_id, } return {"asset_map": asset_map} def _match_asset(self, building_type: str, resource_list: list) -> str: for resource in resource_list: if resource["type"] == building_type: return resource["asset_id"] return "generic_asset"

这里不需要调大模型，因为匹配逻辑是确定性规则。这个设计思路也很重要：并不是所有环节都要用 AI，能用代码解决就用代码解决，AI 只负责“需要理解和创作”的部分。这样可以有效控制成本和延迟。

4.8 实现 DirectorAgent：作为全局事件导演

DirectorAgent 的工作是决定“接下来发生什么”。它读取全局状态，根据自己的判断把新事件推入事件队列。

# 文件路径：agents/director_agent.py from core.base_agent import BaseAgent class DirectorAgent(BaseAgent): def run(self, context: dict) -> dict: state = context["state"] scene = state.get("scene", {}) towns_name = scene.get("town_name", "AI小镇") # 这里不依赖大模型，而是用简单规则驱动事件 events = [] if state.get("current_area") == "中央广场": events.append({ "agent": "dialogue", "npc_name": "迈克", "player_message": "嗨，我需要一份工作。", }) if len(state.get("quests", [])) == 0: events.append({ "agent": "quest", }) return {"director_events": events}

DirectorAgent 目前使用规则触发事件，这是因为对于“导演”角色来说，规则比大模型更稳定。后续如果你想做更复杂的动态事件，可以让 DirectorAgent 也调用大模型，根据玩家历史行为和当前环境生成事件，但要确保输出结构足够规范，否则调度器无法解析。

4.9 编写 main.py 并运行

现在把整个流程串起来。main.py的职责是：读取配置、初始化 LLM、注册 6 个 Agent、初始化全局状态、推送初始事件、执行调度器。

# 文件路径：main.py import json import os import yaml from rich.console import Console from core.llm import LLMClient from core.agent_manager import AgentManager from agents.scene_agent import SceneAgent from agents.npc_agent import NPCAgent from agents.dialogue_agent import DialogueAgent from agents.quest_agent import QuestAgent from agents.asset_agent import AssetAgent from agents.director_agent import DirectorAgent console = Console() def load_config(path="config.yaml"): with open(path, "r", encoding="utf-8") as f: return yaml.safe_load(f) def load_resources(path="data/resources.json"): with open(path, "r", encoding="utf-8") as f: return json.load(f) def run_game(): config = load_config() mock = config["agent"]["mock"] llm = LLMClient(mock=mock) manager = AgentManager(global_state={ "player": { "name": "玩家", "level": 1, "completed_quests": [], }, "resources": load_resources(), "scene": {}, "npcs": [], "quests": [], "asset_map": {}, "last_dialogue": {}, "director_events": [], }) manager.register_agent(SceneAgent("scene", llm)) manager.register_agent(NPCAgent("npc", llm)) manager.register_agent(DialogueAgent("dialogue", llm)) manager.register_agent(QuestAgent("quest", llm)) manager.register_agent(AssetAgent("asset", llm)) manager.register_agent(DirectorAgent("director", llm)) # 初始事件：先生成场景，再生成 NPC，再生成任务和资源映射 manager.push_event({"agent": "scene", "town_name": "洛圣都小镇"}) manager.push_event({"agent": "npc"}) manager.push_event({"agent": "quest"}) manager.push_event({"agent": "asset"}) # 根据 DirectorAgent 的返回值继续追加事件 for _ in range(config["agent"]["max_rounds"]): manager.run() director_result = manager.global_state.get("director_events", []) if director_result: for event in director_result: manager.push_event(event) manager.global_state["director_events"] = [] else: break # 保存运行结果 with open("output/run_result.json", "w", encoding="utf-8") as f: json.dump(manager.global_state, f, ensure_ascii=False, indent=2) console.print("[bold cyan]运行完成，输出文件位于 output/run_result.json[/bold cyan]") if __name__ == "__main__": run_game()

运行命令：

python main.py

预期输出大致如下：

注册 Agent: scene 注册 Agent: npc 注册 Agent: dialogue 注册 Agent: quest 注册 Agent: asset 注册 Agent: director scene 执行完成 npc 执行完成 quest 执行完成 asset 执行完成 director 执行完成 dialogue 执行完成 quest 执行完成 diredtor 执行完成 运行完成，输出文件位于 output/run_result.json

注意director会触发两个新事件，分别是dialogue和quest，所以max_rounds至少为 2 才能轮完整个流程。这也是多 Agent 协作循环的直观体现：每个 Agent 都可能会触发其他 Agent，最终形成一张生成网络。

4.10 结果说明

运行结束后，output/run_result.json里会有以下关键字段：

• scene：地图数据，包含城镇名称、区域、建筑。
• npcs：NPC 数据，包含人格、日程。
• quests：任务列表。
• asset_map：建筑与资源 ID 的映射关系。
• last_dialogue：最近一次对话内容。
• director_events：导演 Agent 最后输出的触发事件。

你可以把这个 JSON 文件直接作为游戏服务器的“世界存档”，或者经过转换后导入 Unity、Godot、Cocos 等引擎的编辑器。

5. 常见问题与排查思路

在运行多 Agent 项目时，你可能会遇到下面这些问题。我把它们整理成一张排查表，方便直接对照处理。

其中，“上下文裁剪”是最容易忽略的一点。很多 AI 应用开发新手会把整个 JSON 一股脑丢给大模型，结果 Token 消耗巨大，生成质量反而下降。正确做法是只传目标 Agent 需要的最小字段。

6. 最佳实践与工程建议

6.1 结构化输出是第一优先级

在 AI Agent 工程里，结构化输出比“生成得好不好看”重要得多。大模型返回的自然语言无法直接被程序使用，必须通过 JSON 或 YAML 统一格式。如果你发现某次输出经常不是合法 JSON，可以在 Prompt 后追加一句“如果无法确定某个字段，请返回空字符串，不要输出解释”，然后配合一次json.loads与 fallback。

6.2 用 Mock 模式降低开发成本

Mock 模式是工程效率的关键。没有真实 API Key 时，先定义好完整的接口和数据结构，用 Mock 数据跑通全链路；等到真正联调时，再把mock改成 false。这样开发过程中不会被模型的不稳定性阻塞，也能在没有网络的环境里继续写代码。

6.3 重要文件及时落盘，方便回溯

每次运行结果都保存为output/run_result.json，并可以按时间加前缀存档。这样当你修改 Prompt 或架构后，能方便地对比不同版本的输出差异。这在做 AI Agent 开发的日常调试中非常实用，可以快速判断“是哪一次变更导致生成效果变差”。

6.4 安全与合规注意事项

在真实项目中接入大模型 API 时，要注意几个安全点：

• API Key 放在环境变量或密钥管理服务中，不要提交到 Git 仓库。
• 如果要在生产环境使用，应该接入网关层做限流、审计和用户数据脱敏。
• 玩家输入内容不可信，对话 Agent 的 Prompt 中要防止提示词注入，不要简单拼接用户输入。
• 游戏内如果涉及多人在线，对于生成内容的审核是必要的，避免生成违规言论。

另外，涉及删除、重置数据的操作尽量设计成软删除，增加一个is_deleted字段，生产环境变更前先备份数据库。这些通用工程习惯虽然看起来简单，但对 AI 应用尤其重要，因为大模型的行为不可控，必须在外围增加更多保护层。

6.5 性能优化：缓存、批量与异步

目前示例代码是同步执行，Agent 之间轮流等待。如果你的游戏需要同时管理几十个 NPC，同步调用会非常慢。优化方向有三个：

• 对 NPC 对话结果做缓存，同一玩家在同一地点问同一问题直接命中缓存。
• 对场景和任务生成做批量处理，一次让模型生成多个候选，而不是逐个调用。
• 把 Agent 调用改成协程或异步任务，模型等待期间可以继续处理其他逻辑。

6.6 从“单轮生成”走向“循环更新”

这篇文章里，每个 Agent 都是运行一次后直接返回结果。但在真实的开放世界模拟中，NPC 的行为应该是持续变化的：早上开店，中午吃饭，晚上巡逻。你需要一个定时循环，每帧或每分钟调用一次 DirectorAgent，让它根据当前环境决定让 NPC 做什么。这样游戏就具备了“生发”（emergent）效果，玩家会发现 NPC 的行为并不完全由策划写死。

7. 总结与学习路线

这篇文章从一个实际需求出发：如何用 6 个 AI Agent 联手从零打造一个 GTA 风格的小沙盒原型。核心不是复刻一个完整 GTA，而是演示“多 Agent 协作”在游戏内容生成上的可行性。我们从架构设计开始，把场景、NPC、对话、任务、资源、导演事件拆成 6 个专业 Agent，然后用一个调度器统一驱动，最终生成一份完整的世界状态 JSON。

想继续深入，建议按这条路线走：

1. 先把本文代码在本地跑通，感受 Agent 调度循环的执行顺序。
2. 把mock改为 false，接入真实大模型，体验 Prompt 调优对输出质量的影响。
3. 尝试给 NPCAgent 增加记忆功能，让它能记住和玩家的历史对话。
4. 尝试给 DirectorAgent 换成大模型驱动，从规则逻辑过渡到开放事件生成。
5. 把 JSON 输出对接一个游戏引擎的渲染层，比如 Pygame 或 Godot，做一个能实际“走动”的小镇界面。

在动手之前，还要提醒一句：AI Agent 生成内容不是万能的，建议把“AI 生成”和“规则校验”结合起来。比如任务生成后，用脚本检查任务奖励是否合理、目标 NPC 是否存在、地点是否在地图内，避免出现无法执行的逻辑。把 AI 当作创意引擎，把规则当作质量底线，这是目前最稳妥的 AI Agent 工程实践。

如果你在跑代码时遇到“JSON 解析失败”“事件队列死循环”“调用超时”这类问题，可以对照第 5 节的排查表逐一处理。希望这篇文章能帮你把“AI + 开放世界游戏”的前期原型搭得又快又稳。