สร้างตัวแทน ADK ข้อมูลเชิงลึกด้านสถานที่ตั้งด้วยเซิร์ฟเวอร์ MCP สำหรับ BigQuery และ Google Maps

1. บทนำ

ใน Codelab นี้ คุณจะได้สร้าง Agent ด้วย ADK ที่ขับเคลื่อนโดย Gemini 3.0 Pro เอเจนต์จะมีเครื่องมือจากเซิร์ฟเวอร์ MCP 2 เครื่องที่อยู่ระยะไกล (โฮสต์โดย Google) เพื่อเข้าถึง BigQuery อย่างปลอดภัยสำหรับข้อมูลด้านประชากรศาสตร์ ราคา และยอดขาย รวมถึง Google Maps สำหรับการวิเคราะห์และตรวจสอบสถานที่ตั้งในโลกแห่งความเป็นจริง

เอเจนต์จะประสานงานคำขอระหว่างผู้ใช้และบริการ Google Cloud เพื่อแก้ปัญหาทางธุรกิจที่เกี่ยวข้องกับชุดข้อมูลร้านเบเกอรี่สมมติ

สิ่งที่คุณต้องทำ

• ตั้งค่าข้อมูล: สร้างชุดข้อมูลเบเกอรี่พื้นฐานใน BigQuery
• พัฒนา Agent: สร้าง Agent อัจฉริยะโดยใช้ Agent Development Kit (ADK)
• ผสานรวมเครื่องมือ: ติดตั้งฟังก์ชันการทำงานของ BigQuery และ Maps ให้กับเอเจนต์ผ่านเซิร์ฟเวอร์ MCP
• วิเคราะห์ตลาด: โต้ตอบกับเอเจนต์เพื่อประเมินแนวโน้มตลาดและความอิ่มตัว

สิ่งที่คุณต้องมี

• เว็บเบราว์เซอร์ เช่น Chrome
• โปรเจ็กต์ Google Cloud ที่เปิดใช้การเรียกเก็บเงิน หรือบัญชี Gmail

Codelab นี้มีไว้สำหรับนักพัฒนาแอปทุกระดับ รวมถึงผู้เริ่มต้น คุณจะใช้อินเทอร์เฟซบรรทัดคำสั่งใน Google Cloud Shell และโค้ด Python สำหรับการพัฒนา ADK คุณไม่จำเป็นต้องเป็นผู้เชี่ยวชาญด้าน Python แต่ความเข้าใจพื้นฐานเกี่ยวกับวิธีอ่านโค้ดจะช่วยให้คุณเข้าใจแนวคิดต่างๆ ได้

2. ก่อนเริ่มต้น

สร้างโปรเจ็กต์ Google Cloud

1. ในคอนโซล Google Cloud ให้เลือกหรือสร้างโปรเจ็กต์ Google Cloud ในหน้าตัวเลือกโปรเจ็กต์

2. ตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ Cloud แล้ว ดูวิธีตรวจสอบว่าได้เปิดใช้การเรียกเก็บเงินในโปรเจ็กต์แล้วหรือไม่

เริ่มต้น Cloud Shell

Cloud Shell คือสภาพแวดล้อมบรรทัดคำสั่งที่ทำงานใน Google Cloud ซึ่งโหลดเครื่องมือที่จำเป็นไว้ล่วงหน้า

1. คลิกเปิดใช้งาน Cloud Shell ที่ด้านบนของคอนโซล Google Cloud

2. เมื่อเชื่อมต่อกับ Cloud Shell แล้ว ให้เรียกใช้คำสั่งนี้เพื่อยืนยันการตรวจสอบสิทธิ์ใน Cloud Shell

gcloud auth list

3. เรียกใช้คำสั่งต่อไปนี้เพื่อยืนยันว่าโปรเจ็กต์ได้รับการกำหนดค่าให้ใช้กับ gcloud แล้ว

gcloud config get project

4. ยืนยันว่าโปรเจ็กต์เป็นไปตามที่คาดไว้ จากนั้นเรียกใช้คำสั่งด้านล่างเพื่อตั้งค่ารหัสโปรเจ็กต์

export PROJECT_ID=$(gcloud config get project)

3. รับโค้ด

โคลนที่เก็บ

1. โคลนที่เก็บไปยังสภาพแวดล้อม Cloud Shell

git clone https://github.com/google/mcp.git

2. ไปที่ไดเรกทอรีการสาธิต

