---
name: ambient-agent
description: Ambient Agent - 持续后台运行的智能代理，用于主动监控事件和执行操作
allowed-tools: ambient_goals,ambient_status,ambient_think,ambient_remember,ambient_control
---

# Ambient Agent

Ambient Agent 是一个持续后台运行的智能代理，监控事件并主动执行操作。

## 核心概念

### Goal（目标）

目标是对话式 LLM 派发的任务，包含：

- `title` - 目标标题
- `description` - 目标描述
- `priority` - 优先级 1-10
- `actions` - 要执行的操作列表
- `conditions` - 激活条件（如监听特定事件）
- `persistent` - 是否持久化（默认 true，false 为一次性任务）
- `state` - 状态：`pending` | `active` | `completed` | `failed`

### Action（操作）

操作是目标的最小执行单元，有三种类型：

| 类型      | 说明     | 参数                                    |
| --------- | -------- | --------------------------------------- |
| `tool`    | 调用工具 | `name` 工具名, `args` 参数              |
| `message` | 发送消息 | `content` 消息内容                      |
| `think`   | 触发思考 | `topic` 主题, `mode` 模式, `depth` 深度 |

每个 action 有 `completed` 标记，执行完成后标记为 true。

### Event（事件）

目标可以监听以下框架事件：

| 事件                       | 触发时机          | 数据结构                                                                        |
| -------------------------- | ----------------- | ------------------------------------------------------------------------------- | ---- |
| `email:received`           | 收到新邮件        | `{uid, messageId, from, to, subject, text, body, html, attachments, timestamp}` |
| `webhook:received`         | 收到 Webhook 请求 | `{path, method, query, body, timestamp}`                                        |
| `webhook:processed`        | Webhook 处理完成  | `{path, method, query, body, response, timestamp}`                              |
| `scheduler:task_created`   | 定时任务创建      | `{taskId, taskName, type, scheduleTime, cronExpression}`                        |
| `scheduler:reminder`       | 定时提醒触发      | `{taskId, message, time}`                                                       |
| `scheduler:task_completed` | 定时任务完成      | `{taskId, result}`                                                              |
| `scheduler:task_failed`    | 定时任务失败      | `{taskId, error}`                                                               |
| `think:thought_completed`  | 思考完成          | `{mode, topic, thought, depth}`                                                 |
| `tool:result`              | 工具执行成功      | `{name, args, result, source}` (source: tool                                    | mcp) |
| `tool:error`               | 工具执行错误      | `{name, args, error, source}` (source: tool                                     | mcp) |
| `tool:call`                | 工具被调用        | `{name, args, source}` (source: tool                                            | mcp) |
| `agent:message`            | Agent 发送消息    | `{content, sessionId, userMessage}`                                             |
| `worker:completed`         | Worker 完成       | `{workerId, name, result, notification}`                                        |
| `worker:error`             | Worker 错误       | `{workerId, name, error, notification}`                                         |
| `subagent:chat:end`        | 子 Agent 聊天结束 | `{parentAgent, subAgent, subAgentName, result}`                                 |

## 工具

### ambient_goals - 目标管理

```javascript
// 列出所有目标
await ambient_goals({ action: 'list' })

// 创建持久化目标（默认）- 事件驱动，执行完等待下一事件
await ambient_goals({
  action: 'create',
  title: '监控邮件',
  description: '收到邮件后自动回复',
  priority: 8,
  persistent: true,  // 默认 true，持久化目标
  actions: [
    { id: 'auto-reply', type: 'tool', name: 'email_auto_reply', args: {...} }
  ],
  conditions: {
    events: ['email:received']
  }
})

// 创建一次性目标 - 执行完自动完成，不等待新事件
await ambient_goals({
  action: 'create',
  title: '处理定时提醒',
  description: '提醒到达后执行一次操作',
  priority: 8,
  persistent: false,  // 一次性任务
  actions: [
    { id: 'process', type: 'tool', name: 'some_tool', args: {...} }
  ],
  conditions: {
    events: ['scheduler:reminder']
  }
})

// 更新目标
await ambient_goals({
  action: 'update',
  goalId: 'xxx-xxx',
  title: '新标题',
  persistent: false,  // 改为一次性
  actions: [...]  // 新操作列表
})

// 删除目标
await ambient_goals({ action: 'delete', goalId: 'xxx-xxx' })

// 激活目标
await ambient_goals({ action: 'activate', goalId: 'xxx-xxx' })
```

### ambient_status - 获取状态

```javascript
await ambient_status({});
// 返回: { running, tickCount, activeGoals, pendingGoals, recentActivities }
```

### ambient_think - 触发思考

```javascript
await ambient_think({
  goalId: 'xxx-xxx', // 可选，关联目标
  mode: 'reflect', // reflect | brainstorm | plan | analyze
  topic: '反思主题', // 可选
  depth: 2, // 可选，1-5
});
```

### ambient_remember - 记忆管理

```javascript
// 存储记忆
await ambient_remember({
  action: 'store',
  key: 'user-preference',
  content: '用户喜欢在早上收到摘要',
});

// 检索最近记忆
await ambient_remember({
  action: 'retrieve',
  limit: 10,
});

// 搜索记忆
await ambient_remember({
  action: 'search',
  query: '邮件',
});
```

