Haritalar deneyimi temsilci araçları

Maps Experience Agent 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) desteği sunan bir Google Haritalar Platformu hizmetidir. MCP sunucusu, LLM'lerin yerler, hava durumu ve rotalarla ilgili verilere erişmesine olanak tanıyan araçlar sağlar. Diğer araçlar, konum adlarını ve Google Haritalar URL'lerini yer kimliklerine dönüştürür. Maps Experience temsilci araçlarını, MCP sunucularını destekleyen herhangi bir araçta etkinleştirerek deneyebilirsiniz.

Maps Experience Agent Tools, 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, kapsamlı yer ayrıntıları, arama başına daha fazla yer, rota başına daha fazla ara durak ve canlı trafikle rota oluşturma özelliklerini ekler. Sınırlı GA sırasında Pro seçenekleri yalnızca Pro izin verilenler listesindeki projeler tarafından kullanılabilir. Her iki SKU da aynı MCP sunucusunu, araçları ve kimlik bilgilerini kullanır. Ayrıntılar için Essentials ve Pro başlıklı makaleyi inceleyin.

Araçlar

Maps Experience temsilci 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, özetteki her yer için yer kimlikleri, koordinatlar ve Google Haritalar bağlantıları da yer alır. Yer kimliklerini ve koordinatları diğer Google Haritalar Platformu API'leriyle birlikte kullanarak yerleri haritada gösterebilirsiniz. Pro ile yorumlardan elde edilen analizler gibi kapsamlı yer ayrıntıları isteyebilir ve istek başına en fazla 10 yer ekleyebilirsiniz.
• Hava durumunu öğrenme: Hava durumu hakkında bilgi isteyin ve mevcut koşulları, saatlik tahminleri ve günlük tahminleri alın.

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

  Not: Haritalar Deneyimi temsilci araçları, adım adım yol tarifi veya navigasyon bilgileri sağlamaz. Pro seçenekleri olmadan hesaplanan rotalarda canlı trafik dikkate alınmaz.

• 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 bilgilerini almak için sunucunun araçlarını çağırabilir. LLM, bu bilgileri bağlam için kullanabilir. Ancak son yanıtı, MCP sunucusunun döndürdüğü bilgilerin tamamını içermeyebilir. Oluşturulan yanıtın doğruluğunu kontrol etmeniz gerekir.

Essentials ve Pro

Pro yalnızca belirli müşteriler tarafından kullanılabilir. Daha fazla bilgi edinmek için satış ekibiyle iletişime geçin.

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 alanlardır. Bu nedenle, LLM bunları sizin adınıza kullanabilir. Temsilciler aynı görüşmede iki SKU'yu da kullanabilir. Örneğin, bir temsilci, önemli bir yerin yakınındaki kafeleri bulmak için Essentials'ı kullanabilir. Ardından, özel 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 birlikte temellendirilmiş 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.

	Haritalar deneyimi temsilci araçları		Google Haritalar ile Temellendirme
	Essentials SKU'su (eski adıyla Maps Grounding Lite)	Pro SKU
İstekler nasıl faturalandırılır?	Pro seçeneği kullanmayan her araç isteği	Pro seçeneğini kullanan her araç isteği: include_extended_details, 5'in üzerinde page_size, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL veya 10'dan fazla ara yol noktası	Platforma ve modele bağlı olarak her Google Haritalar sorgusu veya temellendirilmiş istem
Modeller ve platformlar	MCP'yi destekleyen tüm modeller veya temsilci çerçeveleri. Her iki SKU için bir MCP sunucusu, bir araç seti ve aynı kimlik bilgileri		Gemini API, Google AI Studio ve Gemini Enterprise Agent Platform'daki Gemini modelleri
Araçların döndürdüğü bilgiler	Temel bilgiler: Arama başına en fazla 5 yer için yer ayrıntıları, canlı trafik olmadan rota mesafesi ve süresi, mevcut hava durumu ve tahminler	Essentials'taki her şeyin yanı sıra kapsamlı yer ayrıntıları (ör. yorumlardan elde edilen analizler), arama başına 10 yere kadar, canlı trafik bilgisi içeren rotalar ve 25'e kadar ara nokta	Yorumlardan elde edilen yer ayrıntıları ve analizler ile canlı trafik bilgileri içeren rota bilgileri
Örnek istekler	Gerçeklere ve lojistiğe dayalı sorular: mağaza veya işletme bulma, çalışma saatleri, adresler ve mesafe ya da seyahat süresi tahminleri	Öznel veya geniş kapsamlı sorular: atmosfer, özel yemekler, ziyaretçi ipuçları, 6 ila 10 yerin karşılaştırması ve mevcut trafikte seyahat süreleri	Gemini'da etkileşimli arama, seyahat planlama ve yerel keşif
Places UI Kit görselleştirmeleri	Temsilci tabanlı veri görselleştirme jetonuyla (Önizleme) ek ücret ödemeden kullanılabilir.		Ayrı faturalandırılır
Aylık ücretsiz kullanım	10.000 istek	5.000 istek	Platforma ve modele bağlıdır. Örneğin, Gemini API'de Gemini 3 ve daha yeni modeller, ayda 5.000 ücretsiz arama sorgusu içerir. Bu sınırdan sonra, arama sorgularının maliyeti 1.000 sorgu başına 14 ABD dolarıdır.
Kullandıkça öde fiyatı	1.000 istek başına 7,00 ABD doları (hacim indirimleri uygulanır)	1.000 istek başına 14 ABD doları. Toplu fiyatlandırma için satış ekibiyle iletişime geçin.
Abone olarak tasarruf edin	Essentials ve Pro planlarına dahildir.	Dahil değil	Kullanılamıyor
Başlayın	Her iki SKU için de tek bir kurulum: LLM'leri MCP sunucusunu kullanacak şekilde yapılandırma başlıklı makaleyi inceleyin. Sınırlı GA sırasında Pro seçenekleri için Pro izin verilenler listesinde bir proje de gerekir.		Gemini API veya Agent Platform

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ı ve Resolution API. İsteğin hangi SKU altında faturalandırılacağını değiştirmezler.

Pro SKU kapsamında faturalandırılanlar

Araç	Kapasite	Essentials	Pro
Yerler'de arama yapma	İstek başına yer sayısı	En fazla 5	6-10 (6-10 arası page_size)
	Arama özetlerinde genişletilmiş yer ayrıntıları (yorumlardan elde edilen analizler, menüde öne çıkanlar, atmosfer, bir yerin yoğunluğu, ziyaretçi ipuçları ve yakınlık sorguları için mesafe veya seyahat süresi)	Kullanılamıyor	include_extended_details ile kullanılabilir
