Skip to content

docs: rewrite plugins section for clarity and accuracy#689

Merged
Timonwa merged 2 commits intomainfrom
686-review-test-and-update-the-plugins-section-of-the-adk-ts-documentation
Apr 16, 2026
Merged

docs: rewrite plugins section for clarity and accuracy#689
Timonwa merged 2 commits intomainfrom
686-review-test-and-update-the-plugins-section-of-the-adk-ts-documentation

Conversation

@Timonwa
Copy link
Copy Markdown
Contributor

@Timonwa Timonwa commented Apr 15, 2026 •
edited
Loading

Pull Request

Description

Rewrote all 5 plugin documentation pages (index + 4 individual plugin pages) for clarity and accuracy. Pages now lead with what the plugin does and why, show a quick start first, then progressive detail. Fixed multiple type errors in code snippets and removed duplicated content.

Key changes:

  • Rewrote index.mdx from ~1,100 lines to ~280 lines — clear explanation of what plugins are, how they work, and how to use them
  • Rewrote all 4 plugin pages with consistent template: Quick Start → Usage tabs → Configuration → How It Works → Troubleshooting → Next Steps cards
  • Fixed filterModel snippets (requires BaseLlm via LLMRegistry.newLLM(), not a string)
  • Fixed missing description on LlmAgent constructor, wrong toPlainText visibility, missing TrackingScope import
  • Removed phantom "plugins" entry from meta.json that caused a broken nav link
  • Consolidated duplicated best practices/troubleshooting into the index page
  • Bug fix: afterModelCallback never receives llmRequest — threaded it through PluginManager and BaseLlmFlow

Related Issue

Closes #686

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Performance improvement
  • Code refactoring (no functional changes)
  • Tests
  • Other (please describe):

How Has This Been Tested?

  • pnpm build --filter=@iqai/adk-docs — 384 pages build successfully, no broken links
  • pnpm test --filter=adk — 538 tests pass
  • Code snippets tested for type correctness by pasting into example file and running tsc --noEmit --skipLibCheck

Checklist

  • My code follows the code style of this project
  • I have updated the documentation accordingly
  • I have added tests to cover my changes
  • All new and existing tests passed
  • My changes generate no new warnings
  • I have checked for potential breaking changes and addressed them

Additional Notes

Source code changes (bug fix): This PR includes a small fix to plugin-manager.ts and base-llm-flow.ts. The afterModelCallback hook was never receiving llmRequest despite BasePlugin declaring it as an optional parameter. The LangfusePlugin tries to read params.llmRequest?.model for token tracking but always gets undefined. The fix threads llmRequest through the call chain. This was an incomplete wiring from commit 65d79260 ("fix: wire up remaining plugin callbacks").

🤖 Generated with Claude Code

Timonwa added 2 commits April 15, 2026 15:20
@Timonwa
Refactor plugin documentation and enhance functionality
7e5218e 
- Updated `meta.json` to remove unnecessary pages.
- Enhanced `model-fallback-plugin.mdx` with improved installation instructions, usage examples, and configuration details.
- Added new sections for best practices and troubleshooting in `model-fallback-plugin.mdx`.
- Improved `reflect-and-retry.mdx` with quick start examples and refined configuration options.
- Updated `tool-output-filter.mdx` to streamline installation instructions and usage examples, including new configuration options.
- Enhanced error handling and performance considerations across plugin documentation.
- Modified `BaseLlmFlow` and `PluginManager` to include optional `llmRequest` parameter in callback methods for better context handling.
@Timonwa
Refactor documentation for Model Fallback, Reflect and Retry, and Too…
a66107b 
…l Output Filter plugins

- Updated descriptions and key capabilities for clarity and conciseness.
- Enhanced installation instructions and quick start sections.
- Improved usage examples and configuration details for better understanding.
- Added troubleshooting sections with clear issue-fix tables.
- Included next steps with related plugin links for user guidance.
@Timonwa Timonwa linked an issue Apr 15, 2026 that may be closed by this pull request
Review, test, and update the Plugins section of the ADK-TS documentation #686
Closed
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Apr 15, 2026

⚠️ No Changeset found

Latest commit: a66107b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@vercel
Copy link
Copy Markdown
Contributor

vercel Bot commented Apr 15, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
adk-typescript-docs Ready Ready Preview Apr 15, 2026 3:59pm
adk-web Ready Ready Preview Apr 15, 2026 3:59pm

Request Review

gemini-code-assist[bot]
gemini-code-assist Bot reviewed Apr 15, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

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

Code Review

This pull request significantly simplifies and restructures the documentation for ADK-TS plugins, introducing clearer quick-start guides and updating examples to favor the AgentBuilder API. It also includes a functional change to the BaseLlmFlow and PluginManager to pass the llmRequest object into the afterModelCallback, enabling plugins to access request context after a model execution. Feedback was provided regarding several code examples in the documentation where LlmAgent instances were missing the required model property, which would result in runtime errors.

Comment thread apps/docs/content/docs/framework/plugins/reflect-and-retry.mdx
Comment thread apps/docs/content/docs/framework/plugins/reflect-and-retry.mdx
Comment thread apps/docs/content/docs/framework/plugins/reflect-and-retry.mdx
@Timonwa Timonwa requested a review from Copilot April 15, 2026 16:08
@Timonwa Timonwa requested review from MarvelNwachukwu and removed request for Copilot April 15, 2026 16:09
@Timonwa Timonwa self-assigned this Apr 15, 2026
@Timonwa Timonwa requested a review from Adebesin-Cell April 15, 2026 16:19
MarvelNwachukwu
MarvelNwachukwu approved these changes Apr 16, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@MarvelNwachukwu MarvelNwachukwu left a comment

Choose a reason for hiding this comment

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

LGTM

@Timonwa Timonwa merged commit 9c0e72e into main Apr 16, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@MarvelNwachukwu MarvelNwachukwu MarvelNwachukwu approved these changes

@Adebesin-Cell Adebesin-Cell Adebesin-Cell approved these changes

+1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

@Timonwa Timonwa

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Review, test, and update the Plugins section of the ADK-TS documentation

3 participants

@Timonwa @MarvelNwachukwu @Adebesin-Cell