> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能体运行时

> 专家的大脑——AI 推理引擎的核心机制

智能体运行时是每一个专家的「大脑」。当用户发送消息时，Runtime 负责构建完整的对话上下文、调用大模型进行推理、执行工具操作、管理多轮交互，并将整个过程以流式方式实时呈现给用户。

## Agent Loop：核心推理循环

专家的每一次响应都由一个精密的推理循环驱动：

```mermaid theme={null}
sequenceDiagram
    participant User as 用户
    participant Core as Core API
    participant RT as 智能体运行时
    participant LLM as 大模型
    participant SB as 沙盒
    participant Tools as 工具集

    User->>Core: 发送消息
    Core->>RT: 构建运行时负载
    RT->>RT: 组装上下文<br/>(历史+记忆+技能+工具)
    RT->>LLM: 流式推理请求

    loop 工具调用循环
        LLM-->>RT: 文本 + 工具调用
        RT-->>User: SSE: 文本流
        RT->>Tools: 执行工具
        Tools->>SB: 沙盒操作
        SB-->>Tools: 执行结果
        Tools-->>RT: 工具返回值
        RT->>LLM: 携带结果继续推理
    end

    LLM-->>RT: 最终回复
    RT-->>User: SSE: 完成
    RT->>RT: 后台自进化(可选)
```

## 上下文构建

每次推理前，Runtime 会为专家精心组装上下文——这决定了 AI 「知道什么」和「能做什么」：

<Steps>
  <Step title="系统人格注入">
    专家的核心人格（心智模型、决策启发式、表达风格）作为系统指令注入，定义 AI 的「灵魂」。
  </Step>

  <Step title="历史消息加载">
    从对话历史中加载相关消息。当历史过长时，自动触发上下文压缩（详见 [上下文引擎](/zh/documentation/how-it-works/context-engine)）。
  </Step>

  <Step title="记忆检索">
    从专家的记忆图谱中检索与当前对话相关的长期记忆，让 AI 记住用户的偏好和历史上下文。
  </Step>

  <Step title="技能装载">
    根据对话场景动态激活相关技能——技能赋予专家特定领域的专业操作流程。
  </Step>

  <Step title="工具声明">
    根据专家的能力配置和当前模式，声明可用的工具集合（代码执行、文件操作、网络搜索、创意生成等）。
  </Step>
</Steps>

## 流式输出：实时交互体验

袋袋使用 Server-Sent Events (SSE) 协议实现实时流式输出。用户不需要等待 AI 完成全部思考——每一个 token、每一个工具调用、每一个中间状态都会实时推送：

| 事件类型 | 含义        | 用户体验         |
| ---- | --------- | ------------ |
| 文本片段 | AI 正在生成文字 | 逐字出现的打字效果    |
| 思考状态 | AI 正在内部推理 | 「正在思考...」指示器 |
| 工具调用 | AI 决定使用工具 | 显示工具名称和参数    |
| 工具结果 | 工具执行完成    | 展示执行结果卡片     |
| 完成信号 | 整轮对话结束    | 启用输入框        |

<Tip>
  流式输出的好处不仅是用户体验——它还意味着即使 AI 生成一段很长的回复，用户也能随时通过「停止」按钮中断，节省不必要的 Token 消耗。
</Tip>

## 多轮工具执行

专家的强大之处在于它可以像人类一样「动手做事」。在一次回复中，AI 可能需要连续调用多个工具：

```mermaid theme={null}
graph TD
    A[用户: 帮我创建一个 React 项目并部署] --> B[AI 思考]
    B --> C[工具: 初始化项目]
    C --> D[工具: 安装依赖]
    D --> E[工具: 编写组件代码]
    E --> F[工具: 启动预览服务器]
    F --> G[AI: 项目已就绪，预览地址是...]
```

每次工具调用后，AI 会审视结果并决定下一步：继续执行、修正错误、还是向用户汇报。这个「观察-决策-行动」循环是 Agent 与普通聊天机器人的本质区别。

## HITL：人类在环确认

对于敏感操作（如文件删除、外部 API 调用、支付操作），专家不会直接执行。它会先向用户展示计划并请求确认：

