Add ResearchAgent subagent + wire it as a tool

- New agents.py: ResearchAgent with breakdown → research → synthesize →
evaluate → refine loop (uses ChatGroq + DuckDuckGo)
- tools.py: expose the subagent as @tool `research` alongside `search_tool`
- requirements.txt: restore langchain-community and ddgs for DuckDuckGo

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P5ATYTWHCUTyrfgYsSU1nL

agents.py

@@ -0,0 +1,230 @@
+import os
+import re
+from typing import TypedDict, Annotated, Literal
+
+from pydantic import BaseModel, Field
+from langchain_groq import ChatGroq
+from langgraph.graph.message import add_messages
+from langgraph.graph import StateGraph, END
+from langchain_core.messages import AnyMessage, HumanMessage, SystemMessage
+
+
+class ResearchAgentState(TypedDict):
+    question: str
+    sub_questions: list[str]
+    research_findings: dict[str, str]
+    research_rounds: int
+    final_answer: str | None
+    evaluation: str | None
+    refinement_count: int
+    messages: Annotated[list[AnyMessage], add_messages]
+
+
+class _Evaluation(BaseModel):
+    label: Literal["excellent", "adequate", "needs_improvement"] = Field(
+        description="Overall quality of the answer."
+    )
+
+
+class ResearchAgent:
+    MAX_RESEARCH_ROUNDS = 5
+    MAX_REFINEMENTS = 2
+    MAX_SNIPPET_CHARS = 3000
+
+    def __init__(self):
+        self.chat = ChatGroq(
+            model="openai/gpt-oss-120b",
+            temperature=0.1,
+            api_key=os.getenv("GROQ_API_KEY"),
+        )
+        self.graph = self._build_graph()
+
+    def __call__(self, question: str) -> str:
+        return self.answer(question)
+
+    def answer(self, question: str) -> str:
+        initial_state: ResearchAgentState = {
+            "question": question,
+            "sub_questions": [],
+            "research_findings": {},
+            "research_rounds": 0,
+            "final_answer": None,
+            "evaluation": None,
+            "refinement_count": 0,
+            "messages": [HumanMessage(content=question)],
+        }
+        final_state = self.graph.invoke(initial_state)
+        return final_state["final_answer"] or "(no answer produced)"
+
+    def _build_graph(self):
+        builder = StateGraph(ResearchAgentState)
+        builder.add_node("breakdown", self.breakdown_question)
+        builder.add_node("research", self.research_with_search)
+        builder.add_node("synthesize", self.synthesize_findings)
+        builder.add_node("evaluate", self.evaluate_answer)
+        builder.add_node("refine", self.refine_answer)
+
+        builder.set_entry_point("breakdown")
+        builder.add_edge("breakdown", "research")
+        builder.add_conditional_edges(
+            "research",
+            self.select_next_step,
+            {"research": "research", "synthesize": "synthesize"},
+        )
+        builder.add_edge("synthesize", "evaluate")
+        builder.add_conditional_edges(
+            "evaluate",
+            self.needs_refinement,
+            {"refine": "refine", "complete": END},
+        )
+        builder.add_edge("refine", "evaluate")
+
+        return builder.compile()
+
+    def parse_sub_questions(self, text: str) -> list[str]:
+        lines = [ln.strip() for ln in text.splitlines() if ln.strip()]
+        cleaned: list[str] = []
+        for ln in lines:
+            stripped = re.sub(r"^(\d+[\.\)]\s+|[-*]\s+)", "", ln)
+            if stripped:
+                cleaned.append(stripped)
+        seen: set[str] = set()
+        result: list[str] = []
+        for q in cleaned:
+            if q not in seen:
+                seen.add(q)
+                result.append(q)
+        return result[:5]
+
+    def pick_next_unanswered(
+        self, sub_questions: list[str], findings: dict[str, str]
+    ) -> str | None:
+        for q in sub_questions:
+            if q not in findings:
+                return q
+        return None
+
+    def breakdown_question(self, state: ResearchAgentState) -> dict:
+        print("[Node] breakdown_question")
+        response = self.chat.invoke([
+            SystemMessage(
+                content="Break the main question into 3-5 concise, standalone sub-questions. "
+                "Return each on a new line without bullets or numbers."
+            ),
+            HumanMessage(content=state["question"]),
+        ])
+        sub_questions = self.parse_sub_questions(response.content)
+        if not sub_questions:
+            sub_questions = [state["question"]]
+        return {
+            "sub_questions": sub_questions,
+            "research_findings": {},
+            "research_rounds": 0,
+            "refinement_count": 0,
+        }
+
+    def research_with_search(self, state: ResearchAgentState) -> dict:
+        print("[Node] research_with_search")
+        next_q = self.pick_next_unanswered(
+            state["sub_questions"], state["research_findings"]
+        )
+        if next_q is None or state["research_rounds"] >= self.MAX_RESEARCH_ROUNDS:
+            return {}
+
+        from tools import search_tool  # lazy: avoids circular import with tools.py
+
+        try:
+            search_results = search_tool.invoke(next_q)
+        except Exception as e:
+            search_results = f"(Search error) {e}"
+
+        response = self.chat.invoke([
+            SystemMessage(
+                content="Answer the sub-question using the provided web search snippets. "
+                "Be concise, cite key points, and avoid speculation."
+            ),
+            HumanMessage(
+                content=(
+                    f"Sub-question: {next_q}\n\n"
+                    f"Search snippets:\n{search_results[: self.MAX_SNIPPET_CHARS]}"
+                )
+            ),
+        ])
+
+        findings = {**state["research_findings"], next_q: response.content}
+        return {
+            "research_findings": findings,
+            "research_rounds": state["research_rounds"] + 1,
+        }
+
+    def select_next_step(self, state: ResearchAgentState) -> str:
+        remaining = [
+            q for q in state["sub_questions"] if q not in state["research_findings"]
+        ]
+        if remaining and state["research_rounds"] < self.MAX_RESEARCH_ROUNDS:
+            return "research"
+        return "synthesize"
+
+    def synthesize_findings(self, state: ResearchAgentState) -> dict:
+        print("[Node] synthesize_findings")
+        findings_text = "\n\n".join(
+            f"{q}:\n{a}" for q, a in state["research_findings"].items()
+        )
+        response = self.chat.invoke([
+            SystemMessage(
+                content="Synthesize a clear, structured answer to the main question "
+                "using the findings provided. Be balanced, specific, and concise."
+            ),
+            HumanMessage(
+                content=(
+                    f"Main question:\n{state['question']}\n\n"
+                    f"Findings:\n{findings_text or '(No findings gathered)'}"
+                )
+            ),
+        ])
+        return {"final_answer": response.content}
+
+    def evaluate_answer(self, state: ResearchAgentState) -> dict:
+        print("[Node] evaluate_answer")
+        structured = self.chat.with_structured_output(_Evaluation)
+        try:
+            result: _Evaluation = structured.invoke([
+                SystemMessage(
+                    content="Evaluate the answer for correctness, completeness and clarity."
+                ),
+                HumanMessage(
+                    content=f"Question:\n{state['question']}\n\nAnswer:\n{state.get('final_answer') or '(empty)'}"
+                ),
+            ])
+            label = result.label
+        except Exception as e:
+            print(f"  [warn] structured eval failed: {e}; defaulting to adequate")
+            label = "adequate"
+        return {"evaluation": label}
+
+    def needs_refinement(self, state: ResearchAgentState) -> str:
+        if state["refinement_count"] >= self.MAX_REFINEMENTS:
+            return "complete"
+        if state["evaluation"] in ("excellent", "adequate"):
+            return "complete"
+        return "refine"
+
+    def refine_answer(self, state: ResearchAgentState) -> dict:
+        print("[Node] refine_answer")
+        response = self.chat.invoke([
+            SystemMessage(
+                content="Refine the answer to address weaknesses and improve clarity, "
+                "structure, and specificity."
+            ),
+            HumanMessage(
+                content=(
+                    f"Main question:\n{state['question']}\n\n"
+                    f"Current answer:\n{state.get('final_answer') or '(empty)'}\n\n"
+                    f"Evaluation: {state.get('evaluation')}"
+                )
+            ),
+        ])
+        return {
+            "final_answer": response.content,
+            "refinement_count": state["refinement_count"] + 1,
+        }

