KU Parking Assistant: A Simple Tool-Using Agent

Every agent notebook you have seen so far in this course relies on the LLM to do all the heavy lifting -- reasoning, planning, and generating answers from its own knowledge. But there are tasks where pure LLM reasoning is the wrong tool for the job. Calculating the distance between two GPS coordinates, for example, requires precise trigonometry. An LLM might approximate the answer, but it will sometimes get it wrong in ways that matter (ranking a lot as “closest” when it is actually third-closest). A Python function using the Haversine formula will get it right every time, in microseconds, with no hallucination risk.

This notebook builds a small agent that combines the best of both worlds. The LLM handles what it is good at -- understanding natural language (“Where can I park near the business school?”), fuzzy matching building names, and formatting a helpful response. Python functions handle what they are good at -- looking up coordinates in a dictionary, computing great-circle distances, sorting results, and constructing Google Maps URLs. The LLM decides when to call which tool, but it never does the math itself.

What makes this different from the other agent notebooks:

• We use real deterministic tools (distance math, data lookups) instead of a pure text-in/text-out workflow

• The LLM decides when to call which tool, but it does not do the math itself -- it delegates to Python

• This is a pure workflow, not a chatbot: one input produces one structured output

Teaching goal: Show the difference between fuzzy LLM reasoning (good for language understanding: “business school” maps to “Capitol Federal Hall”) and precise tool execution (good for deterministic tasks: distance math, sorting, data lookup). A well-designed agent lets each side do what it is best at.

Note on data: The real KU parking map is at https://parking.ku.edu/sites/parking/files/documents/parkingmap.pdf. For this demo we use a small illustrative dataset with approximate coordinates so the notebook runs standalone.

This notebook picks up where the agents in Chapters 16 and 17 left off — the single-agent, multi-agent, and autonomous notebooks all reasoned over text alone, while here the LLM delegates the precise work to real Python tools it chooses to call.

Imports and LLM Setup¶

We use llm_cascade for automatic LLM provider fallback, and Python’s built-in math module for the distance calculations. No external APIs needed.

Data: KU Buildings and Parking Lots¶

We hardcode two small datasets that represent the physical world the agent needs to reason about. In a real deployment, these would come from a database, a GIS system, or a parsed PDF. For this classroom demo, approximate coordinates are sufficient to demonstrate the architecture.

KU Buildings are the destinations students might ask about. The dictionary maps human-readable names (with common aliases in parentheses) to latitude/longitude tuples. This naming convention is deliberate: when a student asks about “the business school,” our fuzzy matcher will find “Capitol Federal Hall (Business School)” because the alias appears in the dictionary key.

KU Parking Lots include a color code indicating who can park there. Understanding these colors is essential context for the agent’s final answer -- it is not helpful to recommend a Yellow (faculty-only) lot to a student with a Blue permit. The colors are:

• Blue -- student commuter permit

• Yellow -- faculty / staff permit

• Gold -- premium permit (close to central campus)

• Red -- restricted / reserved

• Visitor -- open to visitors, usually metered or short-term

• Park & Ride -- free remote lot with shuttle service

The Tools (plain Python functions)¶

Three simple tools the agent can call. Notice there is no LLM inside these functions -- they are pure deterministic Python. The LLM will decide when to call them based on the user’s question, but every computation inside them produces an exact, repeatable result.

The distance calculation uses the Haversine formula, which computes the great-circle distance between two latitude/longitude points on a sphere. For the short distances on a university campus (typically under 1 mile), the Haversine result is accurate to within a few feet -- far better than asking an LLM to eyeball coordinate differences. The 2-mile radius filter is a practical constraint that keeps the results useful: a parking lot 5 miles away is technically “near” the campus, but no student would walk there.

Approximate building matching¶

Real users rarely type the full canonical building name. They write “Ambler gym”, “student gym”, “the phog”, “basketball stadium”, or “school of business”. Our _match_building helper handles this by combining three strategies:

1. Alias table. Each canonical building name has a list of common nicknames and school/department associations (e.g., Allen Fieldhouse gets phog, phog stadium, basketball arena, ku basketball; Ambler SRFC gets ambler gym, student gym, fitness center, gym).

2. Substring matching in both directions, against the canonical name and every alias.

3. Token-overlap scoring (F1 over tokens, with a small stopword list) for phrases that don’t substring-match but share enough words with the building or an alias.

