feat: Add /apps/{app_name}/app-info endpoint to ADK CLI web server

This endpoint provides detailed **static** information about an application's agents, including their description, instructions, tools, and sub-agents, specifically for LlmAgent instances.

Co-authored-by: Liang Wu <wuliang@google.com>
PiperOrigin-RevId: 895470828
Change-Id: I16c88b440087aec1698b3db1f80ba20f06c36eeb

Author: wuliang229

src/google/adk/cli/adk_web_server.py

@@ -60,6 +60,8 @@
 from ..agents.base_agent import BaseAgent
 from ..agents.live_request_queue import LiveRequest
 from ..agents.live_request_queue import LiveRequestQueue
+from ..agents.llm_agent import LlmAgent
+from ..agents.llm_agent import ToolUnion
 from ..agents.run_config import RunConfig
 from ..agents.run_config import StreamingMode
 from ..apps.app import App
@@ -90,7 +92,10 @@
 from ..runners import Runner
 from ..sessions.base_session_service import BaseSessionService
 from ..sessions.session import Session
+from ..utils.agent_info import AgentInfo
+from ..utils.agent_info import get_agents_dict
 from ..utils.context_utils import Aclosing
+from ..utils.feature_decorator import experimental
 from ..version import __version__
 from ..workflow._node_status import NodeStatus
 from .cli_eval import EVAL_SESSION_ID_PREFIX
@@ -496,6 +501,7 @@ class AppInfo(common.BaseModel):
   description: str
   language: Literal["yaml", "python"]
   is_computer_use: bool = False
+  agents: Optional[dict[str, AgentInfo]] = None
 
 
 class ListAppsResponse(common.BaseModel):
