Skip to content

Rewrite ADK documentation#459

Open
aj-botpress wants to merge 70 commits intomasterfrom
aj/adk-docs-update
Open

Rewrite ADK documentation#459
aj-botpress wants to merge 70 commits intomasterfrom
aj/adk-docs-update

Conversation

@aj-botpress
Copy link
Copy Markdown

Summary

Complete rewrite of the ADK documentation section. Restructures the sidebar from a flat "Concepts" list into 11 topic-based groups with 30 pages, all verified against the ADK source code.

What changed:

  • Rewrote Get Started (Welcome, Quickstart) with accurate install flow and dev console description
  • New Setting up your agent section (Agent Configuration, Environment Setup, Integrations)
  • New Handling conversations section (7 pages covering setup, execute(), tools, messages, custom components, lifecycle, state)
  • New Handling longform logic section (Create workflows, steps, request/notify)
  • Renamed and wrote Actions and triggers section
  • New Working with data section (Tables, Knowledge bases with RAG Search)
  • New Testing and debugging section (Evals, Agent Steps, logs/traces, scripts)
  • Rewrote LLM Utilities section with ADK-native adk.zai usage (4 pages)
  • New AI Native Development section (Skills with MCP server)
  • New Advanced section (HITL with Desk distinction)
  • Rewrote CLI Reference from scratch against cli.ts source (added ~15 missing commands)
  • Removed all orphaned files (old concepts/, runtime.mdx, managing-integrations.mdx, zai/reference.mdx)
  • All sidebar subgroups expanded by default

Content principles:

  • Every claim verified against ADK source code
  • No em dashes
  • Dev console capabilities woven into content (not standalone sections)
  • Each page links to the next, creating a learning journey
  • Image placeholders for dev console screenshots (to be captured separately)

Test plan

  • Verify all pages render correctly on Mintlify
  • Check sidebar navigation matches expected structure
  • Capture and add dev console screenshots for image placeholders
  • Verify all internal links resolve correctly
  • Review code examples for accuracy

🤖 Generated with Claude Code

Add the Install page covering CLI prerequisites, install scripts for
macOS/Linux/Windows, version pinning, custom install directory,
self-upgrade, and the npm alternative. Empty placeholders for
quickstart, welcome, and quickstart-with-coding-assistant land
alongside to establish the v2 get-started structure.
…arted section

Consolidates the ADK v2 install and quickstart drafts into a new Get started folder
inside the existing ADK docs, and removes the standalone introduction, quickstart,
and project-structure pages whose content is folded into the new pages (or covered
by upcoming v2 concept pages). Drops the separate ADK v2 sidebar group.

Updates docs.json, the ADK card on the home page, and the Zai overview link to
point at the new paths so the broken-links check stays green.
jacksonyzj and others added 19 commits April 21, 2026 09:55
Reorganize the ADK docs from a flat "Concepts" list into 11 topic-based
groups matching the new documentation plan. Rewrite Welcome and Quickstart
pages with verified, accurate content. Remove standalone Install page
(folded into Quickstart) and Quickstart with coding assistant page.

Add stub files for all new sections (setup, conversations, workflows,
external, data, testing, zai utilities, ai-native, advanced).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add content for Agent Configuration (project structure, defineConfig
walkthrough), Environment Setup (secrets, configuration values, dev/prod,
preflight checks), and Integrations (dev console hub as primary,
CLI as secondary, config stored on Botpress Cloud per bot).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Seven pages covering the full conversation lifecycle:
- Set up conversations: channels, handler types, events, state
- Run AI agents: execute() loop, instructions, knowledge, exits, hooks
- Define Tools: standalone, inline, actions/workflows as tools, signals
- Send messages: message types, typing, tags, Conversation.get()
- Custom components: .bp.tsx, direct send, LLM-driven, build pipeline
- Manage lifecycle: nudge, expiration, sessions, mermaid flow diagram
- Manage states: bot/user/conversation scopes, User.get(), references, tags

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Three pages covering workflows:
- Create workflows: definition, starting (programmatic, scheduled, as tool),
  deduplication, instance methods, timeout, handler params