The matcher tries exact → substring → token-overlap in that order and requires a token overlap of at least 0.5 before it commits to an approximate match. That threshold prevents random words from latching onto a building. The alias table lives right next to the coordinates, so adding a new nickname is a one-line edit. The Google Maps URLs are constructed by embedding the latitude and longitude into a standard maps?q=LAT,LNG template, which produces a clickable pin link that works on any device.

Test the Tools (no LLM yet)¶

Before wiring up the agent, let’s call the tools directly to make sure they work. This is a critical debugging practice: if the raw tool output is wrong, no amount of prompt engineering on the agent side will fix it. By testing the tools in isolation, we can verify that the fuzzy matcher resolves “business school” correctly, that the distance calculations are sensible, and that the Google Maps URLs point to the right locations. Only after we trust the tools should we hand them to an LLM.

The Agent (LLM that calls the tools)¶

We use a prompt-based ReAct loop -- no bind_tools, no special API features, works with any LLM. The system prompt describes the three available tools and tells the LLM to output a JSON action like {"tool": "find_parking_near_building", "input": "business school"} when it wants to call one. Our loop parses the JSON, executes the tool, feeds the result back into the conversation, and repeats until the LLM produces a natural-language final answer instead of a tool call.

This is a deliberately simple architecture. Framework-based agents (LangChain, CrewAI) add convenience methods and error handling, but the core pattern is exactly what you see here: prompt the LLM, check if it wants to call a tool, execute the tool if so, feed the result back, repeat. Understanding this loop demystifies what frameworks do under the hood and gives you the confidence to debug agent behavior when something goes wrong.

Ask the Agent Some Questions¶

Now we let the agent run end-to-end. For each question, the agent should: (1) figure out which tool to call based on the user’s natural language, (2) call find_parking_near_building with the user’s phrase (the fuzzy matcher handles informal names), and (3) format a helpful response with the ranked list, permit colors, and clickable Google Maps links. Try uncommenting the other questions to see how the agent handles visitor-specific queries, requests for the color legend, and different building names.

How to Build the Same Thing in Dify (multi-node workflow with real tools)¶

A proper Dify workflow uses alternating tool and LLM nodes, matching the architecture you see in typical agentic workflow diagrams. Each tool node fetches data, each LLM node reasons about what to do next with that data.

The workflow architecture¶

Start (user types a KU building name)
  |
  v
