diff --git a/adk/advanced/hitl.mdx b/adk/advanced/hitl.mdx new file mode 100644 index 00000000..afce21d5 --- /dev/null +++ b/adk/advanced/hitl.mdx @@ -0,0 +1,140 @@ +--- +title: Human-in-the-loop +description: Escalate conversations to live human agents. +--- + + + This covers the HITL integration and plugin, which connects your agent to external helpdesk platforms (Zendesk, Intercom, etc.). This is separate from integrating your ADK agent with [Botpress Desk](/desk/introduction). + + +HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. It's powered by two dependencies working together: the **HITL integration** (the transport to a helpdesk or agent platform) and the **HITL plugin** (the actions your code calls). + +## Add HITL to your agent + +Add both the integration and the plugin to `agent.config.ts`. The plugin's `dependencies` block points at the integration by alias: + +```typescript +import { defineConfig } from "@botpress/runtime" + +export default defineConfig({ + name: "my-agent", + + defaultModels: { + autonomous: "openai:gpt-4.1-mini-2025-04-14", + zai: "openai:gpt-4.1-mini-2025-04-14", + }, + + dependencies: { + integrations: { + chat: "chat@1.0.0", + webchat: "webchat@0.3.0", + hitl: "hitl@2.0.2", + }, + + plugins: { + hitl: { + version: "hitl@1.3.0", + dependencies: { + hitl: { + integrationAlias: "hitl", + integrationInterfaceAlias: "hitl", + }, + }, + }, + }, + }, +}) +``` + +`integrationAlias` must match a key in `dependencies.integrations`. The ADK validates this at build time, so a typo here fails fast. `integrationInterfaceAlias` tells the plugin which interface entity the integration implements (`hitlSession` for the generic HITL integration, `hitlTicket` for Zendesk, and so on). + +The HITL plugin also accepts a top-level `config` object for plugin-wide behavior. See the HITL plugin's Hub listing for the full set of fields. + +## Start a handoff + +Import `plugins` from `@botpress/runtime` and call `startHitl` from a conversation handler. All inputs are typed against the plugin: + +```typescript +import { Conversation, plugins } from "@botpress/runtime" + +export default new Conversation({ + channel: ["chat.channel", "webchat.channel"], + handler: async ({ execute, conversation, message }) => { + if (message.payload.text.toLowerCase() === "/starthitl") { + await plugins.hitl.actions.startHitl({ + title: "Support HITL", + description: "Escalate to support agent", + conversationId: conversation.id, + userId: message.userId, + configurationOverrides: { + onHitlHandoffMessage: "Escalating to support...", + userHitlCloseCommand: "/end", + agentAssignedTimeoutSeconds: 100, + }, + }) + return + } + + await execute({ + instructions: "You are a helpful assistant. If the user asks for a human, tell them to type /starthitl.", + }) + }, +}) +``` + +The fields passed to `startHitl`: + +| Field | Description | +|-------|-------------| +| `title` | Short label shown to the human agent when the ticket opens | +| `description` | Longer context the human agent sees alongside the conversation | +| `conversationId` | The conversation to hand off (use `conversation.id` from the handler) | +| `userId` | The user initiating the handoff | +| `configurationOverrides` | Optional per-handoff overrides of the plugin config | + +Common override fields: + +| Field | Description | +|-------|-------------| +| `onHitlHandoffMessage` | Message sent to the user when the handoff begins | +| `userHitlCloseCommand` | Message text the user can send to close the session | +| `agentAssignedTimeoutSeconds` | How long to wait for a human agent to pick up before timing out | + +For the full set of override fields, see the HITL plugin's Hub listing. + +## Use a different provider + +The HITL plugin works with any integration that implements the HITL interface. To swap the generic HITL integration for Zendesk, change the integration and update the alias. `hitlTicket` replaces `hitlSession` because Zendesk implements the interface with tickets instead of sessions: + +```typescript +dependencies: { + integrations: { + zendesk: "zendesk@1.0.0", + }, + plugins: { + hitl: { + version: "hitl@1.3.0", + dependencies: { + hitl: { + integrationAlias: "zendesk", + integrationInterfaceAlias: "hitl", + }, + }, + }, + }, +}, +``` + +Your application code doesn't change. `plugins.hitl.actions.startHitl` works the same regardless of which integration is wired underneath. + +## Deploy and test + +Run `adk deploy` to push the agent to Botpress Cloud. See the [CLI reference](/adk/cli-reference#adk-deploy) for all deploy flags: + +```bash +adk deploy +``` + + + HITL only works against a deployed bot. `adk dev` downloads the plugin into `bp_modules/` and generates types, but handoffs need the integration's real connection to your helpdesk, which is configured on the production bot. + diff --git a/adk/ai-native/skills.mdx b/adk/ai-native/skills.mdx new file mode 100644 index 00000000..5379036f --- /dev/null +++ b/adk/ai-native/skills.mdx @@ -0,0 +1,84 @@ +--- +title: Skills +description: Give AI coding assistants deep ADK knowledge with installable skills. +--- + +Skills are packaged instructions and documentation that teach AI coding assistants how to build with the ADK. When installed, assistants like Claude Code, Cursor, and Codex use them automatically when you ask them to build features, debug issues, write evals, or connect integrations. `adk init` installs them for you alongside your dependencies, so most projects get them out of the box. + +## Manual installation + +If you need to install skills in an existing project or reinstall them, run the same command `adk init` runs: + +```bash +npx skills add botpress/skills -s '*' -a codex claude-code -y +``` + +Use `bunx` instead of `npx` if your project has a `bun.lockb`. + +To install a single skill instead of all of them: + +```bash +npx skills add botpress/skills --skill adk +``` + +Or install as a Claude Code plugin: + +``` +/plugin marketplace add botpress/skills +/plugin install adk@botpress-skills +``` + +## Available skills + +| Skill | What it teaches | Use when | +|-------|----------------|----------| +| **adk** | Core ADK framework: actions, tools, workflows, conversations, tables, knowledge, triggers, Zai, configuration | Building any feature with the ADK | +| **adk-debugger** | Trace reading, log analysis, common failure diagnosis, the debug loop | Bot isn't responding, tools failing, workflows stuck, LLM issues | +| **adk-evals** | Eval file format, all assertion types, CLI usage, per-primitive testing patterns | Writing and running automated tests | +| **adk-frontend** | Authentication, type generation, client setup, calling bot actions from React/Next.js | Building a frontend that connects to your bot | +| **adk-integrations** | Discovery, adding, configuring, and using integrations end-to-end | Connecting Slack, WhatsApp, Linear, or any integration | +| **adk-docs** | Documentation standards, creation, review, and maintenance | Writing or updating docs for your bot | + +## Slash commands + +Skills come with slash commands for Claude Code. Type the command instead of describing what you need: + +| Command | What it does | +|---------|-------------| +| `/adk-init` | Scaffold a new ADK project | +| `/adk-debug` | Debug bot issues using traces, logs, and the debug loop | +| `/adk-eval` | Write, run, or debug evals | +| `/adk-frontend` | Build frontend apps that integrate with ADK bots | +| `/adk-integration` | Discover, add, and configure integrations | +| `/adk-doc-create` | Create documentation for a feature | +| `/adk-doc-review` | Review project docs for accuracy | +| `/adk-doc-update` | Update docs after code changes | +| `/adk-doc-sync` | Check if docs are in sync with code | +| `/adk-doc-search` | Search project documentation | + +## MCP server + +Skills are the recommended way to give AI assistants ADK knowledge. The ADK also ships an MCP (Model Context Protocol) server that gives assistants live access to your running project, kept here for reference. + +Generate the MCP configuration files: + +```bash +adk mcp:init --all +``` + +This writes config for Claude Code (`.mcp.json`), VS Code (`.vscode/mcp.json`), and Cursor (`.cursor/mcp.json`). See [`adk mcp:init`](/adk/cli-reference#adk-mcpinit) for all flags. + +The server exposes these tools: + +| Tool | What it does | +|------|-------------| +| `adk_get_agent_info` | Get project structure and primitives | +| `adk_search_integrations` | Search the Botpress Hub | +| `adk_get_integration` | Get detailed integration info | +| `adk_add_integration` | Add an integration to the project | +| `adk_send_message` | Send a test message to the running bot | +| `adk_query_traces` | Query trace spans for debugging | +| `adk_get_dev_logs` | Get dev server logs and errors | +| `adk_list_workflows` | List available workflows | +| `adk_start_workflow` | Start a workflow or get its input schema | +| `adk_init_project` | Scaffold a new ADK project (only available outside an ADK project) | diff --git a/adk/assets/actions-console-dark.png b/adk/assets/actions-console-dark.png new file mode 100644 index 00000000..9f18cb44 Binary files /dev/null and b/adk/assets/actions-console-dark.png differ diff --git a/adk/assets/actions-console.png b/adk/assets/actions-console.png new file mode 100644 index 00000000..925251ae Binary files /dev/null and b/adk/assets/actions-console.png differ diff --git a/adk/assets/agent-steps-dark.png b/adk/assets/agent-steps-dark.png new file mode 100644 index 00000000..fee4fde3 Binary files /dev/null and b/adk/assets/agent-steps-dark.png differ diff --git a/adk/assets/agent-steps.png b/adk/assets/agent-steps.png new file mode 100644 index 00000000..470ab5a0 Binary files /dev/null and b/adk/assets/agent-steps.png differ diff --git a/adk/assets/config-variables-console-dark.png b/adk/assets/config-variables-console-dark.png new file mode 100644 index 00000000..844d3307 Binary files /dev/null and b/adk/assets/config-variables-console-dark.png differ diff --git a/adk/assets/config-variables-console.png b/adk/assets/config-variables-console.png new file mode 100644 index 00000000..f9685757 Binary files /dev/null and b/adk/assets/config-variables-console.png differ diff --git a/adk/assets/control-panel-quickstart-dark.png b/adk/assets/control-panel-quickstart-dark.png deleted file mode 100644 index 292a5967..00000000 Binary files a/adk/assets/control-panel-quickstart-dark.png and /dev/null differ diff --git a/adk/assets/control-panel-quickstart.png b/adk/assets/control-panel-quickstart.png deleted file mode 100644 index f4569d23..00000000 Binary files a/adk/assets/control-panel-quickstart.png and /dev/null differ diff --git a/adk/assets/conversations-chat-dark.png b/adk/assets/conversations-chat-dark.png new file mode 100644 index 00000000..97584ea7 Binary files /dev/null and b/adk/assets/conversations-chat-dark.png differ diff --git a/adk/assets/conversations-chat.png b/adk/assets/conversations-chat.png new file mode 100644 index 00000000..97584ea7 Binary files /dev/null and b/adk/assets/conversations-chat.png differ diff --git a/adk/assets/environment-selector-dark.png b/adk/assets/environment-selector-dark.png new file mode 100644 index 00000000..90ae5e50 Binary files /dev/null and b/adk/assets/environment-selector-dark.png differ diff --git a/adk/assets/environment-selector.png b/adk/assets/environment-selector.png new file mode 100644 index 00000000..93326e38 Binary files /dev/null and b/adk/assets/environment-selector.png differ diff --git a/adk/assets/evals-console-dark.png b/adk/assets/evals-console-dark.png new file mode 100644 index 00000000..eef06434 Binary files /dev/null and b/adk/assets/evals-console-dark.png differ diff --git a/adk/assets/evals-console.png b/adk/assets/evals-console.png new file mode 100644 index 00000000..a366230c Binary files /dev/null and b/adk/assets/evals-console.png differ diff --git a/adk/assets/integration-config-console-dark.png b/adk/assets/integration-config-console-dark.png new file mode 100644 index 00000000..4103b9f1 Binary files /dev/null and b/adk/assets/integration-config-console-dark.png differ diff --git a/adk/assets/integration-config-console.png b/adk/assets/integration-config-console.png new file mode 100644 index 00000000..72d598a6 Binary files /dev/null and b/adk/assets/integration-config-console.png differ diff --git a/adk/assets/integrations-console-dark.png b/adk/assets/integrations-console-dark.png new file mode 100644 index 00000000..9de8bc06 Binary files /dev/null and b/adk/assets/integrations-console-dark.png differ diff --git a/adk/assets/integrations-console.png b/adk/assets/integrations-console.png new file mode 100644 index 00000000..6fa808f3 Binary files /dev/null and b/adk/assets/integrations-console.png differ diff --git a/adk/assets/knowledge-console-dark.png b/adk/assets/knowledge-console-dark.png new file mode 100644 index 00000000..843b0106 Binary files /dev/null and b/adk/assets/knowledge-console-dark.png differ diff --git a/adk/assets/knowledge-console.png b/adk/assets/knowledge-console.png new file mode 100644 index 00000000..bd53f5e5 Binary files /dev/null and b/adk/assets/knowledge-console.png differ diff --git a/adk/assets/logs-view-dark.png b/adk/assets/logs-view-dark.png new file mode 100644 index 00000000..b1f6bf14 Binary files /dev/null and b/adk/assets/logs-view-dark.png differ diff --git a/adk/assets/logs-view.png b/adk/assets/logs-view.png new file mode 100644 index 00000000..81b890da Binary files /dev/null and b/adk/assets/logs-view.png differ diff --git a/adk/assets/quickstart-dark.png b/adk/assets/quickstart-dark.png new file mode 100644 index 00000000..f0de5b90 Binary files /dev/null and b/adk/assets/quickstart-dark.png differ diff --git a/adk/assets/quickstart.png b/adk/assets/quickstart.png new file mode 100644 index 00000000..51b67ffe Binary files /dev/null and b/adk/assets/quickstart.png differ diff --git a/adk/assets/secrets-console-dark.png b/adk/assets/secrets-console-dark.png new file mode 100644 index 00000000..0198132d Binary files /dev/null and b/adk/assets/secrets-console-dark.png differ diff --git a/adk/assets/secrets-console.png b/adk/assets/secrets-console.png new file mode 100644 index 00000000..b3b45b40 Binary files /dev/null and b/adk/assets/secrets-console.png differ diff --git a/adk/assets/tables-console-dark.png b/adk/assets/tables-console-dark.png new file mode 100644 index 00000000..49fa1074 Binary files /dev/null and b/adk/assets/tables-console-dark.png differ diff --git a/adk/assets/tables-console.png b/adk/assets/tables-console.png new file mode 100644 index 00000000..b3cbcdc8 Binary files /dev/null and b/adk/assets/tables-console.png differ diff --git a/adk/assets/traces-view-dark.png b/adk/assets/traces-view-dark.png new file mode 100644 index 00000000..ee698cc2 Binary files /dev/null and b/adk/assets/traces-view-dark.png differ diff --git a/adk/assets/traces-view.png b/adk/assets/traces-view.png new file mode 100644 index 00000000..4874a360 Binary files /dev/null and b/adk/assets/traces-view.png differ diff --git a/adk/assets/triggers-console-dark.png b/adk/assets/triggers-console-dark.png new file mode 100644 index 00000000..d09b6b3e Binary files /dev/null and b/adk/assets/triggers-console-dark.png differ diff --git a/adk/assets/triggers-console.png b/adk/assets/triggers-console.png new file mode 100644 index 00000000..4694af91 Binary files /dev/null and b/adk/assets/triggers-console.png differ diff --git a/adk/assets/welcome-dark.png b/adk/assets/welcome-dark.png new file mode 100644 index 00000000..bc5ed623 Binary files /dev/null and b/adk/assets/welcome-dark.png differ diff --git a/adk/assets/welcome.png b/adk/assets/welcome.png new file mode 100644 index 00000000..8b0741ad Binary files /dev/null and b/adk/assets/welcome.png differ diff --git a/adk/assets/workflows-console-dark.png b/adk/assets/workflows-console-dark.png new file mode 100644 index 00000000..745b137a Binary files /dev/null and b/adk/assets/workflows-console-dark.png differ diff --git a/adk/assets/workflows-console.png b/adk/assets/workflows-console.png new file mode 100644 index 00000000..196d0948 Binary files /dev/null and b/adk/assets/workflows-console.png differ diff --git a/adk/cli-reference.mdx b/adk/cli-reference.mdx index c78e08a2..a9987052 100644 --- a/adk/cli-reference.mdx +++ b/adk/cli-reference.mdx @@ -3,649 +3,533 @@ title: CLI reference description: All commands and flags available with the ADK CLI. --- -The ADK CLI provides commands for creating, developing, building, and deploying Botpress agents. +The `adk` CLI is how you scaffold, run, deploy, and debug ADK agents. Run `adk --help` for the top-level command list, or `adk --help` for flags on a specific command. ## Global flags -These flags are available for all commands: +These flags work with every command: -| Flag | Alias | Description | -|------|-------|-------------| -| `--help` | `-h` | Show help information | -| `--version` | `-V` | Show version number | -| `--no-cache` | | Disable caching for integration lookups | +| Flag | Description | +|------|-------------| +| `--help`, `-h` | Show help information | +| `--version`, `-V` | Show version number | +| `--no-cache` | Disable caching for integration lookups | +| `--profile ` | Credentials profile to use (overrides the `ADK_PROFILE` env var and the current profile) | + +Most commands also accept `--format json` for machine-readable output. The following commands don't: `dev`, `login`, `profiles list`, `profiles set`, `upgrade`, `remove`, `self-upgrade`, `telemetry`, `theme`, `mcp`, `mcp:init`, `run`, `assets pull`. + +## Project -## Commands +These commands manage an agent project from scaffold to deploy: -### `adk init` +| Command | Description | +|---------|-------------| +| `adk init [name]` | Initialize a new project | +| `adk dev` | Start development mode with hot reloading | +| `adk build` | Build the agent for production | +| `adk deploy` | Deploy the agent to Botpress Cloud | +| `adk check` | Validate project structure and config (no login required) | +| `adk status` | Show project status, integrations, and server state | +| `adk link` | Link local agent to a workspace and bot | -Initialize a new ADK agent project. +### adk init + +Scaffold a new agent project. Pass a name, or omit it to be prompted: -**Usage:** ```bash adk init my-agent adk init my-agent --template hello-world +adk init --list-templates ``` -**Arguments:** - -| Argument | Description | -|----------|-------------| -| `project-name` | Name of the project directory to create | - -**Flags:** - -| Flag | Description | Default | -|------|-------------|---------| -| `--template` | Template to use: `blank` or `hello-world` | `blank` | - ---- +| Flag | Description | +|------|-------------| +| `-t, --template