- Use workflow steps: persistence, retries, sleep, listen, fail/abort,
  child workflows, parallel processing (map, forEach, batch)
- Request and notify: step.request/provide, step.notify, workflow callbacks,
  summary table of mechanisms

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Rename section from "Allowing interaction from outside" to "Actions and
triggers". Rename "Build Actions" to "Create actions" for consistency.

- Create actions: definition, calling from all primitives, .asTool(),
  integration actions, external API access via Runtime API
- Set up triggers: event subscriptions, custom events, multiple events,
  calling actions from triggers

Remove standalone scheduling page (already covered in Create workflows).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Tables: schema definition, naming rules (verified against regex), CRUD
  operations, filtering operators, semantic search, aggregation, dev console
- Knowledge bases: all data source types (sitemap, base URL, llms.txt,
  specific URLs, directory), using in conversations, refresh workflow,
  RAG Search view, dev console

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Write and run evals: file format, conversation turns, all assertion
  types (response, tools, state, tables, workflow, timing), llm_judge,
  setup/seeding, outcome assertions, CLI commands, dev console
- Agent Steps: real-time debugging panel in Chat view
- Debug with logs and traces: Traces view, Logs view, adk logs CLI
- Run scripts: adk run, script exports, arguments, prod mode

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Introduction to Zai: adk.zai access, method overview table, model config
- Extract structured data: basic/complex schemas, practical example
- Generate text and summaries: text, rewrite, summarize, answer, patch
- Classify, validate and filter: check, label, filter, sort, rate, group

All 12 methods verified against latest Zai source.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Skills page covering all 6 ADK skills, slash commands, installation
(packaged with adk init), and MCP server setup. Removed Agent (O) and
Autonomous loops from sidebar (pre-beta).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add HITL page (from Linear guide): setup, plugin wiring, starting
handoff, alternative providers, deploy warning.

Remove orphaned files no longer in sidebar:
- adk/concepts/ (9 files, replaced by new structure)
- adk/runtime.mdx, adk/managing-integrations.mdx, adk/zai/reference.mdx
- adk/advanced/frontend.mdx, autonomous-execution.mdx, tracked-state.mdx
- adk/ai-native/agent-o.mdx, autonomous-loops.mdx

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Complete rewrite of CLI reference verified against cli.ts. Grouped by
category (project, integrations, configuration, chat/testing, workflows,
debugging, knowledge, assets, AI assistants, account). Added missing
commands: traces, workflows subcommands, assets, kb sync, models,
profiles, self-upgrade, telemetry, theme, status, link.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@aj-botpress aj-botpress requested a review from adkah as a code owner April 21, 2026 20:27
@aj-botpress
Copy link
Copy Markdown
Author

Screenshots needed

All images need light + dark variants saved to adk/assets/. Existing assets (✅) are already in place.

Existing (no action needed)

  • welcome.png / welcome-dark.png — Welcome banner
  • quickstart.png / quickstart-dark.png — Dev console chat page

Get Started

  • adk-init.png / adk-init-dark.pngadk init interactive wizard menu (referenced in quickstart but Frame was removed — verify if still needed)

Setting up your agent

  • environment-selector.png / environment-selector-dark.png — Dev/prod toggle in top bar
  • secrets-console.png / secrets-console-dark.png — Settings > Secrets view
  • config-variables-console.png / config-variables-console-dark.png — Settings > Config Variables view
  • integrations-console.png / integrations-console-dark.png — Integrations hub page
  • integration-config-console.png / integration-config-console-dark.png — Integration configuration panel

Handling conversations

  • conversations-chat.png / conversations-chat-dark.png — Chat page with a conversation in progress
  • traces-view.png / traces-view-dark.png — Traces timeline view (also used in debugging page)

Handling longform logic

  • workflows-console.png / workflows-console-dark.png — Workflows page with run history

Actions and triggers

  • actions-console.png / actions-console-dark.png — Actions page
  • triggers-console.png / triggers-console-dark.png — Triggers page