[TOOL #1] Knowledge Retrieval - KU_Buildings KB
  | (acts as the "access Google Maps" step: returns the building's lat/lng)
  v
[LLM #1] Parse the building coordinates
  | (extracts a clean {lat, lng} from the retrieved text)
  v
[TOOL #2] Knowledge Retrieval - KU_Parking_Lots KB
  | (acts as the "access KU map" step: returns all parking lot data)
  v
[LLM #2] Compute distances, filter to 2 miles, rank top 5, format output
  | (does the math approximately using the coordinates)
  v
End (returns formatted parking list with Google Maps pin URLs)

Five processing nodes: 2 Knowledge Retrieval (tool) nodes + 2 LLM nodes + Start/End. No Code nodes, no custom APIs, no Python.

Why Knowledge Retrieval instead of HTTP Request?¶

In Dify’s workflow builder, a “tool” is any node that fetches external data. Knowledge Retrieval nodes are the easiest kind of tool because:

• You upload the data once (buildings + parking lots as markdown files)

• Dify chunks, embeds, and indexes it automatically

• Retrieval is just a vector search — fast and free

• No API keys, no rate limits, no billing

An alternative would be an HTTP Request node calling Nominatim (OpenStreetMap’s free geocoding API), but Nominatim is rate-limited and doesn’t know anything about specific KU building nicknames like “business school” or “the phog”. Our pre-uploaded Knowledge Base is more reliable for a classroom demo.

Approximate building matching in Dify¶

The Colab agent above uses an explicit alias table plus token-overlap scoring. Dify’s Knowledge Retrieval node does not have that — instead, approximate matching comes from vector embeddings: the user’s phrase is embedded and compared against embedded chunks from ku_buildings.md. For informal queries like “Ambler gym” or “the phog” to surface the correct chunk, the aliases must appear in the markdown itself.

That is why Agentic/dify_data/ku_buildings.md embeds each building’s common aliases directly in its Description: line (nicknames, school/department affiliations, department functions). For example, the Allen Fieldhouse entry mentions “basketball stadium”, “the Phog”, and “Phog Allen” explicitly so a vector search against “phog stadium” still retrieves that chunk. If you add a new nickname that users type, edit the markdown, re-upload (or sync) the Knowledge Base, and re-run the workflow.

If you ever find vector retrieval missing a phrase that the Colab agent handles correctly, either:

• Add that phrase to the building’s Description line in ku_buildings.md, or

• Switch the Dify workflow to call the Supabase MCP endpoint from the sibling ku_parking_mcp.ipynb notebook — that endpoint uses the same explicit alias table as the Colab code cell above.

Step-by-step setup¶

Part A: upload the two data files as Knowledge Bases¶

The notebook directory includes two markdown files at Agentic/dify_data/:

• ku_buildings.md - one section per building with coordinates and alias-rich descriptions

• ku_parking_lots.md - one section per parking lot with color and coordinates

In Dify:

1. Go to cloud.dify.ai -> Knowledge -> Create Knowledge

2. Upload ku_buildings.md. Name the KB KU_Buildings.

3. On the chunking screen, pick Custom chunking:

   • Chunk delimiter: \n# (hash + space — this splits on every heading)

   • Max chunk length: 500 tokens

   • This ensures each building becomes its own retrievable chunk, and the alias-rich description stays within that chunk.

4. Indexing: High Quality (vector embeddings).

5. Click Save & Process. Wait ~30 seconds.

6. Repeat: create a second Knowledge Base called KU_Parking_Lots and upload ku_parking_lots.md with the same chunking settings.

Part B: build the workflow¶

1. Studio -> Create App -> Workflow (not Chatflow).

2. Name it KU Parking Assistant.

3. On the canvas, click the Start node:

   • Add input variable: name = destination, type = Text, label = “Which KU building are you visiting? (informal names like ‘the phog’, ‘Ambler gym’, ‘business school’ all work)”

4. Add TOOL #1: Knowledge Retrieval (Buildings)

   • Click + after Start -> Knowledge Retrieval

   • Query variable: Start.destination

   • Knowledge: select KU_Buildings

   • Rename this node to Retrieve Building

5. Add LLM #1: Parse Building Coordinates

   • Click + after Retrieve Building -> LLM

   • Model: your preferred (gpt-4o-mini, gemini-2.5-flash, etc.)

   • System prompt:

     You are a data extractor. You will receive:
     1. A user query that may use a nickname or informal name
        (e.g., "the phog", "Ambler gym", "student union", "business school").
     2. One or more retrieved KU building chunks, each containing a canonical
        building name, its coordinates, and a description that lists common
        aliases and school/department associations.
     
     Pick the single chunk whose canonical name or description best matches
     the user's query, and extract its canonical name and coordinates. If the
     query uses a nickname, use the alias list in the description to choose
     the correct building (e.g., "the phog" -> Allen Fieldhouse;
     "Ambler gym" or "student gym" -> Ambler Student Recreation Fitness Center;
     "school of business" -> Capitol Federal Hall).
     
     Reply with ONLY this JSON format (nothing else):
     {"building": "full canonical name", "lat": 38.9573, "lng": -95.2519}

   • User prompt:

     Retrieved building information:
     {{#Retrieve_Building.result#}}
     
     User query: {{#Start.destination#}}

   • Rename this node to Parse Coords

6. Add TOOL #2: Knowledge Retrieval (Parking Lots)

   • Click + after Parse Coords -> Knowledge Retrieval

   • Query variable: Start.destination (or a fixed query like “parking lots”)

   • Knowledge: select KU_Parking_Lots

   • In the node settings, set Top K to 15 (to retrieve all lots, since our KB is small)

   • Rename this node to Retrieve Parking

7. Add LLM #2: Distance + Filter + Format

   • Click + after Retrieve Parking -> LLM

   • System prompt:

     You are a parking assistant. You will receive:
     1. A destination building with its latitude and longitude (as JSON).
     2. A list of KU parking lots with their coordinates and colors.
     
     Your job:
     - Compute the approximate great-circle distance in miles from the destination
       to each parking lot. For Lawrence KS, 0.001 degrees of latitude is about
       0.069 miles and 0.001 of longitude is about 0.054 miles.
     - Filter to lots within 2 miles of the destination.
     - Rank the remaining lots from nearest to farthest.
     - Return the top 5 as a numbered list with these fields for each:
       * Rank, lot name, permit color
       * Distance in miles (2 decimals) and approximate walk time (3 mph walking speed)
       * Google Maps pin URL in this exact format: https://www.google.com/maps?q=LAT,LNG
     - End with a short note explaining what the permit color of the closest lot means.
     - If no lots are within 2 miles, say so and suggest the Park & Ride shuttle.

   • User prompt:

     Destination: {{#Parse_Coords.text#}}
     
     Available parking lots:
     {{#Retrieve_Parking.result#}}
     
     Give me the top 5 parking lots within 2 miles.

   • Rename this node to Rank and Format

8. Configure the End node

   • Output variable: Rank_and_Format.text

9. Publish and click Run to test the approximate matcher end-to-end:

   • business school / school of business -> Capitol Federal Hall

   • the phog / basketball stadium / phog stadium -> Allen Fieldhouse

   • Ambler gym / student gym / fitness center -> Ambler SRFC

   • the union / student union -> Kansas Union

   • football stadium / ku football -> Memorial Stadium

What each node does and why¶

Notice the alternation: Tool -> LLM -> Tool -> LLM. Each tool fetches fresh data, each LLM reasons about what to do with it. This is the standard pattern in Dify workflows and maps directly to the architecture diagram you described.

Colab (real tools) vs. Dify (workflow tools) - the teaching contrast¶

When to pick each approach¶

• Colab agent (this notebook): when the agent needs to decide dynamically whether to call list_buildings, find_parking_near_building, or get_parking_colors_legend based on the question. Good for conversational or exploratory use cases.

• Dify workflow (above): when every query follows the same steps (lookup destination -> lookup parking -> rank). Good for a production app where you want consistent, debuggable behavior without per-query reasoning overhead.

Limitations of the Dify version¶

• The LLM’s distance math is approximate. For 15 lots in a small area it usually gets the top 3 right, but lots at very similar distances may be mis-ranked by 1-2 positions.

• Approximate building matching depends on the aliases being present in the markdown. A nickname that isn’t written into ku_buildings.md will only match if it’s semantically close enough for the embedding model to score highly — and that is less reliable than the explicit alias table in the Colab agent.

• If your Knowledge Base grows beyond a few hundred entries, the vector retrieval step may miss relevant items. At that scale you’d switch to HTTP Request calls to a real database, or to the MCP endpoint in ku_parking_mcp.ipynb.

• The 2-mile filter is enforced in the LLM prompt, not in code. A rogue LLM response could include a lot outside 2 miles. In production you’d add a Template Transform or Parameter Extractor node to enforce the filter programmatically.

Exercises¶

• Add a new building (e.g., 'Budig Hall': (lat, lng)) and a new parking lot, then rerun — notice you don’t need to change any tool code.

• Add a fourth tool: find_parking_by_color(color, near_building) that filters to only lots of a specific permit color.

• Replace the hardcoded data with a real parse of the KU parking map PDF — this is where real data engineering begins.

• In Dify, try removing the coordinates from the system prompt and just listing lot names. How does answer quality change? This shows why giving the LLM structured numeric data matters.

• Compare the Colab and Dify outputs for the same query. How often do they agree on the top-3 ranking?

Key takeaways¶

• Tool-using agents combine LLM strengths (fuzzy language understanding) with Python strengths (deterministic math and lookups), letting each side do what it does best.

• The Haversine formula gives exact great-circle distances in microseconds, which is far more reliable than asking the LLM to eyeball coordinate differences.

• Alias tables plus token-overlap scoring resolve informal phrases like “the phog” or “student gym” to canonical building names before any tool runs.

• A prompt-based ReAct loop -- emit JSON action, run the tool, feed the result back -- is all you need to build a working agent without a framework.

• Dify workflows are the fixed-flow counterpart: alternating Knowledge Retrieval and LLM nodes give predictable behavior, while the Python agent offers dynamic tool selection.

Run the code¶

To run this notebook, copy the URL below into your browser’s address bar. The link opens the notebook directly in Google Colab. (If your PDF viewer makes the URL clickable and lands on a broken page, copy the full text manually -- the viewer may have truncated the link at a line break.)

Estimated run time: ~2 minutes (1-3 LLM calls per question)

https://colab.research.google.com/github/KarAnalytics/code_demos/blob/main/KU_Parking_Assistant.ipynb