# Gumloop 官方文档 — Agents（完整）

> 来源：https://docs.gumloop.com/core-concepts/agents.md
> 抓取日期：2026-05-30
> 关联 Spec：`spec_subagents.md`、`spec_queue-steer.md`、`spec_incognito-mode.md`

---

## 什么是 Agent

AI 驱动的助手，能使用工具解决开放式任务。关键特征：自适应、工具驱动、对话式、上下文感知。

**Agent vs 工作流：** Agent = 编排者/四分卫（协调多种工具，适应新情况）；工作流 = 可重复的标准操作（预设步骤，确定性执行）。

---

## 创建 Agent

三步：添加工具（从 2-3 个开始，使用描述性工作流名称）→ 编写指令（明确角色、工具使用规则、确认规则、回复风格）→ 充分测试（边缘案例、基于错误优化提示词）。

**限制工具能力（推荐）：** 对 MCP 集成可切换特定工具的访问权限。例如 Gmail 仅搜索/读取，Salesforce 仅 get/search 不包含 delete/update。

---

## Subagents（子代理）

### 两种模式

**Self-Cloning：**
- Agent 创建自身副本，继承相同的工具、指令和能力
- **默认开启**
- 在 Subagents 列表中显示为 "(Me)"
- 可通过 `tool_scope` 限制副本的 MCP 工具范围
- 非 MCP 工具（沙箱、图片生成、网页搜索）始终保留
- **深度限制 1**：副本不能再自我克隆

**调用其他 Agent：**
- 父 Agent 通过 ID 调用不同专业 Agent
- 必须显式添加到父 Agent 的 Subagents 列表
- 仅同一项目内的自定义 Agent 可选
- Agent 自身被排除在列表外
- **跨 Agent 调用链无深度限制**（A→B→C 可以无限）

### 执行细节（六件事）

1. **创建交互记录**——每个子 Agent 有独立记录，父对话引用子交互
2. **并行执行**——多个子 Agent 同时运行。最大并发取决于订阅层级
3. **进度追踪**——批量调用时共享进度面板。兄弟 Agent "可以查看彼此的进度并通过广播笔记通信"
4. **文件传输**——父 Agent 可在启动前传输特定沙箱文件给子 Agent。完成后对话记录可被父 Agent 读取
5. **超时处理**——子 Agent 作为排队后台任务运行，时间预算约**父 Agent 时间限制的一半**。超时时先优雅中止，不响应则强制取消
6. **深度限制**——Self-cloning 深度限制为 1。跨 Agent 调用链无限制

### 凭据
子 Agent "在与父 Agent 相同的用户上下文中运行"，使用对话发起者的凭据。

### FAQ
- **任何 Agent 都能用吗？** 所有自定义 Agent 都有 invoke_agent 工具。Self-cloning 默认开启。调用其他 Agent 需显式添加
- **使用谁的凭据？** 父 Agent 发起者的凭据
- **子 Agent 能调用子 Agent 吗？** 可以——如果其 Subagents 列表中有其他 Agent。Self-clone 不能再克隆
- **如何查看子 Agent 做了什么？** 出现在聊天历史中。父对话包含指向子交互的链接
- **子 Agent 失败了怎么办？** 失败报告回父 Agent。父 Agent 可重试、尝试不同方案或报告错误
- **并发有限制吗？** 是，最大并发取决于订阅层级

---

## Message Queue and Steering（消息排队与引导）

### 工作方式

当 Agent 显示 "Responding..." 时，用户可以继续发送消息。消息进入队列，Agent 在处理步骤间隙（如完成一个工具调用后）自动拉取并融入对话。

### 队列管理能力

| 能力 | 说明 |
|------|------|
| **排队多条消息** | Agent 响应期间无限制发送跟进消息 |
| **包含附件** | 文件和图片与普通消息一样支持 |
| **递送前编辑** | 点击排队消息修改文本 |
| **重新排序** | 拖拽消息改变处理顺序 |
| **删除** | 递送前取消排队消息 |
| **重试失败消息** | 重新尝试发送失败的排队消息 |

### 引导（Steering）

排队消息在模型步骤之间的自然断点注入，充当**引导输入**：
- **重定向**：将焦点从 Q2 移至 Q3
- **补充上下文**：添加截止日期等缺失细节
- **优化输出**："更简洁一些"或要求图表
- **串联任务**：排列顺序指令

