feat(web): add list-apps-detailed endpoint

[dylan-apex]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• Closes: Detailed List Apps #3429

2. Or, if no issue exists, describe the change:

If applicable, please follow the issue templates to provide as much detail as
possible.

Problem:
The existing /list-apps endpoint only returns the name of the folder that each agent is in

Solution:
This adds a new endpoint /list-apps-detailed which will load each agent using the existing AgentLoader.load_agent method, and then return the folder name, display name (with underscores replaced with spaces for a more readable version), description, and the agent type.

This does introduce overhead if you had multiple agents since they all need to be loaded, but by maintaining the existing /list-apps endpoint, users can choose which one to hit if they don't want to load all agents. Since the existing load_agents method will cache results, there's only a penalty on the first hit.

Testing Plan

Created a unit test for this, similar to the /list-apps. Also tested this with my own ADK instance to verify it loaded correctly.

curl --location "localhost:8000/list-apps-detailed"

{
    "apps": [
        {
            "name": "agent_1",
            "displayName": "Agent 1",
            "description": "A test description for a test agent",
            "agentType": "package"
        },
        {
            "name": "agent_2",
            "displayName": "Agent 2",
            "description": "A test description for a test agent ",
            "agentType": "package"
        },
        {
            "name": "agent_3",
            "displayName": "Agent 3",
            "description": "A test description for a test agent",
            "agentType": "package"
        }
    ]
}

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

3054 passed, 2383 warnings in 46.96s

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

[gemini-code-assist]

Summary of Changes

Hello @dylan-apex, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant enhancement to the web server by providing a new endpoint that offers detailed information about registered agents. This addresses the limitation of the existing basic listing endpoint, allowing users to retrieve richer metadata for each agent, including its display name, description, and type. The design ensures efficiency by integrating with the existing agent loading and caching mechanisms, providing a more informative user experience without sacrificing performance.

Highlights

• New Detailed Apps Endpoint: A new endpoint, /list-apps-detailed, has been added to the web server. This endpoint provides more comprehensive information about each agent compared to the existing /list-apps endpoint.
• Enhanced Agent Information: The detailed endpoint returns each agent's name, a user-friendly display name (with underscores replaced by spaces), a description, and its determined type (yaml, python, or package).
• Agent Loading and Caching: The implementation leverages the existing AgentLoader.load_agent method to retrieve agent details. This method benefits from caching, meaning that subsequent requests for detailed agent information will incur minimal overhead after the initial load.
• API Model Definitions: New Pydantic models, AppInfo and ListAppsResponse, have been introduced to define the structure of the detailed agent information returned by the new API endpoint.
• Agent Loader Enhancements: The AgentLoader class now includes a list_agents_detailed method and a private helper _determine_agent_type to facilitate the retrieval and classification of agent types.
• Unit Testing: Dedicated unit tests have been added to verify the functionality and correctness of the new /list-apps-detailed endpoint.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new /list-apps-detailed endpoint to provide more metadata about available agents, which is a great enhancement. The implementation is mostly solid, with new Pydantic models, a new method in the AgentLoader, and corresponding unit tests.

My review includes a few key points:

1. A critical issue in agent_loader.py where a cached agent's state is modified. This could lead to unpredictable behavior elsewhere.
2. An invalid type hint in the base_agent_loader.py abstract method.
3. A suggestion to improve the robustness of the agent type detection logic.

These changes will improve the correctness and maintainability of the new feature.

[dylan-apex]

@boyangsvl
Used existing list-apps endpoint with detailed=true query param
used simple_name for the file/folder name
use agent_name for the value that comes from agent.name - the end user can convert underscores to spaces if they wish
removed python type - confused it with yaml

[dylan-apex]

@boyangsvl recommended changes made, autoformat ran, and all unit tests pass

[hangfei]

@dylan-apex You also need to implement it for InMemoryAgentLoader.

Right now, it's failing some tests. Please help fix.

[dylan-apex]

@hangfei I don't have access to see which tests are failing. I also assume you mean src/google/adk/cli/utils/agent_loader.py when you say InMemoryAgentLoader, but want to confirm.

I found this commit which hints at an InMemory implementation, but not sure if this is what you mean.

[hangfei]

@hangfei I don't have access to see which tests are failing. I also assume you mean src/google/adk/cli/utils/agent_loader.py when you say InMemoryAgentLoader, but want to confirm.

I found this commit which hints at an InMemory implementation, but not sure if this is what you mean.

i meant this one: https://github.com/google/adk-python/pull/3430/files#r2547636742. Thanks.

[dylan-apex]

@hangfei added a default implementation that just pulls the name from the regular list_agents method

[adk-bot]

Thank you @dylan-apex for your contribution! 🎉

Your changes have been successfully imported and merged via Copybara in commit b57fe5f.

Closing this PR as the changes are now in the main branch.