adk-integrations

ADK 集成管理

在帮助用户在 ADK 项目中查找、添加、配置和使用 Botpress 集成时，请使用此技能。

何时使用此技能

在用户遇到以下情况时启用此技能：

• 询问集成相关问题（“如何添加 Slack？”、“有哪些可用集成？”）
• 想要连接外部服务（Slack、WhatsApp、Linear 等）
• 提到 adk add、adk search、adk info 或 adk list
• 询问 agent.config.ts 依赖项或 dependencies.integrations 代码块
• 需要配置集成方面的帮助（OAuth、API 密钥、Dev Console）
• 询问如何在代码中调用集成操作（actions.slack.* 等）
• 提到想让 Agent 与之交互的特定平台或服务
• 遇到与集成注册或配置有关的错误

可用文档

文件	描述
references/discovery.md	查找集成：adk search、adk list、adk info 及其所有标志
references/lifecycle.md	端到端指南：查找、添加、配置并在代码中使用
references/configuration.md	配置类型：无需配置、可选配置、OAuth、API 密钥、沙盒
references/common-integrations.md	聊天、网页聊天、浏览器、slack、whatsapp、linear、webhook 的快速参考

如何回答

1. 从 CLI 命令开始 — 提出建议前，先使用 adk search、adk info、adk list 获取实时数据。通过 Bash 工具运行这些命令。
2. 运行 adk add 前先确认 — 添加集成到用户项目之前，务必先询问用户。
3. 始终指定版本 — 使用 adk add <name>@<version>，不要只用 adk add <name>。
4. 说明配置要求 — 添加后，根据 adk info --format json 的输出，告知用户所需配置（OAuth 链接、API 密钥等）。
5. 指向 Dev Console — OAuth 流程和凭证录入在 Botpress Dev Console 中进行，而不是在代码中进行。

CLI 快速参考

命令	描述	关键标志
adk search <query>	按关键字搜索集成	--format json、--limit <number>（默认值：20）
adk list --available	浏览 Hub 中的所有集成	--format json、--limit <number>（默认值：50）
adk list	显示已安装的依赖项	--format json、--limit <number>（默认值：50）
adk info <name>	完整的集成详情（仅限集成，不包括插件）	--actions、--channels、--events、--full、--format json
adk add <name>@<version>	将集成添加到项目	--alias <name>、--format json
adk add plugin:<name>@<version>	将插件添加到项目	--alias <name>、--format json
adk remove <name>	移除集成、插件或接口	--format json
adk upgrade [name]	升级依赖项（或以交互方式升级全部依赖项）	--format json

使用 --format json 检查 CLI 信息。

关键模式

始终使用 CLI

# CORRECT - Use adk add
adk add [email protected]
adk add plugin:[email protected]
adk add interface:[email protected]

# WRONG - Never manually edit agent.config.ts dependencies
# Don't hand-write entries in the dependencies block

固定版本

# CORRECT - Pin to specific version
adk add [email protected]

# RISKY - Resolves to latest, may change unexpectedly
adk add browser

访问集成操作

// CORRECT - Import from @botpress/runtime, use alias from agent.config.ts
import { actions } from '@botpress/runtime'
await actions.slack.sendMessage({ channel: '#general', text: 'Hello' })

// The alias in agent.config.ts determines the accessor name
// { browser: { version: '[email protected]', enabled: true } }
await actions.browser.webSearch({ query: 'search term' })

检查配置要求

# Use --format json to check what configuration an integration needs
adk info slack --format json

# Look at configuration.schema for required fields
# Look at configuration.identifier for OAuth
# Look at configurations for alternative config modes

此技能可回答的问题示例

入门

• “有哪些可用集成？”
• “如何将 Slack 添加到我的 Agent？”
• “浏览器集成是什么？”

中级

• “如何在沙盒模式下配置 WhatsApp？”
• “webchat 集成提供哪些操作？”
• “如何在工作流中调用 Linear 操作？”
• “chat 和 webchat 有什么区别？”

高级

• “如何使用私有工作区集成？”
• “registration_pending 状态是什么意思？”
• “如何为集成设置别名，让代码更简洁？”
• “如何以编程方式检查集成的配置架构？”