### 关键细节
- 消息一次处理一条，按顺序
- 每条消息成为对话历史的一部分，保持完整上下文
- 如果 Agent 在排空队列前完成响应，未处理消息作为标准跟进消息递送
- "队列仅在 Agent 响应期间活跃"

---

## Incognito Mode（隐身模式）

### 概述
"Incognito 模式让你与 Agent 进行**不保存到数据库**的对话。" 消息仅存于临时内存，**24 小时后自动删除**。

### 启用方式
在聊天输入栏中切换 **Incognito** 按钮（发送消息前）。一旦激活，"对话完全绕过永久存储"。

### Incognito vs 标准模式

| 维度 | Incognito | 标准 |
|------|-----------|------|
| **消息** | 不保存到数据库 | 持久化 |
| **侧边栏/搜索** | 隐藏，不可搜索 | 正常显示 |
| **数据导出** | 排除 | 包含 |
| **文件/Artifacts** | 临时存储，不创建永久记录 | 永久存储 |
| **Reflections** | 排除——Agent 不能从中学习 | 参与学习 |
| **子 Agent** | 自动传播 | 正常模式 |
| **生命周期** | 24 小时后永久删除 | 持久保留 |

### 限制
- **不可恢复**：24 小时后所有消息和文件永久消失——"无法恢复它们"
- **全对话范围**：不能仅让部分对话 Incognito
- **子 Agent 自动传播**：Incognito 自动传播到所有子 Agent

---

## Code Sandbox（代码沙箱）

原生启用。支持 Python（数据分析/可视化）和 Shell（文件操作）。预装 80+ 包（pandas, numpy, matplotlib, scikit-learn, openai, anthropic, boto3 等）。

限制：Python 120s 超时、Shell 60s 超时、文件最大 300MB、仅限当前会话、无 GUI、无本地网络访问。

---

## Voice Input（语音输入）

支持的格式：mp3, mp4, mpeg, m4a, wav, webm。最大 25MB。使用 OpenAI Whisper、GPT-4o Transcribe 或 GPT-4o Mini Transcribe 模型。

---

## Triggers（触发器）

Agent 可通过 **Scheduled Triggers**（定时，cron）或 **Event-Based Triggers**（事件驱动——Gmail、Slack、Teams、Google Sheets、Notion、Airtable、Zendesk 等）自主运行。

---

## Skills

"可复用的知识包，教你的 Agent 如何按你的方式做特定工作。" 编码多步骤流程、存储模板、仅在相关时加载（节省 Token）、随时间改进。

---

## AI Advanced Settings（AI 高级设置）

三个标签页：
- **Model Config**：OpenAI（Reasoning Effort, Temperature, Max Output Tokens, Top P, Parallel Tool Calls）、Anthropic（Extended Thinking, Budget Tokens, Temperature, Top P, Top K）、Google（Thinking Level, Temperature, Top P, Top K）
- **Auto Summarization**：接近上下文限制时压缩旧消息
- **Fallback**：错误时自动切换模型（限流 2 次重试、5xx 1 次、网络 0 次、超时 1 次）

---

## Context Usage Meter（上下文使用表）

实时环形图标显示 Token 分解：System、AI Instructions、Abilities、Tools、Skills、Subagents、Conversation。显示百分比和精确计数。

---

## Credit Costs（信用成本）

按 AI 交互计费，取决于消息长度、模型、历史和工具。
- Budget 模型：2-4 credits/message
- Advanced 模型：15-25
- Expert 模型：30-200+

---

## Credentials & Authentication（凭据和认证）

"默认情况下，Agent 使用运行 Agent 的人的凭据，而非 Agent 创建者的凭据。"

选项：使用个人默认、使用团队默认（团队 Agent）、使用特定账户（固定账户）。

---

## App Rules（应用规则）

"App Rules 让你为 Agent 能使用的工具设置护栏。" 基于 CEL 条件拦截或标记工具调用。Pro 计划每 Agent 最多 3 条，Enterprise 更多。Agent 可在对话中提议规则（需开启 App Rules Creation 开关），显式批准/拒绝。

---

## Best Practices（最佳实践）

从简单开始、将 Agent 视为持续改进的产物、为 Agent 设计工作流、设定明确边界（永删客户数据、无批准不发送邮件、不做出财务承诺）、监控性能指标。

---

## Incognito Mode 补充

Incognito 对话被排除在 self-improvement reflections 之外。