# 将消息路由到你的 AI 代理

Bird 将你在 WhatsApp、SMS、Apple Messages 或代理邮箱上收到的每条消息发送到你的 AI 代理。只需用代理的详细信息和凭据连接一次，之后每条新消息都会到达它。

支持两种代理：

- **Claude Managed Agents**：每条消息会启动你在 Claude Console 中创建的代理的一个会话。
- **Grok Bot**：每条消息会唤醒你的一个 Grok Bot 例程。

Bird 将每条匹配的消息发送到你的代理，并重试失败的投递，因此被重试的消息可能会启动另一次运行。代理会收到消息的事件 JSON，即与普通 [webhook 端点](/docs/guides/webhooks)收到的相同载荷，并通过你提供的任何工具进行回复，例如 [Bird MCP 服务器](/docs/ai/mcp-server)。

## 选择代理回复的消息

你的代理只能回复传入消息：`whatsapp.received`、`sms.received`、`amb.received`（Apple Messages）和 `email_mailbox.message_received`。选择代理应处理的消息类型。投递回执、状态变更和其他事件不会发送给代理。

## Claude Managed Agents

首先，在 [Claude Console](https://platform.claude.com/docs/en/managed-agents/quickstart#create-your-first-session) 中设置你的代理：创建代理及其环境，并在同一工作区中创建一个 [API 密钥](https://platform.claude.com/settings/keys)。记下代理 ID 和环境 ID。新会话使用代理的最新版本。

然后在 Bird 中连接它：

1. [创建 webhook](https://bird.com/dashboard/w/webhooks/new)，选择 **Claude Managed Agents**。
2. 在 **Triggers** 下，选择 Claude 应回复的消息类型。
3. 在 **Connect** 下，为 webhook 命名，并输入 agent ID、environment ID 和 API 密钥。
4. 检查 webhook 配置并创建。

每条消息会启动一个会话，其第一条用户消息为 `New Bird event:`，后跟事件 JSON。

## Grok Bot

首先，让 Grok Bot 创建一个带有 webhook 触发器的 routine。它会返回该 routine 的 webhook URL 和 sender key。如需手动设置触发器，请参阅 [Cursor 的 webhook 触发器](https://cursor.com/docs/cloud-agent/automations#webhook-triggers)。

然后在 Bird 中连接它：

1. [创建 webhook](https://bird.com/dashboard/w/webhooks/new)，选择 **Grok Bot**。
2. 在 **Triggers** 下，选择 Grok Bot 应回复的消息类型。
3. 在 **Connect** 下，为 webhook 命名，并粘贴 webhook URL 和 sender key。
4. 检查 webhook 配置并创建。

每条消息将事件 JSON 以 POST 方式发送到例程的 webhook URL，发送者密钥作为 Bearer 令牌，例程随即运行其保存的提示词。

## 通过 CLI 或 API 创建

`bird webhooks create --help` 列出每个连接器及其字段、哪些字段为机密、它接受的事件以及需要先完成的设置。通过 `--field name=value` 传入非机密字段，通过 `--secret-env name=ENV_VAR` 从环境变量传入每个机密值，或使用 `--secret-stdin name` 以管道方式传入，以避免其出现在 shell 历史记录中。`--events` 默认为连接器接受的所有消息事件。

对于 Claude，在代理所在的工作区中创建一个 [API 密钥](https://platform.claude.com/settings/keys)，然后在不回显的情况下将其读入环境变量，使其不会出现在命令行或 shell 历史记录中：

```bash
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY  # paste the key, then press Enter
bird webhooks create --connector claude_managed_agents \
  --field agent_id=agent_123 --field environment_id=env_123 \
  --secret-env api_key=ANTHROPIC_API_KEY
```

API 在 [`POST /v1/webhooks`](/docs/api/reference/create-webhook) 上接受相同的 `destination`。省略 `url`：Bird 会根据连接器自动构建。响应中不会包含凭据。

## 测试连接

创建 webhook 后，立即选择 **Send test**。之后可在 webhook 页面或行操作中使用 **Send test event**，或调用 [`POST /v1/webhooks/{webhook_id}/test`](/docs/api/reference/test-webhook)。在 Claude 或 Cursor 中确认会话或运行已启动。然后向你的某个号码或渠道发送一条真实消息，确认代理能正确处理。

## 运维操作

- **轮换凭据。** 编辑 webhook 并仅输入新值；留空的字段将保留其已存储的值。通过 API，在 [`PATCH /v1/webhooks/{webhook_id}`](/docs/api/reference/update-webhook) `credentials` 中发送更改后的密钥。下一次投递将使用新值，包括重试。
- **指向另一个代理。** 创建一个新的 webhook。编辑操作无法切换平台或更改代理 ID、webhook URL 等设置。
- **暂停或移除。** 暂停 webhook 会停止其投递。删除 webhook 会清除其凭据。
- **查看失败记录。** Webhook 的尝试列表显示每次投递的平台响应状态和正文，如果无法连接到平台则显示为空。在 Bird 发送任何内容之前就失败的尝试（例如事件发生后连接发生变化）会携带 `failure_reason`。

## 后续步骤

- [Webhook 与事件](/docs/guides/webhooks)
- [MCP 服务器](/docs/ai/mcp-server)
- [设置你的编程代理](/docs/ai/set-up-your-agent)

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)