Working with data

  • tables-console.png / tables-console-dark.png — Tables page with data grid
  • knowledge-console.png / knowledge-console-dark.png — Knowledge page with indexed sources

Testing and debugging

  • evals-console.png / evals-console-dark.png — Evals page with run results
  • agent-steps.png / agent-steps-dark.png — Agent Steps panel in Chat view (showing tool calls, reasoning)
  • logs-view.png / logs-view-dark.png — Logs view

Total: 17 new screenshot pairs (34 files) + 2 existing pairs

Copy link
Copy Markdown

@github-actions github-actions Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

adk/cli-reference.mdx|358 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|384 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|392 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/conversations/custom-components.mdx|191 col 17| [Vale.Spelling] Did you really mean 'esbuild'?
adk/conversations/custom-components.mdx|222 col 44| [Vale.Spelling] Did you really mean 'tsconfig'?
adk/data/knowledge.mdx|158 col 41| [Vale.Spelling] Did you really mean 'evals'?
adk/get-started/quickstart.mdx|67 col 207| [Vale.Spelling] Did you really mean 'evals'?
adk/get-started/welcome.mdx|42 col 5| [Vale.Spelling] Did you really mean 'Evals'?
adk/setup/configuration.mdx|231 col 5| [Vale.Spelling] Did you really mean 'Evals'?
adk/setup/configuration.mdx|245 col 44| [Vale.Spelling] Did you really mean 'eval'?
adk/setup/configuration.mdx|249 col 25| [Vale.Spelling] Did you really mean 'evals'?
adk/setup/configuration.mdx|249 col 51| [Vale.Spelling] Did you really mean 'evals'?
adk/setup/environment.mdx|22 col 49| [Vale.Spelling] Did you really mean 'gitignored'?
adk/setup/environment.mdx|23 col 62| [Vale.Spelling] Did you really mean 'gitignored'?
adk/setup/environment.mdx|25 col 92| [Vale.Spelling] Did you really mean 'gitignored'?
adk/testing/scripts.mdx|72 col 54| [Vale.Spelling] Did you really mean 'reindexing'?
adk/testing/evals.mdx|6 col 1| [Vale.Spelling] Did you really mean 'Evals'?
adk/testing/evals.mdx|6 col 163| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|8 col 16| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|35 col 4| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|82 col 26| [Vale.Spelling] Did you really mean 'params'?
adk/testing/evals.mdx|86 col 5| [Vale.Spelling] Did you really mean 'Param'?
adk/testing/evals.mdx|245 col 10| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|258 col 12| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|276 col 27| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|276 col 62| [Vale.Spelling] Did you really mean 'Evals'?
adk/workflows/create.mdx|184 col 88| [Vale.Spelling] Did you really mean 'setTimeout'?
adk/zai/classify.mdx|10 col 26| [Vale.Spelling] Did you really mean 'boolean'?
adk/zai/classify.mdx|23 col 32| [Vale.Spelling] Did you really mean 'boolean'?
adk/workflows/steps.mdx|128 col 5| [Vale.Spelling] Did you really mean 'forEach'?
adk/zai/overview.mdx|22 col 24| [Vale.Spelling] Did you really mean 'boolean'?

Comment thread adk/ai-native/skills.mdx
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, your assistant (Claude Code, Cursor, Codex) automatically uses them when you ask it to build features, debug issues, write evals, or connect integrations.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'evals'?

Comment thread adk/ai-native/skills.mdx

| 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 |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?

Comment thread adk/ai-native/skills.mdx
|-------|----------------|----------|
| **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 |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Eval'?

