hypREspace: Rearchitecting NL-to-SQL into an Agentic Analytics Engine

At a Glance

The Product

hypREspace is an AI-driven transaction management platform for corporate real estate, built by real estate transaction professionals. In April 2025, Cushman & Wakefield, one of the largest commercial real estate services firms in the world, selected hypREspace as its transaction management technology provider. Part of what makes the platform stand out is its AI chat interface: transaction professionals ask questions about their portfolio in plain English and get answers and charts back, drawn from four core tables covering Projects, Properties, Leases, and Lease Options.

That chat feature was the problem. Under the hood it ran on a chain of hard-coded prompts, and as usage grew, the chain kept breaking in ways nobody could see into. I was brought in to rearchitect it.

The engagement centered on four objectives:

• Replace the multi-hop prompt chain with a single agent that reasons through queries end to end.
• Make every step of query handling observable, so failures are diagnosable instead of silent.
• Reuse the existing FastAPI backend rather than rebuilding data access from scratch.
• Handle the hard cases the old system dropped: complex multi-table questions, currency and unit conversion, and chart generation.

The Challenge

The core tension of this project was flexibility versus control. A pipeline of fixed prompts is predictable until the question does not fit the pipeline, and then it fails without explanation.

1. A five-hop chain with no visibility. The old system ran a fixed sequence: analyze the user query, map it to the right table, select the appropriate fields, generate the SQL, then post-process results for the user's preferred currency and measurement units. Chart questions added a separate Python code generator on top. When a complex query failed, and they often did, sometimes with no response at all, there was no way to know which hop broke.

2. Hard-coded knowledge of four tables. Table mapping and field selection were baked into prompts. Every schema change meant prompt surgery, and any question spanning Projects, Properties, Leases, and Lease Options at once pushed the chain past what its fixed steps could express.

3. Enterprise data cannot be handed to an LLM raw. hypREspace serves enterprise clients. The agent could not be given open database access. It needed a controlled, auditable surface where the backend team decides exactly what the agent can touch.

4. Post-processing complexity. Multi-currency conversion to each user's preferred currency and multiple measurement units were bolted on after SQL generation, which meant the reasoning step and the formatting step could silently disagree.

My Approach

I treated this as an agent architecture problem, not a prompt improvement problem. The fixed chain was replaced by a LangGraph ReAct agent that decides its own path through each query.

A custom MCP layer over the existing backend. Instead of giving the agent SQL access, I built a custom MCP server with FastMCP directly on top of hypREspace's existing FastAPI backend. Because the backend is FastAPI, every endpoint already carries typed input and output schemas and descriptions, and the MCP layer passes those to the agent as tool definitions automatically. Exposure is config-driven: only endpoints explicitly whitelisted in configuration become tools. The backend team controls the agent's entire surface area from a config file.

A ReAct agent instead of a fixed chain. The LangGraph ReAct agent, running Claude on AWS Bedrock, reasons about each question and picks the tools it needs, in the order it needs them. Table mapping, field selection, query construction, currency conversion, and chart generation stopped being separate hard-coded stages and became decisions the agent makes per query. A question the old chain could not route now simply takes a different path through the same tools.

Observability as a first-class outcome. Every reasoning step and every tool call is a discrete, logged event. When something goes wrong, the trace shows exactly which step failed and why. The days of "the chat did not respond and we do not know why" ended with the chain.

The agent as its own service. The agent runs as a separate FastAPI service alongside the main backend, so it scales and deploys independently and the existing product surface stays untouched.

Engineering Highlights

• Config-driven tool exposure. A custom FastMCP layer where whitelisted FastAPI endpoints become agent tools, schemas and descriptions included, with zero manual tool definitions to maintain.
• LangGraph ReAct orchestration. One agent replaces five hard-coded stages, choosing its own tool sequence per query.
• Claude on AWS Bedrock. Enterprise-grade inference inside the client's AWS environment, keeping data within their cloud boundary.
• Schema changes without prompt surgery. When the backend adds or changes an endpoint, the tool definition updates with it. No prompts to rewrite.
• Currency and units inside the loop. Conversion to the user's preferred currency and measurement units happens through tools the agent calls as part of its reasoning, not as a bolt-on afterthought.
• Chart generation unified. Visualization requests flow through the same agent instead of a separate code-generation pipeline.
• Full trace logging. Every query leaves a step-by-step record of reasoning and tool calls for debugging and audit.
• Independent agent service. A dedicated FastAPI service for the agent, deployable and scalable apart from the core backend.

The Impact

• Complex queries stopped failing silently. Questions spanning multiple tables, currencies, and units, the exact cases that broke the old chain, are now handled by the agent's own reasoning.
• Failures became diagnosable. When something does go wrong, the trace points to the exact step, replacing opaque debugging mysteries with trace-guided investigation.
• The backend team kept control. The config-driven MCP layer means the agent's capabilities grow by editing a whitelist, not by writing integration code.
• A foundation, not a patch. New tables, new endpoints, and new capabilities plug into the same agent, so the analytics feature scales with the product instead of against it.

Tech Stack and Deliverables

• Platform: LangGraph, LangChain, FastAPI, AWS Bedrock (Claude)
• Agent layer: Custom MCP server built with FastMCP over the existing FastAPI backend, config-driven endpoint exposure
• Deliverables: Agent architecture design, custom MCP layer, LangGraph ReAct agent service, currency and unit handling inside the agent loop, unified chart generation, trace logging and observability, deployment as an independent FastAPI service