Aviation Agent Architecture Review

Review code changes in shared/aviation_agent/ and web/server/api/aviation_agent_chat.py for compliance with the LangGraph agent architecture.

Agent Flow

Planner -> [Predict Next Queries] -> Tool -> Formatter -> END

The planner selects the appropriate tool based on user query. No routing layer.

Available Tools (from shared/airport_tools.py)

Airport Tools:

• •search_airports - Text/name/code search, country queries
• •find_airports_near_location - Proximity search near a place
• •find_airports_near_route - Airports along a route
• •get_airport_details - Details for a specific ICAO code
• •get_notification_for_airport - Notification requirements

Rules Tools:

• •answer_rules_question - RAG-based semantic search (single country)
• •browse_rules - Tag-based listing with pagination
• •compare_rules_between_countries - Semantic comparison (2+ countries)

Architecture Rules

1. •

   UI Payload Stability - Flattened approach:

   • •Stable top-level keys (kind, tool, departure, icao, etc.)
   • •tool field for frontend context (e.g., legend mode switching)
   • •Flattened common fields (filters, visualization, airports)
   • •suggested_queries for follow-up suggestions
   • •show_rules for rules tools
2. •

   Tool Name Consistency:

   • •Tool names must match shared/airport_tools.get_shared_tool_specs()
   • •Planner uses literal tool names from manifest
3. •

   State Management:

   • •Use AgentState TypedDict, no direct mutations
   • •Errors stored in state, not raised as exceptions
   • •Use LangGraph reducers (operator.add for messages)
4. •

   UI Payload Building:

   • •Only build_ui_payload() creates ui_payload
   • •Centralized in formatting.py
   • •Tool-to-kind mapping must be correct
5. •

   Visualization Types (from tool results):

   • •route_with_markers - Route with airport markers
   • •markers - General airport markers
   • •point_with_markers - Location point with airports
   • •marker_with_details - Single airport focus
6. •

   Filter Extraction:

   • •Filters in plan.arguments.filters
   • •Extracted by planner, not formatter
   • •Tools return filter_profile
7. •

   Error Handling:

   • •Store errors in state["error"]
   • •Formatter handles errors gracefully
   • •Errors emitted as SSE events
8. •

   Separation of Concerns:

   • •planning.py - Planner logic only
   • •execution.py - Tool execution only
   • •formatting.py - Formatting and UI payload
   • •graph.py - LangGraph nodes only
9. •

   Configuration Management:

   • •LLM settings from behavior_config.llms.*
   • •Feature flags from behavior_config.*.enabled
   • •Prompts via behavior_config.load_prompt(key)
   • •No hardcoded config values
10. •

    Tools Return DATA, Formatters Do SYNTHESIS:

    • •Tools NEVER call LLMs or do synthesis
    • •Tools return _tool_type marker for formatter routing
    • •Formatter selects prompt based on _tool_type
    • •Example: _tool_type: "comparison" → use comparison_synthesis_v1.md
11. •

    Streaming Requirements:

    • •Use astream_events(version="v2") for streaming
    • •SSE events: plan, thinking, tool_call_start, tool_call_end, message, ui_payload, done, error
    • •Track token usage across all LLM calls
12. •

    Structured Output:

    • •Prefer with_structured_output(method="function_calling") for OpenAI
    • •Validate planner output against tool manifest
    • •Fallback to PydanticOutputParser for non-OpenAI models

Review Checklist

UI Payload Structure

• •ui_payload has kind field?
• •ui_payload has tool field for frontend context?
• •Common fields flattened at top level?
• •build_ui_payload() is the only place creating ui_payload?

Tool Name Consistency

• •Tool names match shared/airport_tools.py?
• •No hardcoded tool names that don't exist?

State Management

• •Uses AgentState TypedDict?
• •Errors stored in state, not raised?
• •Messages use operator.add reducer?

Configuration

• •No hardcoded LLM models/temperatures?
• •Prompts loaded from config?

Formatter Strategy

• •Comparison tool returns _tool_type: "comparison"?
• •Formatter checks _tool_type and uses correct prompt?
• •No LLM synthesis happening in tools?

Streaming

• •Uses astream_events(version="v2")?
• •Token usage tracked across all LLM calls?

Red Flags

• •Breaking UI payload structure: Changing stable top-level fields
• •Missing tool field: UI payload without tool field
• •Invented tool names: Using names not in shared/airport_tools.py
• •Direct state mutations: state["key"] = value instead of returning dict
• •UI payload outside build_ui_payload(): Creating manually
• •Raised exceptions: raise Exception() instead of return {"error": "..."}
• •Hardcoded config: LLM models, temperatures in code
• •LLM synthesis in tools: Tools calling LLM directly (should return data only)
• •Missing _tool_type marker: Comparison tool not setting _tool_type: "comparison"
• •Wrong streaming API: Using deprecated astream() instead of astream_events(version="v2")

Output Format

APPROVED:

• •file:line - Explanation of why it's correct

VIOLATION:

• •file:line - Description
• •Problem: Why it violates architecture
• •Fix: Suggested corrected implementation
• •Impact: What breaks

Key Files

Core Agent

• •shared/aviation_agent/state.py - AgentState TypedDict
• •shared/aviation_agent/planning.py - Planner and AviationPlan
• •shared/aviation_agent/execution.py - Tool execution
• •shared/aviation_agent/formatting.py - Formatter and UI payload
• •shared/aviation_agent/graph.py - LangGraph assembly

RAG & Comparison

• •shared/aviation_agent/rules_rag.py - RAG system for rules retrieval
• •shared/aviation_agent/answer_comparer.py - Embedding-based comparison
• •shared/aviation_agent/comparison_service.py - High-level comparison API

Adapters

• •shared/aviation_agent/adapters/streaming.py - SSE streaming adapter
• •shared/aviation_agent/next_query_predictor.py - Follow-up suggestions

External

• •shared/airport_tools.py - Tool manifest
• •configs/aviation_agent/default.json - Config schema
• •web/server/api/aviation_agent_chat.py - FastAPI endpoint

Design Documents

• •designs/LLM_AGENT_DESIGN.md - Full architecture reference
• •designs/CHATBOT_WEBUI_DESIGN.md - WebUI integration
• •designs/UI_FILTER_STATE_DESIGN.md - Filter and visualization mapping