3.3 环境构建与交互设计

3.3 环境构建与交互设计

在体系中的位置：3.2 写了演员，这一节建舞台——把 2.3 的环境模型落成代码。环境是 AgentScope 区别于普通"聊天编排库"的关键，建好它，多智能体才有共享世界。

先讲因果：为什么不能把所有状态塞进某个智能体的记忆？因为那会让该智能体成为单点，且其他智能体要读状态就得直接找它——又回到紧耦合。环境把"共享世界"独立出来，谁都能读、谁都能改（按规则），谁都不必认识谁。

内置环境与自定义环境

AgentScope 提供基础 Environment 承载消息总线与状态。复杂逻辑（如游戏地图、市场规则）需继承 EnvironmentBase 自定义。下面先用内置环境做发布-订阅。

from agentscope.environment import Environment

# 构建一个共享项目看板环境
board = Environment(name="项目看板")

# 其他智能体用 board.get_state("intro_done") 感知，无需直接联系发布者
​

运行说明：上面是语义骨架，具体方法名随版本微调，但"发布-订阅 + 状态读写"的交互契约稳定。环境作为单一事实来源，Studio 能直接画它的状态，调试极方便（呼应 2.3）。

自定义环境：以游戏地图为例

当内置环境不够，继承基类扩展。下面构建一个带地图和胜负判定的 GameEnvironment，提供 move 和 check_win 专用接口。

from agentscope.environment import EnvironmentBase

class GameEnvironment(EnvironmentBase):
    def __init__(self, size: int = 10):
        super().__init__(name="对战地图")
        self.size = size
        self.state = {"players": {}, "winner": None}

    def move(self, agent_name: str, direction: str) -> dict:
        """让某智能体朝指定方向移动，返回新坐标。"""
        pos = self.state["players"].get(agent_name, [0, 0])
        dx, dy = {"上": (0, 1), "下": (0, -1),
                  "左": (-1, 0), "右": (1, 0)}[direction]
        new_pos = [pos[0] + dx, pos[1] + dy]
        # 规则执行者：越界则不动
        if 0 <= new_pos[0] < self.size and 0 <= new_pos[1] < self.size:
            self.state["players"][agent_name] = new_pos
        return {"agent": agent_name, "pos": self.state["players"].get(agent_name)}

    def check_win(self, target: list) -> str:
        """某智能体到达目标点则判胜。"""
        for name, pos in self.state["players"].items():
            if pos == target:
                self.state["winner"] = name
                return name
        return "未分胜负"
​

运行说明：智能体调用 env.move("A", "右") 移动，env.check_win([9, 9]) 判胜。规则（越界不动、到达即胜）封装在环境，智能体只管策略。换规则改环境一处，智能体不动——2.3 说的可维护性在此兑现。

交互协议：智能体如何与环境对话

智能体与环境的交互遵循"感知-行动-反馈"闭环（2.3 图）。落到代码就是：读状态 → 决定动作 → 调环境接口 → 收反馈。下面用一张时序图串起来。

案例：市场模拟环境的规则落地

背景：经济学研究想观察价格波动涌现（2.3 案例）。环境要承载价格表、库存，并执行"报价不超现价 20%"规则。

操作：自定义 MarketEnvironment，内部 state 存价格与库存，提供 quote(agent, price) 方法，内部校验合法性后才更新价格表；非法报价返回拒绝原因。

结果：买家/卖家智能体只管策略，规则统一由环境把关，上千轮后价格自然收敛。

解读：规则进环境后，改"20%"为"30%"只动环境一行，所有智能体无感。若规则散落智能体，改起来灾难。

变式：若想研究"无约束市场"，把校验方法置空即可，智能体代码不变。环境与业务解耦的红利再次显现。

四之一、环境的事件钩子：规则执行的可观测性

自定义环境除了"存状态 + 校验"，还常在关键动作上留钩子，让外部（Studio、监控、审计）能感知发生了什么。这把"环境是单点"的劣势转成优势——所有状态变更都经过一处，天然可埋点。

from agentscope.environment import EnvironmentBase

class ObservableMarket(EnvironmentBase):
    def __init__(self):
        super().__init__(name="可观测市场")
        self.state = {"price": 100, "log": []}

    def quote(self, agent_name: str, price: float) -> str:
        if price > self.state["price"] * 1.2:
            verdict = "REJECT"
        else:
            self.state["price"] = price
            verdict = "OK"
        # 钩子：每次报价都留痕，便于回放与审计
        self.state["log"].append(f"{agent_name} 报 {price} -> {verdict}")
        return verdict

# ['买家甲 报 110 -> OK', '买家乙 报 200 -> REJECT']
​

运行说明：报价无论通过与否都被记进 log，环境成为全系统唯一的"事实账本"。调试时不用去翻每个智能体的记忆拼凑发生了什么，看环境日志即可回放整局。这正好印证 2.3 说的"环境是单一事实来源"——既是状态来源，也是事件来源。

本节要点回顾

• 状态塞进单个智能体记忆会造单点+紧耦合；环境把"共享世界"独立，谁都能按规则读写。
• 内置 Environment 够日常；复杂逻辑（地图、市场）继承 EnvironmentBase 自定义。
• 智能体与环境交互遵循"读状态→决定→调接口→收反馈"闭环，规则封装在环境。
• 规则集中进环境，改规则不动智能体；环境成单点，故规则逻辑要简单可测（2.3 提醒）。

⚠️ 自定义环境的规则逻辑要保持简单、可测。环境是单点，规则一复杂有 bug，全系统异常且难定位——别把业务塞进环境。

💡 设计环境先列"哪些是全局事实、哪些是角色策略"。全局事实（价格、进度、地图）进环境状态；角色策略留智能体。这条线画清，交互设计就顺了。