cd mcp/examples/launchmybakery

ตรวจสอบสิทธิ์

เรียกใช้คำสั่งต่อไปนี้เพื่อตรวจสอบสิทธิ์ด้วยบัญชี Google Cloud คุณต้องมีสิทธิ์นี้เพื่อให้ ADK เข้าถึง BigQuery ได้

gcloud auth application-default login

ทำตามข้อความแจ้งเพื่อดำเนินการตรวจสอบสิทธิ์ให้เสร็จสมบูรณ์

หมายเหตุ: ADK จะไม่รีเฟรชโทเค็น OAuth 2.0 โดยอัตโนมัติ หากเซสชันแชทนานกว่า 60 นาที คุณอาจต้องตรวจสอบสิทธิ์อีกครั้งโดยใช้คำสั่งด้านบน

4. กำหนดค่าสภาพแวดล้อมและ BigQuery

เรียกใช้สคริปต์การตั้งค่า

1. เรียกใช้สคริปต์การตั้งค่าสภาพแวดล้อม สคริปต์นี้จะเปิดใช้ BigQuery และ Google Maps API รวมถึงสร้างไฟล์ .env ที่มีรหัสโปรเจ็กต์และคีย์ Maps API

chmod +x setup/setup_env.sh
./setup/setup_env.sh

2. เรียกใช้สคริปต์การตั้งค่า BigQuery สคริปต์นี้จะสร้างที่เก็บข้อมูล Cloud Storage, อัปโหลดข้อมูล และจัดสรรชุดข้อมูลและตาราง BigQuery โดยอัตโนมัติ

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

เมื่อสคริปต์ทำงานเสร็จแล้ว ระบบจะสร้างmcp_bakeryชุดข้อมูลและป้อนข้อมูลลงในตารางต่อไปนี้

• ข้อมูลประชากร - ข้อมูลการทำสำมะโนประชากรและลักษณะประชากรตามรหัสไปรษณีย์
• bakery_prices - รายละเอียดผลิตภัณฑ์และราคาของคู่แข่งสำหรับขนมอบต่างๆ
• sales_history_weekly - ประสิทธิภาพการขายรายสัปดาห์ (ปริมาณและรายได้) ตามร้านค้าและผลิตภัณฑ์
• foot_traffic - คะแนนการเข้าชมหน้าร้านจริงโดยประมาณตามรหัสไปรษณีย์และช่วงเวลาของวัน

3. ยืนยันว่าระบบได้สร้างชุดข้อมูลและตารางแล้วโดยไปที่คอนโซล BigQuery ในโปรเจ็กต์ Google Cloud

5. ติดตั้ง ADK

เมื่อโครงสร้างพื้นฐานพร้อมแล้ว ให้สร้างสภาพแวดล้อม Python เสมือนและติดตั้งแพ็กเกจที่จำเป็นสำหรับ ADK

1. สร้างสภาพแวดล้อมเสมือน

python3 -m venv .venv

2. เปิดใช้งานสภาพแวดล้อมเสมือน

source .venv/bin/activate

3. ติดตั้ง ADK โดยทำดังนี้

pip install google-adk

4. ไปที่ไดเรกทอรีของ Agent โดยใช้คำสั่งต่อไปนี้

cd adk_agent/

6. ตรวจสอบแอปพลิเคชัน ADK

คลิกปุ่มเปิดเครื่องมือแก้ไขใน Cloud Shell เพื่อเปิด Cloud Shell Editor และดูที่เก็บที่โคลนไว้ในไดเรกทอรี mcp/examples/launchmybakery

รหัสตัวแทนมีอยู่ในไดเรกทอรี adk_agent/ อยู่แล้ว มาดูโครงสร้างโซลูชันกัน

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

ไฟล์สำคัญใน mcp_bakery_app

• agent.py: ตรรกะหลักที่กำหนด Agent, เครื่องมือ และโมเดล (Gemini 3.0 Pro เวอร์ชันตัวอย่าง)
• tools.py: มีคำจำกัดความเครื่องมือที่กำหนดเอง
• .env: มีการกำหนดค่าโปรเจ็กต์และข้อมูลลับ (เช่น คีย์ API) ที่สร้างขึ้นโดยสคริปต์การตั้งค่า

1. การเริ่มต้นชุดเครื่องมือ MCP

