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

1. บทนำ

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

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

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

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

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

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

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

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

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

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

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

เริ่มต้น Cloud Shell

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

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

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

gcloud auth list

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

gcloud config get project

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

export PROJECT_ID=$(gcloud config get project)

3. รับโค้ด

โคลนที่เก็บ

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

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

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

cd mcp/examples/launchmybakery

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

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

gcloud auth application-default login

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

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

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

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

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

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

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

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

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

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

5. ติดตั้ง ADK

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

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

python3 -m venv .venv

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

source .venv/bin/activate

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

pip install google-adk==1.28.0

ไปที่ไดเรกทอรีของ 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.1 Pro เวอร์ชันตัวอย่าง)
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: ฟังก์ชันนี้จะกำหนดค่าการเชื่อมต่อกับเซิร์ฟเวอร์ BigQuery MCP โดยจะใช้ google.auth เพื่อดึงข้อมูลเข้าสู่ระบบของ Cloud โดยอัตโนมัติ สร้างโทเค็นผู้ถือ OAuth และแทรกลงในส่วนหัวการให้สิทธิ์

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 จะได้รับการมอบหมายให้แก่ตัวแทน ซึ่งจะทำให้ตัวแทนเข้าถึงความสามารถของทั้ง 2 บริการได้

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

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

กลับไปที่เทอร์มินัลใน 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: ใช้การแสดงตัวอย่างเว็บ

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

ภาพหน้าจอแสดงวิธีเปิด UI ของ ADK

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

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

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

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

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

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

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

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

8. ล้าง

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

เรียกใช้สคริปต์การล้างข้อมูล สคริปต์นี้จะลบชุดข้อมูล BigQuery, Bucket ของ 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 Agent กับเซิร์ฟเวอร์ MCP ระยะไกลที่แตกต่างกัน 2 เครื่อง (BigQuery และ Maps) โดยไม่ต้องเขียน Wrapper API ที่ซับซ้อน
การให้เหตุผลแบบรวม: คุณสร้างเอเจนต์เดียวที่สามารถรวมข้อมูลเชิงลึกจาก 2 โดเมนที่แตกต่างกันอย่างมีกลยุทธ์เพื่อแก้ปัญหาทางธุรกิจ