最近在探索AI Agent的落地场景时，发现很多演示都停留在简单的问答或工具调用上，缺乏动态、连续决策的复杂环境。这让我思考：能否构建一个更“好玩”、更能体现智能体自主决策能力的竞技场？受此启发，我们团队尝试复现并深度解析了Hacker News上热议的“Agentic World Cup”项目——一个让大型语言模型（LLM）在1v1足球模拟环境中自主对抗的竞赛平台。本文将带你从零开始，深入理解其架构，并手把手教你搭建自己的“AI足球联赛”，体验LLM在动态环境中的策略博弈。

本文适合对AI Agent、多智能体系统、LLM应用开发感兴趣的开发者。无论你是想了解Agentic设计模式，还是希望为你的LLM寻找一个有趣的评估沙盒，都能在这里找到完整的代码、配置与实战经验。我们将覆盖从环境搭建、智能体设计、比赛运行到结果分析的完整闭环。

1. 背景与核心概念：为什么是“AI足球”？

在深入代码之前，我们首先要厘清几个关键概念，并理解这个项目背后的意义。

1.1 什么是 Agentic AI？“Agentic”一词源于“Agent”（智能体），它描述的是一种能够感知环境、自主设定目标、制定并执行计划以达成目标的AI系统。与传统的一次性问答不同，Agentic AI强调持续性、目标导向性和工具使用能力。一个Agentic LLM不仅会回答问题，还会在长期任务中分解步骤、使用外部工具（如搜索、计算、执行代码）并适应环境变化。

1.2 从传统RAG到Agentic RAG的演进搜索热词中提到了“从传统RAG到Agentic RAG的进阶优化”。这揭示了当前的一个技术趋势：

• 传统RAG (Retrieval-Augmented Generation)：主要用于增强LLM的知识，通过检索相关文档来生成更准确的答案。它是一个被动的、响应式的系统。
• Agentic RAG：将RAG能力嵌入到一个主动的智能体中。智能体可以主动决定何时进行检索、检索什么、如何利用检索到的信息来推进一个多步骤的任务。这体现了“Agentic”的自主决策特性。我们的足球Agent就是一个简化版的Agentic系统，它需要根据球场状态（环境），主动决定行动（如传球、射门），以达成进球的目标。

1.3 项目核心价值：一个理想的智能体测试床为什么选择足球作为测试场景？

1. 动态环境：球场状态瞬息万变，要求智能体进行实时感知和决策。
2. 长期规划：从后场组织到前场射门，需要多步连贯的策略，而非单次反应。
3. 竞争与协作：虽然是1v1，但本质上涉及对抗性决策，能很好地测试模型的策略性。
4. 可量化评估：胜负、进球数、控球率等指标清晰，便于客观比较不同LLM或提示词的效果。

这个项目并非要训练一个踢足球的强化学习模型，而是评估和激发LLM作为“决策大脑”在模拟环境中的规划与推理能力。

2. 环境准备与版本说明

我们将基于一个开源复现的框架来搭建环境。为了确保可复现性，以下是经过验证的环境配置。

2.1 基础运行环境

• 操作系统：Ubuntu 20.04+/macOS Monterey+/Windows 10+ (建议使用Linux或macOS进行开发，Windows可通过WSL2运行)。
• Python版本：Python 3.9 或 3.10。不推荐使用3.11+的某些最新版本，以避免潜在的库依赖冲突。
• 包管理工具：pip最新版。

2.2 核心依赖库我们将创建一个独立的虚拟环境来管理依赖。

# 创建并激活虚拟环境（以conda为例，也可使用venv） conda create -n agentic_world_cup python=3.9 conda activate agentic_world_cup # 安装核心依赖 pip install openai==1.6.1 # 用于调用GPT系列API # 注：如果你使用其他LLM API（如Anthropic Claude, DeepSeek），需安装对应SDK # pip install anthropic # pip install openai # DeepSeek兼容OpenAI API pip install numpy==1.24.3 pip install pygame==2.5.0 # 用于2D足球环境可视化（可选，但推荐） pip install pytest==7.4.0 # 用于运行测试

2.3 LLM API密钥配置本项目核心是LLM，你需要准备相应的API密钥。以OpenAI GPT为例：

1. 访问 OpenAI Platform 创建API Key。
2. 在项目根目录创建.env文件，避免将密钥硬编码在代码中。

# .env 文件内容 OPENAI_API_KEY=sk-your-actual-api-key-here # 可选：如果你使用其他服务 # ANTHROPIC_API_KEY=your-claude-key # DEEPSEEK_API_KEY=your-deepseek-key # DEEPSEEK_API_BASE=https://api.deepseek.com/v1 # DeepSeek的API端点

