docs(adk): rewrite Managing Integrations page

adk/managing-integrations.mdx

@@ -2,162 +2,235 @@
 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
+```
 
-<Tip>
-Use `@latest` when you want to automatically receive updates. Use specific versions for production deployments to ensure stability.
-</Tip>
+```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.
+<Note>
+  Newly added integrations are disabled by default. Enable and configure them in the Control Panel during `adk dev`.
+</Note>
 
-## 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 <integration-name>
-```
 
-### Manually
+<Note>
+  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.
+</Note>
+
+### Workspace-scoped integrations
 
-You can also update the version it manually:
+Add a private or custom integration from your workspace:
 
-1. Update the version in `agent.config.ts`:
-   ```typescript
-   dependencies: {
-     integrations: {
-       webchat: {
-         version: "webchat@0.3.0",
-         enabled: true,
-       },
-     },
-   }
-   ```
+```bash
+adk add my-workspace/custom-integration@1.0.0
+```
 
-2. Run `adk dev` or `adk build` to regenerate types
+## Configuring integrations
 
-3. Test your agent to ensure compatibility
+Integration settings (API keys, tokens, OAuth credentials) are managed in the Control Panel, not in `agent.config.ts`.
 
-## Removing integrations
+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
 
-### Using the CLI
+<Frame>
+  <img alt="Integrations in the Control Panel" className="block dark:hidden" src="./assets/adk-integration-page.png" />
+  <img alt="Integrations in the Control Panel" className="hidden dark:block" src="./assets/adk-integration-page-dark.png" />
+</Frame>
 
-Remove an integration using the `adk remove` command:
+Each integration card in the Control Panel shows its current status:
 
-```bash
-adk remove <integration-name>
-```
+| Status | Meaning |
+|--------|---------|
+| Connected | Enabled, registered, and configured |
+| Disabled | Turned off, can be enabled |
+| Needs Action | Requires installation, configuration, or enabling |
+| Failed | Registration error |
 
-### Manually
+## Migrating from object format
 
-You can also remove an integration by deleting it from `agent.config.ts`:
+Earlier versions of the ADK used an object format for integrations in `agent.config.ts`:
 
 ```typescript
+// Old format (deprecated)
 dependencies: {
   integrations: {
-    webchat: {
-      version: "webchat@latest",
+    chat: {
+      version: "chat@0.7.7",
       enabled: true,
     },
-    // Removed slack integration
   },
 }
 ```
 
-Run `adk dev` or `adk build` to update generated types.
+This has been replaced by string shorthand, with settings now managed in the Control Panel:
 
-<Tip>
-Always test your agent after adding, updating, or removing integrations to ensure everything works correctly.
-</Tip>
+```typescript
+// New format
+dependencies: {
+  integrations: {
+    chat: "chat@0.7.7",
+  },
+}
+```
+
+When you run `adk dev` with the old format, the CLI detects it and prompts you to migrate:
+
+1. The CLI displays which integrations use the deprecated format
+2. You're asked to confirm the migration
+3. Integrations without custom configs are automatically converted to string shorthand
+4. Integrations with custom configs need manual updates — move their settings to the Control Panel
+
+## Listing installed integrations
+
+View integrations currently installed in your project. The **Alias** column shows the key you use to reference each integration in your code:
+
+```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 upgrade linear
+```
+
+### Update all integrations interactively
+
+```bash
+adk upgrade
+```
+
+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
+```
+
+```txt
+✓ Removed linear from agent.config.ts dependencies
+  Run adk dev to update your project
+```
+
+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).