add: swap agent

requirements.txt

@@ -59,4 +59,6 @@ mypy>=1.5.0
 
 # ClickHouse dependencies
 clickhouse-connect>=0.7.0
-clickhouse-sqlalchemy==0.3.2
+clickhouse-sqlalchemy==0.3.2
+
+langchain-tavily>=0.2.11

src/agents/search/agent.py

@@ -0,0 +1,21 @@
+import logging
+from langgraph.prebuilt import create_react_agent
+
+from src.agents.search.tools import get_tools
+
+logger = logging.getLogger(__name__)
+
+
+class SearchAgent:
+    """Agent dedicated to answering queries via web search tools."""
+
+    def __init__(self, llm):
+        self.llm = llm
+        tools = get_tools()
+        if not tools:
+            logger.warning("Search agent initialised without tools; it will act as a plain LLM.")
+        self.agent = create_react_agent(
+            model=llm,
+            tools=tools,
+            name="search_agent",
+        )

src/agents/search/tools.py

@@ -0,0 +1,59 @@
+
+import logging
+import os
+from typing import List
+
+from langchain_core.tools import Tool
+
+logger = logging.getLogger(__name__)
+
+
+def _build_tavily_tool():
+    """Create a Tavily search tool if the dependency and API key are available."""
+    api_key = os.getenv("TAVILY_API_KEY")
+    if not api_key:
+        logger.warning("TAVILY_API_KEY not set; web search tool disabled.")
+        return None
+
+    try:
+        from langchain_tavily import TavilySearch
+    except ImportError as exc:  # pragma: no cover - dependency may be optional
+        logger.warning("langchain_tavily package is unavailable: %s", exc)
+        return None
+
+    try:
+        # TavilySearch currently expects the API key either via keyword or env var.
+        try:
+            return TavilySearch(api_key=api_key)
+        except TypeError:
+            return TavilySearch(tavily_api_key=api_key)
+    except Exception as exc:  # pragma: no cover - runtime init guard
+        logger.error("Failed to initialise Tavily search tool: %s", exc)
+        return None
+
+
+def _search_unavailable(query: str) -> str:
+    return (
+        "Search service is unavailable right now."
+        " Configure TAVILY_API_KEY and install langchain-tavily to enable live results."
+    )
+
+
+def get_tools() -> List:
+    """Return the toolset used by the search agent."""
+    tools = []
+    tavily_tool = _build_tavily_tool()
+    if tavily_tool:
+        tools.append(tavily_tool)
+    else:
+        tools.append(
+            Tool(
+                name="search_unavailable",
+                func=_search_unavailable,
+                description=(
+                    "Fallback search stub that informs the user when the web search"
+                    " service is not configured."
+                ),
+            )
+        )
+    return tools

src/agents/supervisor/agent.py

@@ -1,16 +1,18 @@
 from langchain_google_genai import ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings
 from langgraph_supervisor import create_supervisor
 from src.agents.config import Config
-from typing import TypedDict, Literal, List, Any
+from typing import TypedDict, Literal, List, Any, Tuple
 import re
 import json
 from src.agents.metadata import metadata
+from src.agents.crypto_data.config import Config as CryptoConfig
 
 # Agents
 from src.agents.crypto_data.agent import CryptoDataAgent
 from src.agents.database.agent import DatabaseAgent
 from src.agents.default.agent import DefaultAgent
 from src.agents.swap.agent import SwapAgent
