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

1. บทนำ

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

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

สิ่งที่คุณจะได้ทำ

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

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

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

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

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

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

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

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

เริ่มต้น 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 ที่มีรหัสโปรเจ็กต์และคีย์ API ของ Maps

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

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

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

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

• demographics - ข้อมูลการทำสำมะโนประชากรและลักษณะประชากรตามรหัสไปรษณีย์
• 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==1.28.0

4. ไปที่ไดเรกทอรี Agent

cd adk_agent/

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

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

โค้ด Agent มีให้ในไดเรกทอรี 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.1 Pro Preview)
• tools.py: มีคำจำกัดความของเครื่องมือที่กำหนดเอง
• .env: มีการกำหนดค่าโปรเจ็กต์และความลับ (เช่น คีย์ API) ที่สร้างขึ้นโดยสคริปต์การตั้งค่า

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

ตอนนี้ให้เปิด adk_agent/mcp_bakery_app/tools.py ในตัวแก้ไขเพื่อทำความเข้าใจวิธีเริ่มต้นชุดเครื่องมือ MCP

หากต้องการให้ Agent สื่อสารกับ 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 เพื่อดึงข้อมูลเข้าสู่ระบบคลาวด์โดยอัตโนมัติ สร้างโทเค็น OAuth Bearer และแทรกลงในส่วนหัวการให้สิทธิ์

2. คำจำกัดความของ Agent

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

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

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

root_agent = LlmAgent(
    model='gemini-3.1-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]
)

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

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

7. แชทกับ Agent ของคุณ

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

cd adk_agent/

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

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

เมื่อเซิร์ฟเวอร์เริ่มต้นขึ้น คุณจะเห็นข้อความต่อไปนี้ใน Cloud Shell

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

คุณมี 2 ตัวเลือกในการเข้าถึง UI ของ ADK

ตัวเลือกที่ 1: คลิกลิงก์ในเครื่อง คลิกลิงก์ http://127.0.0.1:8000 ที่ปรากฏในเทอร์มินัล Cloud Shell

ตัวเลือกที่ 2: ใช้การแสดงตัวอย่างเว็บ

1. คลิกปุ่มการแสดงตัวอย่างเว็บ ที่มุมขวาบนของ Cloud Shell
2. เลือกเปลี่ยนพอร์ต
3. ป้อน 8000 เป็นหมายเลขพอร์ต แล้วคลิกเปลี่ยนและแสดงตัวอย่าง

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

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

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

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

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

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

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

เมื่อทดสอบ Agent เสร็จแล้ว คุณสามารถปิดอินเทอร์เฟซเว็บ ADK ได้โดยกด Ctrl+C ในเทอร์มินัล Cloud Shell

8. ล้าง

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

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

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

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

ภารกิจสำเร็จ! คุณได้สร้าง Agent เครื่องมือตำแหน่งอัจฉริยะโดยใช้ Agent Development Kit (ADK) เรียบร้อยแล้ว

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

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

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

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

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