diff --git a/adk/coding-with-ai/adk-copilot.mdx b/adk/coding-with-ai/adk-copilot.mdx new file mode 100644 index 00000000..92931a79 --- /dev/null +++ b/adk/coding-with-ai/adk-copilot.mdx @@ -0,0 +1,4 @@ +--- +title: ADK Copilot +sidebarTitle: ADK Copilot +--- diff --git a/adk/coding-with-ai/skills-for-agents.mdx b/adk/coding-with-ai/skills-for-agents.mdx new file mode 100644 index 00000000..6363bb3f --- /dev/null +++ b/adk/coding-with-ai/skills-for-agents.mdx @@ -0,0 +1,4 @@ +--- +title: Skills for Agents +sidebarTitle: Skills for Agents +--- diff --git a/adk/concepts/actions.mdx b/adk/concepts/actions.mdx index a6860acb..a8870637 100644 --- a/adk/concepts/actions.mdx +++ b/adk/concepts/actions.mdx @@ -115,7 +115,7 @@ export default new Conversation({ ## Integration actions -When you [install an integration](/adk/managing-integrations), its actions become available anywhere in your agent's source: +When you [install an integration](/adk/integrations/adding-integration), its actions become available anywhere in your agent's source: ```ts highlight={1, 12-14} import { Trigger, actions } from "@botpress/runtime"; diff --git a/adk/control-panel.mdx b/adk/control-panel.mdx new file mode 100644 index 00000000..c753438b --- /dev/null +++ b/adk/control-panel.mdx @@ -0,0 +1,4 @@ +--- +title: Control Panel +sidebarTitle: Control Panel +--- diff --git a/adk/guides/build-extend/adding-hitl.mdx b/adk/guides/build-extend/adding-hitl.mdx new file mode 100644 index 00000000..43d8ef12 --- /dev/null +++ b/adk/guides/build-extend/adding-hitl.mdx @@ -0,0 +1,4 @@ +--- +title: Adding HITL (Human-In-The-Loop) +sidebarTitle: Adding HITL +--- diff --git a/adk/guides/build-extend/authentication.mdx b/adk/guides/build-extend/authentication.mdx new file mode 100644 index 00000000..727f094b --- /dev/null +++ b/adk/guides/build-extend/authentication.mdx @@ -0,0 +1,4 @@ +--- +title: Adding authentication +sidebarTitle: Adding authentication +--- diff --git a/adk/guides/build-extend/external-apis.mdx b/adk/guides/build-extend/external-apis.mdx new file mode 100644 index 00000000..ce0ca25d --- /dev/null +++ b/adk/guides/build-extend/external-apis.mdx @@ -0,0 +1,4 @@ +--- +title: Connecting external APIs +sidebarTitle: Connecting external APIs +--- diff --git a/adk/guides/build-extend/mcp-server.mdx b/adk/guides/build-extend/mcp-server.mdx new file mode 100644 index 00000000..0e869584 --- /dev/null +++ b/adk/guides/build-extend/mcp-server.mdx @@ -0,0 +1,4 @@ +--- +title: Setting up an MCP server +sidebarTitle: Setting up an MCP server +--- diff --git a/adk/guides/evaluate-improve/debugging-traces.mdx b/adk/guides/evaluate-improve/debugging-traces.mdx new file mode 100644 index 00000000..183e5b9c --- /dev/null +++ b/adk/guides/evaluate-improve/debugging-traces.mdx @@ -0,0 +1,4 @@ +--- +title: Debugging agents +sidebarTitle: Debugging agents +--- diff --git a/adk/guides/evaluate-improve/running-evals.mdx b/adk/guides/evaluate-improve/running-evals.mdx new file mode 100644 index 00000000..cd3d7db5 --- /dev/null +++ b/adk/guides/evaluate-improve/running-evals.mdx @@ -0,0 +1,4 @@ +--- +title: Running evaluations +sidebarTitle: Running evaluations +--- diff --git a/adk/guides/operate-scale/deploying.mdx b/adk/guides/operate-scale/deploying.mdx new file mode 100644 index 00000000..c89e8702 --- /dev/null +++ b/adk/guides/operate-scale/deploying.mdx @@ -0,0 +1,4 @@ +--- +title: Deploying your agent +sidebarTitle: Deploying your agent +--- diff --git a/adk/guides/operate-scale/react-frontend.mdx b/adk/guides/operate-scale/react-frontend.mdx new file mode 100644 index 00000000..1a4c54c5 --- /dev/null +++ b/adk/guides/operate-scale/react-frontend.mdx @@ -0,0 +1,4 @@ +--- +title: Connect to React frontend +sidebarTitle: Connect to React frontend +--- diff --git a/adk/integrations/adding-integration.mdx b/adk/integrations/adding-integration.mdx new file mode 100644 index 00000000..0ebfcbe4 --- /dev/null +++ b/adk/integrations/adding-integration.mdx @@ -0,0 +1,109 @@ +--- +title: Adding an integration +sidebarTitle: Adding an integration +--- + +This guide walks you through installing and configuring a Botpress integration in an ADK agent. + + + You will need: + + - A [Botpress account](https://sso.botpress.cloud) + - A local [ADK](/adk/introduction) project + + +## 1. Discover and pick an integration + +Search the hub by keyword: + +```bash +adk search +``` + +List every integration available to install: + +```bash +adk list --available +``` + +Inspect a single integration—actions, channels, events, and metadata: + +```bash +adk info +``` + + +For a full list of flags (for example JSON output or limits), see [`adk search`](/adk/cli-reference#adk-search), [`adk list`](/adk/cli-reference#adk-list), and [`adk info`](/adk/cli-reference#adk-info) in the CLI reference. + + +## 2. Add it to the project + +Install a specific version: + +```bash +adk add slack@2.5.5 +``` + +**Optional alias** (changes how you reference the integration in code): + +```bash +adk add linear@2.0.0 --alias my-linear +``` + +The CLI updates your project configuration and generated types. **As of ADK 1.9+,** integrations are declared under `dependencies.integrations` in **`agent.config.ts`** (not `dependencies.json`). + + +After adding or changing integrations, run `adk dev` or `adk build` so TypeScript types stay in sync with what you installed. + + +## 3. Configure credentials and settings + +### Method 1: Control Panel (recommended for OAuth and guided setup) + +1. Run `adk dev`. +2. Open the Control Panel (often [`http://localhost:3001`](http://localhost:3001)) and go to the Integration page and configure your account. + +For more detail, see [Managing an integration](/adk/integrations/managing-integration). + +### Method 2: `agent.config.ts` + +Edit `version`, `enabled`, and any `config` / `configurationType` fields the integration expects. Sensitive values are often wired through **`process.env.*`** and your workspace or deployment environment. + +## 4. Use it in code + +Import the generated **`actions`** object and call the integration using its **key** in `dependencies.integrations` (or the key from **`--alias`**): + +```typescript +import { actions } from "@botpress/runtime"; + +await actions.slack.sendMessage({ channel: "#general", text: "Hello!" }); +``` + +**Pattern:** `await actions..(params)`. + +- **``**: The name under `dependencies.integrations` in `agent.config.ts` (for example `slack`, or `my-linear` if you used `--alias my-linear`). +- **``**: The action exposed by that integration (see `adk info` or your editor’s types). + +**Optional: expose to the model as a tool** + +Inside a conversation `execute` call, you can pass integration actions as tools: + +```typescript +await execute({ + instructions: "…", + tools: [actions.slack.sendMessage.asTool()], +}); +``` + +Use the same `actions...asTool()` pattern as for [custom actions](/adk/concepts/actions#as-a-tool-in-a-conversation). + +## Next steps + + + + Call and compose actions from conversations, workflows, and triggers + + + `adk add`, `adk remove`, and related commands + + diff --git a/adk/integrations/integrations-overview.mdx b/adk/integrations/integrations-overview.mdx new file mode 100644 index 00000000..8db4d058 --- /dev/null +++ b/adk/integrations/integrations-overview.mdx @@ -0,0 +1,4 @@ +--- +title: Integrations overview +sidebarTitle: Overview +--- diff --git a/adk/integrations/managing-integration.mdx b/adk/integrations/managing-integration.mdx new file mode 100644 index 00000000..02c287cc --- /dev/null +++ b/adk/integrations/managing-integration.mdx @@ -0,0 +1,4 @@ +--- +title: Managing an integration +sidebarTitle: Managing an integration +--- diff --git a/adk/integrations/removing-integration.mdx b/adk/integrations/removing-integration.mdx new file mode 100644 index 00000000..14f28d8d --- /dev/null +++ b/adk/integrations/removing-integration.mdx @@ -0,0 +1,4 @@ +--- +title: Removing an integration +sidebarTitle: Removing an integration +--- diff --git a/adk/managing-integrations.mdx b/adk/managing-integrations.mdx deleted file mode 100644 index b570cdfd..00000000 --- a/adk/managing-integrations.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -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. - -## Adding integrations - -### Using the CLI - -Add an integration using the `adk add` command: - -```bash -adk add webchat -adk add slack@latest -adk add my-workspace/custom-integration@1.0.0 -``` - -### Using an alias - -Add an integration with a custom alias: - -```bash -adk add webchat --alias custom-webchat -``` - -This automatically: -- Adds the integration to `agent.config.ts` -- Generates TypeScript types for the integration - -### Manual configuration - -You can also manually edit `agent.config.ts`: - -```typescript -export default defineConfig({ - // ... other config ... - dependencies: { - integrations: { - webchat: { - version: "webchat@latest", - enabled: true, - }, - slack: { - version: "slack@0.5.0", - enabled: true, - }, - }, - }, -}); -``` - -After editing manually, run `adk dev` or `adk build` to regenerate types. - -## Integration versions - -Integration versions use the format `name@version`: - -- `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 - - -Use `@latest` when you want to automatically receive updates. Use specific versions for production deployments to ensure stability. - - -## Enabling and disabling - -Control which integrations are active: - -```typescript -dependencies: { - integrations: { - webchat: { - version: "webchat@latest", - enabled: true, - }, - slack: { - version: "slack@latest", - enabled: false, - }, - }, -} -``` - -Disabled integrations are still included in your project but won't be active when your agent runs. - -## Integration configuration - -If you install an integration that requires configuration, you'll receive a message instructing you to configure it: - -```bash -adk add instagram -``` - -```text -✓ Added instagram version x.x.x to agent.config.ts - -Please configure it in the UI using the adk dev command to start using it. -``` - -## Updating integrations - -To update an integration: - -### Using the CLI - -``` -adk upgrade -``` - -### Manually - -You can also update the version it manually: - -1. Update the version in `agent.config.ts`: - ```typescript - dependencies: { - integrations: { - webchat: { - version: "webchat@0.3.0", - enabled: true, - }, - }, - } - ``` - -2. Run `adk dev` or `adk build` to regenerate types - -3. Test your agent to ensure compatibility - -## Removing integrations - -### Using the CLI - -Remove an integration using the `adk remove` command: - -```bash -adk remove -``` - -### Manually - -You can also remove an integration by deleting it from `agent.config.ts`: - -```typescript -dependencies: { - integrations: { - webchat: { - version: "webchat@latest", - enabled: true, - }, - // Removed slack integration - }, -} -``` - -Run `adk dev` or `adk build` to update generated types. - - -Always test your agent after adding, updating, or removing integrations to ensure everything works correctly. - - diff --git a/adk/quickstart.mdx b/adk/quickstart.mdx index 22842d83..ba7008f5 100644 --- a/adk/quickstart.mdx +++ b/adk/quickstart.mdx @@ -131,7 +131,7 @@ Type "exit" or press ESC key to quit ### View the ADK console -Visit [`http://localhost:3001/`](http://localhost:3001/) to access the interactive ADK console. This gives you an intuitive, visual breakdown of your agent project and lets you [configure its integration's settings](/adk/managing-integrations#integration-configuration). +Visit [`http://localhost:3001/`](http://localhost:3001/) to access the interactive ADK console. This gives you an intuitive, visual breakdown of your agent project and lets you [configure its integration's settings](/adk/integrations/managing-integration). ## Build your agent diff --git a/docs.json b/docs.json index 079060fc..67c14306 100644 --- a/docs.json +++ b/docs.json @@ -107,13 +107,62 @@ "/adk/concepts/tools" ] }, - "/adk/managing-integrations", - "/adk/runtime", + "/adk/control-panel", { - "group": "Zai", - "pages": ["/adk/zai/overview", "/adk/zai/reference"] + "group": "Integrations", + "pages": [ + "/adk/integrations/integrations-overview", + "/adk/integrations/adding-integration", + "/adk/integrations/managing-integration", + "/adk/integrations/removing-integration" + ] + }, + { + "group": "Guides", + "pages": [ + { + "group": "Build & Extend", + "pages": [ + "/adk/guides/build-extend/adding-hitl", + "/adk/guides/build-extend/mcp-server", + "/adk/guides/build-extend/external-apis", + "/adk/guides/build-extend/authentication" + ] + }, + { + "group": "Evaluate & Improve", + "pages": [ + "/adk/guides/evaluate-improve/running-evals", + "/adk/guides/evaluate-improve/debugging-traces" + ] + }, + { + "group": "Operate & Scale", + "pages": [ + "/adk/guides/operate-scale/deploying", + "/adk/guides/operate-scale/react-frontend" + ] + } + ] }, - "/adk/cli-reference" + { + "group": "Coding with AI", + "pages": [ + "/adk/coding-with-ai/skills-for-agents", + "/adk/coding-with-ai/adk-copilot" + ] + }, + { + "group": "References", + "pages": [ + { + "group": "Zai", + "pages": ["/adk/zai/overview", "/adk/zai/reference"] + }, + "/adk/runtime", + "/adk/cli-reference" + ] + } ] }, { @@ -648,6 +697,26 @@ "source": "/for-developers/adk/:slug*", "destination": "/adk/:slug*" }, + { + "source": "/adk/managing-integrations", + "destination": "/adk/integrations/integrations-overview" + }, + { + "source": "/adk/integrations/overview", + "destination": "/adk/integrations/integrations-overview" + }, + { + "source": "/adk/integrations/adding", + "destination": "/adk/integrations/adding-integration" + }, + { + "source": "/adk/integrations/managing", + "destination": "/adk/integrations/managing-integration" + }, + { + "source": "/adk/integrations/removing", + "destination": "/adk/integrations/removing-integration" + }, { "source": "/for-developers/zai/:slug*", "destination": "/adk/zai/:slug*"