Rewrite artifacts documentation for clarity and correctness

[Timonwa]

Pull Request

Description

Full rewrite of all 8 pages in the artifacts documentation section (apps/docs/content/docs/framework/artifacts/) to match the style established in PR #689 (plugins section rewrite). Every page was audited for first-read clarity, correct API usage, and completeness.

• index.mdx — Rewritten as a focused overview with Mermaid flow diagram and navigation cards. Removed details that belong in sub-pages.
• runner-configuration.mdx — Clear wiring for both AgentBuilder and Runner direct patterns, explained auto-save behaviour end-to-end, fixed Buffer.from() placeholder that didn't compile.
• context-integration.mdx — Explains CallbackContext vs ToolContext upfront, tabbed examples for all four callback types, restored afterModelCallback and session summary examples.
• scoping-and-versioning.mdx — Added prose explaining why to choose each scope, fixed undefined variables in deletion examples.
• service-implementations.mdx — Production warning on InMemoryArtifactService, full custom service interface with all five methods, fixed null → undefined in troubleshooting.
• best-practices.mdx — Fixed Part | null → Part | undefined return type, ❌/✅ sequential vs parallel batch example, concrete deletion examples with usage call, retry section with usage example.
• recipes.mdx — Added opening paragraph and scenario context before each recipe.
• troubleshooting.mdx — Added Cause column to issues table, fixed wiring check to use AgentBuilder (no undefined variables), added GCS IAM grant command.

Related Issue

Closes #692

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?

• All code snippets verified against packages/adk/src/artifacts/ source for correct method signatures and return types
• agentBuilder() lowercase calls replaced with correct AgentBuilder.create() static factory pattern throughout
• Undefined variables (agent, appName, userId, sessionId) replaced with concrete values
• Part | null return type corrected to Part | undefined to match actual loadArtifact signature

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

BaseArtifactService export was added to packages/adk/src/artifacts/index.ts in a prior commit on this branch to support the import patterns shown in the docs.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
adk-typescript-docs	Ready	Preview	May 4, 2026 10:39am
adk-web	Ready	Preview	May 4, 2026 10:39am

[changeset-bot]

⚠️ No Changeset found

Latest commit: b07fba7

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

[gemini-code-assist]

Code Review

This pull request performs a comprehensive overhaul of the Artifacts documentation, improving clarity through simplified descriptions, visual aids like Mermaid diagrams, and updated code examples across all sections. Key feedback points out type mismatches in examples where undefined was used instead of null to align with the BaseArtifactService interface. Additionally, the removal of the index page from the sidebar configuration in meta.json was flagged as a potential navigation issue.

[Timonwa]

@claude review

[claude]

Claude finished @Timonwa's task —— View job

---

I'll review this comprehensive rewrite of the artifacts documentation.

Review Progress

• Analyze the scope and nature of changes
• Review documentation structure and organization
• Verify code examples against actual ADK source code
• Check for type accuracy and API correctness
• Evaluate clarity and completeness improvements
• Address existing review comments
• Provide comprehensive review feedback

Detailed Review

Summary

This PR significantly improves the artifacts documentation with clear examples, better organization, and enhanced clarity. The rewrite successfully addresses many previous issues while introducing comprehensive coverage of the artifact system. However, there are several type accuracy issues that need to be resolved.

🔴 Critical Issues

1. Type Mismatch: Part | null vs Part | undefined

Location: best-practices.mdx:31 and service-implementations.mdx:153

The existing review comments are correct. There's a fundamental inconsistency:

• BaseArtifactService.loadArtifact returns Promise<Part | null> (line 18 in base-artifact-service.ts)
• CallbackContext.loadArtifact returns Promise<Part | undefined> (line 52 in callback-context.ts)
• Documentation examples inconsistently use both Part | undefined and Part | null

Impact: The documentation examples won't compile against the actual service interface.

Fix Required: Documentation should use Part | null when showing direct service usage, and Part | undefined when showing context usage. The examples need to be corrected based on which interface they're demonstrating.

2. Missing BaseArtifactService Export

Location: Mentioned in PR description but not verified

The PR description mentions that BaseArtifactService export was added to support documentation imports, but it's not currently exported from packages/adk/src/artifacts/index.ts. This will cause import errors in the documentation examples.

🟡 Moderate Issues

3. Index Page Removal from Sidebar

Location: meta.json:3

Removing "index" from the pages array may hide the artifacts overview page from navigation, as noted in the existing review. This affects discoverability.

✅ Strengths

1. Excellent Structure & Organization

• Clear progression from overview → configuration → integration → advanced topics
• Logical flow with proper cross-references between sections
• Effective use of Mermaid diagrams to visualize the artifact flow

2. Comprehensive Coverage

• Covers all major use cases: development, production, custom implementations
• Includes practical recipes and troubleshooting guidance
• Addresses performance considerations (caching, batching, retry logic)

3. Code Quality Improvements

• Replaced undefined variables with concrete examples
• Fixed compilation issues (e.g., Buffer.from() examples)
• Consistent use of AgentBuilder.create() static factory pattern
• Proper error handling and validation examples

4. Enhanced Usability

• Clear distinction between CallbackContext and ToolContext capabilities
• Tabbed examples showing different approaches
• Warning callouts for production considerations
• ❌/✅ comparison examples for best practices

5. Technical Accuracy

• Examples correctly reflect actual ADK source code patterns (verified against codebase)
• Proper scoping examples with user: prefix explanation
• Accurate GCS setup and configuration guidance

Minor Observations

• The new recipes section provides good scenario context before examples
• Troubleshooting section is much more actionable with cause/fix columns
• Production warnings appropriately placed (InMemoryArtifactService)
• Good coverage of versioning behavior and cleanup patterns

Recommendations

1. Fix type inconsistencies - This is the highest priority
2. Verify BaseArtifactService export - Ensure imports work
3. Consider index page navigation - Test if removal affects discoverability
4. Add changeset - Documentation improvements deserve a patch version

The rewrite dramatically improves documentation quality and will significantly help developers working with artifacts in ADK-TS. Once the type issues are resolved, this will be an excellent addition to the docs.

---