Skip to content

docs(adk): audit ADK rewrite#463

Closed
jacksonyzj wants to merge 84 commits intomasterfrom
jackson-audit-adk-docs-v2
Closed

docs(adk): audit ADK rewrite#463
jacksonyzj wants to merge 84 commits intomasterfrom
jackson-audit-adk-docs-v2

Conversation

@jacksonyzj
Copy link
Copy Markdown
Contributor

@jacksonyzj jacksonyzj commented Apr 23, 2026

Summary

Audited each ADK section against the latest source, fixed inaccuracies, and documented features that had shipped but weren't in the docs. Updated tone and flow to better match the docs style, and refreshed the dev console screenshots across pages.

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.
aj-botpress and others added 14 commits April 21, 2026 16:16
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) <[email protected]>
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) <[email protected]>
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
Remove Install and Quickstart with coding assistant cards that pointed
to deleted pages.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
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) <[email protected]>
Audited each ADK section against the agent-lack source repo and the
skills repo. Fixed incorrect content, documented missing features,
tightened prose, removed trailing nav Cards, and refreshed dev console
screenshots.

Corrections:
- CLI reference: added --profile global flag, corrected --format
  availability, added subsections for adk search, adk mcp, adk
  telemetry, adk theme
- HITL: switched integration deps to string shorthand (object form is
  deprecated), reworded dev-mode warning to match the real constraint
- Skills: matched install command args to source (-a codex claude-code),
  added adk_init_project to the MCP tools table
- Evals: fixed Eval import path (@botpress/runtime -> @botpress/adk)
  and evals directory (src/evals -> evals), documented event/
  expectSilence turns and idleTimeout
- Debugging: removed bogus 'adk logs "webhook"' content-filter example,
  added since= and limit= tokens
- Scripts: updated flag pass-through example to use -- separator
- Actions: fixed callAction curl (chat.botpress.cloud ->
  api.botpress.cloud, added Authorization header)
- Triggers: removed incorrect client parameter from handler table

Documented missing features:
- Tables: computed columns, \$options regex modifier, keyColumn,
  waitComputed
- Actions: cached prop
- Knowledge: search() method, Directory source options, description role
- Zai: summarize format/intermediateFactor/sliding, answer() response
  types, rate() multi-criteria, group() initialGroups/maxGroups

Flow and structure:
- Rewrote evals with cleaner ordering
- Restructured knowledge page with dev console inlined after Create
- Moved action-vs-tool comparison to the asTool subsection
- Tightened intros on knowledge and actions pages
- Inlined dev console mentions into Create sections across pages
- Removed trailing next-page Cards from nearly every page

Screenshots updated: actions, agent-steps, evals, knowledge, logs,
tables, traces, triggers.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
@mintlify
Copy link
Copy Markdown

mintlify Bot commented Apr 23, 2026

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

Project Status Preview Updated (UTC)
botpress 🟢 Ready View Preview Apr 23, 2026, 2:40 AM

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

@jacksonyzj jacksonyzj changed the title docs(adk): audit and polish ADK sections against source docs(adk): audit ADK sections Apr 23, 2026
@jacksonyzj jacksonyzj changed the title docs(adk): audit ADK sections docs(adk): audit ADK rewrite Apr 23, 2026
adkah and others added 4 commits April 23, 2026 11:31
…ctions

Continues the audit pass. Fixed inaccuracies, documented missing
features, tightened prose, inlined dev console mentions, and refreshed
screenshots.

Workflows:
- Added state prop, workflow.fail, workflow.execute
- Added step.progress, noted getOrCreate default statuses
- Rewrote ambiguous step-name uniqueness paragraph
- Updated request.workflow.provide examples to pass request.step
- Inlined workflow dev console mention into Create section

Conversations:
- Fixed tools title casing (Define Tools -> Define tools)
- Clarified customComponent vs custom message types
- Added execute() signal? prop (AbortSignal cancellation)
- Noted nudge.interval default and max-unlimited behavior
- Replaced Chat page screenshot with agent-steps screenshots
- Fixed webchat integration install note (no auto-prompt)
- Replaced duplicated Traces blurb with link to debugging page

Setup:
- Fixed swapped default model claim in configuration
- Fixed evals.idleTimeout unit (seconds -> milliseconds)
- Title casing: Agent Configuration / Environment Setup -> sentence case
- Removed evals row pointing at src/evals, updated to evals/
- Trimmed project structure table to core files only
- Reworked integrations install vs configure framing
- Enable/disable example now leads with string shorthand
- Inlined secrets and config dev console mentions into existing sections

Screenshots refreshed: workflows, environment selector, secrets,
config variables, integrations hub, integration config.

Removed trailing next-page Cards from every page in these sections.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Incorporates PR #461 (adrian-kahali):
- Get Started restructure: welcome -> introduction, new top-level
  quickstart, updated docs.json sidebar
- Configuration page: <Tip> blocks linking to related guides,
  expandable config snippet, cleaner prose
- Environment setup: consolidated secrets + config explanations,
  better wording
- Integrations: clearer intro, CLI section labelled
- Conversations: <CodeGroup> for channel matching, <Tip> blocks
  for cross-references
- AI execution: <Note> for LLMz reference, tighter phrasing
- Tools: highlight annotations on code blocks