ตอนนี้ให้เปิด adk_agent/mcp_bakery_app/tools.py ในเอดิเตอร์เพื่อดูว่ามีการเริ่มต้นชุดเครื่องมือ MCP อย่างไร

หากต้องการให้เอเจนต์สื่อสารกับ BigQuery และ Google Maps ได้ เราต้องกำหนดค่าไคลเอ็นต์ Model Context Protocol (MCP)

โค้ดจะสร้างการเชื่อมต่อที่ปลอดภัยกับเซิร์ฟเวอร์ MCP ระยะไกลของ Google โดยใช้ StreamableHTTPConnectionParams

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

• ชุดเครื่องมือ Maps: กำหนดค่าการเชื่อมต่อกับเซิร์ฟเวอร์ MCP ของ Maps โดยใช้คีย์ API
• ชุดเครื่องมือ BigQuery: ฟังก์ชันนี้จะกำหนดค่าการเชื่อมต่อกับเซิร์ฟเวอร์ MCP ของ BigQuery โดยจะใช้ google.auth เพื่อดึงข้อมูลเข้าสู่ระบบของ Cloud โดยอัตโนมัติ สร้างโทเค็นผู้ถือสิทธิ์ OAuth และแทรกลงในส่วนหัวการให้สิทธิ์

2. คำจำกัดความของเอเจนต์

ตอนนี้ให้เปิด adk_agent/mcp_bakery_app/agent.py ในเครื่องมือแก้ไขเพื่อดูวิธีกำหนด Agent

ระบบจะเริ่มต้น LlmAgent ด้วยโมเดล gemini-3-pro-preview

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

• วิธีการของระบบ: ตัวแทนจะได้รับวิธีการที่เฉพาะเจาะจงในการรวมข้อมูลเชิงลึกจากทั้ง BigQuery (สำหรับข้อมูล) และ Maps (สำหรับการวิเคราะห์ตำแหน่ง)
• เครื่องมือ: ระบบจะกำหนดทั้ง maps_toolset และ bigquery_toolset ให้กับตัวแทน ซึ่งจะทำให้ตัวแทนเข้าถึงความสามารถของทั้ง 2 บริการได้

เอเจนต์จะปฏิบัติตามวิธีการและเครื่องมือที่กำหนดไว้ในที่เก็บ คุณสามารถเปลี่ยนแปลงวิธีการเพื่อดูว่าการเปลี่ยนแปลงดังกล่าวส่งผลต่อลักษณะการทำงานของเอเจนต์อย่างไร

7. แชทกับตัวแทน

กลับไปที่เทอร์มินัลใน Cloud Shell แล้วเรียกใช้คำสั่งนี้เพื่อไปยังไดเรกทอรี adk_agent

cd adk_agent

เรียกใช้คำสั่งต่อไปนี้เพื่อเริ่มอินเทอร์เฟซเว็บของ ADK คำสั่งนี้จะเปิดเว็บเซิร์ฟเวอร์ที่มีน้ำหนักเบาเพื่อโฮสต์แอปพลิเคชันแชท

adk web

เมื่อเซิร์ฟเวอร์เริ่มทำงานแล้ว คุณจะแชทกับเอเจนต์ได้โดยคลิก URL ที่ระบุเพื่อเปิดอินเทอร์เฟซเว็บของ ADK

โต้ตอบกับตัวแทนโดยถามคำถามต่อไปนี้ คุณควรเห็นการเรียกใช้เครื่องมือที่เกี่ยวข้อง

1. ค้นหาละแวกใกล้เคียง (มาโคร): "ฉันอยากเปิดร้านเบเกอรี่ในลอสแอนเจลิส ค้นหารหัสไปรษณีย์ที่มีคะแนนการเข้าชมในช่วงเช้าสูงสุด"

ตัวแทนควรใช้เครื่องมืออย่าง get_table_info และ execute_sql เพื่อค้นหาตาราง foot_traffic ใน BigQuery

2. ตรวจสอบความถูกต้องของตำแหน่ง (ขนาดเล็ก): "คุณค้นหา "ร้านเบเกอรี่" ในรหัสไปรษณีย์นั้นเพื่อดูว่ามีการแข่งขันสูงหรือไม่ได้ไหม"

เอเจนต์ควรใช้search placesเครื่องมือในชุดเครื่องมือของ Maps เพื่อตอบคำถามนี้

ทดลองได้เลย ลองดูคำถามตัวอย่างเหล่านี้เพื่อดูการทำงานของเอเจนต์ ADK