app.py

@@ -1,7 +1,7 @@
 import os
 import gradio as gr
 import requests
-import inspect
+
 import pandas as pd
 import spaces
 from langchain_groq import ChatGroq
@@ -28,6 +28,7 @@ def _zerogpu_stub():
 
 
 class AgentState(TypedDict):
+
     messages: Annotated[list[AnyMessage], add_messages]
 
 
@@ -43,12 +44,12 @@ class BasicAgent:
             api_key=os.getenv("GROQ_API_KEY"),
         )
         self.chat = self.chat.bind_tools(self.tools)
-        self.agent = self.__init__agent()
+        self.agent = self.__init__agent__()
 
     def __call__(self, question: str) -> str:
         return self.answer(question)
 
-    def __init__agent(self):
+    def __init__agent__(self):
         builder = StateGraph(AgentState)
         builder.add_node("assistant", self.assitant)
         builder.add_node("tools", ToolNode(self.tools))

requirements.txt

@@ -3,6 +3,6 @@ requests
 pandas
 langgraph
 langchain-core
-langchain-community
 langchain-groq
+langchain-community
 ddgs

tools.py

@@ -1,3 +1,22 @@
 from langchain_community.tools import DuckDuckGoSearchRun
+from langchain_core.tools import tool
+
+from agents import ResearchAgent
 
 search_tool = DuckDuckGoSearchRun()
+research_agent = ResearchAgent()
+
+
+@tool
+def research(request: str) -> str:
+    """Answer factual questions using web research.
+
+    Use this when the user asks for information that requires up-to-date or
+    external knowledge — names, dates, events, statistics, biographies, or
+    anything that depends on the current state of the world. Handles query
+    decomposition, web search, cross-checking and synthesis.
+
+    Input: Natural language research question (e.g., 'who won the 2024 Nobel
+    Prize in Physics?')
+    """
+    return research_agent(request)