AzureAICommunity.Agent.Middleware.AzureMapsAddressSuggestionMiddleware 1.0.0

<div align="center">

🗺️ AzureAICommunity – Azure Maps Address Suggestion Middleware (.NET)

Find points of interest anywhere in the world directly from your AI agent pipeline using Azure Maps.

Getting Started · Configuration · Usage · Field Profiles · How It Works · Type Reference · Contributing

</div>

Overview

AzureAICommunity.Agent.Middleware.AzureMapsAddressSuggestionMiddleware is a plug-and-play location search layer for AI agent pipelines built on Microsoft.Agents.AI and Microsoft.Extensions.AI. It exposes a SearchSuggestionAsync AI tool that geocodes a location to coordinates (via the Azure Maps Geocoding API) and then finds real points of interest nearby (via the Azure Maps Fuzzy Search API) — returning rich address data with only the fields your scenario actually needs.

✨ Features

📦 Installation

dotnet add package AzureAICommunity.Agent.Middleware.AzureMapsAddressSuggestionMiddleware

🚀 Quick Start

using AzureAICommunity.Agent.Middleware.AzureMapsAddressSuggestionMiddleware;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OllamaSharp;

var mapsConfig = new MapsSearchConfig
{
    AzureMapsKey = Environment.GetEnvironmentVariable("AZURE_MAPS_KEY")!,
    MaxResults   = 5,
    Profile      = AddressFieldProfile.Basic,
};

var tools = MapsSearchTools.Create(mapsConfig);

IChatClient baseClient = new OllamaApiClient("http://localhost:11434/", "llama3.2");

AIAgent originalAgent = new ChatClientAgent(baseClient,
    instructions: """
        You are a helpful location assistant powered by Azure Maps.
        Always call the Azure Maps tool whenever the user asks to find any type of place.
        Never answer from memory — always rely on the tool response for location data.
        List every result returned by the tool without omitting any entry.
        """,
    tools: tools);

AIAgent agent = new AIAgentBuilder(originalAgent)
    .UseAzureMapsSearch(mapsConfig)
    .Build();

var response = await agent.RunAsync("Find coffee shops near Chennai and list every address.");
Console.WriteLine(response);

⚙️ Configuration

All settings are provided through a MapsSearchConfig instance:

var mapsConfig = new MapsSearchConfig
{
    AzureMapsKey = Environment.GetEnvironmentVariable("AZURE_MAPS_KEY")!,
    MaxResults   = 10,
    Profile      = AddressFieldProfile.Navigation,
};

🧑‍💻 Usage

Middleware Pipeline

Register the middleware on an AIAgentBuilder so the agent automatically intercepts and handles SearchSuggestionAsync tool calls:

var tools = MapsSearchTools.Create(mapsConfig);

AIAgent agent = new AIAgentBuilder(
        new ChatClientAgent(baseClient, instructions: "...", tools: tools))
    .UseAzureMapsSearch(mapsConfig)
    .Build();

var response = await agent.RunAsync("Find hospitals near Austin, TX.");
Console.WriteLine(response);

Custom Field Profile

Cherry-pick exactly the fields your scenario needs:

var mapsConfig = new MapsSearchConfig
{
    AzureMapsKey = Environment.GetEnvironmentVariable("AZURE_MAPS_KEY")!,
    MaxResults   = 5,
    Profile      = AddressFieldProfile.Custom,
    CustomFields = AddressFieldOptions.Name
                 | AddressFieldOptions.City
                 | AddressFieldOptions.Country
                 | AddressFieldOptions.Latitude
                 | AddressFieldOptions.Longitude
                 | AddressFieldOptions.Category,
};

🎛️ Field Profiles

Five built-in profiles control exactly which address fields reach the LLM — keeping the payload small and relevant:

Available AddressFieldOptions Flags

Name · Location · Latitude · Longitude
StreetAddress · StreetName · StreetNumber
City · State · Country · PostalCode · Neighborhood
Category · Confidence · FeatureId
MatchCodes · BoundingBox · GeocodePoints

Combine any flags with |:

CustomFields = AddressFieldOptions.Name | AddressFieldOptions.Latitude | AddressFieldOptions.Longitude

🔑 Getting an Azure Maps Key

1. Go to the Azure Portal.
2. Create an Azure Maps Account resource.
3. Navigate to Authentication and copy the Primary Key.
4. Store the key in an environment variable:

# Windows PowerShell
$env:AZURE_MAPS_KEY = "YOUR_KEY_HERE"

# Linux / macOS
export AZURE_MAPS_KEY="YOUR_KEY_HERE"

⚠️ Never commit your Azure Maps key to source control.

📐 Type Reference

MapsSearchConfig

Address

MapsSearchTools

🤝 Contributing

Contributions are welcome! Please open an issue to discuss what you'd like to change before submitting a pull request.

📁 Repository: https://github.com/rvinothrajendran/AgentFramework

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

👤 Author

Built and maintained by Vinoth Rajendran.

• 🐙 GitHub: github.com/rvinothrajendran — follow for more projects!
• 📺 YouTube: youtube.com/@VinothRajendran — subscribe for tutorials and demos!
• 💼 LinkedIn: linkedin.com/in/rvinothrajendran — let's connect!

📄 License

MIT