• "ฉันกำลังมองหาทำเลที่ตั้งร้านเบเกอรี่แห่งที่ 4 ในลอสแอนเจลิส ฉันต้องการย่านที่มีกิจกรรมตั้งแต่เช้า ค้นหารหัสไปรษณีย์ที่มีคะแนนการเข้าชมในช่วงเช้าสูงสุด"
• "คุณค้นหา "ร้านเบเกอรี่" ในรหัสไปรษณีย์นั้นได้ไหมเพื่อดูว่ามีการแข่งขันสูงหรือไม่ หากมีร้านกาแฟมากเกินไป ให้มองหาร้าน "กาแฟพิเศษ" เพื่อให้ฉันได้ตั้งร้านใกล้ๆ กับร้านเหล่านั้นเพื่อดึงดูดผู้สัญจร"
• "โอเค และฉันต้องการวางตำแหน่งให้เป็นแบรนด์พรีเมียม "ราคาสูงสุดของ "ขนมปังซาวโดว์" ในเขตเมโทรของลอสแอนเจลิสคือเท่าใด"
• "ตอนนี้ฉันต้องการการคาดการณ์รายได้สำหรับเดือนธันวาคม 2025 ดูประวัติการขายของฉันและนำข้อมูลจากร้านค้าที่มีประสิทธิภาพดีที่สุดมาใช้กับ "ขนมปังซาวโดว์" เรียกใช้การคาดการณ์สำหรับเดือนธันวาคม 2025 เพื่อประมาณจำนวนที่ฉันจะขาย จากนั้นคำนวณรายได้รวมที่คาดการณ์โดยใช้ราคาที่ต่ำกว่าราคาพรีเมียมที่เราพบเล็กน้อย (สมมติว่าใช้ราคา $18)"
• "เงินนั้นจะพอจ่ายค่าเช่า สุดท้าย มายืนยันโลจิสติกส์กัน หาร้าน "Restaurant Depot" ที่ใกล้ที่สุดในพื้นที่ที่เสนอ และตรวจสอบว่าใช้เวลาขับรถไม่เกิน 30 นาทีสำหรับการเติมสต็อกรายวัน"

8. ล้างข้อมูล

โปรดลบทรัพยากรที่สร้างขึ้นระหว่าง Codelab นี้เพื่อหลีกเลี่ยงการเรียกเก็บเงินอย่างต่อเนื่องในบัญชี Google Cloud

เรียกใช้สคริปต์การล้างข้อมูล สคริปต์นี้จะลบชุดข้อมูล BigQuery, ที่เก็บข้อมูล Cloud Storage และคีย์ API ที่สร้างขึ้นระหว่างการตั้งค่า

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. ขอแสดงความยินดี

ภารกิจสำเร็จ! คุณสร้าง Location Intelligence Agent โดยใช้ Agent Development Kit (ADK) เรียบร้อยแล้ว

การเชื่อมช่องว่างระหว่างข้อมูล "องค์กร" ใน BigQuery กับบริบทตำแหน่งในโลกแห่งความเป็นจริงจาก Google Maps ทำให้คุณได้สร้างเครื่องมืออันทรงพลังที่สามารถให้เหตุผลทางธุรกิจที่ซับซ้อนได้ โดยทั้งหมดนี้ขับเคลื่อนด้วย Model Context Protocol (MCP) และ Gemini

สิ่งที่คุณทำสำเร็จ

• โครงสร้างพื้นฐานเป็นโค้ด: คุณจัดสรรสแต็กข้อมูลโดยใช้เครื่องมือ Google Cloud CLI
• การผสานรวม MCP: คุณเชื่อมต่อเอเจนต์ AI กับเซิร์ฟเวอร์ MCP ระยะไกลที่แตกต่างกัน 2 เครื่อง (BigQuery และ Maps) โดยไม่ต้องเขียน Wrapper API ที่ซับซ้อน
• การให้เหตุผลแบบรวม: คุณสร้างเอเจนต์เดียวที่สามารถรวมข้อมูลเชิงลึกจาก 2 โดเมนที่แตกต่างกันอย่างมีกลยุทธ์เพื่อแก้ปัญหาทางธุรกิจ

เอกสารอ้างอิง

• ใช้เซิร์ฟเวอร์ MCP ของ BigQuery
• ใช้เซิร์ฟเวอร์ MCP ของ Maps Groundling Lite
• ตรวจสอบสิทธิ์ MCP