CivAgent 入门:接入第一个智能体玩家
从克隆项目、配置模型到启动 Unciv 对局,搭建一个由大语言模型驱动、能够读取战局并作出决策的数字玩家。
- 1
准备运行环境
安装 Python、Git 与 Unciv,在终端克隆 CivAgent:git clone https://github.com/fuxiAIlab/CivAgent.git,然后进入仓库并按 README 创建虚拟环境、安装依赖。
- 2
配置大语言模型
复制项目提供的环境变量或配置文件模板,填入模型 API 地址、密钥、模型名称及超时参数;密钥只放本地环境变量,不要提交到 Git。
- 3
设置文明与策略参数
在 CivAgent 的智能体配置中选择文明、玩家名称和策略提示词,设定决策温度、行动频率等参数;先用默认文明验证完整链路。
- 4
连接 Unciv 对局
按项目说明启动 CivAgent 与 Unciv 服务,在 Unciv 中创建或载入对局,添加智能体玩家并填写其连接信息,确认双方使用同一端口与房间。
- 5
运行并观察决策
启动智能体进程,在终端日志中检查模型请求、状态解析和动作提交;进入游戏观察其完成采集、探索或建设,并核对回合是否推进。
- 6
接入游戏开发管线
将 CivAgent 作为外部对局服务接入测试框架,用固定种子和可复现配置批量评估决策质量,并将日志、动作与胜率结果写入你的实验管线。
💡 实用技巧
- 先验证单回合,再运行完整文明
- 限制输出结构,避免无效游戏动作
- 记录提示词、模型版本与回合日志
- 用固定种子做策略对比实验
⚠️ 常见坑
- API 密钥误写入配置文件或提交仓库
- 端口、文明名称或回合协议不一致
常见问题
Q:虚拟环境创建后仍提示找不到依赖怎么办?
确认当前终端已经进入 CivAgent 仓库并按 README 激活虚拟环境,再重新执行依赖安装命令;随后从同一环境启动智能体,避免系统 Python 与虚拟环境混用。
Q:模型请求失败应先检查哪些配置?
先核对环境变量或配置文件中的 API 地址、密钥、模型名称和超时参数,再查看终端中的模型请求日志。密钥应只保存在本地环境变量中,不要写入仓库。
Q:智能体连不上 Unciv 对局怎么排查?
检查 CivAgent 与 Unciv 是否使用同一端口和房间,并确认 Unciv 中添加的玩家连接信息与项目配置一致。先用默认文明跑通单回合,再核对回合协议与回合推进情况。