+from src.agents.search.agent import SearchAgent
 from src.agents.database.client import is_database_available
 
 llm = ChatGoogleGenerativeAI(
@@ -24,10 +26,12 @@ embeddings = GoogleGenerativeAIEmbeddings(
     google_api_key=Config.GEMINI_API_KEY
 )
 
+
 class ChatMessage(TypedDict):
     role: Literal["system", "user", "assistant"]
     content: str
 
+
 class Supervisor:
     def __init__(self, llm):
         self.llm = llm
@@ -36,25 +40,85 @@ class Supervisor:
         cryptoDataAgent = cryptoDataAgentClass.agent
 
         agents = [cryptoDataAgent]
-        available_agents_text = "- crypto_agent: Handles cryptocurrency-related queries like price checks, market data, NFT floor prices, DeFi protocol TVL, etc.\n"
+        available_agents_text = (
+            "- crypto_agent: Handles cryptocurrency-related queries like price checks, market data, NFT floor prices, DeFi protocol TVL (don't route to this agent if none of the mention information).\n"
+        )
 
         # Conditionally include database agent
         if is_database_available():
             databaseAgent = DatabaseAgent(llm)
             agents.append(databaseAgent)
-            available_agents_text += "- database_agent: Handles database queries and data analysis. Can search and analyze data from the database.\n"
+            available_agents_text += (
+                "- database_agent: Handles database queries and data analysis. Can search and analyze data from the database.\n"
+            )
         else:
             databaseAgent = None
 
         swapAgent = SwapAgent(llm)
         agents.append(swapAgent.agent)
-        available_agents_text += "- swap_agent: Handles swap operations on the Avalanche network and any other swap question related.\n"
+        available_agents_text += (
+            "- swap_agent: Handles swap operations on the Avalanche network and any other swap question related.\n"
+        )
+
+        searchAgent = SearchAgent(llm)
+        self.search_agent = searchAgent.agent
+        agents.append(self.search_agent)
+        available_agents_text += (
+            "- search_agent: Uses web search tools for current events and factual lookups.\n"
+        )
 
         defaultAgent = DefaultAgent(llm)
-        agents.append(defaultAgent.agent)
+        self.default_agent = defaultAgent.agent
+        agents.append(self.default_agent)
 
         # Track known agent names for response extraction
-        self.known_agent_names = {"crypto_agent", "database_agent", "swap_agent", "default_agent"}
+        self.known_agent_names = {"crypto_agent", "database_agent", "swap_agent", "search_agent", "default_agent"}
+        self.specialized_agents = {"crypto_agent", "database_agent", "swap_agent", "search_agent"}
+        self.failure_markers = (
+            "cannot fulfill",
+            "can't fulfill",
+            "cannot assist",
+            "can't assist",
+            "cannot help",
+            "can't help",
+            "cannot tell",
+            "can't tell",
+            "cannot tell you",
+            "can't tell you",
+            "cannot comply",
+            "transfer you",
+            "specialized agent",
+            "no response available",
+            "failed to retrieve",
+            "api at the moment",
+            "handling your request",
+            "crypto_agent is handling",
+            "will provide",
+            "provide the price",
+            "tool error",
+            "search service is unavailable",
+            "configure tavily_api_key",
+            "no results found",
+            "unable to",
+            "cannot get",
+            "can't get",
+            "cannot find",
+            "can't find",
+            "could not find",
+            "do not have that information",
+            "don't have that information",
+            "having trouble",
+            "trouble finding",
+            "I can only"
+        )
+        self.config_failure_messages = {
+            CryptoConfig.PRICE_FAILURE_MESSAGE.lower(),
+            CryptoConfig.FLOOR_PRICE_FAILURE_MESSAGE.lower(),
+            CryptoConfig.TVL_FAILURE_MESSAGE.lower(),
+            CryptoConfig.FDV_FAILURE_MESSAGE.lower(),
+            CryptoConfig.MARKET_CAP_FAILURE_MESSAGE.lower(),
+            CryptoConfig.API_ERROR_MESSAGE.lower(),
+        }
 
         # Prepare database guidance text to avoid backslashes in f-string expressions
         if databaseAgent:
@@ -70,6 +134,16 @@ class Supervisor:
             database_instruction = "Do not delegate to a database agent; answer best-effort without DB access or ask the user to start the database."
             database_examples = ""
 
+        search_instruction = (
+            "When the user asks about breaking news, recent developments, or requests a web lookup, delegate to the search_agent first."
+        )
+        search_examples = (
+            "Examples of search queries to delegate:\n"
+            "- \"What happened with Bitcoin this week?\"\n"
+            "- \"Find the latest Avalanche ecosystem partnerships\"\n"
+            "- \"Who just won the most recent Formula 1 race?\"\n"
+        )
+
         # System prompt to guide the supervisor
         system_prompt = f"""You are a helpful supervisor that routes user queries to the appropriate specialized agents.
 
@@ -78,6 +152,7 @@ Available agents:
 
 When a user asks about cryptocurrency prices, market data, NFTs, or DeFi protocols, delegate to the crypto_agent.
 {database_instruction}
+{search_instruction}
 For all other queries, respond directly as a helpful assistant.
 
 IMPORTANT: your final response should answer the user's query. Use the agents response to answer the user's query if necessary. Avoid returning control-transfer notes like 'Transferring back to supervisor' — return the substantive answer instead.
@@ -93,12 +168,20 @@ Examples of swap queries to delegate:
 - What are the available tokens for swapping?
 - I want to swap 100 USD for AVAX
 
+When a swap conversation is already underway (the user is still providing swap
+details or the swap_agent requested follow-up information), keep routing those
+messages to the swap_agent until it has gathered every field and signals the
+swap intent is ready.
+
 {database_examples}
 
+{search_examples}
+
 Examples of general queries to handle directly:
 - "Hello, how are you?"
 - "What's the weather like?"
 - "Tell me a joke"
+- "What is the biggest poll in Trader Joe?"
 """
 
         self.supervisor = create_supervisor(
@@ -180,7 +263,7 @@ Examples of general queries to handle directly:
             if collected:
                 return " ".join(collected)
         return None
-    
+
     def _extract_payload(self, text: str) -> tuple[dict, str]:
         # Try JSON payload first
         try:
@@ -214,32 +297,8 @@ Examples of general queries to handle directly:
                 return art
         return {}
 
-    def invoke(self, messages: List[ChatMessage]) -> dict:
-        from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
-
-        langchain_messages = []
-        for msg in messages:
-            if msg.get("role") == "user":
-                langchain_messages.append(HumanMessage(content=msg.get("content", "")))
-            elif msg.get("role") == "system":
-                langchain_messages.append(SystemMessage(content=msg.get("content", "")))
-            elif msg.get("role") == "assistant":
-                langchain_messages.append(AIMessage(content=msg.get("content", "")))
-
-        try:
-            response = self.app.invoke({"messages": langchain_messages})
-            print("DEBUG: response", response)
-        except Exception as e:
-            print(f"Error in Supervisor: {e}")
-            return {
-                "messages": [],
-                "agent": "supervisor",
-                "response": "Sorry, an error occurred while processing your request."
-            }
-
+    def _extract_response_from_graph(self, response: Any) -> Tuple[str, str, list]:
         messages_out = response.get("messages", []) if isinstance(response, dict) else []
-
-        # Prefer the last specialized agent message over any router/supervisor meta message
         final_response = None
         final_agent = "supervisor"
 
@@ -254,7 +313,6 @@ Examples of general queries to handle directly:
                 # Prefer sanitized content
                 return sanitized, agent_name
             return None, None
-        
 
         # 1) Try to find the last message from a known specialized agent that is not a handoff/route-back note
         for m in reversed(messages_out):
@@ -286,16 +344,117 @@ Examples of general queries to handle directly:
                 final_response = "No response available"
 
         cleaned_response = final_response or "Sorry, no meaningful response was returned."
-        meta = {}
-        if final_agent == "swap_agent":
-            meta = {'src': 'AVAX', 'dst': 'USDC', 'amount': '100'}
-        elif final_agent == "crypto_agent":
-            meta = metadata.get_crypto_data_agent() or {}
-        else:
-            meta = {}
+        final_agent = final_agent or "supervisor"
+        return final_agent, cleaned_response, messages_out
+
+    def _needs_supervisor_fallback(self, agent_name: str, response_text: str) -> bool:
+        if not response_text:
+            return agent_name in self.specialized_agents
+        lowered = response_text.strip().lower()
+        if lowered in self.config_failure_messages:
+            return True
+        if any(marker in lowered for marker in self.failure_markers):
+            return True
+        if agent_name in self.specialized_agents and not lowered:
+            return True
+        return False
+
+    def _run_default_agent(self, langchain_messages: List[Any]) -> Tuple[str | None, str | None, list]:
+        if not getattr(self, "default_agent", None):
+            return None, None, []
+        try:
+            fallback_response = self.default_agent.invoke({"messages": langchain_messages})
+            print("DEBUG: default agent fallback response", fallback_response)
+        except Exception as exc:
+            print(f"Error invoking default agent fallback: {exc}")
+            return None, None, []
+        fallback_agent, fallback_text, fallback_messages = self._extract_response_from_graph(fallback_response)
+        if not fallback_agent:
+            fallback_agent = "default_agent"
+        return fallback_agent, fallback_text, fallback_messages
+
+    def _run_search_agent(self, langchain_messages: List[Any]) -> Tuple[str | None, str | None, list]:
+        if not getattr(self, "search_agent", None):
+            return None, None, []
+        try:
+            fallback_response = self.search_agent.invoke({"messages": langchain_messages})
+            print("DEBUG: search agent fallback response", fallback_response)
+        except Exception as exc:
+            print(f"Error invoking search agent fallback: {exc}")
+            return None, None, []
+        fallback_agent, fallback_text, fallback_messages = self._extract_response_from_graph(fallback_response)
+        if not fallback_agent:
+            fallback_agent = "search_agent"
+        return fallback_agent, fallback_text, fallback_messages
+
+    def _build_metadata(self, agent_name: str, messages_out) -> dict:
+        if agent_name == "swap_agent":
+            swap_meta = metadata.get_swap_agent()
+            return swap_meta.copy() if swap_meta else {}
+        if agent_name == "crypto_agent":
+            tool_meta = self._collect_tool_metadata(messages_out)
+            if tool_meta:
+                metadata.set_crypto_data_agent(tool_meta)
+            return metadata.get_crypto_data_agent() or {}
+        return {}
+
+    def invoke(self, messages: List[ChatMessage]) -> dict:
+        from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
+
+        langchain_messages = []
+        for msg in messages:
+            if msg.get("role") == "user":
+                langchain_messages.append(HumanMessage(content=msg.get("content", "")))
+            elif msg.get("role") == "system":
+                langchain_messages.append(SystemMessage(content=msg.get("content", "")))
+            elif msg.get("role") == "assistant":
+                langchain_messages.append(AIMessage(content=msg.get("content", "")))
+
+        try:
+            response = self.app.invoke({"messages": langchain_messages})
+            print("DEBUG: response", response)
+        except Exception as e:
+            print(f"Error in Supervisor: {e}")
+            return {
+                "messages": [],
+                "agent": "supervisor",
+                "response": "Sorry, an error occurred while processing your request."
+            }
+
+        final_agent, cleaned_response, messages_out = self._extract_response_from_graph(response)
+
+        if self._needs_supervisor_fallback(final_agent, cleaned_response):
+            print("INFO: Fallback triggered for agent", final_agent)
+            fallback_agent = None
+            fallback_response = None
+            fallback_messages: list = []
+
+            if final_agent != "search_agent":
+                search_agent, search_response, search_messages = self._run_search_agent(langchain_messages)
+                if search_response and not self._needs_supervisor_fallback(search_agent or "search_agent", search_response):
+                    fallback_agent = search_agent or "search_agent"
+                    fallback_response = search_response
+                    fallback_messages = search_messages
+                else:
+                    fallback_agent = search_agent
+                    fallback_response = search_response
+                    fallback_messages = search_messages
+
+            if not fallback_response or self._needs_supervisor_fallback(fallback_agent or "", fallback_response):
+                default_agent, default_response, default_messages = self._run_default_agent(langchain_messages)
+                if default_response:
+                    fallback_agent = default_agent or "default_agent"
+                    fallback_response = default_response
+                    fallback_messages = default_messages
+
+            if fallback_response:
+                final_agent = fallback_agent or "default_agent"
+                cleaned_response = fallback_response
+                messages_out = fallback_messages
+
+        meta = self._build_metadata(final_agent, messages_out)
         print("meta: ", meta)
         print("cleaned_response: ", cleaned_response)
-
         print("final_agent: ", final_agent)
 
         return {
@@ -303,4 +462,4 @@ Examples of general queries to handle directly:
             "agent": final_agent,
             "response": cleaned_response or "Sorry, no meaningful response was returned.",
             "metadata": meta,
-        }
+        }

src/agents/swap/config.py

@@ -1,42 +1,135 @@
+"""Network-aware swap configuration helpers."""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, Optional, Set, Tuple
+
+
 class SwapConfig:
-    """Configuration and simple interface for supported swap tokens.
-
-    This provides a canonical set of allowed token symbols and helpers to
-    normalize and validate user input before executing swaps.
-    """
-
-    # Canonical symbols for Avalanche swaps (expand as needed)
-    SUPPORTED_TOKENS = {
-        "AVAX",   # Native token
-        "WAVAX",  # Wrapped AVAX
-        "USDC",
-        "USDT",
-        "DAI",
-        "WBTC",
-        "WETH",
+    """Expose swap metadata so tools can validate user input safely."""
+
+    # Canonical networks we support. Values are the tokens available on that chain.
+    _NETWORK_TOKENS: Dict[str, Set[str]] = {
+        "avalanche": {
+            "AVAX",
+            "WAVAX",
+            "USDC",
+            "USDT",
+            "DAI",
+            "BTC.B",
+        },
+        "ethereum": {
+            "ETH",
+            "WETH",
+            "USDC",
+            "USDT",
+            "DAI",
+            "WBTC",
+        },
+    }
+
+    # Friendly aliases -> canonical keys
+    _NETWORK_ALIASES: Dict[str, str] = {
+        "avax": "avalanche",
+        "avalanche": "avalanche",
+        "ethereum": "ethereum",
+        "eth": "ethereum",
     }
 
+    _TOKEN_ALIASES: Dict[str, str] = {
+        "avax": "AVAX",
+        "wavax": "WAVAX",
+        "usdc": "USDC",
+        "usdt": "USDT",
+        "dai": "DAI",
+        "btc.b": "BTC.B",
+        "btcb": "BTC.B",
+        "wbtc": "WBTC",
+        "eth": "ETH",
+        "weth": "WETH",
+    }
+
+    # Optional allow list of directional routes (canonical network names).
+    _SUPPORTED_ROUTES: Set[Tuple[str, str]] = {
+        ("avalanche", "ethereum"),
+        ("ethereum", "avalanche"),
+        ("avalanche", "avalanche"),
+        ("ethereum", "ethereum"),
+    }
+
+    # ---------- Public helpers ----------
     @classmethod
-    def normalize_symbol(cls, symbol: str) -> str:
-        """Return canonical uppercase symbol without surrounding whitespace."""
-        return (symbol or "").strip().upper()
+    def list_networks(cls) -> Iterable[str]:
+        """Return supported networks in a stable order."""
+        return sorted(cls._NETWORK_TOKENS.keys())
 
     @classmethod
-    def is_supported(cls, symbol: str) -> bool:
-        """Check if a token symbol is supported (case-insensitive)."""
-        return cls.normalize_symbol(symbol) in cls.SUPPORTED_TOKENS
+    def list_tokens(cls, network: str) -> Iterable[str]:
+        """Return supported tokens for a given network."""
+        normalized = cls._normalize_network(network)
+        if normalized not in cls._NETWORK_TOKENS:
+            raise ValueError(
+                f"Unsupported network '{network}'. Available: {sorted(cls._NETWORK_TOKENS)}"
+            )
+        return sorted(cls._NETWORK_TOKENS[normalized])
 
     @classmethod
-    def validate_or_raise(cls, symbol: str) -> str:
-        """Validate token symbol and return its canonical form, or raise ValueError."""
-        canonical = cls.normalize_symbol(symbol)
-        if canonical not in cls.SUPPORTED_TOKENS:
+    def validate_network(cls, network: str) -> str:
+        """Return the canonical network name or raise ValueError."""
+        return cls._normalize_network(network)
+
+    @classmethod
+    def validate_or_raise(cls, token: str, network: Optional[str] = None) -> str:
+        """Validate a token, optionally scoping by network, and return canonical symbol."""
+        canonical = cls._normalize_token(token)
+        if network is not None:
+            normalized_network = cls._normalize_network(network)
+            tokens = cls._NETWORK_TOKENS.get(normalized_network, set())
+            if canonical not in tokens:
+                raise ValueError(
+                    f"Unsupported token '{token}' on {normalized_network}. Available: {sorted(tokens)}"
+                )
+        elif canonical not in cls._all_tokens():
             raise ValueError(
-                f"Unsupported token '{symbol}'. Supported tokens: {sorted(cls.SUPPORTED_TOKENS)}"
+                f"Unsupported token '{token}'. Supported tokens: {sorted(cls._all_tokens())}"
             )
         return canonical
 
     @classmethod
-    def list_supported(cls):
-        """Return a sorted list of supported token symbols."""
-        return sorted(cls.SUPPORTED_TOKENS)    
+    def routes_supported(cls, from_network: str, to_network: str) -> bool:
+        """Return whether a swap route is supported."""
+        source = cls._normalize_network(from_network)
+        dest = cls._normalize_network(to_network)
+        return (source, dest) in cls._SUPPORTED_ROUTES
+
+    @classmethod
+    def list_supported(cls) -> Iterable[str]:
+        """Backwards compatible helper returning all tokens across networks."""
+        return sorted(cls._all_tokens())
+
+    # ---------- Internal helpers ----------
+    @classmethod
+    def _normalize_network(cls, network: str) -> str:
+        key = (network or "").strip().lower()
+        if not key:
+            raise ValueError("Network is required.")
+        normalized = cls._NETWORK_ALIASES.get(key)
+        if normalized is None:
+            raise ValueError(
+                f"Unsupported network '{network}'. Available: {sorted(cls._NETWORK_TOKENS)}"
+            )
+        return normalized
+
+    @classmethod
+    def _normalize_token(cls, token: str) -> str:
+        key = (token or "").strip().lower()
+        if not key:
+            raise ValueError("Token is required.")
+        return cls._TOKEN_ALIASES.get(key, key.upper())
+
+    @classmethod
+    def _all_tokens(cls) -> Set[str]:
+        tokens: Set[str] = set()
+        for chain_tokens in cls._NETWORK_TOKENS.values():
+            tokens.update(chain_tokens)
+        return tokens

src/agents/swap/tools.py

@@ -1,49 +1,284 @@
+"""Swap tools that manage a conversational swap intent."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Dict, List, Optional
+
 from langchain_core.tools import tool
+from pydantic import BaseModel, Field, field_validator
+
 from src.agents.metadata import metadata
 from src.agents.swap.config import SwapConfig
 
-@tool
-def swap_avax(amount: float, from_token: str, to_token: str):
-    """
-    Swap AVAX for a given amount of tokens
+# ---------- In-memory intent store (swap session) ----------
+# Replace with persistent storage if the agent runs in multiple instances.
+_INTENTS: Dict[str, "SwapIntent"] = {}
+_DEFAULT_USER_ID = "__default_swap_user__"
+
+
+@dataclass
+class SwapIntent:
+    user_id: str = _DEFAULT_USER_ID
+    from_network: Optional[str] = None
+    from_token: Optional[str] = None
+    to_network: Optional[str] = None
+    to_token: Optional[str] = None
+    amount: Optional[float] = None
+
+    def is_complete(self) -> bool:
+        return all(
+            [
+                self.from_network,
+                self.from_token,
+                self.to_network,
+                self.to_token,
+                self.amount,
+            ]
+        )
+
+    def missing_fields(self) -> List[str]:
+        fields: List[str] = []
+        if not self.from_network:
+            fields.append("from_network")
+        if not self.from_token:
+            fields.append("from_token")
+        if not self.to_network:
+            fields.append("to_network")
+        if not self.to_token:
+            fields.append("to_token")
+        if self.amount is None:
+            fields.append("amount")
+        return fields
+
+
+# ---------- Pydantic input schema ----------
+class UpdateSwapIntentInput(BaseModel):
+    user_id: Optional[str] = Field(
+        default=None,
+        description="Stable ID for the end user / chat session. Optional, but required for multi-user disambiguation.",
+    )
+    from_network: Optional[str] = None
+    from_token: Optional[str] = None
+    to_network: Optional[str] = None
+    to_token: Optional[str] = None
+    amount: Optional[float] = Field(None, gt=0)
+
+    @field_validator("from_network", "to_network", mode="before")
+    @classmethod
+    def _norm_network(cls, value: Optional[str]) -> Optional[str]:
+        return value.lower() if isinstance(value, str) else value
+
+    @field_validator("from_token", "to_token", mode="before")
+    @classmethod
+    def _norm_token(cls, value: Optional[str]) -> Optional[str]:
+        return value.upper() if isinstance(value, str) else value
+
+
+# ---------- Output helpers ----------
+def _response(
+    intent: SwapIntent,
+    ask: Optional[str],
+    choices: Optional[List[str]] = None,
+    done: bool = False,
+    error: Optional[str] = None,
+) -> Dict[str, object]:
+    """Consistent payload for the UI layer."""
+
+    payload: Dict[str, object] = {
+        "event": "swap_intent_ready" if done else "ask_user",
+        "intent": asdict(intent),
+        "ask": ask,
+        "choices": choices or [],
+        "error": error,
+    }
+    if done:
+        payload["metadata"] = {
+            "event": "swap_intent_ready",
+            "from_network": intent.from_network,
+            "from_token": intent.from_token,
+            "to_network": intent.to_network,
+            "to_token": intent.to_token,
+            "amount": intent.amount,
+        }
+    return payload
+
+
+# ---------- Validation utilities ----------
+def _validate_network(network: Optional[str]) -> Optional[str]:
+    if network is None:
+        return None
+    return SwapConfig.validate_network(network)
+
+
+def _validate_token(token: Optional[str], network: Optional[str]) -> Optional[str]:
+    if token is None:
+        return None
+    if network is None:
+        raise ValueError("Please provide the network before choosing a token.")
+    supported = list(SwapConfig.list_tokens(network))
+    if token not in supported:
+        raise ValueError(
+            f"Unsupported token '{token}' on {network}. Available: {supported}"
+        )
+    return SwapConfig.validate_or_raise(token, network)
+
+
+def _validate_route(from_network: str, to_network: str) -> None:
+    if hasattr(SwapConfig, "routes_supported"):
+        if not SwapConfig.routes_supported(from_network, to_network):
+            raise ValueError(
+                f"Route {from_network} -> {to_network} is not supported."
+            )
+
 
-    Args:
-        amount: The amount of tokens to swap
-        from_token: The token to swap from
-        to_token: The token to swap to
+# ---------- Core tool ----------
+@tool("update_swap_intent", args_schema=UpdateSwapIntentInput)
+def update_swap_intent_tool(
+    user_id: Optional[str] = None,
+    from_network: Optional[str] = None,
+    from_token: Optional[str] = None,
+    to_network: Optional[str] = None,
+    to_token: Optional[str] = None,
+    amount: Optional[float] = None,
+):
+    """Update the swap intent and surface the next question or final metadata.
 
-    Returns:
-        The amount of tokens received
+    Call this tool whenever the user provides new swap details. Supply only the
+    fields that were mentioned in the latest message (leave the others as None)
+    and keep calling it until the response event becomes 'swap_intent_ready'.
     """
+
+    intent_key = user_id or _DEFAULT_USER_ID
+    intent = _INTENTS.get(intent_key) or SwapIntent(user_id=intent_key)
+    if user_id:
+        intent.user_id = user_id
+    _INTENTS[intent_key] = intent
+
     try:
-        canonical_from = SwapConfig.validate_or_raise(from_token)
-        canonical_to = SwapConfig.validate_or_raise(to_token)
-    except ValueError as e:
-        return str(e)
+        if from_network is not None:
+            intent.from_network = _validate_network(from_network)
+
+        if intent.from_network is None and from_token is not None:
+            return _response(
+                intent,
+                "From which network?",
+                list(SwapConfig.list_networks()),
+            )
+
+        if from_token is not None:
+            intent.from_token = _validate_token(from_token, intent.from_network)
+
+        if to_network is not None:
+            intent.to_network = _validate_network(to_network)
+
+        if intent.to_network is None and to_token is not None:
+            return _response(
+                intent,
+                "To which network?",
+                list(SwapConfig.list_networks()),
+            )
+
+        if to_token is not None:
+            intent.to_token = _validate_token(to_token, intent.to_network)
+
+        if amount is not None:
+            intent.amount = amount
+
+        if intent.from_network and intent.to_network:
+            _validate_route(intent.from_network, intent.to_network)
+
+    except ValueError as exc:
+        message = str(exc)
+        lowered = message.lower()
+        if "network" in lowered:
+            return _response(
+                intent,
+                "Choose a network.",
+                list(SwapConfig.list_networks()),
+                error=message,
+            )
+        if "token" in lowered and intent.from_network:
+            return _response(
+                intent,
+                f"Choose a token on {intent.from_network}.",
+                list(SwapConfig.list_tokens(intent.from_network)),
+                error=message,
+            )
+        return _response(intent, "Please correct the input.", error=message)
+
+    if intent.from_network is None:
+        return _response(
+            intent,
+            "From which network?",
+            list(SwapConfig.list_networks()),
+        )
+    if intent.from_token is None:
+        return _response(
+            intent,
+            f"Which token on {intent.from_network}?",
+            list(SwapConfig.list_tokens(intent.from_network)),
+        )
+    if intent.to_network is None:
+        return _response(
+            intent,
+            "To which network?",
+            list(SwapConfig.list_networks()),
+        )
+    if intent.to_token is None:
+        return _response(
+            intent,
+            f"Which token on {intent.to_network}?",
+            list(SwapConfig.list_tokens(intent.to_network)),
+        )
+    if intent.amount is None:
+        denom = intent.from_token
+        return _response(intent, f"What is the amount in {denom}?")
 
-    print(f"Swapping {amount} {canonical_from} for {canonical_to}")
     meta = {
-        "from_token": canonical_from,
-        "to_token": canonical_to,
-        "amount": amount
+        "event": "swap_intent_ready",
+        "from_network": intent.from_network,
+        "from_token": intent.from_token,
+        "to_network": intent.to_network,
+        "to_token": intent.to_token,
+        "amount": intent.amount,
     }
     metadata.set_swap_agent(meta)
-    return f'Swapped {amount} {canonical_from} for {canonical_to}'
+    return _response(intent, ask=None, done=True)
 
-@tool
-def get_avaialble_tokens():
-    """
-    Get the available tokens for swapping
-    """
-    return SwapConfig.list_supported()
 
-@tool
-def default_response():
-    """
-    Normal response when the user asks for a swap
-    """
-    return f'What would you like to swap? The available agents are{SwapConfig.list_supported}'
+class ListTokensInput(BaseModel):
+    network: str
+
+    @field_validator("network", mode="before")
+    @classmethod
+    def _norm_network(cls, value: str) -> str:
+        return value.lower() if isinstance(value, str) else value
+
+
+@tool("list_tokens", args_schema=ListTokensInput)
+def list_tokens_tool(network: str):
+    """List the supported tokens for a given network."""
+
+    try:
+        canonical = _validate_network(network)
+        return {
+            "network": canonical,
+            "tokens": list(SwapConfig.list_tokens(canonical)),
+        }
+    except ValueError as exc:
+        return {
+            "error": str(exc),
+            "choices": list(SwapConfig.list_networks()),
+        }
+
+
+@tool("list_networks")
+def list_networks_tool():
+    """List supported networks."""
+
+    return {"networks": list(SwapConfig.list_networks())}
 
 
 def get_tools():
-    return [swap_avax, get_avaialble_tokens, default_response]
+    return [update_swap_intent_tool, list_tokens_tool, list_networks_tool]

src/app.py

@@ -17,6 +17,7 @@ from src.models.chatMessage import ChatMessage
 from src.routes.chat_manager_routes import router as chat_manager_router
 from src.service.chat_manager import chat_manager_instance
 from src.agents.crypto_data.tools import get_coingecko_id, get_tradingview_symbol
+from src.agents.metadata import metadata
 
 # Initialize FastAPI app
 app = FastAPI(title="Zico Agent API", version="1.0")
@@ -107,6 +108,7 @@ def _map_agent_type(agent_name: str) -> str:
         "crypto_agent": "crypto data",
         "default_agent": "default",
         "database_agent": "analysis",
+        "search_agent": "realtime search",
         "swap_agent": "token swap",
         "supervisor": "supervisor",
     }
@@ -115,9 +117,6 @@ def _map_agent_type(agent_name: str) -> str:
 @app.get("/health")
 def health_check():
     return {"status": "ok"}
-@app.get("/")
-def health_check_root():
-    return {"status": "ok"}
 
 @app.get("/chat/messages")
 def get_messages(request: Request):
@@ -161,10 +160,16 @@ def chat(request: ChatRequest):
 
             # Build response metadata and enrich with coin info for crypto price queries
             response_metadata = {"supervisor_result": result}
+            swap_meta_snapshot = None
             # Prefer supervisor-provided metadata
             if isinstance(result, dict) and result.get("metadata"):
                 response_metadata.update(result.get("metadata") or {})
-                print("response_metadata: ", response_metadata)
+            elif agent_name == "token swap":
+                swap_meta = metadata.get_swap_agent()
+                if swap_meta:
+                    response_metadata.update(swap_meta)
+                    swap_meta_snapshot = swap_meta
+            print("response_metadata: ", response_metadata)
             
             # Create a ChatMessage from the supervisor response
             response_message = ChatMessage(
@@ -185,12 +190,26 @@ def chat(request: ChatRequest):
                 conversation_id=request.conversation_id,
                 user_id=request.user_id
             )
-            
+
             # Return only the clean response
-            return {
+            response_payload = {
                 "response": result.get("response", "No response available"),
-                "agentName": agent_name
+                "agentName": agent_name,
             }
+            response_meta = result.get("metadata") or {}
+            if agent_name == "token swap" and not response_meta:
+                if swap_meta_snapshot:
+                    response_meta = swap_meta_snapshot
+                else:
+                    swap_meta = metadata.get_swap_agent()
+                    if swap_meta:
+                        response_meta = swap_meta
+                    metadata.set_swap_agent({})
+            if response_meta:
+                response_payload["metadata"] = response_meta
+            if agent_name == "token swap":
+                metadata.set_swap_agent({})
+            return response_payload
         
         return {"response": "No response available", "agent": "supervisor"}
     except Exception as e: