Skip to content

docs: Add code assistant tutorial - #1386

Open
Rajkumar7633 wants to merge 1 commit into
google:mainfrom
Rajkumar7633:feature/code-assistant
Open

Rajkumar7633 wants to merge 1 commit into
google:mainfrom
Rajkumar7633:feature/code-assistant

Conversation

@Rajkumar7633

@Rajkumar7633 Rajkumar7633 commented Jul 31, 2026 •

Copy link
Copy Markdown

Description

This PR adds a new code assistant tutorial to the tutorials/ modules.

New Features

  • Added code-assistant tutorial module with 4 function tools that perform real deterministic work the model cannot do on its own:
    • analyzeCode — computes exact structural metrics (line counts, brace balance, TODO markers, long lines, trailing whitespace)
    • reviewCode — runs static checks (System.out usage, empty catch blocks, string == comparisons, unbounded while (true) loops)
    • generateSnippet — returns canonical templates for common constructs (hello_world, function, class, main) in Java, Python, and JavaScript
    • debugCode — applies rule-based diagnostics for common errors (NullPointerException, IndexOutOfBounds, StackOverflow, syntax errors, etc.)
  • Created CodeAssistant.java using the gemini-2.5-flash model
  • Added detailed README with setup and usage instructions
  • Updated parent pom.xml to include the new module
  • The module sets exec.mainClass (like other tutorials) and overrides maven-deploy-plugin with <skip>true</skip> so it stays out of the Maven Central release

Testing

Unit Tests

Added CodeAssistantTest.java with 12 unit tests covering:

  • analyzeCode metrics and brace-balance detection (2 tests)
  • reviewCode findings and clean-code verdict (2 tests)
  • generateSnippet templates for Java/Python and unsupported constructs (3 tests)
  • debugCode diagnostics for NPE, unmatched errors, and syntax errors (3 tests)
  • ROOT_AGENT validation (2 tests)

All 12 unit tests pass successfully (./mvnw test -pl tutorials/code-assistant).

Manual E2E Tests

  • mvn exec:java boots the ADK web server with the code_assistant agent registered
  • Verified all tools via web interface at http://localhost:8080
  • mvn deploy logs Skipping artifact deployment
  • Tested existing tutorials still work after changes

@google-cla

google-cla Bot commented Jul 31, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@Rajkumar7633
Rajkumar7633 force-pushed the feature/code-assistant branch from 339221f to c64aa51 Compare July 31, 2026 08:31

@Rajkumar7633 Rajkumar7633 left a comment

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

No existing issue. This PR adds:

  1. New code assistant tutorial feature

  2. Critical code quality improvements (unsafe Optional.get() fixes)
    Problem:

  3. Missing code assistant tutorial for developers

  4. Unsafe Optional.get() calls that could cause NoSuchElementException crashes

  5. Inconsistent error handling in LLM flow processing
    Solution:

  6. Added new code-assistant tutorial with 4 tools (generate, review, explain, debug code)

  7. Replaced unsafe .get() calls with orElseThrow() for better error handling

  8. Added meaningful error messages for debugging

  9. Removed duplicate condition checks
    Testing Plan:

Unit Tests:

  • All 24 modules pass successfully (BUILD SUCCESS)
  • ./mvnw test completed in 2:23 min with no failures

Manual E2E Tests:

  • Tested code assistant tutorial with GOOGLE_API_KEY
  • Verified all 4 tools work correctly via web interface
  • Tested existing tutorials still work after changes

@hemasekhar-p hemasekhar-p self-assigned this Aug 3, 2026
@hemasekhar-p

Copy link
Copy Markdown
Contributor

Hi @Rajkumar7633, thank you for your contribution! We appreciate you taking the time to submit this pull request. To proceed with the review, could you please address the following,

  1. Please provide clear and detailed description of your PR.
  2. Please include corresponding unit tests to verify your changes.
  3. As per our contribution policy, please squash your changes into a single commit.

@hemasekhar-p hemasekhar-p added the waiting on reporter Waiting for reaction by reporter. Failing that, maintainers will eventually closed it as stale. label Aug 3, 2026
@hemasekhar-p hemasekhar-p mentioned this pull request Aug 3, 2026
10 tasks done
@Rajkumar7633
Rajkumar7633 force-pushed the feature/code-assistant branch 3 times, most recently from 46ef6dd to da774e6 Compare August 3, 2026 09:27
@hemasekhar-p

Copy link
Copy Markdown
Contributor

@Rajkumar7633, thank you for addressing the feedback and squashing your commits, Currently this PR is under review by our team, we will keep you posted if any additional information is required. thank you

@hemasekhar-p hemasekhar-p added needs review and removed waiting on reporter Waiting for reaction by reporter. Failing that, maintainers will eventually closed it as stale. labels Aug 3, 2026

@damianmomotgoogle damianmomotgoogle left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please also keep PR as single commit and update both commit message and PR title to follow conventional commits.

As this looks to be example/tutorial you could use docs: Add code assistant tutorial

