Managing dependencies

Your agent depends on two kinds of external resources:

• Integrations connect your agent to a channel or service, like Webchat, Slack, Linear, or Stripe. You browse and install them from the Botpress Hub.
• Plugins are reusable behaviors provided by Botpress, like human handoff or analytics. A plugin adds logic to your bot and builds on integrations to reach the outside world.

How dependencies work

In ADK 2.0, Botpress Cloud is the source of truth for your dependencies, stored separately for each bot. Since your development bot is private to you, its integrations are yours alone; the production bot holds the shared, deployed set.

You manage that state from two interchangeable places, and both write to Cloud directly:

• The CLI (adk integrations and adk plugins).
• The Dev Console’s Integration Hub.

The ADK keeps a local cache of installed dependencies in .adk/dependencies/dev.json and .adk/dependencies/prod.json. These snapshots are generated mirrors of Cloud state for fast reads, offline status, code generation, and deploy checks. They are gitignored, may contain config values, and should never be edited or committed. If a snapshot is stale or corrupt, the ADK refreshes it from Cloud.

You also no longer declare integrations in agent.config.ts.

Adding integrations

Browse the catalog and install from the Integration Hub in the Dev Console, no CLI required:

Or use the CLI. Commands default to your development bot; pass --target prod to act on production instead:

adk integrations search linear           # find integrations in the catalog
adk integrations add linear              # install the latest version
adk integrations add stripe@1.4.2        # pin a specific version
adk integrations list                    # see what's installed
adk integrations remove linear           # uninstall

Reference a version with name@latest (the default) or name@version (for example, stripe@1.4.2).

Configuring integrations

Most integrations need configuration, such as API keys or an OAuth connection, before they can run. Configure them in the Dev Console:

Or from the CLI:

adk integrations configure notion --set apiKey=secret_...
adk integrations enable notion
adk integrations disable notion

Integration configuration is stored on Botpress Cloud, not in your project files. Your development and production bots each have their own, so you can use different keys per target. OAuth integrations are connected in the Botpress Control Panel rather than with a key.

Dependency status

Every dependency resolves to one status, which the CLI and Dev Console both report:

Status	Meaning
available	Installed, configured, and ready to use
disabled	Installed but turned off; it won’t run
unconfigured	Installed but missing required configuration or a connection
unresolved	The requested version or resource couldn’t be resolved
not_installed	Declared but not installed on this bot
errored	Failed to load

Missing required config and pending OAuth or connection setup both appear as unconfigured. The CLI may include missingFields or an authorization-pending hint to explain what is blocking the dependency.

Check status any time:

adk integrations status

adk deploy blocks when an enabled dependency is unconfigured, unresolved, not_installed, or errored, so you don’t ship a broken integration. Disabled dependencies ship inert and never block. To deploy anyway, disable the dependency or pass adk deploy --allow-unconfigured.

Promoting from development to production

The everyday loop is to build an integration on your development bot, then promote it to production. adk integrations copy reconciles one bot’s dependencies to match another’s. Always preview with --dry-run first:

adk integrations copy --from dev --to prod --dry-run   # preview the changes
adk integrations copy --from dev --to prod --yes       # apply them

copy works in either direction. To seed a fresh development bot with the production setup, reverse it:

adk integrations copy --from prod --to dev

The source bot is never modified. The target bot is reconciled to match the source, so review the dry run before applying, especially when it includes removals.

copy moves integrations and plugins, not your agent code, table rows, knowledge data, or conversations. Shipping code is a separate step: adk deploy.

Automation tips

For scripts and coding agents, prefer machine-readable output and explicit targets:

ADK_TARGET=prod adk integrations status --format json
adk integrations copy --from dev --to prod --dry-run --format json

Use --yes only after reviewing the dry run. Do not edit files under .adk/dependencies/; refresh or mutate dependencies through the CLI or Dev Console instead.

Plugins

Where an integration connects your bot to a service, a plugin adds reusable behavior on top of it. For a worked example, see HITL with Desk, which uses the desk-hitl plugin to hand conversations off to a human agent.

adk plugins mirrors the full set of integration verbs (add, remove, configure, enable, disable, list, status, copy, and more):

adk plugins add <name>
adk plugins configure <alias> --set key=value