在Python代码中，使用python-dotenv加载配置：

pip install python-dotenv==1.0.0

# config.py import os from dotenv import load_dotenv load_dotenv() OPENAI_API_KEY = os.getenv("OPENAI_API_KEY") if not OPENAI_API_KEY: raise ValueError("请在 .env 文件中设置 OPENAI_API_KEY")

3. 项目架构与核心模块拆解

一个典型的Agentic World Cup系统包含以下几个核心模块，理解它们有助于我们后续的编码和调试。

3.1 环境模拟器 (Environment Simulator)这是足球比赛的“物理引擎”。它定义了：

• 状态空间：球场尺寸（如100x50），球的位置(x, y)，球员A的位置，球员B的位置，比分，比赛时间等。
• 动作空间：球员在每个回合可以执行的动作，例如：{“move”: “north”},{“shoot”: “towards_goal”},{“pass”: “to_teammate”}（在1v1中简化为直接控制）。
• 状态转移逻辑：根据球员动作、球的位置、物理规则（简单的碰撞检测、射门概率计算）更新下一时刻的状态。
• 奖励与终止条件：进球得1分，比赛时间结束或达到最大回合数则终止。

3.2 智能体封装器 (Agent Wrapper)这是连接LLM和环境的桥梁。它的核心职责是：

1. 观察：从环境获取当前状态（如球员位置、球权、比分）。
2. 提示工程：将状态信息格式化成LLM能理解的提示词（Prompt）。
3. 调用LLM：向LLM API发送请求，获取其决定的行动。
4. 解析与执行：解析LLM的返回结果（通常是JSON或特定格式文本），将其转化为环境能执行的动作指令。

3.3 裁判与日志系统 (Referee & Logger)

• 裁判：判定动作是否合法（如是否越位？在1v1中可简化），计算进球，宣布比赛结果。
• 日志系统：记录每一回合的状态、LLM的思考过程、最终动作和结果。这对于赛后分析、调试提示词至关重要。

3.4 比赛运行器 (Tournament Runner)负责组织多轮比赛，让不同的LLM（或同一LLM的不同提示词策略）相互对抗，并统计积分榜。

4. 完整实战：搭建你的第一届AI世界杯

接下来，我们分步骤实现一个简化但功能完整的版本。

4.1 项目结构创建首先，创建清晰的项目目录。

agentic_world_cup/ ├── .env # 环境变量（API密钥） ├── requirements.txt # 依赖列表 ├── config.py # 配置文件 ├── environment.py # 足球环境模拟器 ├── agent.py # 智能体封装器 ├── referee.py # 裁判与规则 ├── game_runner.py # 单场比赛运行器 ├── tournament.py # 锦标赛运行器 ├── prompts/ # 存放不同策略的提示词 │ └── basic_strategy.txt └── logs/ # 比赛日志

4.2 实现足球环境模拟器 (environment.py)我们实现一个非常简化的2D网格足球环境。

