Misc. cleanup - use a .widget file for metro map; handle selection; add tool call descriptions (#34)

* Add metro-map node select state

* use .widget file for line select widget

* Add tool call param descriptions

Author: jiwon-oai

examples/cat-lounge/backend/app/cat_agent.py

@@ -115,7 +115,11 @@ async def _add_hidden_context(ctx: RunContextWrapper[CatAgentContext], content:
     )
 
 
-@function_tool(description_override="Read the cat's current stats before deciding what to do next.")
+@function_tool(
+    description_override=(
+        "Read the cat's current stats before deciding what to do next. No parameters."
+    )
+)
 async def get_cat_status(
     ctx: RunContextWrapper[CatAgentContext],
 ) -> dict[str, Any]:
@@ -125,7 +129,12 @@ async def get_cat_status(
     return state.to_payload(ctx.context.thread.id)
 
 
-@function_tool(description_override="Feed the cat to replenish energy and keep moods stable.")
+@function_tool(
+    description_override=(
+        "Feed the cat to replenish energy and keep moods stable.\n"
+        "- `meal`: Meal or snack description to include in the update."
+    )
+)
 async def feed_cat(
     ctx: RunContextWrapper[CatAgentContext],
     meal: str | None = None,
@@ -138,7 +147,12 @@ async def feed_cat(
     # No need to return payload for a client tool call; agent must be configured to stop after this tool call.
 
 
-@function_tool(description_override="Play with the cat to boost happiness and create fun moments.")
+@function_tool(
+    description_override=(
+        "Play with the cat to boost happiness and create fun moments.\n"
+        "- `activity`: Toy or activity used during playtime."
+    )
+)
 async def play_with_cat(
     ctx: RunContextWrapper[CatAgentContext],
     activity: str | None = None,
@@ -151,7 +165,12 @@ async def play_with_cat(
     # No need to return payload for a client tool call; agent must be configured to stop after this tool call.
 
 
-@function_tool(description_override="Clean the cat to tidy up and improve cleanliness.")
+@function_tool(
+    description_override=(
+        "Clean the cat to tidy up and improve cleanliness.\n"
+        "- `method`: Cleaning method or item used."
+    )
+)
 async def clean_cat(
     ctx: RunContextWrapper[CatAgentContext],
     method: str | None = None,
@@ -165,7 +184,10 @@ async def clean_cat(
 
 
 @function_tool(
-    description_override="Give the cat a permanent name and update the thread title to match."
+    description_override=(
+        "Give the cat a permanent name and update the thread title to match.\n"
+        "- `name`: Desired name for the cat."
+    )
 )
 async def set_cat_name(
     ctx: RunContextWrapper[CatAgentContext],
@@ -206,7 +228,13 @@ async def set_cat_name(
     # No need to return payload for a client tool call; agent must be configured to stop after this tool call.
 
 
-@function_tool(description_override="Show the cat's profile card with avatar and age.")
+@function_tool(
+    description_override=(
+        "Show the cat's profile card with avatar and age.\n"
+        "- `age`: Cat age (in years) to display and persist.\n"
+        "- `favorite_toy`: Favorite toy label to include."
+    )
+)
 async def show_cat_profile(
     ctx: RunContextWrapper[CatAgentContext],
     age: int | None = None,
@@ -250,13 +278,17 @@ def mutate(state: CatState) -> None:
         )
 
 
-@function_tool(description_override="Speak as the cat so a bubble appears in the dashboard.")
+@function_tool(
+    description_override=(
+        "Speak as the cat so a bubble appears in the dashboard.\n"
+        "- `line`: The text the cat should say."
+    )
+)
 async def speak_as_cat(
     ctx: RunContextWrapper[CatAgentContext],
     line: str,
-    mood: str | None = None,
 ):
-    print(f"[TOOL CALL] speak_as_cat({line}, {str(mood)})")
+    print(f"[TOOL CALL] speak_as_cat({line})")
     message = line.strip()
     if not message:
         raise ValueError("A line is required for the cat to speak.")
@@ -266,14 +298,14 @@ async def speak_as_cat(
         arguments={
             "state": state.to_payload(ctx.context.thread.id),
             "message": message,
-            "mood": mood or "playful",
         },
     )
 
 
 @function_tool(
     description_override=(
-        "Render up to three creative cat name options provided in the `suggestions` argument."
+        "Render up to three creative cat name options provided in the `suggestions` argument.\n"
+        "- `suggestions`: List of name suggestions with a `name` and `reason` for each."
     )
 )
 async def suggest_cat_names(

examples/metro-map/backend/app/agents/metro_map_agent.py

@@ -96,7 +96,12 @@ class StationDetailResult(BaseModel):
     lines: list[Line]
 
 
-@function_tool(description_override="Show a clickable widget listing metro lines.")
+@function_tool(
+    description_override=(
+        "Show a clickable widget listing metro lines.\n"
+        "- `message`: Text shown above the widget to prompt the user."
+    )
+)
 async def show_line_selector(ctx: RunContextWrapper[MetroAgentContext], message: str):
     widget = build_line_select_widget(ctx.context.metro.list_lines())
     await ctx.context.stream(
@@ -112,27 +117,39 @@ async def show_line_selector(ctx: RunContextWrapper[MetroAgentContext], message:
     await ctx.context.stream_widget(widget)
 
 
-@function_tool(description_override="Load the latest metro map with lines and stations.")
+@function_tool(
+    description_override=("Load the latest metro map with lines and stations. No parameters.")
+)
 async def get_map(ctx: RunContextWrapper[MetroAgentContext]) -> MapResult:
     print("[TOOL CALL] get_map")
     metro_map = ctx.context.metro.get_map()
     await ctx.context.stream(ProgressUpdateEvent(text="Retrieving the latest metro map..."))
     return MapResult(map=metro_map)
 
 
-@function_tool(description_override="List all metro lines with their colors and endpoints.")
+@function_tool(
+    description_override=("List all metro lines with their colors and endpoints. No parameters.")
+)
 async def list_lines(ctx: RunContextWrapper[MetroAgentContext]) -> LineListResult:
     print("[TOOL CALL] list_lines")
     return LineListResult(lines=ctx.context.metro.list_lines())
 
 
-@function_tool(description_override="List all stations and which lines serve them.")
+@function_tool(
+    description_override=("List all stations and which lines serve them. No parameters.")
+)
 async def list_stations(ctx: RunContextWrapper[MetroAgentContext]) -> StationListResult:
     print("[TOOL CALL] list_stations")
     return StationListResult(stations=ctx.context.metro.list_stations())
 
 
-@function_tool(description_override="Show the user the planned route.")
+@function_tool(
+    description_override=(
+        "Show the user the planned route.\n"
+        "- `route`: Ordered list of stations in the journey.\n"
+        "- `message`: One-sentence description of the itinerary."
+    )
+)
 async def plan_route(
     ctx: RunContextWrapper[MetroAgentContext],
     route: list[Station],
@@ -167,7 +184,12 @@ async def plan_route(
     )
 
 
-@function_tool(description_override="Look up a single station and the lines serving it.")
+@function_tool(
+    description_override=(
+        "Look up a single station and the lines serving it.\n"
+        "- `station_id`: Station identifier to retrieve."
+    )
+)
 async def get_station(
     ctx: RunContextWrapper[MetroAgentContext],
     station_id: str,
@@ -251,6 +273,7 @@ async def add_station(
     tool_use_behavior=StopAtTools(
         stop_at_tool_names=[
             add_station.name,
+            plan_route.name,
             show_line_selector.name,
         ]
     ),

examples/metro-map/backend/app/data/metro_map_store.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
 import json
-from dataclasses import dataclass
 import re
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal
 

examples/metro-map/backend/app/server.py

@@ -35,11 +35,7 @@
 from .memory_store import MemoryStore
 from .request_context import RequestContext
 from .thread_item_converter import MetroMapThreadItemConverter
-from .widgets.line_select_widget import (
-    LINE_SELECT_ACTION_TYPE,
-    LineSelectPayload,
-    build_line_select_widget,
-)
+from .widgets.line_select_widget import build_line_select_widget
 
 
 class MetroMapServer(ChatKitServer[RequestContext]):
@@ -108,11 +104,12 @@ async def action(
         sender: WidgetItem | None,
         context: RequestContext,
     ) -> AsyncIterator[ThreadStreamEvent]:
-        if action.type == LINE_SELECT_ACTION_TYPE:
-            payload = self._parse_line_select_payload(action)
-            if payload is None:
+        if action.type == "line.select":
+            if action.payload is None:
                 return
-            async for event in self._handle_line_select_action(thread, payload, sender, context):
+            async for event in self._handle_line_select_action(
+                thread, action.payload, sender, context
+            ):
                 yield event
             return
 
@@ -122,24 +119,19 @@ async def to_message_content(self, _input: Attachment) -> ResponseInputContentPa
         raise RuntimeError("File attachments are not supported in this demo.")
 
     # -- Helpers ----------------------------------------------------
-    def _parse_line_select_payload(self, action: Action[str, Any]) -> LineSelectPayload | None:
-        try:
-            return LineSelectPayload.model_validate(action.payload or {})
-        except ValidationError as exc:
-            print(f"[WARN] Invalid line.select payload: {exc}")
-            return None
-
     async def _handle_line_select_action(
         self,
         thread: ThreadMetadata,
-        payload: LineSelectPayload,
+        payload: dict[str, Any],
         sender: WidgetItem | None,
         context: RequestContext,
     ) -> AsyncIterator[ThreadStreamEvent]:
+        line_id = payload["id"]
+
         # Update the widget to show the selected line and disable further clicks.
         updated_widget = build_line_select_widget(
             self.metro_map_store.list_lines(),
-            selected=payload.id,
+            selected=line_id,
         )
 
         if sender:
@@ -155,7 +147,7 @@ async def _handle_line_select_action(
                 id=self.store.generate_item_id("message", thread, context),
                 thread_id=thread.id,
                 created_at=datetime.now(),
-                content=f"<LINE_SELECTED>{payload.id}</LINE_SELECTED>",
+                content=f"<LINE_SELECTED>{line_id}</LINE_SELECTED>",
             ),
             context=context,
         )
@@ -178,7 +170,7 @@ async def _handle_line_select_action(
                 id=self.store.generate_item_id("tool_call", thread, context),
                 thread_id=thread.id,
                 name="location_select_mode",
-                arguments={"lineId": payload.id},
+                arguments={"lineId": line_id},
                 created_at=datetime.now(),
                 call_id=self.store.generate_item_id("tool_call", thread, context),
             ),