Comment thread adk/ai-native/skills.mdx
|---------|-------------|
| `/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 |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'evals'?

Comment thread adk/advanced/hitl.mdx
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).
</Info>

HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. This is powered by two dependencies working together: the **HITL integration** (provides the transport to a helpdesk or agent platform) and the **HITL plugin** (provides the actions your code calls).
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'helpdesk'?

Comment thread adk/cli-reference.mdx
| `adk run <script> [args...]` | Run a TypeScript script with the ADK runtime |

Synchronize assets with remote storage.
### adk logs
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?

Comment thread adk/cli-reference.mdx
| `--summary` | Emit a single JSON summary (requires `--format json`) |

List all asset files.
### adk traces
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?

Comment thread adk/cli-reference.mdx
| `--include-llm` | Include LLM instructions and code in drill-in mode |

Show asset synchronization status.
### adk run
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?

Comment thread adk/cli-reference.mdx
| `adk assets pull` | Download remote assets to local directory |

**Flags:**
### adk assets sync
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?

Comment thread adk/cli-reference.mdx
| `--force` | Force re-upload all files |

**Flags:**
### adk assets list
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?

@mintlify
Copy link
Copy Markdown

mintlify Bot commented Apr 21, 2026

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
botpress 🟢 Ready View Preview Apr 21, 2026, 8:37 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

aj-botpress and others added 2 commits April 21, 2026 16:30
Remove Install and Quickstart with coding assistant cards that pointed
to deleted pages.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Fix two broken links pointing to deleted pages (frontend, autonomous
execution). Add placeholder images for all dev console screenshots
to unblock CI link checker. Placeholders should be replaced with
actual screenshots.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copy link
Copy Markdown

@github-actions github-actions Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

adk/zai/overview.mdx|22 col 24| [Vale.Spelling] Did you really mean 'boolean'?

Comment thread adk/cli-reference.mdx
| `adk mcp:init` | Generate MCP configuration files |

Manage telemetry preferences.
### adk mcp:init
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?

Comment thread adk/cli-reference.mdx
| `adk theme` | Manage CLI theme (dark/light) |

The ADK also provides npm scripts that you can use in your `package.json`:
### adk login
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?

Comment thread adk/cli-reference.mdx
| `--api-url <url>` | Botpress API URL |

Run these with your package manager:
### adk self-upgrade
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'adk'?


1. **Discover** - scans `src/` for `.ts` files that export `CustomComponent` instances
2. **Resolve** - finds the `.bp.tsx` import in each wrapper
3. **Bundle** - esbuild bundles the `.bp.tsx` into standalone ESM (`react` and `react-dom` are externalized)
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'esbuild'?

| LLM never uses the component | Missing metadata or not in `components` array | Add `{ description, props, exampleValues }` and list in `components` |
| Styles look wrong | Using CSS classes | Switch to inline styles |
| A prop is `undefined` | Reserved prop name (e.g., `status`) | Rename to something specific (e.g., `ticketStatus`) |
| TypeScript errors on `.bp.tsx` | Missing tsconfig settings | Add `"jsx": "react"`, `"allowImportingTsExtensions": true`, and `"noEmit": true` |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'tsconfig'?

Comment thread adk/testing/scripts.mdx
- **Seed data** into tables for development or testing
- **Run migrations** to update table schemas or transform data
- **Generate reports** by querying tables and knowledge bases
- **Maintenance tasks** like cleaning up old data or reindexing
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'reindexing'?

Comment thread adk/workflows/create.mdx
| `client` | `object` | Botpress client for API calls |
| `execute` | `function` | Run the AI model (same as in conversations) |
| `signal` | `AbortSignal` | Indicates when the workflow should stop |
| `workflow` | `object` | Current workflow instance (id, name, tags, cancel, complete, setTimeout) |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'setTimeout'?

Comment thread adk/workflows/steps.mdx
)
```

### forEach
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'forEach'?

Comment thread adk/zai/classify.mdx

## Check a condition

`zai.check()` verifies a boolean condition against input:
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'boolean'?

Comment thread adk/zai/classify.mdx

## Label content

`zai.label()` applies multiple boolean labels to content:
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'boolean'?

Comment thread adk/zai/overview.mdx
| Method | What it does | Page |
|--------|-------------|------|
| `extract()` | Pull structured data from unstructured text | [Extract structured data](/adk/zai/extract) |
| `check()` | Verify a boolean condition | [Classify, validate and filter](/adk/zai/classify) |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'boolean'?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants