agent-starter-pack 0.5.3__py3-none-any.whl → 0.6.1__py3-none-any.whl

agents/adk_gemini_fullstack/template/.templateconfig.yaml

@@ -0,0 +1,37 @@
+# Copyright 2025 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.
+
+description: "A production-ready fullstack research agent that uses Gemini to strategize, research, and synthesize comprehensive reports with human-in-the-loop collaboration"
+example_question: "A report on the latest Google I/O event"
+settings:
+  requires_data_ingestion: false
+  deployment_targets: ["agent_engine", "cloud_run"]
+  extra_dependencies: ["google-adk~=1.3.0"]
+  tags: ["adk"]
+  frontend_type: "adk_gemini_fullstack"
+  commands:
+    override:
+      install: "npm --prefix frontend install"
+    extra:
+      dev: 
+        command: 'make dev-backend & make dev-frontend'
+        description: "Start the ADK API server and React frontend development server simultaneously"
+      dev-backend:
+        command: 
+          agent_engine: 'uv run adk api_server app --allow_origins="*"'
+          cloud_run: 'ALLOW_ORIGINS="*" uv run uvicorn app.server:app --host 0.0.0.0 --port 8000 --reload'
+        description: "Start the ADK API server"
+      dev-frontend:
+        command: 'npm --prefix frontend run dev'
+        description: "Start the React frontend development server"

agents/adk_gemini_fullstack/tests/integration/test_agent.py

@@ -0,0 +1,58 @@
+# Copyright 2025 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.
+
+# mypy: disable-error-code="union-attr"
+from google.adk.agents.run_config import RunConfig, StreamingMode
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+
+from app.agent import root_agent
+
+
+def test_agent_stream() -> None:
+    """
+    Integration test for the agent stream functionality.
+    Tests that the agent returns valid streaming responses.
+    """
+
+    session_service = InMemorySessionService()
+
+    session = session_service.create_session_sync(user_id="test_user", app_name="test")
+    runner = Runner(agent=root_agent, session_service=session_service, app_name="test")
+
+    message = types.Content(
+        role="user", parts=[types.Part.from_text(text="Why is the sky blue?")]
+    )
+
+    events = list(
+        runner.run(
+            new_message=message,
+            user_id="test_user",
+            session_id=session.id,
+            run_config=RunConfig(streaming_mode=StreamingMode.SSE),
+        )
+    )
+    assert len(events) > 0, "Expected at least one message"
+
+    has_text_content = False
+    for event in events:
+        if (
+            event.content
+            and event.content.parts
+            and any(part.text for part in event.content.parts)
+        ):
+            has_text_content = True
+            break
+    assert has_text_content, "Expected at least one message with text content"

agents/agentic_rag/notebooks/adk_app_testing.ipynb

@@ -261,7 +261,7 @@
    "source": [
     "### Local Testing\n",
     "\n",
-    "> You can run the application locally via the `make backend` command."
+    "> You can run the application locally via the `make local-backend` command."
    ]
   },
   {

src/base_template/Makefile

@@ -1,11 +1,26 @@
 install:
 	@command -v uv >/dev/null 2>&1 || { echo "uv is not installed. Installing uv..."; curl -LsSf https://astral.sh/uv/0.6.12/install.sh | sh; source ~/.bashrc; }
 	uv sync --dev{% if cookiecutter.agent_name != 'live_api' and "adk" not in cookiecutter.tags %} --extra streamlit{%- endif %} --extra jupyter --frozen{% if cookiecutter.agent_name == 'live_api' %} && npm --prefix frontend install{%- endif %}
+{%- if cookiecutter.settings.get("commands", {}).get("override", {}).get("install") %} && {{cookiecutter.settings.get("commands", {}).get("override", {}).get("install")}}{%- endif %}
+{%- if cookiecutter.settings.get("commands", {}).get("extra", {}) %}
+{%- for cmd_name, cmd_value in cookiecutter.settings.get("commands", {}).get("extra", {}).items() %}
 
-test:
-	uv run pytest tests/unit && uv run pytest tests/integration
+{{ cmd_name }}:
+{%- if cmd_value is mapping %}
+{%- if cmd_value.command is mapping and cookiecutter.deployment_target in cmd_value.command %}
+	{{ cmd_value.command[cookiecutter.deployment_target] }}
+{%- else %}
+	{{ cmd_value.command if cmd_value.command is string else "" }}
+{%- endif %}
+{%- else %}
+	{{ cmd_value }}
+{%- endif %}
+{%- endfor %}{%- endif %}
 
 playground:
+{%- if cookiecutter.settings.get("commands", {}).get("override", {}).get("playground") %}
+	{{cookiecutter.settings.get("commands", {}).get("override", {}).get("playground")}}
+{%- else %}
 	@echo "==============================================================================="
 	@echo "| 🚀 Starting your agent playground...                                        |"
 	@echo "|                                                                             |"
@@ -27,6 +42,7 @@ playground:
 	{% if cookiecutter.deployment_target == 'agent_engine' %}PYTHONPATH=. {% endif %}uv run streamlit run frontend/streamlit_app.py --browser.serverAddress=localhost --server.enableCORS=false --server.enableXsrfProtection=false
 {%- endif %}
 {%- endif %}
+{%- endif %}
 
 backend:
 {%- if cookiecutter.deployment_target == 'cloud_run' %}
@@ -82,6 +98,9 @@ data-ingestion:
 		--pipeline-name="data-ingestion-pipeline")
 {%- endif %}
 
+test:
+	uv run pytest tests/unit && uv run pytest tests/integration
+
 lint:
 	uv run codespell
 	uv run ruff check . --diff

src/base_template/README.md

@@ -46,6 +46,11 @@ make install && make playground
 | Command              | Description                                                                                 |
 | -------------------- | ------------------------------------------------------------------------------------------- |
 | `make install`       | Install all required dependencies using uv                                                  |
+{%- if cookiecutter.settings.get("commands", {}).get("extra", {}) %}
+{%- for cmd_name, cmd_value in cookiecutter.settings.get("commands", {}).get("extra", {}).items() %}
+| `make {{ cmd_name }}`       | {% if cmd_value is mapping %}{% if cmd_value.description %}{{ cmd_value.description }}{% else %}{% if cookiecutter.deployment_target in cmd_value %}{{ cmd_value[cookiecutter.deployment_target] }}{% else %}{{ cmd_value.command if cmd_value.command is string else "" }}{% endif %}{% endif %}{% else %}{{ cmd_value }}{% endif %} |
+{%- endfor %}
+{%- endif %}
 {%- if cookiecutter.deployment_target == 'cloud_run' %}
 | `make playground`    | Launch local development environment with backend and frontend{%- if "adk" in cookiecutter.tags %} - leveraging `adk web` command. {%- endif %}|
 | `make backend`       | Deploy agent to Cloud Run |
@@ -84,7 +89,7 @@ Here’s the recommended workflow for local development:
 2.  **Start the Backend Server:**
     Open a terminal and run:
     ```bash
-    make backend
+    make local-backend
     ```
     The backend is ready when you see `INFO:     Application startup complete.` Wait for this message before starting the frontend.
 
@@ -96,7 +101,7 @@ Here’s the recommended workflow for local development:
     ```bash
     export VERTEXAI=false
     export GOOGLE_API_KEY="your-google-api-key" # Replace with your actual key
-    make backend
+    make local-backend
     ```
     Ensure `GOOGLE_API_KEY` is set correctly in your environment.
     </details>
@@ -130,7 +135,7 @@ To run the agent using Google Cloud Shell:
 2.  **Start the Backend:**
     Open a *new* Cloud Shell tab. Set your project: `gcloud config set project [PROJECT_ID]`. Then run:
     ```bash
-    make backend
+    make local-backend
     ```
 
 3.  **Configure Backend Web Preview:**

src/base_template/pyproject.toml

@@ -99,11 +99,8 @@ exclude = [".venv"]
 
 [tool.codespell]
 ignore-words-list = "rouge"
-{% if cookiecutter.agent_name == 'live_api' %}
 skip = "./locust_env/*,uv.lock,.venv,./frontend,**/*.ipynb"
-{% else %}
-skip = "./locust_env/*,uv.lock,.venv,**/*.ipynb"
-{%- endif %}
+
 
 [build-system]
 requires = ["hatchling"]

src/cli/commands/create.py

@@ -191,6 +191,13 @@ def create(
         if debug:
             logging.debug(f"Selected agent: {agent}")
 
+        template_path = (
+            pathlib.Path(__file__).parent.parent.parent.parent
+            / "agents"
+            / final_agent
+            / "template"
+        )
+        config = load_template_config(template_path)
         # Data ingestion and datastore selection
         if include_data_ingestion or datastore:
             # If datastore is specified but include_data_ingestion is not, set it to True
@@ -206,13 +213,6 @@ def create(
                 logging.debug(f"Selected datastore type: {datastore}")
         else:
             # Check if the agent requires data ingestion
-            template_path = (
-                pathlib.Path(__file__).parent.parent.parent.parent
-                / "agents"
-                / final_agent
-                / "template"
-            )
-            config = load_template_config(template_path)
             if config and config.get("settings", {}).get("requires_data_ingestion"):
                 include_data_ingestion = True
                 datastore = prompt_datastore_selection(final_agent)
@@ -322,9 +322,16 @@ def create(
         )
         # Determine the correct path to display based on whether output_dir was specified
         console.print("\n🚀 To get started, run the following command:")
-        console.print(
-            f"   [bold bright_green]cd {cd_path} && make install && make playground[/]"
-        )
+
+        # Check if the agent has a 'dev' command in its settings
+        if config["settings"].get("commands", {}).get("extra", {}).get("dev"):
+            console.print(
+                f"   [bold bright_green]cd {cd_path} && make install && make dev[/]"
+            )
+        else:
+            console.print(
+                f"   [bold bright_green]cd {cd_path} && make install && make playground[/]"
+            )
     except Exception:
         if debug:
             logging.exception(

src/cli/utils/template.py

@@ -80,7 +80,12 @@ def get_available_agents(deployment_target: str | None = None) -> dict:
         deployment_target: Optional deployment target to filter agents
     """
     # Define priority agents that should appear first
-    PRIORITY_AGENTS = ["adk_base", "agentic_rag", "langgraph_base_react"]
+    PRIORITY_AGENTS = [
+        "adk_base",
+        "adk_gemini_fullstack",
+        "agentic_rag",
+        "langgraph_base_react",
+    ]
 
     agents_list = []
     priority_agents_dict = dict.fromkeys(PRIORITY_AGENTS)  # Track priority agents
@@ -499,15 +504,12 @@ def process_template(
                 copy_data_ingestion_files(project_template, datastore)
 
             # Create cookiecutter.json in the template root
-            # Process extra dependencies
-            extra_deps = template_config.get("settings", {}).get(
-                "extra_dependencies", []
-            )
-            # Get frontend type from template config
-            frontend_type = template_config.get("settings", {}).get(
-                "frontend_type", DEFAULT_FRONTEND
-            )
-            tags = template_config.get("settings", {}).get("tags", ["None"])
+            # Get settings from template config
+            settings = template_config.get("settings", {})
+            extra_deps = settings.get("extra_dependencies", [])
+            frontend_type = settings.get("frontend_type", DEFAULT_FRONTEND)
+            tags = settings.get("tags", ["None"])
+
             cookiecutter_config = {
                 "project_name": "my-project",
                 "agent_name": agent_name,
@@ -516,6 +518,7 @@ def process_template(
                 "example_question": template_config.get("example_question", "").ljust(
                     61
                 ),
+                "settings": settings,
                 "tags": tags,
                 "deployment_target": deployment_target or "",
                 "frontend_type": frontend_type,

src/deployment_targets/cloud_run/app/server.py

@@ -28,6 +28,9 @@ from app.utils.typing import Feedback
 _, project_id = google.auth.default()
 logging_client = google_cloud_logging.Client()
 logger = logging_client.logger(__name__)
+allow_origins = (
+    os.getenv("ALLOW_ORIGINS", "").split(",") if os.getenv("ALLOW_ORIGINS") else None
+)
 
 bucket_name = f"gs://{project_id}-{{cookiecutter.project_name}}-logs-data"
 create_bucket_if_not_exists(
@@ -41,7 +44,10 @@ trace.set_tracer_provider(provider)
 
 AGENT_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 app: FastAPI = get_fast_api_app(
-    agents_dir=AGENT_DIR, web=True, artifact_service_uri=bucket_name
+    agents_dir=AGENT_DIR,
+    web=True,
+    artifact_service_uri=bucket_name,
+    allow_origins=allow_origins,
 )
 app.title = "{{cookiecutter.project_name}}"
 app.description = "API for interacting with the Agent {{cookiecutter.project_name}}"

src/deployment_targets/cloud_run/tests/integration/test_server_e2e.py

@@ -157,7 +157,7 @@ def test_chat_stream(server_fixture: subprocess.Popen[str]) -> None:
     }
 {% endif %}
     response = requests.post(
-        STREAM_URL, headers=HEADERS, json=data, stream=True, timeout=10
+        STREAM_URL, headers=HEADERS, json=data, stream=True, timeout=60
     )
     assert response.status_code == 200
 

src/deployment_targets/cloud_run/tests/load_test/.results/.placeholder

@@ -0,0 +1,321 @@
+import datetime
+import logging
+import os
+import re
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from typing import Literal
+
+import google.auth
+from google.adk.agents import LlmAgent, LoopAgent, SequentialAgent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.planners import BuiltInPlanner
+from google.adk.tools import google_search
+from google.genai import types as genai_types
+from pydantic import BaseModel, Field
+
+from google.adk.tools.agent_tool import AgentTool
+from google.adk.agents import BaseAgent
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.events import Event, EventActions
+
+
+_, project_id = google.auth.default()
+os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
+os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
+os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")
+
+
+# --- Centralized Configuration ---
+@dataclass
+class ResearchConfiguration:
+    critic_model: str = "gemini-2.5-pro"
+    worker_model: str = "gemini-2.5-flash"
+    max_search_iterations: int = 5
+
+
+config = ResearchConfiguration()
+
+
+# --- Structured Output Models ---
+class SearchQuery(BaseModel):
+    search_query: str = Field(
+        description="A highly specific and targeted query for web search."
+    )
+
+
+class Feedback(BaseModel):
+    grade: Literal["pass", "fail"] = Field(
+        description="Evaluation result. 'pass' if the research is sufficient, 'fail' if it needs revision."
+    )
+    comment: str = Field(
+        description="Detailed explanation of the evaluation, highlighting strengths and/or weaknesses of the research."
+    )
+    follow_up_queries: list[SearchQuery] | None = Field(
+        default=None,
+        description="A list of specific, targeted follow-up search queries needed to fix research gaps. This should be null or empty if the grade is 'pass'.",
+    )
+
+# --- Callbacks ---
+def collect_research_sources_callback(callback_context: CallbackContext) -> None:
+    session = callback_context._invocation_context.session
+    url_to_short_id = callback_context.state.get("url_to_short_id", {})
+    sources = callback_context.state.get("sources", {})
+    id_counter = len(url_to_short_id) + 1
+    for event in session.events:
+        if not (event.grounding_metadata and event.grounding_metadata.grounding_chunks):
+            continue
+        chunks_info = {}
+        for idx, chunk in enumerate(event.grounding_metadata.grounding_chunks):
+            if not chunk.web:
+                continue
+            url = chunk.web.uri
+            title = (
+                chunk.web.title
+                if chunk.web.title != chunk.web.domain
+                else chunk.web.domain
+            )
+            if url not in url_to_short_id:
+                short_id = f"src-{id_counter}"
+                url_to_short_id[url] = short_id
+                sources[short_id] = {
+                    "short_id": short_id,
+                    "title": title,
+                    "url": url,
+                    "domain": chunk.web.domain,
+                    "supported_claims": [],
+                }
+                id_counter += 1
+            chunks_info[idx] = url_to_short_id[url]
+        if event.grounding_metadata.grounding_supports:
+            for support in event.grounding_metadata.grounding_supports:
+                confidence_scores = support.confidence_scores or []
+                chunk_indices = support.grounding_chunk_indices or []
+                for i, chunk_idx in enumerate(chunk_indices):
+                    if chunk_idx in chunks_info:
+                        short_id = chunks_info[chunk_idx]
+                        confidence = (
+                            confidence_scores[i] if i < len(confidence_scores) else 0.5
+                        )
+                        text_segment = support.segment.text if support.segment else ""
+                        sources[short_id]["supported_claims"].append(
+                            {
+                                "text_segment": text_segment,
+                                "confidence": confidence,
+                            }
+                        )
+    callback_context.state["url_to_short_id"] = url_to_short_id
+    callback_context.state["sources"] = sources
+
+
+def citation_replacement_callback(callback_context: CallbackContext) -> genai_types.Content:
+    final_report = callback_context.state.get("final_cited_report", "")
+    sources = callback_context.state.get("sources", {})
+    def tag_replacer(match: re.Match) -> str:
+        short_id = match.group(1)
+        if not (source_info := sources.get(short_id)):
+            logging.warning(f"Invalid citation tag found and removed: {match.group(0)}")
+            return ""
+        display_text = source_info.get("title", source_info.get("domain", short_id))
+        return f" [{display_text}]({source_info['url']})"
+    processed_report = re.sub(
+        r'<cite\s+source\s*=\s*["\']?\s*(src-\d+)\s*["\']?\s*/>', tag_replacer, final_report
+    )
+    processed_report = re.sub(r'\s+([.,;:])', r'\1', processed_report)
+    callback_context.state["final_report_with_citations"] = processed_report
+    return genai_types.Content(parts=[genai_types.Part(text=processed_report)])
+
+
+# --- Custom Agent for Loop Control ---
+class EscalationChecker(BaseAgent):
+    """Checks research evaluation and escalates to stop the loop if grade is 'pass'."""
+    def __init__(self, name: str):
+        super().__init__(name=name)
+    async def _run_async_impl(self, ctx: InvocationContext) -> AsyncGenerator[Event, None]:
+        evaluation_result = ctx.session.state.get("research_evaluation")
+        if evaluation_result and evaluation_result.get("grade") == "pass":
+            logging.info(f"[{self.name}] Research evaluation passed. Escalating to stop loop.")
+            yield Event(author=self.name, actions=EventActions(escalate=True))
+        else:
+            logging.info(f"[{self.name}] Research evaluation failed or not found. Loop will continue.")
+            # Yielding an event without content or actions just lets the flow continue.
+            yield Event(author=self.name)
+
+
+# --- AGENT DEFINITIONS ---
+
+plan_generator = LlmAgent(
+    model=config.worker_model,
+    name="plan_generator",
+    description="Generates a 4-5 line action-oriented research plan, using minimal search only for topic clarification.",
+    instruction=f"""
+    You are a research strategist. Your job is to create a high-level RESEARCH PLAN, not a summary.
+    **RULE: Your output MUST be a bulleted list of 4-5 action-oriented research goals or key questions.**
+    - A good goal starts with a verb like "Analyze," "Identify," "Investigate."
+    - A bad output is a statement of fact like "The event was in April 2024."
+    **TOOL USE IS STRICTLY LIMITED:**
+    Your goal is to create a generic, high-quality plan *without searching*.
+    Only use `google_search` if a topic is ambiguous or time-sensitive and you absolutely cannot create a plan without a key piece of identifying information.
+    You are explicitly forbidden from researching the *content* or *themes* of the topic. That is the next agent's job. Your search is only to identify the subject, not to investigate it.
+    Current date: {datetime.datetime.now().strftime("%Y-%m-%d")}
+    """,
+    tools=[google_search],
+)
+
+
+section_planner = LlmAgent(
+    model=config.worker_model,
+    name="section_planner",
+    description="Breaks down the research plan into a structured markdown outline of report sections.",
+    instruction="""
+    You are an expert report architect. Using the research topic and the plan from the 'research_plan' state key, design a logical structure for the final report.
+    Your task is to create a markdown outline with 4-6 distinct sections that cover the topic comprehensively without overlap.
+    You can use any markdown format you prefer, but here's a suggested structure:
+    # Section Name
+    A brief overview of what this section covers
+    Feel free to add subsections or bullet points if needed to better organize the content.
+    Make sure your outline is clear and easy to follow.
+    Do not include a "References" or "Sources" section in your outline. Citations will be handled in-line.
+    """,
+    output_key="report_sections",
+)
+
+
+section_researcher = LlmAgent(
+    model=config.worker_model,
+    name="section_researcher",
+    description="Performs the crucial first pass of web research.",
+    planner=BuiltInPlanner(
+        thinking_config=genai_types.ThinkingConfig(include_thoughts=True)
+    ),
+    instruction="""
+    You are a diligent and exhaustive researcher. Your task is to perform the initial, broad information gathering for a report.
+    You will be provided with a list of sections in the 'report_sections' state key.
+    For each section where 'research' is marked as 'true', generate a comprehensive list of 4-5 targeted search queries to cover the topic from multiple angles.
+    Execute all of these queries using the 'google_search' tool and synthesize the results into a detailed summary for that section.
+    """,
+    tools=[google_search],
+    output_key="section_research_findings",
+    after_agent_callback=collect_research_sources_callback,
+)
+
+research_evaluator = LlmAgent(
+    model=config.critic_model,
+    name="research_evaluator", 
+    description="Critically evaluates research and generates follow-up queries.",
+    instruction=f"""
+    You are a meticulous quality assurance analyst evaluating the research findings in 'section_research_findings'.
+    
+    **CRITICAL RULES:**
+    1. Assume the given research topic is correct. Do not question or try to verify the subject itself.
+    2. Your ONLY job is to assess the quality, depth, and completeness of the research provided *for that topic*.
+    3. Focus on evaluating: Comprehensiveness of coverage, logical flow and organization, use of credible sources, depth of analysis, and clarity of explanations.
+    4. Do NOT fact-check or question the fundamental premise or timeline of the topic.
+    5. If suggesting follow-up queries, they should dive deeper into the existing topic, not question its validity.
+
+    Be very critical about the QUALITY of research. If you find significant gaps in depth or coverage, assign a grade of "fail", 
+    write a detailed comment about what's missing, and generate 5-7 specific follow-up queries to fill those gaps. 
+    If the research thoroughly covers the topic, grade "pass".
+
+    Current date: {datetime.datetime.now().strftime("%Y-%m-%d")}
+    Your response must be a single, raw JSON object validating against the 'Feedback' schema.
+    """,
+    output_schema=Feedback,
+    output_key="research_evaluation",
+)
+
+enhanced_search_executor = LlmAgent(
+    model=config.worker_model,
+    name="enhanced_search_executor",
+    description="Executes follow-up searches and integrates new findings.",
+    planner=BuiltInPlanner(
+        thinking_config=genai_types.ThinkingConfig(include_thoughts=True)
+    ),
+    instruction="""
+    You are a specialist researcher executing a refinement pass.
+    You have been activated because the previous research was graded as 'fail'.
+
+    1.  Review the 'research_evaluation' state key to understand the feedback and required fixes.
+    2.  Execute EVERY query listed in 'follow_up_queries' using the 'google_search' tool.
+    3.  Synthesize the new findings and COMBINE them with the existing information in 'section_research_findings'.
+    4.  Your output MUST be the new, complete, and improved set of research findings.
+    """,
+    tools=[google_search],
+    output_key="section_research_findings",
+    after_agent_callback=collect_research_sources_callback,
+)
+
+report_composer = LlmAgent(
+    model=config.critic_model,
+    name="report_composer_with_citations",
+    include_contents="none",
+    description="Transforms research data and a markdown outline into a final, cited report.",
+    instruction="""
+    Transform the provided data into a polished, professional, and meticulously cited research report.
+
+    ---
+    ### INPUT DATA
+    *   Research Plan: `{research_plan}`
+    *   Research Findings: `{section_research_findings}`
+    *   Citation Sources: `{sources}`
+    *   Report Structure: `{report_sections}`
+
+    ---
+    ### CRITICAL: Citation System
+    To cite a source, you MUST insert a special citation tag directly after the claim it supports.
+
+    **The only correct format is:** `<cite source="src-ID_NUMBER" />`
+
+    ---
+    ### Final Instructions
+    Generate a comprehensive report using ONLY the `<cite source="src-ID_NUMBER" />` tag system for all citations.
+    The final report must strictly follow the structure provided in the **Report Structure** markdown outline.
+    Do not include a "References" or "Sources" section; all citations must be in-line.
+    """,
+    output_key="final_cited_report",
+    after_agent_callback=citation_replacement_callback,
+)
+
+research_pipeline = SequentialAgent(
+    name="research_pipeline",
+    description="Executes a pre-approved research plan. It performs iterative research, evaluation, and composes a final, cited report.",
+    sub_agents=[
+        section_planner,
+        section_researcher,
+        LoopAgent(
+            name="iterative_refinement_loop",
+            max_iterations=config.max_search_iterations,
+            sub_agents=[
+                research_evaluator,
+                EscalationChecker(name="escalation_checker"),
+                enhanced_search_executor,
+            ],
+        ),
+        report_composer,
+    ],
+)
+
+interactive_planner_agent = LlmAgent(
+    name="interactive_planner_agent",
+    model=config.worker_model,
+    description="The primary research assistant. It collaborates with the user to create a research plan, and then executes it upon approval.",
+    instruction=f"""
+    You are a research planning assistant. Your primary function is to convert ANY user request into a research plan.
+
+    **CRITICAL RULE: Never answer a question directly or refuse a request.** Your one and only first step is to use the `plan_generator` tool to propose a research plan for the user's topic.
+    If the user asks a question, you MUST immediately call `plan_generator` to create a plan to answer the question.
+
+    Your workflow is:
+    1.  **Plan:** Use `plan_generator` to create a draft plan and present it to the user.
+    2.  **Refine:** Incorporate user feedback until the plan is approved.
+    3.  **Execute:** Once the user gives EXPLICIT approval (e.g., "looks good, run it"), you MUST delegate the task to the `research_pipeline` agent, passing the approved plan.
+
+    Current date: {datetime.datetime.now().strftime("%Y-%m-%d")}
+    Do not perform any research yourself. Your job is to Plan, Refine, and Delegate.
+    """,
+    sub_agents=[research_pipeline],
+    tools=[AgentTool(plan_generator)],
+    output_key="research_plan",
+)
+
+root_agent = interactive_planner_agent