### ambient_control - 控制循环

```javascript
// 暂停
await ambient_control({ action: 'pause' });

// 恢复
await ambient_control({ action: 'resume' });

// 调整参数
await ambient_control({
  action: 'adjust',
  tickInterval: 10000, // 新 tick 间隔（毫秒）
  cooldownPeriod: 5000, // 新冷却时间（毫秒）
});
```

## action 与 step 的关系

Ambient Agent 的 action 与 Workflow Engine 的 step 共用 `StepExecutor` 执行：

```
action.type → step.type
───────────────────────
tool      → tool
message   → message
think     → think
```

这意味着：

- 变量引用语法一致：`${variableName}`（Ambient Agent 使用 `${}`)
- sessionId 传递机制一致
- 错误处理方式一致

## action 执行上下文

当 action 执行时，可用的上下文：

```javascript
// context.variables 中可用
context.variables._event; // 触发的事件数据（如果有）
context.variables._action; // 当前执行的 action 对象
context.variables.loopIndex; // 循环索引（如果被 loop 执行）

// context.input 中可用
context.input; // 工作流/目标输入参数
```

## 变量引用语法

Ambient Agent 使用 `${}` 语法在 action 参数中引用变量：

### 1. 事件数据引用 `${event.xxx}`

当 goal 监听事件时，事件数据可通过 `${event.xxx}` 直接引用：

```javascript
{
  id: 'auto-reply',
  type: 'tool',
  name: 'email_auto_reply',
  args: {
    to: '${event.from}',
    subject: '${event.subject}',
    body: '${event.text}',
    from: ''
  }
}
```

**注意**：`email:received` 事件的数据结构：

- `event.from` - 发件人地址
- `event.subject` - 邮件主题
- `event.text` - 邮件正文（纯文本）
- `event.body` - 邮件正文（可能含 HTML）
- `event.messageId` - 邮件消息 ID

### 2. 多步骤引用 `${actionId.output.field}`

当有多个顺序执行的 action 时，后续 action 可以引用前一个 action 的输出：

```javascript
actions: [
  {
    id: 'read-email',
    type: 'tool',
    name: 'email_read',
    args: { limit: 1, unreadOnly: true },
  },
  {
    id: 'process',
    type: 'tool',
    name: 'some_processor',
    args: {
      // 引用 read-email 输出的 emails 数组的第一个元素的 from 字段
      sender: '${read-email.output.emails[0].from}',
    },
  },
];
```

### 3. 变量解析规则

`${}` 语法支持嵌套属性访问：

- `${event.from}` - 直接字段
- `${actionId.output.field}` - 嵌套字段
- `${event.data.xxx}` - data 对象内的字段（兼容性别名）

## 创建目标的最佳实践

1. **明确目标标题** - 让用户清楚知道目标意图
2. **设置合适优先级** - 高优先级目标会被优先处理
3. **操作要原子化** - 每个 action 只做一件事
4. **选择合适的持久化模式** - 需要持续监控用 `persistent: true`，一次性任务用 `persistent: false`
5. **检查循环** - 同一 action 连续失败 3 次会判定为循环

## 示例：创建邮件自动回复目标

`email:received` 事件的数据结构：

- `event.from` - 发件人地址
- `event.subject` - 邮件主题
- `event.text` - 邮件正文（纯文本）
- `event.body` - 邮件正文（与 text 相同）
- `event.messageId` - 邮件消息 ID
- `event.uid` - 邮件 UID（数字）

```javascript
await ambient_goals({
  action: 'create',
  title: '邮件自动回复',
  description: '收到邮件后自动回复发件人',
  priority: 8,
  persistent: false, // 一次性任务，回复完成后不再等待新邮件
  actions: [
    {
      id: 'auto-reply',
      type: 'tool',
      name: 'email_auto_reply',
      args: {
        to: '${event.from}',
        subject: '${event.subject}',
        body: '${event.text}',
      },
    },
  ],
  conditions: {
    events: ['email:received'],
  },
});
```

**错误示例**（缺少参数）：

```javascript
// ❌ 错误 - 没有传递必需参数
{ type: 'tool', name: 'email_auto_reply', args: {} }

// ✅ 正确 - 从事件中提取参数
{ type: 'tool', name: 'email_auto_reply', args: {
    to: '${event.from}',
    subject: '${event.subject}',
    body: '${event.text}',
  }
}
```

**注意**：`email_auto_reply` 需要 `to`、`subject`、`body` 三个必需参数，必须从 `${event.xxx}` 提取。由于 `email:received` 事件已携带邮件数据，不需要额外的 `email_read` 步骤来读取邮件。

## 生命周期

```
Goal 创建 → [条件满足] → ACTIVE → 执行 actions → COMPLETED/FAILED
                ↑                              ↓
                └────── 重新激活 ← ─────────────┘（仅 persistent=true）
```

- **pending** - 待激活，满足条件后自动变为 active
- **active** - 执行中，循环处理 actions
- **completed** - 所有 actions 执行完毕（一次性任务执行完后直接完成）
- **failed** - 达到最大尝试次数或检测到循环

**persistent 行为**：

- `persistent: true`（默认）- 事件驱动目标，actions 执行完后等待下一事件再次执行
- `persistent: false` - 一次性目标，所有 actions 执行完后直接完成，不等待新事件