<Steps>
  <Step title="AI 提出行动计划">
    专家识别到即将执行的操作可能有不可逆影响，主动暂停并描述计划。
  </Step>

  <Step title="用户确认或修改">
    用户看到确认卡片，可以批准执行、修改参数、或拒绝操作。
  </Step>

  <Step title="按决策继续">
    获得批准后继续执行；被拒绝则切换到替代方案。
  </Step>
</Steps>

HITL 机制确保 AI 的自主性和用户的控制权之间取得平衡——专家足够聪明可以独立工作，但在关键时刻不会越权。

## Token 预算控制

每个会话都有 Token 预算上限，防止失控的推理消耗：

* **输入预算**：自动触发上下文压缩，保证不超模型窗口
* **输出预算**：单次回复超限时自动恢复续写（最多 3 次）
* **会话总预算**：累计消耗达到上限后优雅停止，而非突然中断

```mermaid theme={null}
graph LR
    subgraph 预算分配
        Total[会话总预算] --> Input[输入预算<br/>上下文压缩管控]
        Total --> Output[输出预算<br/>截断自动恢复]
        Total --> Tools[工具预算<br/>结果压缩管控]
    end
```

<Note>
  预算控制的目标不是「限制」专家的能力，而是确保资源使用可预测。当预算接近用尽时，专家会自动切换到更精简的回复模式，确保每一个 token 都花在刀刃上。
</Note>

## 插件化工具体系

Runtime 的工具系统采用声明式 Manifest 驱动，而非硬编码：

<CardGroup cols={2}>
  <Card title="沙盒工具" icon="terminal">
    代码执行（bash）、文件读写（read/write/edit）、全文搜索（grep/glob）——在隔离容器中运行。
  </Card>

  <Card title="创意工具" icon="palette">
    图片生成、视频生成、音乐创作、语音合成——调用各专业模型 API。
  </Card>

  <Card title="知识工具" icon="book">
    网络搜索、网页阅读、外部知识库连接（飞书/钉钉/语雀等）。
  </Card>

  <Card title="记忆工具" icon="brain">
    记忆存储与检索——专家可以主动记住重要信息，并在未来对话中回忆。
  </Card>
</CardGroup>

每个工具以 Plugin Manifest 注册，声明激活条件和能力。专家创作者可以按需开启或关闭特定工具类别，精确控制 AI 的行为边界。

## 委托执行：专家间协作

一个专家可以将特定子任务委托给其他专家——就像团队中的分工协作：

```mermaid theme={null}
graph TD
    Main[主专家<br/>项目经理] --> |委托设计| Design[设计专家]
    Main --> |委托代码| Code[开发专家]
    Main --> |委托测试| Test[测试专家]
    Design --> |返回设计稿| Main
    Code --> |返回代码| Main
    Test --> |返回报告| Main
```

委托任务在后台异步执行，不阻塞主对话流程。用户会看到实时的任务进度更新。

## 安全防线

Runtime 内置多层安全机制保护专家创作者的知识产权：

* **Prompt 泄露检测**：实时监控 AI 输出，如果检测到系统 Prompt 片段泄露，自动拦截并替换
* **技能内容脱敏**：工具返回的技能原文在发送给前端前被替换为安全摘要
* **Canary Token**：在系统 Prompt 中嵌入隐形标记，任何复制行为可追溯

<Tip>
  安全不是事后补丁，而是 Runtime 的第一设计原则。从上下文构建到最终输出的每一步，都有对应的安全检查点。
</Tip>

## 性能特征

| 指标         | 典型值   | 说明                 |
| ---------- | ----- | ------------------ |
| 首 Token 延迟 | \< 1s | 从收到请求到第一个 Token 送达 |
| 工具执行延迟     | \< 3s | 沙盒内命令执行平均耗时        |
| 上下文压缩      | \< 2s | 触发压缩时的额外延迟         |
| 最大并发会话     | 水平扩展  | 每个 Pod 独立处理，无状态    |

Runtime 是无状态服务——所有会话状态存储在外部（数据库 + Redis），这意味着它可以水平扩展到任意并发量，任何一个 Pod 挂掉不会丢失用户对话。