# environment.py import numpy as np class Soccer1v1Env: def __init__(self, pitch_length=100, pitch_width=50): self.pitch_length = pitch_length self.pitch_width = pitch_width self.reset() def reset(self): """重置环境到初始状态""" # 球员A初始位置（本方半场） self.player_a_pos = np.array([self.pitch_length * 0.25, self.pitch_width / 2]) # 球员B初始位置（对方半场） self.player_b_pos = np.array([self.pitch_length * 0.75, self.pitch_width / 2]) # 球初始位置在中圈 self.ball_pos = np.array([self.pitch_length / 2, self.pitch_width / 2]) # 球权：0-球员A, 1-球员B self.ball_possession = 0 if np.random.rand() > 0.5 else 1 # 比分 self.score_a = 0 self.score_b = 0 # 比赛时间（回合数） self.time_step = 0 self.max_steps = 50 # 一场比赛最多50个回合 self.done = False return self._get_state() def _get_state(self): """获取当前环境状态的字典描述，用于生成提示词""" return { "player_a_pos": self.player_a_pos.tolist(), "player_b_pos": self.player_b_pos.tolist(), "ball_pos": self.ball_pos.tolist(), "ball_possession": "A" if self.ball_possession == 0 else "B", "score": f"{self.score_a}-{self.score_b}", "time_step": self.time_step, "max_steps": self.max_steps, "goal_a": (0, self.pitch_width), # A队球门线（左） "goal_b": (self.pitch_length, self.pitch_width), # B队球门线（右） } def step(self, action_a, action_b): """执行球员A和B的动作，更新环境""" if self.done: raise ValueError("比赛已结束，请调用reset()") self.time_step += 1 # 1. 处理球员移动（简化：直接更新位置） self._process_movement(action_a, action_b) # 2. 处理球权与射门 self._process_ball_and_shoot(action_a, action_b) # 3. 检查比赛是否结束 if self.time_step >= self.max_steps: self.done = True # 4. 返回新状态、奖励、结束标志 next_state = self._get_state() reward_a = 1 if self._check_goal_scored() == 'A' else 0 reward_b = 1 if self._check_goal_scored() == 'B' else 0 # 如果本轮进球，重置球到中圈 if reward_a or reward_b: self.ball_pos = np.array([self.pitch_length / 2, self.pitch_width / 2]) self.ball_possession = 0 if np.random.rand() > 0.5 else 1 return next_state, (reward_a, reward_b), self.done def _process_movement(self, action_a, action_b): # 这是一个非常简化的移动逻辑，实际可以更复杂 move_speed = 5.0 if "move" in action_a: dir_vec = self._parse_direction(action_a["move"]) self.player_a_pos += dir_vec * move_speed self.player_a_pos = np.clip(self.player_a_pos, [0,0], [self.pitch_length, self.pitch_width]) # 同理处理action_b... # 为简洁起见，此处省略action_b的处理和越界检查完整代码 def _process_ball_and_shoot(self, action_a, action_b): # 处理射门逻辑：如果持球球员选择射门，且距离球门足够近，则有概率进球 shoot_range = 20.0 goal_probability = 0.3 if self.ball_possession == 0 and "shoot" in action_a: dist_to_goal_b = np.linalg.norm(self.player_a_pos - np.array([self.pitch_length, self.pitch_width/2])) if dist_to_goal_b < shoot_range and np.random.rand() < goal_probability: self.score_a += 1 # 同理处理球员B的射门... # 处理传球/抢断逻辑（简化） # ... def _check_goal_scored(self): # 检查上一轮step是否有进球，并返回进球方 # 简化实现，实际可根据分数变化判断 pass def _parse_direction(self, dir_str): # 将方向字符串解析为向量 dir_map = { "north": np.array([0, -1]), "south": np.array([0, 1]), "east": np.array([1, 0]), "west": np.array([-1, 0]), } return dir_map.get(dir_str.lower(), np.array([0,0])) def render(self): """可选：使用Pygame进行简单可视化""" # 此处省略Pygame渲染代码，可根据需要实现 pass

4.3 实现智能体封装器 (agent.py)这是项目的核心，负责与LLM对话。

# agent.py import openai from config import OPENAI_API_KEY import json import time class LLMAgent: def __init__(self, name, model="gpt-3.5-turbo", system_prompt_path="./prompts/basic_strategy.txt"): self.name = name self.model = model self.client = openai.OpenAI(api_key=OPENAI_API_KEY) with open(system_prompt_path, 'r', encoding='utf-8') as f: self.system_prompt = f.read() self.conversation_history = [] # 可保存历史，用于具有记忆的Agent def get_action(self, state): """根据环境状态，调用LLM获取动作""" # 1. 构建用户提示词（将状态信息格式化） user_prompt = self._format_state_to_prompt(state) # 2. 调用LLM API try: response = self.client.chat.completions.create( model=self.model, messages=[ {"role": "system", "content": self.system_prompt}, {"role": "user", "content": user_prompt} ], temperature=0.2, # 低温度使输出更稳定、确定性更高 max_tokens=150, response_format={ "type": "json_object" } # 强制返回JSON，便于解析 ) llm_output = response.choices[0].message.content # 3. 解析LLM返回的JSON action = json.loads(llm_output) # 4. 记录日志（可选） self._log_interaction(state, user_prompt, llm_output, action) return action except (openai.APIError, json.JSONDecodeError) as e: print(f"Agent {self.name} 调用LLM失败: {e}，返回默认动作") return {"move": "east"} # 失败时返回一个默认动作 def _format_state_to_prompt(self, state): """将环境状态字典转换为LLM能理解的文本提示""" prompt = f""" 你正在控制一场1v1足球赛中的球员 {self.name}。 当前比赛状态： - 你的位置：{state['player_a_pos'] if self.name=='A' else state['player_b_pos']} - 对手位置：{state['player_b_pos'] if self.name=='A' else state['player_a_pos']} - 球的位置：{state['ball_pos']} - 当前球权：{'你' if state['ball_possession'] == self.name else '对手'} - 比分：{state['score']} - 比赛时间：{state['time_step']}/{state['max_steps']} 你可以执行以下动作之一（请以JSON格式回复，且只包含一个动作）： 1. 移动：{{"move": "方向"}}，方向可选 north, south, east, west。 2. 射门：{{"shoot": "towards_goal"}}（仅当你有球权且靠近对方球门时有效）。 3. 抢断：{{"tackle": "true"}}（仅当你无球权且靠近持球对手时有效）。 请根据当前状态，选择最有利于得分的动作。只返回一个JSON对象。 """ return prompt def _log_interaction(self, state, prompt, llm_output, action): """记录与LLM的交互，用于分析""" log_entry = { "agent": self.name, "state": state, "prompt": prompt, "llm_output": llm_output, "action_taken": action, "timestamp": time.time() } # 可以写入文件或数据库，这里简单打印 print(f"[LOG] {log_entry}")

