<refactor>(artifacts): Broke long page into subpages #1193

tommywagz · 2026-01-27T00:51:33Z

Broke the Artifacts page into sub-pages consistent with previous subheadings:

index
core concepts
interacting with artifacts
available implementations
best practices

... First commit here - just testing the waters

…ation via the nav bar

github-actions · 2026-01-27T00:51:43Z

👋 Thanks for your contribution!
You can enable PR previews by adding the build-preview label to this PR.

koverholt

Thanks for the PR and improvement!

This is a solid refactor that improves the usability of the artifacts docs. Breaking the long single page into focused subpages lines up with how we've been restructuring other docs sections to make it easier for developers (and AI coding tools) to find what they need in a more modular fashion.

I left some comments related to typos, newlines at end of files, language tags, broken anchor links, a couple of code bugs, and a nav suggestion.

Would also like a second review from @joefernandez on this reorganization.

koverholt · 2026-01-27T19:13:58Z

docs/artifacts/available-implementations.md

@@ -0,0 +1,123 @@
+## Available Implementations


Change these to H1 to avoid duplicate H1 (page title) and H2 headings:

koverholt · 2026-01-27T19:14:24Z

docs/artifacts/core-concepts.md

@@ -0,0 +1,252 @@
+## Core Concepts


Change these to H1 to avoid duplicate H1 (page title) and H2 headings.

koverholt · 2026-01-27T19:14:36Z

docs/artifacts/best-practices.md

@@ -0,0 +1,18 @@
+## Best Practices


Change these to H1 to avoid duplicate H1 (page title) and H2 headings.

koverholt · 2026-01-27T19:14:59Z

docs/artifacts/interacting-with-artifacts.md

@@ -0,0 +1,538 @@
+## Interacting with Artifacts (via Context Objects)


Change these to H1 to avoid duplicate H1 (page title) and H2 headings.

koverholt · 2026-01-27T19:15:24Z

mkdocs.yml

    - Artifacts:
      - artifacts/index.md
+      - Core Concepts: artifacts/core-concepts.md
+      - Inteacting with Artifacts: artifacts/interacting-with-artifacts.md


Typo in "Interacting".

koverholt · 2026-01-27T19:25:36Z

docs/artifacts/core-concepts.md

+    // Example: Configuring the Runner with an Artifact Service
+    const myAgent = new LlmAgent({name: "artifact_user_agent", model: "gemini-2.5-flash"});
+    const artifactService = new InMemoryArtifactService(); // Choose an implementation
+    const sessionService = new InMemoryArtifactService();


Not the fault of this PR, but this should be:

const sessionService = new InMemorySessionService();

koverholt · 2026-01-27T19:31:00Z

mkdocs.yml

      - artifacts/index.md
+      - Core Concepts: artifacts/core-concepts.md
+      - Inteacting with Artifacts: artifacts/interacting-with-artifacts.md
+      - Available Implementations: artifacts/available-implementations.md


Suggest putting "Available Implementations" above "Interacting with Artifacts" in the nav, since developers can read through this and select their backend before getting into the interaction patterns.

koverholt · 2026-01-27T20:05:36Z

docs/artifacts/available-implementations.md

@@ -0,0 +1,123 @@
+## Available Implementations
+


Suggest adding language tags like on the index page, on all sub-pages in this PR except for best practices.

koverholt · 2026-01-27T20:05:49Z

docs/artifacts/core-concepts.md

@@ -0,0 +1,252 @@
+## Core Concepts
+


Suggest adding language tags like on the index page, on all sub-pages in this PR except for best practices.

koverholt · 2026-01-27T20:05:58Z

docs/artifacts/interacting-with-artifacts.md

@@ -0,0 +1,538 @@
+## Interacting with Artifacts (via Context Objects)
+


Suggest adding language tags like on the index page, on all sub-pages in this PR except for best practices.

koverholt · 2026-01-27T20:51:20Z

docs/artifacts/interacting-with-artifacts.md

+    });
+    // If no artifactService is configured, calling artifact methods on context objects will throw an error.
+    ```
+    In Java, if an `ArtifactService` instance is not available (e.g., `null`) when artifact operations are attempted, it would typically result in a `NullPointerException` or a custom error, depending on how your application is structured. Robust applications often use dependency injection frameworks to manage service lifecycles and ensure availability.


Happened before this PR, but this line should be moved to the Java tab.

joefernandez · 2026-01-30T17:39:41Z

Thanks for this contribution, @tommywagz !

Unfortunately, just splitting up this page into multiple pages is not a useful information refactoring. The net effect of this change is that it makes getting to the information harder for a developer reader, because now the existing information is split across multiple pages. You are making a mechanical change that doesn't make the information any easier to use. So let's talk about how to refactor this page to make it more useable:

The core information design problem with this page is that is mixes conceptual content and practical application content in a confusing way. For example, it's difficult to see the basics of implementing artifacts in an agent because the code samples are buried in a section called "Core Concepts" which isn't a likely place for folks to look for basic getting started code.

My general requirement for refactoring this page is to split the content into 2 pages (not 5 pages):

Page 1. Practical implementation of artifacts in agents with a brief but useful introduction to the problems this feature solves and the bare minimum of conceptual information
Page 2. Deeper conceptual information about the design of the artifacts feature in ADK and advanced uses of the feature

This split requires refactoring the content more than just splitting out the sections. You need to break apart the sections themselves so that the practical code examples are clearly presented and findable (clear, action-oriented headings like "Get started" and "Read data from artifacts", and you need to preserve and re-organize the conceptual content so that presents information logically, and helps more advanced users navigate advanced use of the feature.

I'm setting a high bar for the refactoring, but it's what it actually needed to really improve the usefulness of content. I understand if this is not what you though you were signing up for. :-) Regardless, thanks for showing an interest in improving the ADK docs. If this refactoring seems like too much, please consider other, less involved contributions. Thanks!

\Joe

<refactor>(artifacts): Broke long page into subpages for easier navig…

e1d06d3

…ation via the nav bar

tommywagz requested a review from koverholt January 27, 2026 00:52

koverholt requested changes Jan 27, 2026

View reviewed changes

koverholt requested a review from joefernandez January 27, 2026 20:07

koverholt reviewed Jan 27, 2026

View reviewed changes

<refactor>(artifacts): Made the changes suggested by code review

4009804

joefernandez added the do not merge label Jan 30, 2026

		@@ -0,0 +1,538 @@
		## Interacting with Artifacts (via Context Objects)

<refactor>(artifacts): Broke long page into subpages #1193

Are you sure you want to change the base?

<refactor>(artifacts): Broke long page into subpages #1193

Conversation

tommywagz commented Jan 27, 2026

Uh oh!

github-actions bot commented Jan 27, 2026

Uh oh!

koverholt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joefernandez commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants