mattpodwysocki

Introducing Mapbox Agents for JavaScript: Location-Aware AI, Done Right

A few months ago I was deep in the middle of building the Mapbox Location Agent, and I kept running into the same problem over and over. Every time I wanted the agent to do something useful with location data, I was writing boilerplate. Tool wrappers, retry logic, conversation state, multi-turn orchestration loops. The kind of stuff that has nothing to do with the actual product and everything to do with just getting the infrastructure out of the way.

At some point I looked at what we had built and realized: this is a framework. A pretty good one. And it would be a shame to keep it locked inside Mapbox.

So we're open-sourcing it. This is the story of what we built, why we built it the way we did, and how you can use it today.

---

mattpodwysocki

Meet-in-the-Middle: Message Flow Diagram

End-to-end flow from user input through ContentView → AIService → external APIs, for both an initial query and a follow-up turn.

sequenceDiagram
    participant U  as User
    participant CV as ContentView
    participant AS as AIService.liveStream()
    participant QP as QueryPlanner

mattpodwysocki

Grounding with Mapbox

LLMs know about the world but can't see it. Without grounding, a model will confidently invent addresses, distances, and business details — some real, some not. Grounding connects the model's outputs (and inputs) to live, verifiable data at inference time.

Mapbox is one grounding source — but not the only one, and not trying to be. The power comes from combining sources that each contribute a different layer of reality.

---

The grounding stack

mattpodwysocki

Enhanced Places Demo — Performance Work Summary

May 2026 · Summary of latency and throughput improvements across the NL search pipeline. All benchmarks run against the 75-case eval fixture (npm run eval) unless noted.

---

TL;DR

| Area | What changed | Win |

mattpodwysocki

AI at Mapbox — 20-Minute Demo Presentation

Date: Monday
Format: Demo-heavy, 20 minutes
Apps: Pre-built before the presentation

---

Structure

mattpodwysocki

name	mapbox-search-patterns
description	Expert guidance on choosing the right Mapbox search tool and parameters for geocoding, POI search, and location discovery

Mapbox Search Patterns Skill

Expert guidance for AI assistants on using Mapbox search tools effectively. Covers tool selection, parameter optimization, and best practices for geocoding, POI search, and location discovery.

Available Search Tools

mattpodwysocki

name	mapbox-geospatial-operations
description	Expert guidance on choosing the right geospatial tool based on problem type, accuracy requirements, and performance needs

Mapbox Geospatial Operations Skill

Expert guidance for AI assistants on choosing the right geospatial tools from the Mapbox MCP Server. Focuses on selecting tools based on what the problem requires - geometric calculations vs routing, straight-line vs road network, and accuracy needs.

Core Principle: Problem Type Determines Tool Choice

mattpodwysocki

How MCP Prompts and Agent Skills Work Together

This document explains the relationship between MCP Prompts and Agent Skills in the Mapbox MCP DevKit Server.

Quick Answer

Prompts provide step-by-step workflows (orchestration) Skills provide domain expertise (knowledge) Tools provide capabilities (actions)

mattpodwysocki

How MCP Prompts and Agent Skills Work Together

This document explains the relationship between MCP Prompts and Agent Skills in the Mapbox MCP DevKit Server.

Quick Answer

Prompts provide step-by-step workflows (orchestration) Skills provide domain expertise (knowledge) Tools provide capabilities (actions)

mattpodwysocki

Iterables, AsyncIterables, Observables, Oh My!

I know there is a lot of confusion around Observables, Iterables, AsyncIterables and AsyncObservables. Let's try to break this down and the reasons for each.

Pull versus Push Collections

When it comes to collections, you have two ways of thinking about collections, push versus pull. With pull, the consumer is in control of when you get the items, but with push, you get the values when the producer is ready.

Pull Based Collections