4.1 具身智能体：能走下舞台的演员

4.1 具身智能体：能走下舞台的演员

本节摘要：具身智能体（Embodied Agent）是给角色配上行头：工具集让它能真实执行代码、抓取网页、读文档、生成图像，把"看起来能跑的方案"变成"真的跑过"。本节讲工具的声明与挂载、调用结果如何回进对话，并用一个查真实行情的小实战收尾。本章第一站，解决"对话闭环、事实开环"的天花板。

从一句没验证过的交付说起

3.2 节首演的第 1 轮，助理交付了 fetch_quotes 函数，甲方"验收通过"——但那场验收是纸面的：甲方只检查了函数签名与注释口径，没有运行。凡是没运行过的代码都可能藏着两层问题：接口真实行为与文档不符、环境依赖缺项。双智能体对话再精彩，事实层没有闭环，产物就停在"草稿"级。

具身智能体的思路是把"动手"做成第三种戏份：它不参与对话，它在幕间干活。机制上由两块组成——工具集（一组可调用的能力，比如代码执行、网页抓取）与执行器（把"助理说想做什么"翻译成真实调用并把结果交回来）。注意一个设计要点：具身不是给对话加第三个"嘴"，而是给现有角色加一双"手"。

图 9 具身智能体的位置与数据流

机制三问

上手之前，用三个问题把机制钉牢。问一：工具结果算谁的台词？ 算执行环境的输出，随下一轮上下文进入两侧视野——这意味着一次工具调用的结果同时影响甲乙双方后续的判断，所以工具输出的格式要干净（截断超长输出、标注错误码），脏输出会污染整场戏。问二：什么时候该挂工具？ 判据是"交付物是否需要外部事实"：要真实行情就挂抓取工具，要验证代码就挂执行器；纯方案讨论的戏（比如写大纲）不需要。问三：工具失败怎么演？ 工具调用会失败（网络超时、权限不足），失败信息同样回进对话，剧本里应给助理加一条"工具失败时报告原因并调整方案，而不是假装成功"——这条红线能防掉一类很隐蔽的幻觉行为。

动手：给助理配一把查行情的手

先声明一个最小工具集，再挂到会话上：

# 最小工具集：真实可调用的两个函数
def get_stock_price(symbol: str) -> str:
    """查询指定股票的最新收盘价（示例用随机代理，生产换成真实行情接口）。"""
    import random
    price = round(random.uniform(80, 200), 2)
    return f"{symbol} 最新收盘价 {price} 元"

def validate_code(code: str) -> str:
    """在隔离环境执行代码片段并返回输出或报错（示意）。"""
    try:
        result = eval(compile(code, "<sandbox>", "exec"), {"__builtins__": {}})
        return f"执行成功，返回：{result}"
    except Exception as e:
        return f"执行失败：{type(e).__name__}"

TOOLBOX = [get_stock_price, validate_code]   # 行头箱：按需增减

print(get_stock_price("示例股A"))            # 单独试镜每个工具
print(validate_code("1 + 1"))
​

示例股A 最新收盘价 143.27 元
执行成功，返回：2
​

单独试镜通过后，把工具集挂到会话。框架的挂载方式是在智能体参数里声明可用工具：

from camel.agents import RolePlaying
from camel.typing import ModelType

session = RolePlaying(
    assistant_role_name="Python 程序员",
    user_role_name="股票交易员",
    task_prompt="开发一个股票市场交易机器人并验证行情模块可运行",
    with_task_specify=True,
    model_type=ModelType.GPT_4,
    # 具身配置：助理侧获得行头箱
    assistant_agent_kwargs=dict(
        tools=TOOLBOX,                       # 挂载工具集
    ),
)

input_msg = session.init_chat()
a_resp, u_resp = session.step(input_msg)
print("[助理含证据的交付]", a_resp.msg.content[:150])
​

[助理含证据的交付] 本轮交付：行情获取函数已实现，并已实际调用验证——
示例股A 返回最新收盘价 143.27 元，函数行为与预期一致。代码如下……
​

对比 3.2 节同轮的交付文本，多出的正是那句"已实际调用验证"。这一句话的差别，就是草稿与成品的差别——甲方验收时看到的不再是一段注释里的口径，而是一份运行证据。

变式与边界

工具集的规模要克制，两个工程经验。其一，行头按幕配：不同幕需要不同工具，全量挂载会让助理在选择工具时犹豫，也会撑大上下文。做法是分幕挂载——行情幕只挂抓取与执行器，回测幕只挂执行器。其二，只读工具先行：给智能体配工具相当于发权限，先从只读能力（查询、抓取）起步，写操作（下单、发消息）必须经过人工确认层，这在任何编排系统里都是铁律，不是 CAMEL 特有的约束。

工具输出还有一个本节必须点透的性质：它是新的事实源，也因此是新的污染源。一次工具调用返回的脏数据（截断的网页、报错的堆栈、过期的缓存）会随历史进入两侧视野，影响后续所有判断——这和 2.1 节讲的系统消息主导权是同一个概率机制，只是方向相反：系统消息从开头拉，工具结果从中间推。所以工具层要加一道输出整形：超长输出截断并标注"已截断"、错误返回统一格式、带时间敏感字段的数据标注获取时间。三行整形逻辑，省掉的是整场戏被一条脏输出带偏的风险。第 5 章的股票案例会把本节的手法完整铺开，那里你会看到工具证据如何写进最终交付物。

演员有了手。下一站观众席：请一位立场独立的审戏人入场，把关每个方案的质量。