Rotaları hesaplama	Yönlendirme tercihi	Canlı trafik hesaba katılmaz.	ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL ile canlı trafik veya toplu taşıma rotaları için anlık toplu taşıma verilerini hesaba katar.
	Rota başına ara yol noktası sayısı	En fazla 10	11-25 (10 intermediate_waypoints'den fazla)
Lookup Weather ve Resolution API	Pro seçeneği yok. Tüm istekler Essentials SKU'su kapsamında faturalandırılır.

Her bir özelliği etkinleştiren istek seçenekleri için Yer arama ve Rota hesaplama bölümlerine bakın.

Sınırlı GA sırasında Pro seçenekleri

Sınırlı GA sırasında Pro seçenekleri yalnızca Pro izin verilenler listesindeki Google Cloud projelerinde kullanılabilir. Erişim istemek için satış ekibiyle iletişime geçin. Bir proje izin verilenler listesine eklendikten sonra, projedeki her API anahtarı ve OAuth istemcisi Pro seçeneklerini kullanabilir.

Projeniz henüz izin verilenler listesinde değilse Pro seçeneklerini kullanan istekler aşağıdaki gibi işlenir:

• Search places: include_extended_details yoksayılır ve page_size değerini daha yüksek bir değere ayarlasanız bile yanıtta en fazla 5 yer bulunur. İstek, Essentials SKU'su kapsamında faturalandırılır.
• Compute routes: ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, ROUTING_PREFERENCE_TRAFFIC_UNAWARE olarak değerlendirilir ve istek, Essentials SKU'su kapsamında faturalandırılır. 10'dan fazla ara yol noktası içeren istekler INVALID_ARGUMENT hatası döndürür.

Projenizin izin verilenler listesinde olup olmadığını kontrol etmek için page_size değeri 10 olarak ayarlanmış bir search_places isteği gönderin. restaurants in Chicago gibi geniş bir sorgu kullanın. İzin verilenler listesindeki bir proje, Pro SKU'su kapsamında faturalandırılan 5'ten fazla yer döndürebilir. Diğer projeler en fazla 5 yer döndürür.

Pro kullanımını kontrol etme

Pro seçenekleri varsayılan olarak kapalıdır. LLM, kullanıcının isteği gerektirdiğinde ve araç şeması veya talimatlarınız izin verdiğinde bunları ayarlar. Araç şeması, 5'e kadar page_size değerini ve en fazla 10 ara noktayı tanımlar. Bu nedenle modeller, daha yüksek Pro sınırlarını yalnızca talimatlarınızda istendiğinde kullanır. Maliyetleri yönetmek için:

• Modele, Pro seçeneklerinin ne zaman uygun olduğunu söyleyin. Örneğin: "include_extended_details değerini yalnızca kullanıcı yorumlar, menüler veya atmosfer hakkında soru sorduğunda ayarlayın." Veya: "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL aracını yalnızca kullanıcı mevcut seyahat süresini sorduğunda kullan."
• Bir temsilciyi Essentials SKU'sunda tutmak için modele hiçbir zaman Pro seçeneğini kullanmamasını söyleyin. Pro seçenekleri include_extended_details, page_size, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL ve 10'dan fazla ara noktadır. MCP istemciniz araç bağımsız değişkenlerini kısıtlayabiliyorsa bu değerleri araç yapılandırmasında da engelleyebilirsiniz.
• Fatura raporlarınızda kullanımınızı izleyin ve bütçe uyarıları ayarlayın.

Resolution API

Haritalar Deneyimi temsilci 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, yapılandırılmamış kullanıcı sorgularını sabit yer kimliklerine dayandırmak için kullanışlıdır.
• 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 sayfasına 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 temsilci 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.

Her Search Places, Compute Routes veya Lookup Weather isteği, tam olarak bir SKU (Essentials veya Pro) kapsamında faturalandırılır. Pro seçeneklerinden herhangi birini kullanan istekler Pro SKU'su kapsamında faturalandırılır. Hiçbir zaman her iki SKU için de faturalandırılmaz ve Pro seçeneklerinin sayısı ücreti değiştirmez. SKU'yu aşağıdaki seçenekler belirler:

Araç	Essentials	Pro
search_places	Pro seçeneği olmayan tüm istekler: 5 veya daha az page_size ve ayarlanmamış include_extended_details veya false	include_extended_details, true olarak ayarlandı veya page_size 6 ile 10 arasında
compute_routes	Pro seçeneği olmayan tüm istekler: routing_preference ayarlanmamış veya ROUTING_PREFERENCE_TRAFFIC_UNAWARE ve herhangi bir seyahat moduyla 10 veya daha az ara nokta	routing_preference, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL olarak ayarlandı veya 11 ila 25 ara nokta var
lookup_weather	Her istek	—

Essentials fiyatlandırması için Essentials SKU ayrıntıları başlıklı makaleyi inceleyin. Pro istekleri,her ay ilk 5.000 istekten sonra 1.000 istek başına 14,00 ABD doları olarak faturalandırılır. Toplu fiyatlandırma için satış ekibiyle iletişime geçin.

Kısıtlanmış GA sırasında Pro seçenekleri yalnızca Pro izin verilenler listesindeki projelerde geçerli olur. Ayrıntılı bilgi için Kısıtlı GA sırasında Pro seçenekleri başlıklı makaleyi inceleyin.

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.

Essentials SKU'sunun kullanımı, Essentials ve Pro Abone olun ve tasarruf edin paketlerine de dahildir. Pro SKU'su, "Abone olun ve tasarruf edin" paketlerine dahil değildir.

Kotalar

Aşağıdaki kotalar, Haritalar deneyimi temsilci araçları tarafından sağlanan araçlar ve API'ler için geçerlidir:

• Search Places: Proje başına dakikada 300 sorgu.
• Hava durumu arama: Proje başına dakikada 300 sorgu.
• Compute Routes: Proje başına dakikada 300 sorgu.
• Adları çözümleme: Proje başına dakikada 600 sorgu.
• Resolve Maps URLs: Proje başına dakikada 600 sorgu.

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

Her Resolution API isteği, içerdiği öğe sayısına bakılmaksızın bir sorgu olarak sayılır.

Politikalar ve hizmet şartları

Maps Experience temsilci 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

Maps Experience 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. Maps Experiments temsilci 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 temsilci araçlarından gelen her araç yanıtı kaynakları içerir. Maps Experience temsilci 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 aracı için kaynaklar

search_places aracının places alanı, summary destekleyen kaynaklar sağlar. places için aşağıdaki meta veriler döndürülür:

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

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

• Haritalar Deneyimi Temsilcisi araçları metin ilişkilendirme yönergelerini uygulayarak her kaynağı Google Haritalar ile ilişkilendirin.
• Yanıttaki places.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 sıfır tabanlı bir dizinle (ör. [0]) belirtir. Bu dizin, places içindeki bir girişle eşlenir. Her yerde, 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 temsilci araçları sonuçlarını sesli olarak sunuyorsa ses öncelikli arayüzlerle ilgili şartları da karşılamanız gerekir. Özet olarak:

• Kaynak gösterme: 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çeriklerin Google Haritalar içeriği barındırabileceğ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

Maps Experience Agent araçlarını kullanmak için Maps Experience Agent araçları API hizmetinin etkin olduğu 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, akışlı HTTP aktarımı 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 Maps Experience Agent araçlarını etkinleştirin.

API anahtarı kullanarak kimlik doğrulama

Maps Experience 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.

Not: Test ve prototip oluşturma için faturalandırma hesabı olmadan Haritalar Demo Anahtarı'nı ücretsiz olarak da kullanabilirsiniz.

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

1. Google Haritalar Platformu'nu kullanmaya başlama başlıklı makaledeki 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.

Not: Bir API anahtarı oluştururken veya yapılandırırken uygun kısıtlamaları uygulayarak kullanımını sınırlandırın. Daha fazla bilgi için API anahtarlarınızı kısıtlama başlıklı makaleyi inceleyin.

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, Maps Experience 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 temsilci araçları MCP sunucusuna erişecek şekilde yapılandırma

Maps Experience agent tools hizmetini etkinleştirip kimlik bilgilerini 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 temsilci araçları MCP sunucusunun nasıl yapılandırılacağıyla ilgili bir örnek verilmiştir. Daha fazla bilgi için Gemini CLI ile MCP sunucuları bölümüne bakın.

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 düzgün ç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 (5 tools)
   Tools:
   -   compute_routes
   -   lookup_weather
   -   resolve_maps_urls
   -   resolve_names
   -   search_places
   

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

Not: OAuth'u bir Gemini CLI uzantısıyla kullanmak için Google Cloud belgelerindeki MCP'nin Gemini CLI bölümüne bakın.

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.

Not: Maps Experience temsilci araçlarını etkinleştirdiğinizden ve bir API anahtarı aldığınızdan emin olun.

Python

Bu örneğin tam uygulamasını GitHub'daki adk-samples deposunda bulabilirsiniz.

1. adım: Haritalar Deneyimi temsilci araçları için temsilcinizi McpToolset ile tanımlayın

agent.py dosyanızı değiştirin. YOUR_GOOGLE_MAPS_API_KEY kısmını gerçek API anahtarınızla değiştirin.

# ./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"
                }
            )
        )
    ]
)
    

2. adım: __init__.py öğesinin mevcut olduğundan emin olun

agent.py ile aynı dizinde bir __init__.py bulunduğundan emin olun:

from . import agent
    

3. adım: adk web uygulamasını çalıştırın ve etkileşim kurun

1. Ortam değişkenini ayarlayın:
   Google Haritalar API anahtarınızı terminalinizde ortam değişkeni olarak ayarlayın:

   export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
           

2. Çalıştırın adk web:
   ADK web arayüzünü başlatmak için aşağıdaki komutu çalıştırın:

   adk web
           

3. Kullanıcı arayüzünde etkileşim kurma:
   • travel_planner_agent'yi seçin.
   • Aşağıdakilere benzer istemler deneyebilirsiniz:
     • "Yarın San Francisco'da olacağım. Hava nasıl?"
     • "Golden Gate Parkı'nın yakınındaki kafeleri bul."
     • "GooglePlex'ten SFO'ya yol tarifi al."

Java

Java'da McpToolset nesnesini başlatan bir temsilci tanımlayın. Ortam değişkeni kullanmıyorsanız YOUR_GOOGLE_MAPS_API_KEY_HERE kısmını aldığınız gerçek API anahtarıyla değiştirin.

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();
        }
    }
}
    

TypeScript

TypeScript'te MCPToolset aracını başlatan bir temsilci tanımlayın:

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: "SseConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            headers: {
                "X-Goog-Api-Key": googleMapsApiKey,
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream"
            }
        })
    ],
});
    

Geri bildirim paylaşma

Haritalar Deneyimi müşteri temsilcisi 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