智能体与会话
理解配置版本、会话、环境和事件，再选择身份与生命周期。
智能体是一份可复用的配置，会话是使用这份配置开展的一段独立对话。先区分这两个对象，才能判断修改指令会影响谁、消息应该发到哪里，以及如何验证任务结束。
配置与运行对象
| 对象 | 包含什么 | 创建与使用 |
|---|---|---|
| 智能体 | 模型、指令、工具、MCP 配置及版本 | 创建后取得 agent_… ID，供多个会话复用 |
| 会话 | 固定版本、消息与工具事件、运行状态 | 以智能体 ID 或带版本的引用创建；后续向该会话发送输入 |
| 环境 | 运行会话的机器配置 | 为需要沙箱的会话选择环境；普通 API 起步可省略 |
| 事件 | 用户输入、回复、工具执行与状态变化 | 写入输入事件，读取历史或订阅事件流 |
| vault | 可供访问工具服务的凭据 | 与配置指令分开管理，不能用提示词代替凭据控制 |
服务智能体为每段会话使用独立运行环境。个人智能体绑定持久电脑，适合保留工作目录的任务；两种类型的选择在创建时确定。API 起步使用服务智能体，不需要先准备个人电脑。
版本与会话生命周期
保存智能体配置会创建新版本。创建会话时，agent 可以是 ID 字符串，表示取当时最新版本；也可以是 { type: "agent", id, version }，明确选择版本。会话固定这份配置，之后修改智能体不会把已有会话换到新版本。
会话可以处于 idle、running、rescheduling 或 terminated 状态。idle 表示当前没有运行中的任务，可以继续发送消息；terminated 会话不能继续运行。归档是另一项状态：记录仍可查询，但不能继续发送消息。保留记录与停止接收输入是不同需求，清理前先判断需要哪一种。
发送 user.message 得到成功响应，只说明输入被接收。读取 agent.message 才能取得回复；观察其后的 session.status_idle 才能判断这一轮已经回到空闲。需要用户批准工具时，应处理待确认事件，不能将等待确认误判为接口无响应。
环境与身份边界
API 创建会话省略 environment_id，且未选择电脑时，使用轻型机器；选择环境时使用对应沙箱配置。环境配置在会话创建时固定。会话的文件和工具能力取决于配置，不应仅凭“环境”这个名字推断支持任意运行时。
组织 API Key 留在服务端。面向终端用户的网页使用嵌入令牌，由宿主后端从已验证登录态确定 external_user_id，再为指定智能体签发。令牌限定智能体、版本及终端用户的访问范围；前端自己填写用户 ID 不能建立可信身份。
公开资料问答可使用可公开 key 获取匿名访客令牌。同一浏览器存储延续匿名身份；这不等于登录账户，也不授予访问订单或其他私有资料的权限。用户切换时销毁旧组件并重新取得凭证，不能只清空消息列表。
工具确认表达用户是否同意本次操作。你的订单或业务服务仍须验证调用凭据和当前用户的资源权限；页面上下文、模型参数和“允许执行”按钮都不能代替这一步。指令和上下文也不适合保存秘密。
选择下一步
第一次验证 API，用运行第一个智能体。要修改配置或选择嵌入版本，读配置智能体；创建与更新请求的字段以 API 参考为准。
接入客户产品时，先选交付形态，再按嵌入令牌与用户接好身份。出现执行问题时，从查看会话与用量定位记录，再按限制与错误处理。