4.4 实现裁判与单场比赛运行器 (game_runner.py)

# game_runner.py from environment import Soccer1v1Env from agent import LLMAgent class GameRunner: def __init__(self, agent_a, agent_b, env=None): self.agent_a = agent_a self.agent_b = agent_b self.env = env if env else Soccer1v1Env() self.log = [] def run(self, render=False): """运行一场完整的比赛""" state = self.env.reset() total_reward_a, total_reward_b = 0, 0 while not self.env.done: # 1. 智能体根据状态决策 action_a = self.agent_a.get_action(state) action_b = self.agent_b.get_action(state) # 2. 环境执行动作，更新状态 next_state, (reward_a, reward_b), done = self.env.step(action_a, action_b) # 3. 记录回合信息 self.log.append({ "step": self.env.time_step, "state": state, "action_a": action_a, "action_b": action_b, "reward_a": reward_a, "reward_b": reward_b, "next_state": next_state }) total_reward_a += reward_a total_reward_b += reward_b state = next_state # 4. 可选：可视化 if render: self.env.render() # 比赛结束 winner = "A" if total_reward_a > total_reward_b else ("B" if total_reward_b > total_reward_a else "Draw") result = { "score": f"{self.env.score_a}-{self.env.score_b}", "winner": winner, "total_rewards": (total_reward_a, total_reward_b), "log": self.log } print(f"比赛结束！比分：{result['score']}，胜者：{result['winner']}") return result

4.5 组织锦标赛并运行 (tournament.py)

# tournament.py from agent import LLMAgent from game_runner import GameRunner import pandas as pd class Tournament: def __init__(self, agent_configs): """ agent_configs: 列表，每个元素是包含'name'和'model'等信息的字典 例如：[{'name':'GPT-4', 'model':'gpt-4'}, {'name':'Claude-3', 'model':'claude-3-sonnet'}] """ self.agents = {cfg['name']: LLMAgent(**cfg) for cfg in agent_configs} self.agent_names = list(self.agents.keys()) self.results = [] # 存储每场比赛结果 self.standings = {name: {'wins':0, 'draws':0, 'losses':0, 'goals_for':0, 'goals_against':0} for name in self.agent_names} def run_round_robin(self, matches_per_pair=1): """循环赛制""" for i, name_a in enumerate(self.agent_names): for name_b in self.agent_names[i+1:]: for match in range(matches_per_pair): print(f"\n=== 比赛开始：{name_a} vs {name_b} (第{match+1}场) ===") runner = GameRunner(self.agents[name_a], self.agents[name_b]) result = runner.run(render=False) # 正式比赛可关闭渲染提升速度 result['player_a'] = name_a result['player_b'] = name_b self.results.append(result) # 更新积分榜 self._update_standings(name_a, name_b, result) def _update_standings(self, name_a, name_b, result): score_a, score_b = map(int, result['score'].split('-')) self.standings[name_a]['goals_for'] += score_a self.standings[name_a]['goals_against'] += score_b self.standings[name_b]['goals_for'] += score_b self.standings[name_b]['goals_against'] += score_a if result['winner'] == 'A': self.standings[name_a]['wins'] += 1 self.standings[name_b]['losses'] += 1 elif result['winner'] == 'B': self.standings[name_b]['wins'] += 1 self.standings[name_a]['losses'] += 1 else: # Draw self.standings[name_a]['draws'] += 1 self.standings[name_b]['draws'] += 1 def display_standings(self): """显示积分榜""" df = pd.DataFrame.from_dict(self.standings, orient='index') df['points'] = df['wins'] * 3 + df['draws'] * 1 df['goal_diff'] = df['goals_for'] - df['goals_against'] df = df.sort_values(['points', 'goal_diff', 'goals_for'], ascending=False) print("\n========== 最终积分榜 ==========") print(df) # 主程序入口 if __name__ == "__main__": # 配置参赛智能体（可以使用不同模型或相同模型不同提示词） agents = [ {'name': 'GPT-4-Turbo', 'model': 'gpt-4-turbo-preview', 'system_prompt_path': './prompts/aggressive.txt'}, {'name': 'GPT-3.5-Turbo', 'model': 'gpt-3.5-turbo', 'system_prompt_path': './prompts/balanced.txt'}, # {'name': 'Claude-3-Haiku', 'model': 'claude-3-haiku-20240307'}, # 需安装anthropic库并配置API_KEY ] tournament = Tournament(agents) tournament.run_round_robin(matches_per_pair=2) # 每对组合比赛2场 tournament.display_standings()