.modelName()
.orElseThrow(
() ->
new IllegalStateException(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This looks like behavior change - if needed please contribute it in a separate PR - this one should be limited to code assistant tutorial itself

.outputSchema()
.orElseThrow(
() ->
new IllegalStateException(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Same ask to keep core logic changes to a separate PR

}

int finalConfirmationEventIndex = confirmationResult.get().eventIndex();
ConfirmationResult result =

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Same ask to move core logic changes to a separate PR

@damianmomotgoogle damianmomotgoogle added waiting on reporter Waiting for reaction by reporter. Failing that, maintainers will eventually closed it as stale. and removed needs review labels Oct 22, 2026
@Rajkumar7633
Rajkumar7633 force-pushed the feature/code-assistant branch from 96fe2b4 to 9ec717b Compare November 13, 2026 21:32
@Rajkumar7633 Rajkumar7633 changed the title Add code assistant tutorial feature docs: Add code assistant tutorial Nov 13, 2026
@Rajkumar7633
Rajkumar7633 force-pushed the feature/code-assistant branch from 9ec717b to 2f2cf0d Compare November 13, 2026 21:41
@Rajkumar7633

Copy link
Copy Markdown
Author

All feedback addressed: core changes moved to #1809, PR is now limited to the code assistant tutorial, squashed to a single conventional commit (docs: Add code assistant tutorial), and rebased on latest main.

<artifactId>google-adk-tutorials-code-assistant</artifactId>
<name>Agent Development Kit - Tutorial: Code Assistant</name>
<description>Code Assistant Agent Tutorial</description>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Running mvn exec:java from the README currently fails with The parameters 'mainClass' for goal org.codehaus.mojo:exec-maven-plugin:3.6.3:java are missing or invalid. Please set exec.mainClass like the other tutorials (and drop the spring-boot-maven-plugin block below):

Suggested change
<properties>
<exec.mainClass>com.google.adk.tutorials.CodeAssistant</exec.mainClass>
</properties>

Comment on lines +47 to +57
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<mainClass>com.google.adk.tutorials.CodeAssistant</mainClass>
</configuration>
</plugin>
</plugins>
</build>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Two things here:

  1. spring-boot-maven-plugin has no version and is not managed in the parent, so it resolves to whatever is latest today (4.2.0-M2, a milestone). With exec.mainClass set above, it isn't needed.
  2. This module shouldn't be published to Maven Central. Releases run ./mvnw -Prelease deploy across the whole reactor, so without a skip it ships as google-adk-tutorials-code-assistant. -Dmaven.deploy.skip / <maven.deploy.skip> doesn't work because the root pom.xml hard-codes <skip>false</skip> on maven-deploy-plugin; override the plugin configuration in this module instead:
Suggested change
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<mainClass>com.google.adk.tutorials.CodeAssistant</mainClass>
</configuration>
</plugin>
</plugins>
</build>
<build>
<plugins>
<plugin>
<!-- Tutorial only: keep it out of the Maven Central release. -->
<artifactId>maven-deploy-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
</build>

With both changes, mvn exec:java starts the server and ./mvnw -Prelease deploy -pl tutorials/code-assistant logs Skipping artifact deployment.

FunctionTool.create(CodeAssistant.class, "debugCode"))
.build();

public static Map<String, String> generateCode(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The four tools don't perform any work: each only echoes its arguments back with a "request received" message while the model does the actual generation, review, and explanation itself. Because the agent would behave the same without them, the tutorial doesn't demonstrate what function tools are for, and the tests only verify that the maps are echoed.

Please give the tools real, deterministic behavior the model can't do on its own.

public static final BaseAgent ROOT_AGENT =
LlmAgent.builder()
.name("code_assistant")
.model("gemini-2.0-flash")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

nit: gemini-2.0-flash is an older model; please use a current one (and update the README to match).

@Rajkumar7633
Rajkumar7633 force-pushed the feature/code-assistant branch from 2f2cf0d to 6c162d9 Compare November 16, 2026 17:57
@Rajkumar7633

Copy link
Copy Markdown
Author

Addressed all review feedback:

  • pom.xml: replaced spring-boot-maven-plugin with the exec.mainClass property (matching other tutorials), and overrode maven-deploy-plugin with <skip>true</skip> so the tutorial stays out of the Maven Central release.
  • CodeAssistant.java: the four tools now do real deterministic work — analyzeCode computes exact metrics (line counts, brace balance, TODOs, long lines), reviewCode runs static checks (System.out usage, empty catch, string ==, while (true) without break), generateSnippet returns canonical templates for common constructs, and debugCode applies rule-based diagnostics for common exceptions. Instruction updated to tell the model to delegate exact computation to the tools.
  • Model: switched to gemini-2.5-flash and updated the README to match.
  • Tests: expanded to 12 tests covering the real tool behavior (metrics, findings, templates, diagnostics) — all passing via ./mvnw test -pl tutorials/code-assistant.

@Rajkumar7633
Rajkumar7633 force-pushed the feature/code-assistant branch from 6c162d9 to 73a7073 Compare November 16, 2026 18:03
@Rajkumar7633

Copy link
Copy Markdown
Author

Polish pass on top of the previous fixes: templates now use Java text blocks via a lookup map (easier to read/extend), all public tool methods are null-safe, diagnostics rules were tightened to avoid false positives, and every line stays within the 100-column style limit. Re-verified end to end: ./mvnw test -pl tutorials/code-assistant (12/12 pass), mvn exec:java boots the server with the code_assistant agent registered, and mvn deploy logs Skipping artifact deployment.

Add a new code-assistant tutorial module whose function tools
perform real deterministic work: code metrics analysis, static
review checks, canonical snippet templates, and rule-based
debugging diagnostics. Includes a README and unit tests.
@Rajkumar7633
Rajkumar7633 force-pushed the feature/code-assistant branch from 73a7073 to c28c2d2 Compare November 16, 2026 18:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

waiting on reporter Waiting for reaction by reporter. Failing that, maintainers will eventually closed it as stale.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants