Haritalar deneyimi temsilci araçları

Haritalar deneyimi temsilci araçları (eski adıyla Maps Grounding Lite), yapay zeka uygulamalarınızı Google Haritalar'dan alınan güvenilir coğrafi verilerle desteklemek için Model Context Protocol (MCP) ve REST desteği sunan bir Google Haritalar Platformu hizmetidir. Araçları sayesinde LLM'ler yerler, hava durumu, hava kalitesi, polen ve rotalarla ilgili verilere erişebilir. Diğer araçlar, konum adlarını ve Google Haritalar URL'lerini yer kimliklerine dönüştürür. Haritalar deneyimi ajan araçlarını, MCP sunucularını destekleyen herhangi bir araçta MCP sunucusunu etkinleştirerek deneyebilirsiniz. Her aracı REST yöntemi olarak da çağırabilirsiniz. Ayrıntılar için Araçları REST ile çağırma başlıklı makaleyi inceleyin.

Haritalar deneyimi ajan araçları, iki SKU'su olan tek bir üründür: Essentials ve Pro. Pro seçeneği kullanılmadığı sürece her istek Essentials kapsamında faturalandırılır. Pro seçenekleri; rota boyunca yer aramaları, genişletilmiş yer ayrıntıları, arama başına daha fazla yer, rota başına daha fazla ara durak, canlı trafikle rota oluşturma, polen tahminleri ve geçmiş hava kalitesi bilgilerini ekler. Her iki SKU da aynı araçları, MCP sunucusunu, REST yöntemlerini ve kimlik bilgilerini kullanır. Ayrıntılar için Essentials ve Pro başlıklı makaleyi inceleyin.

Araçlar

Haritalar deneyimi ajan araçları, LLM'lerin aşağıdaki Google Haritalar özelliklerine erişmesine olanak tanır:

• Yerler için arama yapma: Yerler hakkında bilgi isteyin ve yapay zekayla üretilen özetler alın. Yanıtta ayrıca özetlenen her yer için yer kimlikleri, enlem/boylam koordinatları ve Google Haritalar bağlantıları da yer alır. Yer kimliklerini ve enlem/boylam koordinatlarını diğer Google Haritalar Platformu API'leriyle birlikte kullanarak yerleri haritada gösterebilirsiniz. Bu yerleri Places UI Kit ile ek ücret ödemeden görüntülemek için temsilci veri görselleştirme jetonunu (Önizleme) kullanın. Pro ile yorumlardan elde edilen analizler gibi kapsamlı yer ayrıntıları isteyebilir ve istek başına en fazla 10 yer ekleyebilirsiniz.
• Rota boyunca arama: compute_routes, route_endpoints veya encoded_polyline'ten retrieval_token kullanılarak belirtilen bir seyahat rotası üzerindeki yerleri bulun ve yapay zeka tarafından oluşturulan bir özet, yer ayrıntıları, dolambaçlı yol mesafesi ve seyahat süresi ile aracı veri görselleştirme jetonu (Önizleme) alın. Her search_along_route isteği, Pro SKU'su kapsamında faturalandırılır.
• Hava durumunu öğrenme: Bir konumun hava durumu (mevcut koşullar, 24 saatlik geçmiş, 10 güne kadar saatlik ve günlük tahminler) ve mevcut veya 4 güne kadar hava kalitesi tahmini dahil olmak üzere çevre koşullarını öğrenin. Pro ile ayrıca 5 güne kadar günlük polen tahminleri (bitki türü ayrıntılarıyla birlikte) ve 30 güne kadar saatlik hava kalitesi geçmişi isteyebilirsiniz.

• Rotaları hesaplama: Başlangıç ve varış noktası arasında (isteğe bağlı olarak ara duraklar üzerinden) bir rota isteyin ve rotanın mesafesini, süresini ve search_along_route'ya iletebileceğiniz DRIVE rotaları için bir retrievalToken döndürün. Pro ile rotalar, canlı trafik koşullarını hesaba katabilir ve daha fazla ara durak içerebilir.

• Adları çözümleme ve Haritalar URL'lerini çözümleme: Konum adlarını, adresleri ve Google Haritalar URL'lerini yer kimliklerine çözümleyin. Daha fazla bilgi için Resolution API'ye bakın.

MCP sunucusunu etkinleştirdikten sonra LLM'ler, bu veri türleriyle ilgili dayanak bilgileri almak için sunucunun araçlarını çağırabilir. LLM, bu bilgileri bağlam için kullanabilir. Ancak nihai yanıtı, MCP sunucusunun döndürdüğü bilgilerin tamamını içermeyebilir. Oluşturulan yanıtın doğruluğunu kontrol edin.

Essentials ve Pro

Essentials ve Pro, aynı ürünün iki SKU'sudur; ayrı ürünler veya planlar değildir. Pro seçeneği kullanan istekler Pro kapsamında faturalandırılır. Diğer tüm istekler Essentials kapsamında faturalandırılır. Pro seçenekleri, araç isteğindeki sıradan alanlar olduğundan LLM bunları sizin adınıza kullanabilir. Temsilciler aynı görüşmede iki SKU'yu da kullanabilir. Örneğin, bir temsilci, bir önemli noktanın yakınındaki kafeleri bulmak için Essentials'ı kullanabilir. Ardından, imza içecekleri ve oturma düzeniyle ilgili ek bir soruyu yanıtlamak için Pro'yu kullanabilir. Pro için ayrı bir MCP sunucusu, uç noktası veya kimlik bilgisi yoktur.

Essentials, Pro ve Google Haritalar ile Temellendirme'yi karşılaştırma

Google Haritalar ile Temellendirme ayrı bir üründür. Gemini API, Google AI Studio ve Gemini Enterprise Agent Platform'daki Gemini modellerinde yerleşik olarak bulunur. Model, Google Haritalar'ı ne zaman sorgulayacağına karar verir ve alıntılarla desteklenen yanıtlar döndürür. Gemini'da geliştirme yaparken modelin temellendirme işlemini gerçekleştirmesini istiyorsanız Google Haritalar ile Temellendirme'yi seçin. Diğer modeller veya temsilci çerçeveleri için ya da her araç çağrısını doğrudan kontrol etmek için Haritalar deneyimi temsilci araçlarını seçin.

Aşağıdaki tabloda Essentials SKU'su, Pro SKU'su ve Google Haritalar ile Temellendirme karşılaştırılmaktadır:

Bu seçenekler her iki SKU'da da aynı şekilde çalışır: seyahat modları, kalkış ve varış saatleri, alternatif rotalar, rota çoklu çizgileri, hava durumu aramaları, mevcut ve tahmini hava kalitesi aramaları (kirletici konsantrasyonları ve yerel AQI ölçekleri dahil), hava durumu birim sistemleri ve Resolution API. İsteklerin hangi SKU'ya faturalandırılacağını değiştirmezler.

Pro SKU kapsamında faturalandırılanlar

Aşağıdaki tabloda, Essentials'a dahil olan ve Pro SKU'sunu gerektiren özellikler özetlenmiştir:

Her bir özelliği etkinleştiren istek seçenekleri için Yer arama, Rota boyunca arama yapma, Rota hesaplama ve Hava durumunu öğrenme bölümlerini inceleyin.

Pro kullanımını kontrol etme

Pro seçenekleri search_places, compute_routes ve lookup_weather cihazlarda varsayılan olarak kapalıdır. LLM, kullanıcının isteği gerektirdiğinde ve araç açıklaması veya talimatlarınız izin verdiğinde bunları ayarlar ya da search_along_route çağırır. Araç açıklamaları, modele hangi seçeneklerin daha pahalı olduğunu ve bunları ne zaman kullanacağını söyler: 5'in üzerinde page_size, genişletilmiş yer ayrıntıları, 10'dan fazla ara yol noktası, trafiğe duyarlı rota ve search_along_route. Araçları REST ile çağırırsanız kodunuz her seçeneği ayarlar. Maliyetleri yönetmek için:

• Pro seçeneklerinin ne zaman uygun olduğunu modele söyleyin. Örneğin: "Yalnızca kullanıcı yorumlar, menüler veya atmosfer hakkında soru sorduğunda include_extended_details değerini ayarlayın." Veya: "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL aracını yalnızca kullanıcı mevcut seyahat süresini sorduğunda kullan." Veya: "search_along_route aracını yalnızca kullanıcı bir rota üzerindeki yerleri sorduğunda çağır." Veya: "Yalnızca kullanıcı polen, alerji veya geçmiş hava kalitesi hakkında soru sorduğunda geçmiş date ya da hour ile POLLEN veya AIR_QUALITY değerini ekleyin."
• Bir temsilciyi Essentials SKU'sunda tutmak için modele hiçbir zaman search_along_route çağırmamasını veya Pro seçeneğini kullanmamasını söyleyin. Pro seçenekleri şunlardır: include_extended_details, 5'ten fazla page_size, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, 10'dan fazla ara nokta, capabilities içinde POLLEN ve capabilities içinde AIR_QUALITY ile geçmiş bir date veya hour. MCP istemciniz araçları veya araç bağımsız değişkenlerini kısıtlayabiliyorsa search_along_route ve bu bağımsız değişken değerlerini araç yapılandırmasında da engelleyebilirsiniz.
• Fatura raporlarınızda Maps Grounding Pro SKU'yu izleyin ve bütçe uyarıları ayarlayın.

Resolution API

Haritalar deneyimi ajan araçları, Resolution API'yi sağlar. Serbest biçimli konum metinlerini ve URL'leri yapılandırılmış Google Haritalar yer tanımlayıcılarına dönüştürür. Resolution API, MCP sunucusunda REST yöntemleri ve araçlar olarak kullanılabilir:

• Adları çözümleme (REST, MCP): Bir grup konum adını veya adresini Google Haritalar'daki belirli yer varlıklarıyla eşleştirin. Bu araç, yapılandırılmamış kullanıcı sorgularını sabit yer kimliklerine dayandırmaya yardımcı olur.
• Haritalar URL'lerini çözümleme (REST, MCP): Bir grup Google Haritalar URL'sini belirli yer varlıklarına çözümler. Desteklenen biçimler arasında standart yer URL'leri ve kısaltılmış URL'ler bulunur.

Döndürülen yer kimliklerini diğer Google Haritalar Platformu API'leriyle kullanabilirsiniz. Her yanıtta, çözümlenen yerleri Google Haritalar'da liste olarak kaydeden bir bağlantı da bulunur.

Daha fazla bilgi için Maps Tools Resolution API'ye bakın.

Örnek uygulamayı deneyin (Yeni sekmede açılır)

Faturalandırma ve kotalar

Nasıl faturalandırılırsınız?

Google Haritalar Platformu'nun kullandıkça öde fiyatlandırma modelinde, Haritalar deneyimi ajan araçlarının kullanımı her istek için hesaplanır. Her istek bir faturalandırma etkinliğini temsil eder. Kullanım, her ürün SKU'su için takip edilir. Faturanızda, toplam ücretlerinizin yanı sıra her SKU için bir satır öğesi gösterilir. Daha fazla bilgi için Raporlamaya genel bakış bölümüne bakın.

MCP sunucusu üzerinden veya REST ile yapılan her Search places, Search along route, Compute routes ya da Lookup weather isteği, tek bir SKU kapsamında faturalandırılır: Maps Grounding Essentials veya Maps Grounding Pro. Her search_along_route isteği ve Pro seçeneğini kullanan tüm istekler Pro SKU'su kapsamında faturalandırılır. Bir istek hiçbir zaman her iki SKU kapsamında da faturalandırılmaz ve bir istekteki Pro seçeneklerinin sayısı ücreti değiştirmez. Her bir aracın SKU'sunu belirleyen özellikler ve seçenekler için Pro SKU kapsamında faturalandırılanlar başlıklı makaleyi inceleyin.

Maps Grounding Essentials istekleri,her ay ilk 10.000 istekten sonra 1.000 istek başına 7,00 ABD doları olarak faturalandırılır. Maps Grounding Pro istekleri, her ay ilk 5.000 istekten sonra 1.000 istek başına 14 ABD doları olarak faturalandırılır. Her iki SKU'da da daha yüksek aylık kullanımda toplu indirimler uygulanır.

Fiyatlandırma ayrıntıları için Ana fiyatlandırma tablosu ve Hindistan fiyatlandırma tablosu'na bakın.

Çözümleme API'si istekleri (ResolveNames ve ResolveMapsUrls), Places API Text Search Essentials (Yalnızca Kimlikler) SKU'su kapsamında ücretsiz olarak faturalandırılır.

Places UI Kit ile bir search_places veya search_along_route yanıtındaki yerleri gösteriyorsanız bu Places UI Kit isteklerinin faturalandırılmaması için temsilci veri görselleştirme jetonunu (Önizleme) kullanabilirsiniz.

Essentials SKU'sunun kullanımı, Essentials ve Pro Abone olun ve tasarruf edin planlarına dahildir. Pro SKU'sunun kullanımı Pro planına dahildir.

Kotalar

Maps Experiments ajan araçları tarafından sağlanan araçlar ve API'ler için aşağıdaki kotalar geçerlidir:

• Yer arama: Her proje için dakikada 300 sorgu.
• Rota üzerinde arama: Her proje için dakikada 300 sorgu.
• Hava durumu arama: Her proje için dakikada 300 sorgu.
• Rotaları hesaplama: Her proje için dakikada 300 sorgu.
• Adları çözümleme: Her proje için dakikada 600 sorgu.
• Haritalar URL'lerini çözümleme: Proje başına dakikada 600 sorgu.

Kotalar her araç için sayılır ve Essentials ile Pro SKU'ları tarafından paylaşılır. Pro isteği, aynı araç için Essentials isteğiyle aynı kotayı kullanır.

Her Resolution API isteği, içerdiği öğe sayısından bağımsız olarak bir sorgu olarak sayılır.

Politikalar ve hizmet şartları

Maps Experience agent araçları, hizmete özel şartlar da dahil olmak üzere Google Haritalar Platformu Hizmet Şartları'na tabidir. Bu bölümde, uyumlu LLM'ler ve kaynak ilişkilendirme dahil olmak üzere Maps Experience temsilci araçları için ek kullanım koşulları açıklanmaktadır. Şartlar, bir isteğin hangi SKU kapsamında faturalandırıldığına bakılmaksızın tüm sonuçlar için geçerlidir.

Uyumlu LLM'ler için koşullar

Haritalar deneyimi temsilci araçlarını yalnızca Google Haritalar Platformu Hizmet Şartları'na uygun bir LLM ile kullanabilirsiniz.

Örneğin, Google Haritalar içeriğinin, kullanmayı seçtiğiniz LLM tarafından önbelleğe alınmamasını, depolanmamasını veya LLM'yi iyileştirmek için kullanılmamasını sağlamak sizin sorumluluğunuzdadır. Haritalar deneyimi ajan araçlarını kullanmadan önce, bu araçlarla kullanmayı planladığınız tüm modellerin Hizmet Şartları'nı incelemeniz gerekir. Haritalar Deneyimi temsilci araçlarını, modele girilen verileri model eğitimi veya iyileştirme için kullanan modellerle kullanmamalısınız. Modeli kullanımınızın, hizmete özel şartlar da dahil olmak üzere Google Haritalar Platformu Hizmet Şartları'ndaki Google Haritalar içeriğiyle ilgili kısıtlamalara tam olarak uymasını sağlamak sizin sorumluluğunuzdadır.

Google Haritalar kaynakları için ilişkilendirme koşulları

Haritalar deneyimi ajan araçlarından gelen her araç yanıtı kaynakları içerir. Haritalar deneyimi ajan araçlarından elde edilen sonuçları sunarken ilgili Google Haritalar kaynaklarını eklemeniz ve aşağıdaki şartları karşılamanız gerekir:

• Google Haritalar kaynakları, destekledikleri oluşturulan içeriğin hemen ardından gelmelidir. Oluşturulan bu içerik, temellendirilmiş çıkış olarak da adlandırılır.
• Google Haritalar kaynakları, tek bir kullanıcı etkileşimiyle görüntülenebilir olmalıdır.

"Yer arama" ve "Rota üzerinde arama" araçlarının kaynakları

search_places aracı places alanı ve search_along_route aracı results[].place alanı, summary destekleyen kaynaklar sağlar. Her yer için aşağıdaki meta veriler döndürülür:

• place (kaynak adı)
• id
• location
• googleMapsLinks
• attribution

Her yer için aşağıdaki şartları karşılayan bir bağlantı önizlemesi oluşturmanız gerekir:

• Haritalar deneyimi temsilci araçları metin ilişkilendirme yönergelerini uygulayarak her kaynağı Google Haritalar ile ilişkilendirin.
• Yanıttaki googleMapsLinks.placeUrl öğesini kullanarak kaynağa bağlantı verin.

Bu şartlar, Pro'dan alınan yorumlardan elde edilen analizler gibi kapsamlı yer ayrıntılarını içeren özetler için de geçerlidir. summary, her yeri places veya results içindeki bir girişle eşlenen sıfır tabanlı bir dizinle (ör. [0]) belirtir. Her yerde, yerin Google Haritalar'daki yorumlarına bağlantı veren googleMapsLinks.reviewsUrl da bulunur. Kullanıcılar, bir analizin arkasındaki yorumları görmek için bu bağlantıyı takip edebilir.

Ses öncelikli arayüzler

Uygulamanız, Haritalar deneyimi ajan araçları sonuçlarını sesli olarak sunuyorsa ses öncelikli arayüzlerle ilgili şartları da karşılamanız gerekir. Özet olarak:

• Kaynak bulma: Google Haritalar kaynaklarını, sesli görüşmenin kelimesi kelimesine geçmiş kaydını gösteren tamamlayıcı bir kullanıcı arayüzünde görüntüleyin.
• Etkin açıklama: Etkileşim sırasında kullanıcılara, yapay zekayla üretilen içeriğin Google Haritalar'dan bilgiler içerebileceğini söyleyin. Ayrıca, ayrıntılı kaynakların tamamlayıcı kullanıcı arayüzünde mevcut olduğunu da belirtin. Bunu ekrandan veya sesinizle yapabilirsiniz.
• Kalıcı açıklama: Yapay zekayla üretilen içeriğin Google Haritalar içeriği içerebileceğine dair kalıcı bir açıklama (ör. ses ayarları menüsünde) bulundurun.
• Kullanıcı sorguları: Kullanıcıların içeriğin kaynağıyla ilgili sorularını doğru şekilde yanıtlayın ve ayrıntılar için kullanıcıları tamamlayıcı kullanıcı arayüzüne yönlendirin.

LLM'leri MCP sunucusunu kullanacak şekilde yapılandırma

Haritalar deneyimi ajan araçlarını kullanmak için Haritalar deneyimi ajan araçları API hizmetinin etkinleştirildiği bir Google Cloud projeniz olmalıdır. Ayrıca bir API anahtarına veya OAuth istemci kimliğine ihtiyacınız vardır. Ardından, LLM'leri MCP sunucusuna erişecek şekilde yapılandırabilirsiniz. MCP sunucusu, Streamable HTTP aktarımını kullanır.

Google Cloud projenizde Haritalar deneyimi temsilci araçlarını etkinleştirme

Projenizde API'yi etkinleştirmek için:

1. Google Cloud Console'da, Haritalar deneyimi temsilci araçları için kullanmak istediğiniz projeyi seçin.
2. Google Cloud Console'da proje için faturalandırmayı etkinleştirin.
3. Google Cloud Console API Kitaplığı'nda Haritalar deneyimi temsilci araçlarını etkinleştirin.

API anahtarı kullanarak kimlik doğrulama

Haritalar deneyimi temsilci araçlarıyla mevcut bir API anahtarını kullanabilir veya yeni bir anahtar oluşturabilirsiniz. Her iki durumda da hem Google Cloud projesinde hem de anahtarda Maps Experience agent tools API hizmetini etkinleştirin.

API anahtarı kullanarak kimlik doğrulaması yapmak için:

1. Google Haritalar Platformu'nu kullanmaya başlama bölümündeki adımları uygulayarak API anahtarı oluşturun veya yapılandırın.
2. X-Goog-Api-Key başlığını kullanarak anahtarı MCP sunucusuna iletin. Bunu, LLM'nin MCP aracı yapılandırmasında özel bir HTTP üstbilgisi olarak belirtmeniz gerekir.

OAuth kullanarak kimlik doğrulama

OAuth kimlik bilgileri oluşturup bunları MCP ana makinesine veya MCP sunucu uygulamasına ileterek OAuth kullanarak kimlik doğrulaması yapabilirsiniz.

OAuth kullanarak kimlik doğrulamak için:

1. Google Cloud Console'da, Haritalar deneyimi temsilci araçları için kullanmak istediğiniz projeyi seçin.
2. API ve Hizmetler menüsünde Kimlik Bilgileri'ni seçin.
3. Üst menüde Kimlik bilgileri oluştur > OAuth istemci kimliği'ni seçin.
4. Projenin yapılandırılmış bir kullanıcı rızası ekranı yoksa Configure consent screen'i (Kullanıcı rızası ekranını yapılandır) tıklayın ve ekrandaki talimatları uygulayın.
5. Metrikler bölümünde OAuth istemcisi oluştur'u tıklayın.
6. OAuth istemci kimliği oluştur ekranında bir uygulama türü seçin ve istemci kimliği için bir ad girin.
7. Uygulama türünüzle ilgili ek ayrıntıları belirtin. Örneğin, bir web uygulaması oluşturuyorsanız tarayıcı ve sunucu istekleri için yetkili URI'ler ekleyin.
8. İstemciniz oluşturulduktan sonra istemci kimliğini ve gizli anahtarı kaydedin.
9. MCP ana makinenizi veya MCP sunucu uygulamanızı yapılandırırken OAuth istemci kimliğinizi ve gizli anahtarınızı iletin. Ayrıca aşağıdaki kapsamı da istemeniz gerekir: https://www.googleapis.com/auth/maps-platform.mapstools.

Daha fazla bilgi için Google API'lerine Erişmek İçin OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.

LLM'leri, Haritalar deneyimi ajan araçları MCP sunucusuna erişecek şekilde yapılandırma

Haritalar Deneyimleri ajan araçları hizmetini etkinleştirip kimlik bilgileri oluşturduktan sonra LLM'leri MCP sunucusuna erişecek şekilde yapılandırabilirsiniz. LLM'nizin MCP yapılandırma belgelerini inceleyin ve şu MCP sunucusu URL'sini kullanın: https://mapstools.googleapis.com/mcp

Daha fazla bilgi için Yapay zeka uygulamasında MCP'yi yapılandırma başlıklı makaleyi inceleyin.

Gemini CLI ile Haritalar deneyimi temsilci araçlarını yapılandırma

Bu bölümde, Gemini CLI kullanarak Maps Experience Agent Tools MCP sunucusunun nasıl yapılandırılacağıyla ilgili bir örnek verilmiştir. Daha fazla bilgi için Gemini CLI ile MCP sunucuları başlıklı makaleyi inceleyin.

1. Gemini CLI'yı yükledikten sonra MCP sunucusunu yapılandırmak için gemini mcp add komutunu çalıştırın:

   gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-experience-agent-tools-mcp https://mapstools.googleapis.com/mcp
   

   Yapılandırma başarılı olduysa sunucunun kullanıcı ayarlarınıza eklendiğini belirten bir onay mesajı görürsünüz.

2. Sunucunun çalıştığını doğrulamak için /mcp list komutunu çalıştırın:

   > /mcp list
   
   Configured MCP servers:
   
   maps-experience-agent-tools-mcp - Ready (6 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   resolve_maps_urls
   -   resolve_names
   -   search_along_route
   -   search_places
   

3. KSA ile Haritalar'a Sor ile ilgili sorular sormaya başlayın. Örneğin, "Mountain View'da birkaç restoran öner" diyerek sizin adınıza search_places aracını çağırmasını sağlayabilirsiniz.

Agent Development Kit (ADK) ile Haritalar deneyimi temsilci araçlarını yapılandırma

Bu bölümde, MCP sunucusunun Python, Java veya TypeScript'te Agent Development Kit (ADK) ile nasıl yapılandırılacağı gösterilmektedir.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mapstools.googleapis.com/mcp",
                headers={
                    "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
                    "Content-Type": "application/json",
                    "Accept": "application/json, text/event-stream"
                }
            )
        )
    ]
)
    

from . import agent
    

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}
    

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "StreamableHTTPConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            transportOptions: {
                requestInit: {
                    headers: {
                        "X-Goog-Api-Key": googleMapsApiKey,
                        "Content-Type": "application/json",
                        "Accept": "application/json, text/event-stream"
                    }
                }
            }
        })
    ],
});
    

REST ile araçları çağırma

Haritalar deneyimi temsilci araçlarındaki her araç, REST yöntemi olarak da kullanılabilir. Araçları kendi temsilcinize veya uygulamanıza bağlamak istediğinizde REST yöntemlerini doğrudan çağırın. Örneğin, bir model için kendi işlevlerinizi tanımlamak, modelin ayarlayabileceği seçenekleri belirlemek veya kodunuzda varsayılan değerleri ayarlamak için bu yöntemleri kullanabilirsiniz.

Aşağıdaki tabloda her araç için REST yöntemi listelenmiştir:

REST isteği, ilgili araçla aynı seçenekleri alır ve aynı yanıtı döndürür. REST istek ve yanıt gövdelerinde, alan adları küçük harfle başlayan camel case biçiminde yazılır. Örneğin, text_query yerine textQuery kullanılır. REST istekleri aynı SKU'lar altında faturalandırılır, Pro seçenekleri için aynı kurallara uyar ve MCP araç çağrılarıyla aynı kotalara dahil edilir.

Kimlik doğrulaması için MCP sunucusuyla aynı Google Cloud projesini ve kimlik bilgilerini kullanın. Kurulum adımları için LLM'leri MCP sunucusunu kullanacak şekilde yapılandırma başlıklı makaleyi inceleyin. X-Goog-Api-Key başlığında bir API anahtarı veya Authorization başlığında https://www.googleapis.com/auth/maps-platform.mapstools kapsamına sahip bir OAuth erişim jetonu iletin.

Aşağıdaki örnekte searchText yöntemi çağrılmaktadır:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "coffee shops near Golden Gate Park"
}' \
"https://mapstools.googleapis.com/v1:searchText"

API_KEY kısmını API anahtarınızla değiştirin.

Yanıt, search_places araç sonucuyla aynı summary, places ve contentToken alanlarını içerir. Her aracın kılavuzunda, örneğinin REST sürümü gösterilir.

Geri bildirim paylaşma

Haritalar deneyimi temsilci araçları hakkında geri bildirim paylaşmak için aşağıdaki formları kullanın:

• Hata bildirme
• Özellik isteği gönderme
• Geri bildirim gönderin