diff --git a/adk/assets/adk-integration-page-dark.png b/adk/assets/adk-integration-page-dark.png new file mode 100644 index 00000000..0028e129 Binary files /dev/null and b/adk/assets/adk-integration-page-dark.png differ diff --git a/adk/assets/adk-integration-page.png b/adk/assets/adk-integration-page.png new file mode 100644 index 00000000..5390673b Binary files /dev/null and b/adk/assets/adk-integration-page.png differ diff --git a/adk/managing-integrations.mdx b/adk/managing-integrations.mdx index b570cdfd..6dfc1951 100644 --- a/adk/managing-integrations.mdx +++ b/adk/managing-integrations.mdx @@ -2,162 +2,201 @@ title: Managing integrations --- -Integrations connect your agent to external services and platforms. This guide covers how to add, configure, and manage integrations in your ADK project. +Integrations connect your agent to external services and platforms. This guide covers how to find, add, configure, and manage integrations in your ADK project. -## Adding integrations +## Finding integrations -### Using the CLI +### Search the Botpress Integration Hub -Add an integration using the `adk add` command: +Search for integrations by keyword: ```bash -adk add webchat -adk add slack@latest -adk add my-workspace/custom-integration@1.0.0 +adk search crm ``` -### Using an alias +### List available integrations -Add an integration with a custom alias: +Browse all available integrations from the Botpress Integration Hub: ```bash -adk add webchat --alias custom-webchat +adk list --available ``` -This automatically: -- Adds the integration to `agent.config.ts` -- Generates TypeScript types for the integration +### View integration details -### Manual configuration +Get detailed information about a specific integration, including its actions, events, and channels: -You can also manually edit `agent.config.ts`: +```bash +adk info linear +``` -```typescript -export default defineConfig({ - // ... other config ... - dependencies: { - integrations: { - webchat: { - version: "webchat@latest", - enabled: true, - }, - slack: { - version: "slack@0.5.0", - enabled: true, - }, - }, - }, -}); +You can also filter the output: + +```bash +adk info linear --actions # Show only actions +adk info linear --events # Show only events +adk info linear --channels # Show only channels ``` -After editing manually, run `adk dev` or `adk build` to regenerate types. +See the [CLI reference](/adk/cli-reference) for all available flags and options. -## Integration versions +## Adding integrations -Integration versions use the format `name@version`: +Add an integration using the `adk add` command: -- `webchat@latest` - Use the latest version -- `slack@0.5.0` - Use a specific version -- `my-workspace/custom@1.2.3` - Use an integration from a specific workspace +```bash +adk add linear +``` - -Use `@latest` when you want to automatically receive updates. Use specific versions for production deployments to ensure stability. - +```txt +✓ Added linear version 2.1.2 as linear to agent.config.ts dependencies -## Enabling and disabling +Added as disabled. Enable and configure it in the Control Panel. +``` -Control which integrations are active: +This adds the integration to your `agent.config.ts` as a string shorthand: ```typescript dependencies: { integrations: { - webchat: { - version: "webchat@latest", - enabled: true, - }, - slack: { - version: "slack@latest", - enabled: false, - }, + chat: "chat@0.7.7", + webchat: "webchat@0.3.0", + linear: "linear@2.1.2", }, -} +}, ``` -Disabled integrations are still included in your project but won't be active when your agent runs. + + Newly added integrations are disabled by default. Enable and configure them in the Control Panel during `adk dev`. + -## Integration configuration +### Pinning a version -If you install an integration that requires configuration, you'll receive a message instructing you to configure it: +Add a specific version instead of the latest: ```bash -adk add instagram +adk add notion@3.0.0 ``` -```text -✓ Added instagram version x.x.x to agent.config.ts +### Using an alias -Please configure it in the UI using the adk dev command to start using it. -``` +Add an integration with a custom alias. This is useful when you need multiple instances of the same integration: -## Updating integrations +```bash +adk add webhook --alias webhookOrders +``` -To update an integration: +The alias is how you reference the integration in your code: -### Using the CLI +```typescript +import { actions } from "@botpress/runtime"; +await actions.webhookOrders.send({ url: "https://api.example.com/orders", data: payload }); ``` -adk upgrade + + + Avoid aliasing built-in channel integrations (webchat, chat, slack, teams, telegram, whatsapp). The runtime uses the alias to identify these integrations, and a custom alias will prevent default message components from loading. + + +### Workspace-scoped integrations + +Add a private or custom integration from your workspace: + +```bash +adk add my-workspace/custom-integration@1.0.0 ``` -### Manually +## Configuring integrations -You can also update the version it manually: +Integration settings (API keys, tokens, OAuth credentials) are managed in the Control Panel, not in `agent.config.ts`. -1. Update the version in `agent.config.ts`: - ```typescript - dependencies: { - integrations: { - webchat: { - version: "webchat@0.3.0", - enabled: true, - }, - }, - } - ``` +1. Run `adk dev` to start the development server +2. Open the Control Panel at `http://localhost:3001/integrations` +3. Find the integration and click to configure it +4. Enter the required settings and enable it -2. Run `adk dev` or `adk build` to regenerate types + + Integrations in the Control Panel + Integrations in the Control Panel + -3. Test your agent to ensure compatibility +Each integration card in the Control Panel shows its current status: -## Removing integrations +| Status | Meaning | +|--------|---------| +| Connected | Enabled, registered, and configured | +| Disabled | Turned off, can be enabled | +| Needs Action | Requires installation, configuration, or enabling | +| Failed | Registration error | + +## Listing installed integrations -### Using the CLI +View integrations currently installed in your project. The **Alias** column shows the key you use to reference each integration in your code: -Remove an integration using the `adk remove` command: +```bash +adk list +``` + +```txt +Installed Integrations (3) + +Alias Name Version +─────────────────────────────────────────────────────────────── +chat chat 0.7.7 +webchat webchat 0.3.0 +linear linear 2.1.2 +``` + +## Updating integrations + +### Update a specific integration ```bash -adk remove +adk upgrade linear ``` -### Manually +### Update all integrations interactively -You can also remove an integration by deleting it from `agent.config.ts`: +```bash +adk upgrade +``` -```typescript -dependencies: { - integrations: { - webchat: { - version: "webchat@latest", - enabled: true, - }, - // Removed slack integration - }, -} +This shows available updates and lets you choose which to upgrade: + +```txt +✓ Upgraded: + • linear (2.0.0 → 2.1.2) + +Run adk dev to install the updated integrations +``` + +## Removing integrations + +Remove an integration from your project: + +```bash +adk remove linear ``` -Run `adk dev` or `adk build` to update generated types. +```txt +✓ Removed linear from agent.config.ts dependencies + Run adk dev to update your project +``` - -Always test your agent after adding, updating, or removing integrations to ensure everything works correctly. - +You can also run `adk remove` without a name to choose interactively. + +## Using integrations in code + +Once an integration is installed and enabled, its actions become available in your agent: + +```typescript +import { actions } from "@botpress/runtime"; + +// Call an integration action +await actions.linear.createIssue({ + title: "Bug report from user", + teamId: "TEAM-123", +}); +``` +You can subscribe to integration events in [Triggers](/adk/concepts/triggers) and [Conversations](/adk/concepts/conversations) (via the `events` prop).