4.6 编写提示词 (prompts/balanced.txt)提示词的质量直接决定智能体的“球商”。

你是一个1v1足球比赛的AI球员。你的目标是进球并赢得比赛。 核心策略： 1. 当你有球权时： - 优先考虑向对方球门方向移动（东边）。 - 如果你离对方球门很近（例如距离<20），尝试射门。 - 如果对手靠近你，可以考虑横向移动（北或南）以摆脱。 2. 当你没有球权时： - 快速靠近持球的对手。 - 当足够接近时，尝试抢断。 3. 始终注意比赛时间。如果临近结束且平分，要采取更冒险的策略。 4. 你的回复必须是且仅是一个有效的JSON对象，格式如 {"move": "east"} 或 {"shoot": "towards_goal"} 或 {"tackle": "true"}。 不要添加任何解释性文字。

你可以创建多个提示词文件（如aggressive.txt,defensive.txt），来赋予智能体不同的策略风格。

4.7 运行你的世界杯

1. 确保所有文件就位，.env配置正确。
2. 安装所有依赖：pip install -r requirements.txt。
3. 运行锦标赛：

   python tournament.py

4. 观察控制台输出，查看激烈的AI足球赛况和最终积分榜！

5. 常见问题与排查思路

在实现和运行过程中，你可能会遇到以下问题：

6. 最佳实践与工程优化建议

要让你的Agentic World Cup更稳定、更高效、更具研究价值，可以参考以下进阶实践：

6.1 提示词工程优化

• 角色扮演：让LLM扮演特定风格的球员（如“梅西”、“防守型中场”），观察其行为变化。
• 链式思考 (CoT)：在提示词中要求模型“先简要推理，再输出动作”，这能显著提升决策质量。例如，在用户提示词末尾加上“请先简要说明你的决策理由，然后输出JSON动作。”
• 少样本学习 (Few-Shot)：在提示词中提供几个状态-动作的优秀示例，引导LLM学习有效策略。

6.2 系统架构优化

• 异步并发：使用asyncio和aiohttp并发调用多个LLM API，极大提升锦标赛运行速度。
• 状态抽象：不要将原始坐标直接丢给LLM。将其抽象为更高层次的概念，如“你在对方半场”、“球在禁区附近”、“你正面对对手”，能降低LLM的理解负担。
• 记忆与反思：为智能体添加短期记忆（保存最近N个回合的状态-动作对），并在提示词中让其总结对手的战术模式，实现自适应。

6.3 评估与实验管理

• 系统化日志：不要只打印日志，应将每场比赛的完整轨迹（状态、动作、奖励）保存为结构化文件（如JSONL）或数据库，便于后续分析。
• 可视化分析：开发一个简单的Web面板或使用streamlit，可视化展示比赛回放、智能体的决策热点图、胜率统计等。
• 控制变量实验：科学地比较不同因素（模型、提示词、温度参数）的影响。例如，固定其他条件，只改变提示词策略，运行多次比赛统计胜率。

6.4 成本与性能考量

• 本地模型替代：对于大规模实验，API调用成本可能很高。考虑使用ollama本地运行llama3.2、qwen2.5等开源模型，并通过其提供的兼容OpenAI的API端点接入，成本极低。
• 请求缓存：对完全相同的状态提示词，可以缓存LLM的响应，避免重复计算。
• 简化环境：如果只为测试核心的Agentic能力，可以进一步简化环境（如更小的网格、更少的动作），以减少每个回合的状态描述长度，从而降低Token消耗。

通过这个项目，你不仅搭建了一个有趣的AI竞技场，更深入实践了Agentic AI的核心流程：感知 -> 规划 -> 执行 -> 学习（通过提示词迭代）。你可以在此基础上无限扩展：增加更多球员（2v2）、引入更复杂的物理规则、连接真实的足球游戏模拟器（如Google Research Football），甚至让智能体通过强化学习来自我改进。这为理解和开发更强大的自主AI系统提供了一个绝佳的起点。