@@ -1061,6 +1067,25 @@ async def list_apps(
         return ListAppsResponse(apps=[AppInfo(**app) for app in apps_info])
       return self.agent_loader.list_agents()
 
+    @experimental
+    @app.get("/apps/{app_name}/app-info", response_model_exclude_none=True)
+    async def get_adk_app_info(app_name: str) -> AppInfo:
+      """Returns the detailed info for a given ADK app."""
+      agent_or_app = self.agent_loader.load_agent(app_name)
+      root_agent = self._get_root_agent(agent_or_app)
+      if isinstance(root_agent, LlmAgent):
+        return AppInfo(
+            name=app_name,
+            root_agent_name=root_agent.name,
+            description=root_agent.description,
+            language="python",
+            agents=get_agents_dict(root_agent),
+        )
+      else:
+        raise HTTPException(
+            status_code=400, detail="Root agent is not an LlmAgent"
+        )
+
     @app.get("/debug/trace/{event_id}", tags=[TAG_DEBUG])
     async def get_trace_dict(event_id: str) -> Any:
       event_dict = trace_dict.get(event_id, None)

src/google/adk/utils/agent_info.py

@@ -0,0 +1,77 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.genai import types
+import pydantic
+
+from ..agents.llm_agent import LlmAgent
+from ..agents.llm_agent import ToolUnion
+from ..tools.base_tool import BaseTool
+from ..tools.base_toolset import BaseToolset
+from ..tools.function_tool import FunctionTool
+
+
+class AgentInfo(pydantic.BaseModel):
+  name: str
+  description: str
+  instruction: str
+  tools: list[types.Tool]
+  sub_agents: list[str]
+
+
+def get_tools_info(tools: list[ToolUnion]) -> list[Any]:
+  """Returns the info for a given list of tools."""
+  final_tools = []
+  for tool in tools:
+    if isinstance(tool, BaseTool):
+      final_tools.append(tool)
+    elif isinstance(tool, BaseToolset):
+      final_tools.extend(tool.get_tools())
+    else:
+      final_tools.append(FunctionTool(tool))
+  return [
+      types.Tool(function_declarations=[tool._get_declaration()])
+      for tool in final_tools
+      if tool._get_declaration()
+  ]
+
+
+def get_agents_dict(agent: LlmAgent) -> dict[str, AgentInfo]:
+  """Returns a dict with info for the agent and its sub-agents."""
+  agents_dict = {}
+
+  def _traverse(current_agent: LlmAgent):
+    if current_agent.name in agents_dict:
+      return
+
+    sub_agent_names = []
+    for sub_agent in current_agent.sub_agents:
+      if isinstance(sub_agent, LlmAgent):
+        _traverse(sub_agent)
+        sub_agent_names.append(sub_agent.name)
+
+    agents_dict[current_agent.name] = AgentInfo(
+        name=current_agent.name,
+        description=current_agent.description,
+        instruction=current_agent.instruction,
+        tools=get_tools_info(current_agent.tools),
+        sub_agents=sub_agent_names,
+    )
+
+  _traverse(agent)
+  return agents_dict

tests/unittests/cli/test_fast_api.py

@@ -26,6 +26,7 @@
 
 from fastapi.testclient import TestClient
 from google.adk.agents.base_agent import BaseAgent
+from google.adk.agents.llm_agent import LlmAgent
 from google.adk.agents.run_config import RunConfig
 from google.adk.apps.app import App
 from google.adk.artifacts.base_artifact_service import ArtifactVersion
@@ -801,6 +802,198 @@ def test_list_apps_detailed(test_app):
   logger.info(f"Listed apps: {data}")
 
 
+def test_get_adk_app_info_llm_agent(test_app, mock_agent_loader):
+  """Test retrieving app info when root agent is an LlmAgent."""
+  agent = LlmAgent(
+      name="test_llm_agent", description="test description", model="test_model"
+  )
+  with patch.object(mock_agent_loader, "load_agent", return_value=agent):
+    response = test_app.get("/apps/test_app/app-info")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["name"] == "test_app"
+    assert data["rootAgentName"] == "test_llm_agent"
+    assert data["description"] == "test description"
+    assert data["language"] == "python"
+    assert "agents" in data
+    assert "test_llm_agent" in data["agents"]
+
+
+def test_get_adk_app_info_llm_agent_with_subagents(test_app, mock_agent_loader):
+  """Test retrieving app info when root agent is an LlmAgent with sub_agents and tools."""
+
+  def sub_tool1(a: int) -> str:
+    """Sub tool 1."""
+    return str(a)
+
+  def sub_tool2(b: str) -> str:
+    """Sub tool 2."""
+    return b
+
+  sub_agent1 = LlmAgent(
+      name="sub_agent1",
+      description="sub description 1",
+      model="test_model",
+      tools=[sub_tool1],
+  )
+  sub_agent2 = LlmAgent(
+      name="sub_agent2",
+      description="sub description 2",
+      model="test_model",
+      tools=[sub_tool2],
+  )
+  agent = LlmAgent(
+      name="test_llm_agent",
+      description="test description",
+      model="test_model",
+      sub_agents=[sub_agent1, sub_agent2],
+  )
+  with patch.object(mock_agent_loader, "load_agent", return_value=agent):
+    response = test_app.get("/apps/test_app/app-info")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["rootAgentName"] == "test_llm_agent"
+    assert "test_llm_agent" in data["agents"]
+    assert "sub_agent1" in data["agents"]
+    assert "sub_agent2" in data["agents"]
+
+    # Verify tools for sub_agent1
+    agent1_info = data["agents"]["sub_agent1"]
+    assert "tools" in agent1_info
+    assert len(agent1_info["tools"]) == 1
+    tool1 = agent1_info["tools"][0]
+    field_name1 = (
+        "functionDeclarations"
+        if "functionDeclarations" in tool1
+        else "function_declarations"
+    )
+    assert field_name1 in tool1
+    assert tool1[field_name1][0]["name"] == "sub_tool1"
+
+    # Verify tools for sub_agent2
+    agent2_info = data["agents"]["sub_agent2"]
+    assert "tools" in agent2_info
+    assert len(agent2_info["tools"]) == 1
+    tool2 = agent2_info["tools"][0]
+    field_name2 = (
+        "functionDeclarations"
+        if "functionDeclarations" in tool2
+        else "function_declarations"
+    )
+    assert field_name2 in tool2
+    assert tool2[field_name2][0]["name"] == "sub_tool2"
+
+
+def test_get_adk_app_info_triple_nested_agents_with_tools(
+    test_app, mock_agent_loader
+):
+  """Test retrieving app info when there are triple nested agents with tools."""
+
+  def tool1(a: int) -> str:
+    """Tool 1."""
+    return str(a)
+
+  def tool2(b: str) -> str:
+    """Tool 2."""
+    return b
+
+  def tool3(c: float) -> str:
+    """Tool 3."""
+    return str(c)
+
+  # Level 3 (deepest)
+  agent3 = LlmAgent(
+      name="agent3",
+      description="Level 3 agent",
+      model="test_model",
+      tools=[tool3],
+  )
+
+  # Level 2
+  agent2 = LlmAgent(
+      name="agent2",
+      description="Level 2 agent",
+      model="test_model",
+      tools=[tool2],
+      sub_agents=[agent3],
+  )
+
+  # Level 1 (root)
+  root_agent = LlmAgent(
+      name="root_agent",
+      description="Level 1 agent",
+      model="test_model",
+      tools=[tool1],
+      sub_agents=[agent2],
+  )
+
+  with patch.object(mock_agent_loader, "load_agent", return_value=root_agent):
+    response = test_app.get("/apps/test_app/app-info")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["rootAgentName"] == "root_agent"
+    assert "root_agent" in data["agents"]
+    assert "agent2" in data["agents"]
+    assert "agent3" in data["agents"]
+
+    # Verify each has its tools
+    for agent_name, exp_tool_name in [
+        ("root_agent", "tool1"),
+        ("agent2", "tool2"),
+        ("agent3", "tool3"),
+    ]:
+      ai = data["agents"][agent_name]
+      assert len(ai["tools"]) == 1
+      tool = ai["tools"][0]
+      field_name = (
+          "functionDeclarations"
+          if "functionDeclarations" in tool
+          else "function_declarations"
+      )
+      assert tool[field_name][0]["name"] == exp_tool_name
+
+
+def test_get_adk_app_info_llm_agent_with_function_tool(
+    test_app, mock_agent_loader
+):
+  """Test retrieving app info when root agent has tools."""
+
+  def my_tool(a: int, b: str) -> str:
+    """A dummy tool function."""
+    return f"{a} {b}"
+
+  agent = LlmAgent(
+      name="test_llm_agent",
+      description="test description",
+      model="test_model",
+      tools=[my_tool],
+  )
+  with patch.object(mock_agent_loader, "load_agent", return_value=agent):
+    response = test_app.get("/apps/test_app/app-info")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["rootAgentName"] == "test_llm_agent"
+    assert "test_llm_agent" in data["agents"]
+    agent_info = data["agents"]["test_llm_agent"]
+    assert "tools" in agent_info
+    assert len(agent_info["tools"]) == 1
+
+    # Verify tool serialization
+    tool = agent_info["tools"][0]
+    func_decls = tool["functionDeclarations"]
+    assert len(func_decls) == 1
+    assert func_decls[0]["name"] == "my_tool"
+
+
+def test_get_adk_app_info_non_llm_agent(test_app, mock_agent_loader):
+  """Test retrieving app info when root agent is not an LlmAgent raises 400."""
+  agent = DummyAgent("dummy_agent")
+  with patch.object(mock_agent_loader, "load_agent", return_value=agent):
+    response = test_app.get("/apps/test_app/app-info")
+    assert response.status_code == 400
+    assert "Root agent is not an LlmAgent" in response.json()["detail"]
+
+
 def test_create_session_with_id(test_app, test_session_info):
   """Test creating a session with a specific ID."""
   new_session_id = "new_session_id"