3.4 演出手册：常用API速查

3.4 演出手册：常用API速查

本节摘要：本节把双智能体编排的常用接口收成一页手册：会话初始化、单步推进、谢幕判定、用量统计、单智能体对话，每个接口一段最小示例加一行适用场景。3.2 节的完整脚本用了其中五个，本节补齐日常高频但此前没展开的部分，并给一张调用时序图收束第 3 章。

手册的读法

接口速查最怕两种读法：从头到尾通读（记不住），只抄代码不读场景（用错位）。正确的打开方式是按"你现在想干什么"来查——本节每一段都以一个动词开头：想开场、想推进一步、想知道戏演没演完、想知道花了多少钱、想单独试一个演员。五个动词覆盖日常九成场景。

想开场：会话初始化。 核心 类是 RolePlaying（角色扮演会话），高频参数如下：

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,            # 两侧默认模型
)
# 适用场景：一切双智能体演出的起点；换任务只改中间三行
​

想推进一步：单步接口。 step 一次推进半轮（助理交付加用户新指令），返回两个响应对象：

input_msg = session.init_chat()                 # 首条输入由会话准备
a_resp, u_resp = session.step(input_msg)        # 推进半轮
print(a_resp.msgs[0].content[:60])              # 助理交付文本
print(a_resp.terminated)                        # 本步是否触发谢幕
# 适用场景：自建演出循环；需要精细控制每一步时优先用它
​

想知道戏演没演完：谢幕判定。 判定字段挂在每个响应对象上：

if a_resp.terminated:                           # 框架已检测到完成口令
    print("正常谢幕")
else:
    print("继续推进，下一轮输入：", a_resp.msg.content[:40])
# 适用场景：循环体内的每一步；配合轮次上限构成双保险
​

想知道花了多少钱：用量统计。 用量藏在响应的信息字段里：

usage = a_resp.info.get("usage", {})            # 本步令牌用量
print("本步用量字段:", usage)                    # 接入你的记账闭包
# 适用场景：3.3 节预算控制的数据源；批量实验必接
​

想单独试一个演员：单智能体对话。 排戏之前先试镜，直接跟单个对话智能体聊：

from camel.agents import ChatAgent

agent = ChatAgent(system_message="你是股票交易员，只提需求与验收")
reply = agent.step("请对交易机器人项目下达第一条指令")
print(reply.msgs[0].content[:80])               # 单独检验一个角色是否立得住
# 适用场景：剧本调试阶段的试镜；两侧剧本分别验，别急着开整场
​

指令：实现行情获取函数，输入股票代码与时间区间，输出逐日收盘价。
验收标准：给定示例代码能返回不少于 5 条数据。
​

试镜是本节最想强调的习惯：整场戏最贵的调试方式是跑全场，最便宜的方式是两侧分开试镜。剧本没立住的单侧角色，全场跑十轮才能暴露，试镜一轮就现形。

调用时序：一张图收束

五个接口不是孤立的，它们在一次演出里的调用次序与数据流向如下：

图上有两个此前没有点破的细节。其一，init_chat 返回的首条输入消息由会话根据任务卡准备，你不需要自己写第一条指令——开场那一下框架替你做了。其二，换手发生在编排层内部：指令与方案都是先回到会话再流向对方，两侧演员从不直接通信，这保证了历史记录的单一真源。

一页备查卡

把全册至今用过的接口收成一张表，建议存成模板文件：

备查卡之外补一句选型直觉：需要"全自动演出"就用 RolePlaying 的循环形态；需要"人参与每一轮"就退回 ChatAgent 逐个调用、自己当甲方——两种形态共用同一套剧本资产，切换成本很低。这为第 4 章埋了个引子：评论家在环，本质上就是在这套时序里插入第三位参与者。

手册的维护方式也要交代：本页只收"高频且稳定"的接口，框架每次升级后对照官方变更记录过一遍——变了接口在备查卡上标记，连着两个版本没用到就从卡上撤下。一份越用越短的速查卡，才是活的工具书；一份只增不减的，半年后就没人看了。

演出手册收齐，第 3 章的搭台首演到此收官。下一章开始加戏：给演员工具、给观众席审戏人、给生产线复制机。