“AI Agent”听起来像一个需要机器学习背景的复杂系统，但真正开始动手时，你会发现它更接近一个能够观察环境、做出决策、调用工具并保存状态的软件程序。学习这类系统最有效的方式不是先背概念，而是从一个可运行的小项目开始。
Agent Valley 采用了这种实践路线：学习者在一个低多边形虚拟世界中操作自己的 AI 伙伴，同时通过 Runtime Inspector 观察系统的思考过程、决策和成本。五个模块分别对应 Agent 开发中非常关键的能力：控制、任务拆解、协调、记忆和实时响应。
先把 Agent 看成一个闭环
一个最小 Agent 通常包含四个步骤：
- 读取用户输入或环境事件。
- 根据目标和已有状态决定下一步。
- 调用工具或执行动作。
- 保存结果，并等待下一次输入。
这和普通的聊天机器人不同。聊天机器人主要生成文本，而 Agent 需要对外部世界产生可验证的行为。例如，客服 Agent 可能查询订单、执行退款；代码 Agent 可能读取文件、运行测试；游戏中的伙伴则可能根据环境事件改变行为。
可以用一个不依赖第三方库的 Python 示例理解这个闭环。下面的程序不是生产级 LLM Agent，而是一个可以直接运行的最小模拟器。它把“模型决策”替换成了简单规则，方便观察状态如何流动：
from dataclasses import dataclass, field
from typing import List
@dataclass
class Companion:
name: str
traits: List[str]
memory: List[str] = field(default_factory=list)
coins: int = 10
def remember(self, fact: str) -> None:
if fact not in self.memory:
self.memory.append(fact)
def decide(self, event: str) -> str:
event = event.lower()
if "firework" in event or "烟花" in event:
return "look_at_sky"
if "shop" in event or "商店" in event:
return "open_shop"
return "say_hello"
def act(self, action: str) -> str:
if action == "look_at_sky":
return f"{self.name} looks up at the fireworks."
if action == "open_shop":
if self.coins >= 3:
self.coins -= 3
return f"{self.name} buys a lantern. Coins left: {self.coins}."
return f"{self.name} cannot afford the lantern."
return f"{self.name} says hello."
def run_agent(companion: Companion, event: str) -> None:
print(f"Event: {event}")
action = companion.decide(event)
result = companion.act(action)
companion.remember(f"Observed: {event}")
print(f"Decision: {action}")
print(f"Action: {result}")
print(f"Memory: {companion.memory}")
print()
agent = Companion(name="Mori", traits=["curious", "careful"])
run_agent(agent, "A firework lights up the valley")
run_agent(agent, "The market shop is open")
运行方式：
python agent_demo.py
如果把 decide() 替换成模型调用，把 act() 替换成真实工具调用，这个小程序就会逐步接近一个实际 Agent。关键不是让模型一次生成很长的回答，而是明确每一步的输入、输出和副作用。
五个模块对应五种工程能力
1. CONTROL：让 Agent 保持一致
在对话过程中，Agent 需要稳定地保留名字、性格、目标和行为边界。否则它可能前一轮表现得谨慎，下一轮突然忘记设定；或者把用户随口说过的内容误当成事实。
工程上可以把稳定信息拆成几类：
- 系统规则：Agent 必须遵守的行为约束。
- 角色属性：名字、性格、职责和偏好。
- 当前任务：这一次要完成什么。
- 会话状态：已经完成了哪些步骤，还缺哪些信息。
不要把所有内容都塞进一段不断增长的提示词。稳定属性应该结构化存储，临时任务则应该有明确的生命周期。这样更容易测试，也更容易在上下文过长时压缩历史。
2. DECOMPOSE：把大任务拆给多个 Agent
一个复杂任务通常不应该由一个 Agent 从头做到尾。例如生成一份旅行计划，可以拆成资料搜集、预算计算、行程安排和最终审核。多个助手并行工作时，必须提前定义职责和输出格式，否则它们会重复劳动，甚至互相覆盖结果。
一个简单的协作协议可以写成这样：
workflow: trip_planner
steps:
- id: research
owner: destination_agent
input: destination and travel dates
output: attractions, opening_hours, transport_options
- id: budget
owner: finance_agent
input: attractions and user_budget
output: estimated_cost, cost_risks
- id: review
owner: editor_agent
input: research.output and budget.output
output: final_itinerary
rules:
- agents_must_not_modify_each_others_output
- every_output_must_include_sources_or_assumptions
拆解的价值不只是“多几个模型”。它把复杂度分散到边界清晰的步骤中，并让每个步骤都可以独立替换和测试。代价是系统需要处理更多通信、失败重试和结果合并问题。
3. COORDINATE：让工具调用可靠
虚拟商店这个练习对应的是 Agent 最容易出问题的部分：交易。模型可以决定“给用户退款”，但真正执行退款的代码必须验证订单存在、金额合法、请求是否重复，以及外部服务是否成功。
一个实用原则是：让模型提出结构化意图，让确定性代码执行副作用。例如：
{
"action": "refund_order",
"order_id": "ORD-1042",
"reason": "damaged_item"
}
服务端收到后，应重新校验权限、订单状态和金额，而不是直接相信模型输出。所有会改变数据、扣款、发消息或删除资源的工具，都应该具备参数校验、幂等键、超时和审计日志。
4. REMEMBER：记住有用的信息，而不是全部历史
记忆不是简单地把完整聊天记录永久追加。可靠的记忆系统通常至少区分：
- 短期上下文：当前任务需要的最近对话。
- 长期事实：用户明确确认过、未来可能复用的信息。
- 任务记录：某次工作已经完成或失败的步骤。
- 不确定信息：需要再次确认，不能直接当成事实。
写入长期记忆前，可以要求 Agent 判断信息是否稳定、是否与用户有关、是否值得未来检索。读取记忆时，也要把相关性和时间范围作为过滤条件，避免旧信息污染当前决策。
5. LIVE：响应事件，同时控制成本
实时 Agent 可能同时收到烟花、灯光、用户操作和系统状态变化。如果每一个事件都触发一次完整模型调用，延迟和费用都会迅速上升。
可以采用几种控制手段：合并短时间内的相似事件，只对高价值事件调用模型；对简单动作使用规则或状态机；限制单次任务的最大步数；为每个工具调用设置超时；在 Runtime Inspector 中记录延迟、token、工具失败率和最终结果。
“能行动”不等于“应该行动”。实时系统的质量取决于它是否能在正确的时间，以可接受的成本做出可预测的动作。
一条适合初学者的练习路径
可以把五周课程式的学习拆成一个连续项目：
- 创建一个有名字、性格和目标的 Agent。
- 为它加入一个稳定的状态对象，而不是只依赖聊天记录。
- 添加两个简单工具，例如查询天气和记录任务。
- 把一个较大的目标拆成两个互不覆盖的子任务。
- 给工具调用增加参数校验和失败处理。
- 保存一条用户明确确认过的长期事实。
- 加入实时事件，并测量每次决策的延迟与成本。
每完成一个阶段，都记录三类数据：Agent 看到了什么、它决定了什么、实际执行结果是什么。这个观察视角比单纯查看最终回复更重要，因为很多 Agent 故障都发生在中间步骤。
开始之前需要明确的边界
这类入门项目适合学习 Agent 的基本组成，但不能直接当作生产系统。真实应用还需要身份认证、权限隔离、敏感数据保护、提示词注入防御、工具沙箱、人工审批和完整监控。
可以从小范围、低风险的任务开始：让 Agent 生成草稿、查询只读数据或整理信息。涉及付款、删除、法律结论和对外承诺的动作，应保留确定性校验和人工确认。
Agent Valley 的价值在于把抽象概念变成可观察的操作：你可以看到角色如何保持一致，多助手如何分工，工具调用如何影响状态，记忆如何改变后续决策，以及实时事件怎样影响性能。对初学者来说，这是一条实际可行的起点：先做一个能运行、能检查、能解释的 Agent，再逐步增加模型能力和系统复杂度。