Conflicts resolved in favor of keeping the audit fixes from this
branch (correct default model order, ms units for idleTimeout,
evals/ path, agent-steps screenshot, no trailing Cards, no
standalone Dev console sections, "Botpress Cloud" wording, real
CLI reference secrets table instead of placeholder link) while
taking Adrian's <Tip>/<Note> block styling and structural
improvements.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
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|288 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|313 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|344 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|367 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|397 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|414 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|438 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|438 col 9| [Vale.Spelling] Did you really mean 'mcp'?
adk/cli-reference.mdx|452 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|482 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|498 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|508 col 5| [Vale.Spelling] Did you really mean 'adk'?
adk/cli-reference.mdx|524 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|138 col 121| [Vale.Spelling] Did you really mean 'UIs'?
adk/introduction.mdx|43 col 5| [Vale.Spelling] Did you really mean 'Evals'?
adk/setup/environment.mdx|26 col 49| [Vale.Spelling] Did you really mean 'gitignored'?
adk/setup/environment.mdx|27 col 62| [Vale.Spelling] Did you really mean 'gitignored'?
adk/setup/environment.mdx|29 col 92| [Vale.Spelling] Did you really mean 'gitignored'?
adk/setup/configuration.mdx|239 col 5| [Vale.Spelling] Did you really mean 'Evals'?
adk/testing/scripts.mdx|46 col 79| [Vale.Spelling] Did you really mean 'args'?
adk/testing/scripts.mdx|46 col 121| [Vale.Spelling] Did you really mean 'args'?
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 14| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|35 col 4| [Vale.Spelling] Did you really mean 'eval's'?
adk/testing/evals.mdx|103 col 26| [Vale.Spelling] Did you really mean 'params'?
adk/testing/evals.mdx|184 col 63| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|247 col 14| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|249 col 22| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|265 col 62| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|278 col 13| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|280 col 1| [Vale.Spelling] Did you really mean 'Evals'?
adk/testing/evals.mdx|282 col 50| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|296 col 25| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|313 col 8| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|333 col 27| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|333 col 62| [Vale.Spelling] Did you really mean 'Evals'?
adk/workflows/steps.mdx|140 col 5| [Vale.Spelling] Did you really mean 'forEach'?
adk/zai/classify.mdx|20 col 26| [Vale.Spelling] Did you really mean 'boolean'?
adk/zai/classify.mdx|30 col 32| [Vale.Spelling] Did you really mean 'boolean'?
adk/zai/overview.mdx|21 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, 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.
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. 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).
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
| `--tag <tag>` | Run only evals with this tag | |
| `--type <type>` | Run only `capability` or `regression` evals | |
| `--judge-model <model>` | Model for `llm_judge` assertions | |
| `-v, --verbose` | Show full details for all 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/cli-reference.mdx
| `--server <url>` | Dev server URL | `http://localhost:3001` |

### `adk remove`
### adk evals runs
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
| `--server <url>` | Dev server URL | `http://localhost:3001` |

### `adk remove`
### adk evals runs
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/cli-reference.mdx
### adk evals runs

Remove an integration from your agent.
List past eval runs, or show the details of a specific one:
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/cli-reference.mdx
| `adk workflows run <name> [payload]` | Run a workflow |

### `adk search`
### adk workflows 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'?

Introduction:
- Tightened intro paragraph
- Added Custom components to primitives table
- Dropped src/ qualifier since evals live at the project root

Quickstart:
- Swapped em-dash for colon in the requirements list
- Dropped filler sentence at the top of Test your agent
- Removed the 'Chat in the terminal' section so readers land in the
  dev console
- Normalized smart apostrophe

Refreshed welcome and quickstart screenshots.
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/testing/evals.mdx|247 col 14| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|249 col 22| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|265 col 62| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|278 col 13| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|280 col 1| [Vale.Spelling] Did you really mean 'Evals'?
adk/testing/evals.mdx|282 col 50| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|296 col 25| [Vale.Spelling] Did you really mean 'eval'?
adk/testing/evals.mdx|313 col 8| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|333 col 27| [Vale.Spelling] Did you really mean 'evals'?
adk/testing/evals.mdx|333 col 62| [Vale.Spelling] Did you really mean 'Evals'?
adk/zai/classify.mdx|20 col 26| [Vale.Spelling] Did you really mean 'boolean'?
adk/zai/classify.mdx|30 col 32| [Vale.Spelling] Did you really mean 'boolean'?
adk/workflows/steps.mdx|140 col 5| [Vale.Spelling] Did you really mean 'forEach'?
adk/zai/overview.mdx|21 col 24| [Vale.Spelling] Did you really mean 'boolean'?


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/cli-reference.mdx
---

### `adk list`
### 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`) |

### `adk info`
### 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 |

---
### 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/testing/evals.mdx
description: Automated conversation tests for your agent.
---

Evals are automated tests that simulate conversations with your agent and assert on the results. You write a conversation script with expected behaviors, and the eval runner plays it against your running agent and reports pass/fail.
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/testing/evals.mdx

Evals are automated tests that simulate conversations with your agent and assert on the results. You write a conversation script with expected behaviors, and the eval runner plays it against your running agent and reports pass/fail.

## Create an eval
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/testing/evals.mdx

## Conversation turns

An eval's `conversation` is a sequence of turns. Each turn can send a user message, fire an event, or assert the agent stays silent, plus optionally assert on what happens.
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's'?

Comment thread adk/testing/evals.mdx
| Assertion | Description |
|-----------|-------------|
| `{ called: "toolName" }` | Tool was called |
| `{ called: "toolName", params: { key: { equals: "value" } } }` | Tool was called with matching params |
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 'params'?

Comment thread adk/testing/evals.mdx
}
```

Configure the judge model and pass threshold under [Configure eval behavior](#configure-eval-behavior).
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'?

@adkah adkah closed this Apr 23, 2026
@adkah
Copy link
Copy Markdown
Collaborator

adkah commented Apr 23, 2026

Closing since these changes were merged into aj/adk-docs-update via #464 instead.

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.

3 participants