# 智能体与会话 (/docs/developers/agent/concepts)



智能体是一份可复用的配置，会话是使用这份配置开展的一段独立对话。先区分这两个对象，才能判断修改指令会影响谁、消息应该发到哪里，以及如何验证任务结束。

## 配置与运行对象 [#objects]

| 对象    | 包含什么               | 创建与使用                        |
| ----- | ------------------ | ---------------------------- |
| 智能体   | 模型、指令、工具、MCP 配置及版本 | 创建后取得 `agent_…` ID，供多个会话复用   |
| 会话    | 固定版本、消息与工具事件、运行状态  | 以智能体 ID 或带版本的引用创建；后续向该会话发送输入 |
| 环境    | 运行会话的机器配置          | 为需要沙箱的会话选择环境；普通 API 起步可省略    |
| 事件    | 用户输入、回复、工具执行与状态变化  | 写入输入事件，读取历史或订阅事件流            |
| vault | 可供访问工具服务的凭据        | 与配置指令分开管理，不能用提示词代替凭据控制       |

服务智能体为每段会话使用独立运行环境。个人智能体绑定持久电脑，适合保留工作目录的任务；两种类型的选择在创建时确定。API 起步使用服务智能体，不需要先准备个人电脑。

## 版本与会话生命周期 [#lifecycle]

保存智能体配置会创建新版本。创建会话时，`agent` 可以是 ID 字符串，表示取当时最新版本；也可以是 `{ type: "agent", id, version }`，明确选择版本。会话固定这份配置，之后修改智能体不会把已有会话换到新版本。

会话可以处于 `idle`、`running`、`rescheduling` 或 `terminated` 状态。`idle` 表示当前没有运行中的任务，可以继续发送消息；`terminated` 会话不能继续运行。归档是另一项状态：记录仍可查询，但不能继续发送消息。保留记录与停止接收输入是不同需求，清理前先判断需要哪一种。

发送 `user.message` 得到成功响应，只说明输入被接收。读取 `agent.message` 才能取得回复；观察其后的 `session.status_idle` 才能判断这一轮已经回到空闲。需要用户批准工具时，应处理待确认事件，不能将等待确认误判为接口无响应。

## 环境与身份边界 [#boundaries]

API 创建会话省略 `environment_id`，且未选择电脑时，使用轻型机器；选择环境时使用对应沙箱配置。环境配置在会话创建时固定。会话的文件和工具能力取决于配置，不应仅凭“环境”这个名字推断支持任意运行时。

组织 API Key 留在服务端。面向终端用户的网页使用嵌入令牌，由宿主后端从已验证登录态确定 `external_user_id`，再为指定智能体签发。令牌限定智能体、版本及终端用户的访问范围；前端自己填写用户 ID 不能建立可信身份。

公开资料问答可使用可公开 key 获取匿名访客令牌。同一浏览器存储延续匿名身份；这不等于登录账户，也不授予访问订单或其他私有资料的权限。用户切换时销毁旧组件并重新取得凭证，不能只清空消息列表。

工具确认表达用户是否同意本次操作。你的订单或业务服务仍须验证调用凭据和当前用户的资源权限；页面上下文、模型参数和“允许执行”按钮都不能代替这一步。指令和上下文也不适合保存秘密。

## 选择下一步 [#next]

第一次验证 API，用[运行第一个智能体](/docs/developers/agent/quickstart)。要修改配置或选择嵌入版本，读[配置智能体](/docs/developers/agent/configure)；创建与更新请求的字段以 [API 参考](/docs/api/native/agent)为准。

接入客户产品时，先选[交付形态](/docs/developers/agent/embed/overview)，再按[嵌入令牌与用户](/docs/developers/agent/embed/tokens)接好身份。出现执行问题时，从[查看会话与用量](/docs/developers/agent/monitor)定位记录，再按[限制与错误](/docs/developers/agent/limits-and-errors)处理。