Blog E

[GCP 實戰] LINE Bot 遷移大作戰：從 AI Studio 轉向 Vertex AI 解決 429 額度危機

Mon, 20 Apr 2026 00:00:00 +0000

前情提要

最近我們部署在 Google Cloud Run 上的 LINE 名片助理機器人 (linebot-namecard-python) 突然罷工了。透過 gcloud logging read 查了一下日誌，迎面而來的是這個無情的錯誤：

google.api_core.exceptions.ResourceExhausted: 429 Your billing account has exceeded its monthly spending cap.

這是一個慘痛的教訓：我們當初為了快速開發，直接使用了 Google AI Studio 提供的 API Key（走 google.generativeai 套件）。隨著流量增加，我們很快就撞上了 Google AI Studio Tier 1 的 429 限制（Rate Limit / Quota 爆炸），結果默默把每月的免費額度給打爆了。

為了徹底解決這個問題，我們決定將所有依賴 AI Studio Gemini API Key 的應用程式，全面轉換成 Google Cloud Vertex AI，直接走 GCP 的企業級架構與計費系統。

這篇文章就來分享這次遷移的完整過程，以及途中發現「Vertex AI 的資訊實在太少，導致模型設定常常踩坑」的各種血淚經驗。

身份驗證升級：推薦使用 Workload Identity

在遷移的過程中，最重要的一環就是身分驗證。過去我們習慣在環境變數塞一個 GEMINI_API_KEY，簡單粗暴但充滿資安隱患。

來到 GCP 的世界，很多人第一直覺是去開一個 Service Account（服務帳戶），然後把 JSON 金鑰載下來放進程式裡。但強烈建議不要走 Service Account 金鑰這條路！

搭配 gcloud cli，其實可以很快速地為 Cloud Run 設定 Workload Identity。程式碼中不需要任何金鑰，只要在執行環境中賦予該 Identity 對應的 Vertex AI User 權限，Google Cloud SDK 就會自動取得憑證。這樣不僅大幅降低金鑰外洩的風險，管理起來也更輕鬆。

程式碼升級：從 AI Studio 轉向 Vertex AI

要將專案從 Google AI Studio SDK 遷移到 Vertex AI，主要有三個步驟：

替換依賴套件：在 requirements.txt 中，移除舊的 google.generativeai，換成 google-cloud-aiplatform。
更新環境變數設定：在 config.py 中，我們不再需要 API Key，而是改用 GCP 的 PROJECT_ID 和 LOCATION：
```
PROJECT_ID = os.getenv("PROJECT_ID", None)
LOCATION = os.getenv("LOCATION", "global") # 預設使用 global
```

核心程式碼改寫 (gemini_utils.py)： Vertex AI 的 SDK 介面雖然類似，但對於多模態（如圖片）的處理稍微嚴格一點。我們需要將 PIL.Image 轉換成 vertexai.generative_models.Part 格式：

import vertexai
from vertexai.generative_models import GenerativeModel, Part
from io import BytesIO
import PIL.Image
   
# 初始化 Vertex AI
vertexai.init(project=PROJECT_ID, location=LOCATION)
   
def pil_to_bytes(img: PIL.Image.Image) -> bytes:
    img_byte_arr = BytesIO()
    img.save(img_byte_arr, format='JPEG')
    return img_byte_arr.getvalue()
   
def generate_json_from_image(img: PIL.Image.Image, prompt: str) -> object:
    model = GenerativeModel(
        "gemini-3-flash-preview",
        generation_config={"response_mime_type": "application/json"},
    )
    # ⚠️ 注意這裡：必須轉換成 Part 物件
    img_part = Part.from_data(data=pil_to_bytes(img), mime_type="image/jpeg")
    response = model.generate_content([prompt, img_part], stream=False)
    return response

遷移過程中的血淚踩坑：模型都很笨？還是 Vertex AI 資訊太少？

在遷移的過程中，有一種強烈的感覺：「模型好像都很笨（我是說在座的所有 models），還是其實是 Vertex AI 官方給的資訊太少了？」

許多在 AI Studio 上理所當然的設定，搬到 Vertex AI 後卻頻頻報錯。以下整理了幾個最容易踩到、讓人來來回回除錯的深坑：

踩坑一：殘留的舊 SDK 導致 Cloud Run 啟動失敗

滿心歡喜地用 gcloud run services update 更新了環境變數，結果 Cloud Run 部署失敗，容器連啟動都啟動不了。

查了日誌才發現：

ModuleNotFoundError: No module named 'google.generativeai'

原因：雖然 gemini_utils.py 已經改寫好了，但主程式 app/main.py 裡面還殘留著 import google.generativeai as genai 以及 genai.configure(...) 的初始化程式碼。既然 requirements.txt 已經移除了這個套件，容器啟動時自然會找不到模組而崩潰。

解法：全面 grep 專案，徹底移除所有舊版 SDK 的引用，然後使用 Cloud Build 重新打包 Docker image 再次推送。

踩坑二：Region 必須選 global 才有最多跟最新模型

程式碼清乾淨、容器也順利啟動了，但當我在 LINE 傳送圖片時，機器人卻拋出了 500 錯誤。日誌顯示：

google.api_core.exceptions.NotFound: 404 Publisher Model ... was not found or your project does not have access to it.

這是我這次遇到最大的坑！很多人（包含我）直覺上會把 Vertex AI 的 Region 設定跟 Project 或 Cloud Run 的 Region 綁在一起（例如設定為 asia-east1 台灣區）。

但在 Vertex AI 的世界裡，Region 很容易跟 Project Region 搞混。如果你想要使用最新、最完整的模型（例如 gemini-3-flash-preview），你必須將 Vertex AI 的 LOCATION 設定為 global。如果硬是設定成 asia-east1 或 us-central1，常常會遇到 404 找不到模型的窘境。

踩坑三：Model 名稱選錯，造成來來回回錯誤

在 Google AI Studio，你可以很隨意地用 gemini-1.5-flash 這個 alias 甚至省略後綴。但在 Vertex AI，模型名稱的規定非常嚴格且混亂。

如果你名稱選錯（例如少加了 -002，或是預覽版名稱拼錯），API 不是直接報錯，就是默默地 Fallback 跑到舊版的 1.5 模型去執行，導致你覺得「這模型怎麼變笨了？」，結果查了半天才發現根本叫錯了模型。

最終解法與建議：

將 config.py 的預設 region 改為 global。
呼叫 vertexai.init(project="line-vertex", location="global")。
確保使用的模型名稱與 GCP 官方文件完全一致，例如直接指定 gemini-3-flash-preview。

總結：Vertex AI 帶來的改變

經過一番折騰，名片機器人終於滿血復活，並且順利升級到最新的 Gemini 3 Flash Preview 模型。從 AI Studio 遷移到 Vertex AI 後，帶來了幾個顯著的好處：

擺脫 Quota 焦慮：徹底解決 AI Studio Tier 1 的 429 爆炸問題，直接透過 GCP 帳單扣款，適合生產環境。
安全性大躍進：捨棄了明文 API Key 與 Service Account 金鑰，擁抱 Workload Identity，架構更安全現代化。
穩定性：享受企業級的 SLA 保障。

雖然一開始覺得 Vertex AI 資訊太少、模型名稱與 Region 設定讓人頭痛，但只要掌握了 global region 以及 Workload Identity 這兩個訣竅，後續的維護其實是非常香的。

完整程式碼已更新至 GitHub，如果你也有專案正準備從 AI Studio 搬家到 Vertex AI，希望這篇踩坑紀錄能幫你少走一點彎路！

[Gemini 3.1] Gemini-3.1-flash TTS 實戰：更簡單、更強大的朗讀摘要功能

Wed, 15 Apr 2026 00:00:00 +0000

前情提要

在上一篇實戰中，我們利用 Gemini 3.1 Flash Live 實現了語音辨識，並透過 Gemini 2.5 Live API 的「側擊」方式勉強達成了朗讀摘要（TTS）功能。

但就在 2026 年 4 月，Google 正式發佈了 Gemini 3.1 Flash TTS。這是一個專門為語音輸出設計的原生模型，不再需要掛載 Live WebSocket，直接透過標準的 generate_content 流程就能輸出高品質音訊。

身為開發者，有更優雅、更原生的方案當然要立刻跟上。這篇文章就來分享如何把 LINE Bot 的朗讀摘要功能升級到 Gemini 3.1 Native TTS，以及過程中踩到的「異步大坑」。

技術升級：從 Live API 轉向 Native TTS

之前的朗讀功能是利用 Gemini 2.5 Live API 模擬出來的，雖然可用，但有幾個缺點：

複雜度高：需要管理 WebSocket 連線生命週期。
模型限制：必須使用特定的 native-audio 模型，且主要支援在 us-central1。
回傳格式固定：採樣率通常固定在 16kHz。

Gemini 3.1 Flash TTS 的出現改變了這一切：

模型名稱：gemini-3.1-flash-tts-preview。
介面一致：使用熟悉的 generate_content_stream。
動態參數：支援從回傳的 MIME type 自動偵測採樣率（通常提升到了 24kHz，音質更好）。

核心程式碼進化（tools/tts_tool.py）

新的實作變得更加簡潔，重點在於 response_modalities=["audio"] 這個設定：

async def text_to_speech(text: str) -> tuple[bytes, int]:
    client = genai.Client(api_key=GOOGLE_AI_API_KEY, http_options={"api_version": "v1beta"})

    contents = [
        types.Content(
            role="user",
            parts=[
                # 加入在地化指令，讓語氣更自然
                types.Part.from_text(text=f"請使用台灣用語的繁體中文，以親切且自然的語氣朗讀以下摘要內容。## Transcript:\n{text}"),
            ],
        ),
    ]

    config = types.GenerateContentConfig(
        response_modalities=["audio"],
        speech_config=types.SpeechConfig(
            voice_config=types.VoiceConfig(
                prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Zephyr")
            )
        ),
    )

    pcm_chunks = []
    sample_rate = 24000 # 預設值

    try:
        # ⚠️ 這裡就是那個差點讓我修到天亮的大坑
        response_stream = await client.aio.models.generate_content_stream(
            model="gemini-3.1-flash-tts-preview",
            contents=contents,
            config=config,
        )
        async for chunk in response_stream:
            if chunk.parts:
                for part in chunk.parts:
                    if part.inline_data:
                        pcm_chunks.append(part.inline_data.data)
                        # 從 MIME type 動態取得採樣率（例如 audio/L16;rate=24000）
                        if part.inline_data.mime_type:
                            sample_rate = parse_rate(part.inline_data.mime_type)
    except Exception as e:
        logger.error(f"TTS Error: {e}")
        raise

    pcm_bytes = b"".join(pcm_chunks)
    duration_ms = int(len(pcm_bytes) / (sample_rate * 2) * 1000)
    
    # 後續同樣透過 ffmpeg 轉成 m4a 傳給 LINE...

踩過的坑：那個消失的 `await`

這次升級遇到一個非常隱晦的 TypeError，在遠端部署後一直噴出：

TypeError: 'async for' requires an object with __aiter__ method, got coroutine

❌ 錯誤寫法

當初照著範例寫，直覺地以為可以直接 async for 一個 method：

# 這是錯的！
async for chunk in client.aio.models.generate_content_stream(...):
    pass

✅ 正確解法

在 Google GenAI Python SDK 的非同步版本中，generate_content_stream 本身是一個 async 函式，它會回傳一個 iterator。所以你必須先 await 拿到那個 iterator，然後再對它進行 async for。

# 正確做法：分兩步
response_stream = await client.aio.models.generate_content_stream(...)
async for chunk in response_stream:
    pass

這個細節在一般的同步程式碼或某些舊版 SDK 中不一定存在，但在處理 3.1 Flash TTS 的非同步串流時，這是能否成功跑起來的關鍵。

在地化調整：讓 Bot 說「台灣話」

雖然摘要本身已經是繁體中文，但 TTS 模型在朗讀時，有時會帶有非本土的腔調或用語。我們透過 Prompt Engineering 解決了這個問題：

「請使用台灣用語的繁體中文，以親切且自然的語氣朗讀…」

加入這行指令後，Gemini 輸出的音訊在語調起伏和斷句上更接近台灣使用者的習慣，大大提升了「朗讀摘要」的親和力。

總結：Native TTS 帶來的改變

從 Live API 遷移到 Native TTS 之後：

連線更穩定：不再需要維持一個長時間的 WebSocket。
音質提升：原生支援 24kHz 採樣率。
維護容易：程式碼量減少了約 30%，邏輯更直接。

這次經驗也提醒了我，即使是看似成熟的 SDK，在處理 async 模式時仍要仔細檢查回傳值類型。

如果你也想讓你的 LINE Bot 開口說話，Gemini 3.1 Flash TTS 絕對是目前的最佳選擇。

完整程式碼已更新至 GitHub，我們下次見！

[Gemini 3.1] Flash Live 語音辨識實戰：讓 LINE Bot 聽懂你說的話

Sat, 28 Mar 2026 00:00:00 +0000

前情提要

Google 在 2026 年 3 月底發佈了 Gemini 3.1 Flash Live，主打「讓音訊 AI 更自然、更可靠」。這個模型專門針對即時雙向語音對話設計，低延遲、可中斷、支援多語言。

剛好手邊有一個 LINE Bot 專案（linebot-helper-python）——它已經能處理文字、圖片、URL、PDF、YouTube，唯獨語音訊息完全不理：

用戶傳送語音訊息
Bot：（沉默）

這次就把語音支援補進去，順便分享幾個踩過的坑。

設計決策：Flash Live 還是標準 Gemini API？

第一個問題：Gemini 3.1 Flash Live 是為即時串流設計的，但 LINE 的語音訊息是預錄好的 m4a 檔案，不是即時音訊流。

用 Flash Live 處理預錄檔案，就像用直播攝影機拍照——技術上可行，但工具選錯了。

決定用標準 Gemini API——直接把音訊 bytes 當 inline data 傳進去，一次呼叫拿到轉錄文字。更簡單、更適合這個場景。

架構設計

整合思路

這個 repo 已經有完整的 Orchestrator 架構，會依照訊息內容自動路由到不同 Agent（Chat、Content、Location、Vision、GitHub）。語音訊息的目標很明確：

把語音轉成文字，然後當成一般文字訊息丟進 Orchestrator——讓現有的所有功能自動支援語音輸入。

使用者說「幫我搜尋附近的加油站」→ 轉錄成文字 → Orchestrator 判斷是地點查詢 → LocationAgent 處理。不需要為語音另外實作邏輯。

完整流程

用戶傳送 AudioMessage（m4a）
    │
    ▼ handle_audio_message()
    │
    ├─ ① LINE SDK 下載音訊 bytes
    │       get_message_content(message_id) → iter_content()
    │
    ├─ ② Gemini 轉錄
    │       tools/audio_tool.py → transcribe_audio()
    │       model: gemini-3.1-flash-lite-preview
    │
    ├─ ③ Reply #1：「你說的是：{transcription}」
    │       reply_message()（消耗 reply token）
    │
    └─ ④ Reply #2：Orchestrator 路由
            handle_text_message_via_orchestrator(push_user_id=user_id)
            ↓
            push_message()（reply token 已用掉，改用 push）

為什麼要兩段回覆？

回覆分成兩則，讓使用者立刻看到轉錄結果，不用等 Orchestrator 處理完才知道 Bot 有沒有聽懂自己說什麼。

核心程式碼詳解

Step 1：音訊轉錄工具（tools/audio_tool.py）

from google import genai
from google.genai import types

TRANSCRIPTION_MODEL = "gemini-3.1-flash-lite-preview"

async def transcribe_audio(audio_bytes: bytes, mime_type: str = "audio/mp4") -> str:
    """
    Transcribe audio bytes to text using Gemini.
    LINE 語音訊息固定是 m4a，MIME type 固定填 audio/mp4。
    """
    client = genai.Client(
        vertexai=True,
        project=os.getenv("GOOGLE_CLOUD_PROJECT"),
        location=os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1"),
    )

    audio_part = types.Part.from_bytes(data=audio_bytes, mime_type=mime_type)

    response = await client.aio.models.generate_content(
        model=TRANSCRIPTION_MODEL,
        contents=[
            types.Content(
                role="user",
                parts=[
                    audio_part,
                    types.Part(text="請將以上語音內容完整轉錄成文字，保留原語言，不要加任何說明或前綴。"),
                ],
            )
        ],
    )

    return response.text or ""

設計原則：函式本身不 catch exception，讓上層 handler 統一處理錯誤回覆。

Step 2：handler 主流程（main.py）

async def handle_audio_message(event: MessageEvent):
    """Handle audio (voice) messages — transcribe and route through Orchestrator."""
    user_id = event.source.user_id
    replied = False  # 追蹤 reply token 是否已使用
    try:
        # 下載音訊
        message_content = await line_bot_api.get_message_content(event.message.id)
        audio_bytes = b""
        async for chunk in message_content.iter_content():
            audio_bytes += chunk

        # 轉錄
        transcription = await transcribe_audio(audio_bytes)

        # 空轉錄（無聲或太短）
        if not transcription.strip():
            await line_bot_api.reply_message(
                event.reply_token,
                [TextSendMessage(text="無法辨識語音內容，請重新錄製。")]
            )
            return

        # Reply #1：讓使用者確認轉錄結果（消耗 reply token）
        await line_bot_api.reply_message(
            event.reply_token,
            [TextSendMessage(text=f"你說的是：{transcription.strip()}")]
        )
        replied = True

        # Reply #2：送進 Orchestrator，用 push_message（token 已用掉）
        await handle_text_message_via_orchestrator(
            event, user_id,
            text=transcription.strip(),
            push_user_id=user_id,
        )

    except Exception as e:
        logger.error(f"Error handling audio for {user_id}: {e}", exc_info=True)
        error_text = LineService.format_error_message(e, "處理語音訊息")
        error_msg = TextSendMessage(text=error_text)
        if replied:
            # reply token 已消耗，改用 push
            await line_bot_api.push_message(user_id, [error_msg])
        else:
            await line_bot_api.reply_message(event.reply_token, [error_msg])

Step 3：讓 Orchestrator 支援外部傳入文字

原本的 handle_text_message_via_orchestrator 直接讀 event.message.text，AudioMessage 沒有 .text，所以加兩個 optional 參數：

async def handle_text_message_via_orchestrator(
    event: MessageEvent,
    user_id: str,
    text: str = None,           # ← 外部傳入文字（語音轉錄）
    push_user_id: str = None,   # ← 設定時改用 push_message
):
    msg = text if text is not None else event.message.text.strip()
    try:
        result = await orchestrator.process_text(user_id=user_id, message=msg)
        response_text = format_orchestrator_response(result)
        reply_msg = TextSendMessage(text=response_text)

        if push_user_id:
            await line_bot_api.push_message(push_user_id, [reply_msg])
        else:
            await line_bot_api.reply_message(event.reply_token, [reply_msg])
    except Exception as e:
        error_msg = TextSendMessage(text=LineService.format_error_message(e, "處理您的問題"))
        if push_user_id:
            await line_bot_api.push_message(push_user_id, [error_msg])
        else:
            await line_bot_api.reply_message(event.reply_token, [error_msg])

text is not None（而非 text or ...）是刻意的——萬一語音轉錄出空字串，要讓空字串通過（然後被上層的 if not transcription.strip() 攔掉），不是 fallback 到 event.message.text。

踩過的坑

❌ 坑 1：`Part.from_text()` 不接受 positional argument

最先遇到的 TypeError：

# ❌ 錯誤（TypeError: Part.from_text() takes 1 positional argument but 2 were given）
types.Part.from_text(
    "請將以上語音內容完整轉錄成文字，保留原語言，不要加任何說明或前綴。"
)

# ✅ 正確
types.Part(text="請將以上語音內容完整轉錄成文字，保留原語言，不要加任何說明或前綴。")

在這個版本的 SDK 中，Part.from_text() 的 text 是 keyword argument，或者直接用 Part(text=...) 建構子更保險。

❌ 坑 2：LINE reply token 只能用一次

LINE 的 reply token 是一次性的。一旦呼叫 reply_message()，token 就失效了。

這個專案的語音流程會呼叫兩次：

Reply #1（顯示轉錄文字）→ 消耗 token
Reply #2（Orchestrator 結果）→ token 已失效，會收到 LINE 400 error

解法是讓 Orchestrator handler 支援 push_message 模式（透過 push_user_id 參數），Reply #2 改走 push_message。

錯誤處理也要注意：如果 Reply #1 成功後 Orchestrator 才拋例外，except block 裡也不能再用 reply_message，同樣要改成 push_message。這就是程式碼裡 replied flag 的用途。

❌ 坑 3：Gemini Flash Live 不適合預錄檔案

不是真正的「坑」，但值得說清楚：

Gemini 3.1 Flash Live 是為即時雙向串流設計，有連線建立和串流協定的開銷。LINE 語音訊息是完整的預錄 m4a，一次性處理即可。

直接用 client.aio.models.generate_content() 傳 inline audio bytes，更簡單，延遲也不差。Flash Live 留給真正需要即時對話的場景。

效果展示

場景 1：語音指令查詢

用戶傳送：[語音] 幫我搜尋台北車站附近的咖啡廳

Bot Reply #1：你說的是：幫我搜尋台北車站附近的咖啡廳
Bot Reply #2：[LocationAgent 回覆附近咖啡廳清單]

場景 2：語音問問題

用戶傳送：[語音] Gemini 和 GPT-4 有什麼差別

Bot Reply #1：你說的是：Gemini 和 GPT-4 有什麼差別
Bot Reply #2：[ChatAgent 搭配 Google Search Grounding 回覆比較結果]

場景 3：語音發 URL

用戶傳送：[語音] 幫我摘要這篇文章 https://example.com/article

Bot Reply #1：你說的是：幫我摘要這篇文章 https://example.com/article
Bot Reply #2：[ContentAgent 抓取並摘要文章]

語音轉錄出來的文字直接進 Orchestrator，現有的 URL 偵測、意圖判斷全部照常運作，零額外邏輯。

傳統文字輸入 vs 語音輸入

	文字輸入	語音輸入
輸入格式	TextMessage	AudioMessage（m4a）
前處理	無	Gemini 轉錄
reply token	直接用	Reply #1 消耗，Reply #2 改 push
Orchestrator	直接路由	轉錄文字後路由
支援功能	全部	全部（無需額外設定）
錯誤處理	reply_message	replied flag 判斷 reply/push

分析與展望

這次整合最讓我滿意的是幾乎不用改 Orchestrator 本身。只要在輸入端把語音轉成文字，後面所有的路由邏輯、Agent 呼叫、錯誤處理全都自動繼承。

Gemini 的多模態音訊理解在這個場景裡表現很穩——繁體中文、台語腔調、夾雜英文的句子基本上都能準確轉錄。

未來可以延伸的方向：

多語言自動偵測：轉錄時告訴 Gemini 保留原語言，日文語音→日文轉錄，再由 Orchestrator 決定要不要翻譯
群組語音支援：目前只限 1:1，群組的語音訊息暫時忽略
長錄音摘要：超過一定長度的錄音直接走 ContentAgent 做摘要，而非當指令處理

延伸：🔊 朗讀摘要——讓 Bot 說話

語音辨識讓 Bot「聽懂」使用者說的話。這件事做完之後，自然就有了下一個問題：

Bot 能不能說話回應？

Gemini Live API 有一個 response_modalities: ["AUDIO"] 的設定，可以直接輸出音訊 PCM 串流。我把它接上了另一個場景——朗讀摘要。

功能設計

每次 Bot 摘要完一個 URL、YouTube 或 PDF，訊息底下都會出現「🔊 朗讀」的 QuickReply 按鈕。使用者按下去，Bot 把摘要文字送進 Gemini Live TTS，把 PCM 音訊轉成 m4a，然後用 AudioSendMessage 傳回去。

URL 摘要完成
    │
    ▼ [🔊 朗讀] QuickReply 按鈕
    │
用戶按下按鈕 → PostbackEvent
    │
    ▼ handle_read_aloud_postback()
    │
    ├─ ① 從 summary_store 取出摘要文字（10 分鐘 TTL）
    │
    ├─ ② Gemini Live API → PCM 音訊
    │       model: gemini-live-2.5-flash-native-audio
    │       response_modalities: ["AUDIO"]
    │
    ├─ ③ ffmpeg 轉檔：PCM → m4a
    │       s16le, 16kHz, mono → AAC
    │
    └─ ④ AudioSendMessage 傳給使用者
            original_content_url: /audio/{uuid}
            duration: {ms}

核心程式碼（tools/tts_tool.py）

LIVE_MODEL = "gemini-live-2.5-flash-native-audio"

async def text_to_speech(text: str) -> tuple[bytes, int]:
    client = genai.Client(vertexai=True, project=VERTEX_PROJECT, location="us-central1")
    config = {"response_modalities": ["AUDIO"]}

    async with client.aio.live.connect(model=LIVE_MODEL, config=config) as session:
        await session.send_client_content(
            turns=types.Content(role="user", parts=[types.Part(text=text)]),
            turn_complete=True,
        )
        pcm_chunks = []
        async for message in session.receive():
            if message.server_content and message.server_content.model_turn:
                for part in message.server_content.model_turn.parts:
                    if part.inline_data and part.inline_data.data:
                        pcm_chunks.append(part.inline_data.data)
            if message.server_content and message.server_content.turn_complete:
                break

    pcm_bytes = b"".join(pcm_chunks)
    duration_ms = int(len(pcm_bytes) / 32000 * 1000)  # 16kHz × 16-bit mono

    # PCM → m4a（temp file 模式，避免 moov atom 問題）
    with tempfile.NamedTemporaryFile(suffix=".pcm", delete=False) as f:
        f.write(pcm_bytes)
        pcm_path = f.name
    m4a_path = pcm_path.replace(".pcm", ".m4a")
    subprocess.run(
        ["ffmpeg", "-y", "-f", "s16le", "-ar", "16000", "-ac", "1",
         "-i", pcm_path, "-c:a", "aac", m4a_path],
        check=True, capture_output=True,
    )
    with open(m4a_path, "rb") as f:
        return f.read(), duration_ms

朗讀功能踩的坑

❌ 坑 4：模型名稱完全不同

Gemini Live TTS 的第一個嘗試是：

LIVE_MODEL = "gemini-3.1-flash-live-preview"

照著語音辨識用的 gemini-3.1-flash-lite-preview 推導的，結果直接 1008 policy violation：

Publisher Model `projects/line-vertex/locations/global/publishers/google/
models/gemini-3.1-flash-live-preview` was not found

列出 Vertex AI 可用模型才發現，Live/native audio 的模型命名規則完全不同：

# ✅ 正確
LIVE_MODEL = "gemini-live-2.5-flash-native-audio"

Gemini 3.1 在 Vertex AI 上沒有 Live 版本。Live/native audio 功能目前是 2.5 世代，命名格式是 gemini-live-{version}-{variant}-native-audio，跟一般模型的 gemini-{version}-flash-{variant} 完全是兩套邏輯。

❌ 坑 5：`GOOGLE_CLOUD_LOCATION=global` 讓 Live API 失聯

換了正確的模型名稱之後，錯誤訊息還是一樣：

Publisher Model `projects/line-vertex/locations/global/...` was not found

這次 model 名稱正確了，但 locations/global 很奇怪——我們明明設定了 us-central1。

追查 Google GenAI SDK 的原始碼發現：

# _api_client.py
self.location = location or env_location
if not self.location and not self.api_key:
    self.location = 'global'  # ← 這裡

location or env_location——如果傳進去的 location 是空字串，就會 fallback 到 global。

問題根源是 Cloud Run 的環境變數：

{ "name": "GOOGLE_CLOUD_LOCATION", "value": "global" }

GOOGLE_CLOUD_LOCATION 被設成了 "global" 字串。os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1") 拿到的不是 "us-central1"，而是 "global"——然後 SDK 乖乖連到 global endpoint，但 gemini-live-2.5-flash-native-audio 在 global 沒有 BidiGenerateContent 支援。

Endpoint	標準 API	Live API
`global`	✅ 可用	❌ 模型不在這裡
`us-central1`	✅ 可用	✅ `gemini-live-2.5-flash-native-audio`

解法：Live API 的 location 直接硬寫，不從 env var 讀：

# ❌ 受 GOOGLE_CLOUD_LOCATION=global 影響
VERTEX_LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1")

# ✅ 硬寫，不受 env var 干擾
VERTEX_LOCATION = "us-central1"  # Live API 需要 regional endpoint

語音辨識 vs 朗讀摘要

兩個功能用了完全不同的 Gemini API：

	語音辨識	朗讀摘要
方向	音訊 → 文字	文字 → 音訊
API	標準 `generate_content`	Live API `BidiGenerateContent`
模型	`gemini-3.1-flash-lite-preview`	`gemini-live-2.5-flash-native-audio`
Location	跟著 env var	硬寫 `us-central1`
輸出格式	text	PCM → ffmpeg → m4a
LINE 訊息類型	輸入：`AudioMessage`	輸出：`AudioSendMessage`

總結

Gemini 3.1 Flash Live 的發布讓音訊 AI 更值得認真對待。這次把語音辨識和朗讀摘要都接進了 LINE Bot：

語音辨識：標準 Gemini API，預錄 m4a 一次轉錄，接進現有 Orchestrator
朗讀摘要：Gemini Live TTS，摘要文字轉 PCM，ffmpeg 轉 m4a，AudioSendMessage 傳回

最麻煩的不是功能本身，而是找到正確的模型名稱和定位 SDK 的 location 邏輯——這兩個都沒有在文件顯眼的地方寫清楚，只能靠列出可用模型、讀 SDK 原始碼才找到答案。

完整程式碼在 GitHub，歡迎參考。

我們下次見！

[Gemini] Tool Combo 實戰：在單次 API 呼叫中結合 Maps Grounding 與 Places API 打造 LINE 聚會地點小幫手

Thu, 26 Mar 2026 00:00:00 +0000

參考文章：

Gemini API tooling updates: context circulation, tool combos and Maps grounding for Gemini 3
Google Places API (New) - searchNearby
GitHub: linebot-spot-finder
完整程式碼 GitHub (聚會小幫手 LINE Bot Spot Finder)

前情提要

LINE Bot + Gemini 的組合已經很常見，不管是用 Google Search Grounding 讓模型查即時資訊，還是用 Function Calling 讓模型呼叫自訂邏輯，單獨使用都很成熟。

但如果你想在同一個問題裡同時做到「地圖定位情境」和「查詢真實評分」呢？

以餐廳搜尋來說，傳統做法通常長這樣：

用戶: "幫我找附近評價4星以上的熱炒店"

方案 A（只用 Maps Grounding）：
Gemini 有地圖情境，但評分資訊是 AI 自行描述，不保證準確。

方案 B（只用 Places API）：
可以拿到真實評分，但沒有地圖情境，Gemini 不知道用戶在哪裡。

要兩者兼得，通常需要分兩次 API 呼叫，或是自己手動串接。

AI 能查地圖、也能呼叫外部 API，但要在一次呼叫裡同時做到這兩件事——在 Gemini API 的舊架構下一直是個尷尬的空白。

直到 2026 年 3 月 17 日，Google 發布了 Gemini API Tooling Updates（作者：Mariano Cocirio），這個問題才有了官方解法。

什麼是 Tool Combinations？

Google 在這次更新中宣布了三個核心功能：

1. Tool Combinations（工具組合） 開發者現在可以在單次 Gemini API 呼叫中同時掛上 built-in 工具（如 Google Search、Google Maps）以及自訂 Function Declarations。模型自行決定要呼叫哪個工具、何時呼叫，最後整合結果生成回答。

2. Maps Grounding Gemini 現在可以直接感知地圖資料，不再只是文字描述「位置」，而是真正具備空間情境——知道用戶在哪裡、附近有什麼。

3. Context Circulation 讓多輪工具呼叫之間的情境能自然流通，模型在第二次呼叫時能完整記憶第一次的工具呼叫結果。

這次改動的關鍵在於：

# 舊的做法（兩個工具不能並存）
types.Tool(google_search=types.GoogleSearch())
types.Tool(function_declarations=[MY_FN])

# 新的做法（同一個 Tool 物件，兩者共存）
types.Tool(
    google_maps=types.GoogleMaps(),
    function_declarations=[MY_FN],
)

一行改動，打開了全新的組合方式。

專案目標

這次我用 Tool Combinations 改造了既有的 linebot-spot-finder，讓它從「只能 Maps Grounding 粗略回答」升級到「Google Maps 情境 + Places API 真實資料」：

用戶傳送 GPS 位置後輸入：「請找評價 4 顆星以上、適合多人聚餐的熱炒店，列出名稱、地址和評論摘要。」

Bot（舊版 Maps Grounding）：「附近有幾間熱炒店，評價都不錯。」（AI 自行描述，可能不準）

Bot（新版 Tool Combo）：「老王熱炒｜台北市信義區市民大道100號｜評分 4.6（312則）｜評論：份量大、CP值高，適合聚餐；服務效率高，上菜快。」

差別在於：Gemini 現在同時收到地圖情境（你在哪裡）和 Places API 的真實結構化資料（評分數字、評論文字），回答因此從「模糊描述」變成「有根據的資訊」。

架構設計

整體訊息流程

LINE User 傳送 GPS 位置
    │
    ▼
handle_location()  →  session.metadata 儲存 lat/lng
    │
    └──► 回傳 Quick Reply（餐廳 / 加油站 / 停車場）

LINE User 傳送文字問題（e.g. "找評價4星以上的熱炒店"）
    │
    ▼
handle_text()
    │
    ├── session 有 lat/lng？
    │       是 → tool_combo_search(query, lat, lng)   ← 本文重點
    │       否 → fallback: Gemini Chat + Google Search
    │
    └──► 回傳自然語言答覆

Tool Combo Agentic Loop

tool_combo_search(query, lat, lng)
         │
         ▼
  Step 1: generate_content()
  tools = [google_maps + search_nearby_restaurants]
         │
         ▼
  response.candidates[0].content.parts 裡有 function_call？
       ╱                              ╲
      是                               否
      │                                │
      ▼                                ▼
  _execute_function()           直接回傳 response.text
  → _call_places_api()
    （Places API searchNearby）
    回傳評分、地址、評論
      │
      ▼
  收集成單一 Content(role="user")
  加入 history
      │
      ▼
  Step 3: generate_content(contents=history)
  Gemini 整合地圖情境 + Places 資料
      │
      ▼
  回傳 final.text

為什麼 lat/lng 不放在 Function Declaration 裡？

這是設計上一個重要決策。

如果把 lat/lng 加進 SEARCH_NEARBY_RESTAURANTS_FN 的 parameters，Gemini 會自己填入座標——但它填的是從對話推斷的「大概位置」，不是用戶實際 GPS 座標，誤差可能高達數公里。

正確做法是讓 Python dispatcher 從 session.metadata 取出精確座標，注入進去：

def _execute_function(name: str, args: dict, lat: float, lng: float):
    if name == "search_nearby_restaurants":
        return _call_places_api(
            lat=lat, lng=lng,          # ← 從 session 注入，不讓 Gemini 猜
            keyword=args.get("keyword", ""),
            min_rating=float(args.get("min_rating", 4.0)),
        )

核心程式碼詳解

Step 1：定義 Function Declaration

from google.genai import types

SEARCH_NEARBY_RESTAURANTS_FN = types.FunctionDeclaration(
    name="search_nearby_restaurants",
    description=(
        "用 Google Places API 搜尋附近餐廳，回傳評分、地址與用戶評論。"
        "lat/lng 由系統自動帶入，不需要提供。"
    ),
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "keyword": types.Schema(
                type=types.Type.STRING,
                description="餐廳類型或關鍵字，例如：熱炒、火鍋、義式",
            ),
            "min_rating": types.Schema(
                type=types.Type.NUMBER,
                description="最低評分門檻（1–5），預設 4.0",
            ),
            "radius_m": types.Schema(
                type=types.Type.INTEGER,
                description="搜尋半徑（公尺），預設 1000",
            ),
        },
    ),
)

description 裡明確告訴模型「lat/lng 由系統帶入」，避免模型在 args 裡自己填座標。

Step 2：Places API 呼叫

import httpx

PLACES_API_URL = "https://places.googleapis.com/v1/places:searchNearby"
PLACES_FIELD_MASK = (
    "places.displayName,"
    "places.rating,"
    "places.userRatingCount,"
    "places.formattedAddress,"
    "places.reviews"
)

def _call_places_api(lat, lng, keyword="", min_rating=4.0, radius_m=1000):
    body = {
        "includedTypes": ["restaurant"],
        "maxResultCount": 5,
        "locationRestriction": {
            "circle": {
                "center": {"latitude": lat, "longitude": lng},
                "radiusMeters": radius_m,
            }
        },
    }

    response = httpx.post(
        PLACES_API_URL,
        headers={
            "X-Goog-Api-Key": os.getenv("GOOGLE_MAPS_API_KEY"),
            "X-Goog-FieldMask": PLACES_FIELD_MASK,
        },
        json=body,
        timeout=10.0,
    )
    response.raise_for_status()
    data = response.json()

    restaurants = []
    for place in data.get("places", []):
        rating = place.get("rating", 0)
        if rating < min_rating:
            continue
        reviews = [
            r["text"]["text"]
            for r in place.get("reviews", [])[:3]
            if r.get("text", {}).get("text")
        ]
        restaurants.append({
            "name": place["displayName"]["text"],
            "address": place.get("formattedAddress", ""),
            "rating": rating,
            "rating_count": place.get("userRatingCount", 0),
            "reviews": reviews,
        })

    return {"restaurants": restaurants}

Step 3：Tool Combo 主函式（Agentic Loop）

async def tool_combo_search(query: str, lat: float, lng: float) -> str:
    client = genai.Client(
        vertexai=True,
        project=os.getenv("GOOGLE_CLOUD_PROJECT"),
        location=os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1"),
        http_options=types.HttpOptions(api_version="v1"),
    )

    enriched_query = (
        f"用戶目前位置：緯度 {lat}，經度 {lng}。\n"
        f"請用台灣用語的繁體中文回答，不要使用 markdown 格式。\n\n"
        f"問題：{query}"
    )

    tool_config = types.GenerateContentConfig(
        tools=[
            types.Tool(
                google_maps=types.GoogleMaps(),                      # ← Maps grounding
                function_declarations=[SEARCH_NEARBY_RESTAURANTS_FN], # ← Places API
            )
        ],
    )

    # ── Step 1 ──────────────────────────────────────────────────────
    response = client.models.generate_content(
        model=TOOL_COMBO_MODEL,
        contents=enriched_query,
        config=tool_config,
    )

    if not response.candidates:
        return response.text or "（無法取得回覆）"

    history = [
        types.Content(role="user", parts=[types.Part(text=enriched_query)]),
        response.candidates[0].content,
    ]

    # ── Step 2：處理 function_call ──────────────────────────────────
    function_response_parts = []
    for part in response.candidates[0].content.parts:
        if part.function_call:
            fn = part.function_call
            result = _execute_function(fn.name, dict(fn.args or {}), lat, lng)
            function_response_parts.append(
                types.Part(
                    function_response=types.FunctionResponse(
                        id=fn.id, name=fn.name, response=result,
                    )
                )
            )

    if function_response_parts:
        history.append(types.Content(role="user", parts=function_response_parts))

        # ── Step 3 ────────────────────────────────────────────────────
        final = client.models.generate_content(
            model=TOOL_COMBO_MODEL,
            contents=history,
            config=tool_config,
        )
        return final.text or "（無法取得回覆）"

    return response.text or "（無法取得回覆）"

踩過的坑

❌ 坑 1：`Part.from_function_response()` 不接受 `id` 參數

這是這次最容易踩的坑，而且錯誤只在真實模型呼叫時才會爆，單元測試幾乎不會發現。

原本參考官方範例這樣寫：

# ❌ 錯誤——TypeError 在 runtime 發生
types.Part.from_function_response(
    id=fn.id,       # ← 這個參數不存在！
    name=fn_name,
    response=result,
)

from_function_response 的實際簽名是：

(*, name: str, response: dict, parts: Optional[list] = None) -> Part

完全沒有 id 參數。每次模型真的觸發 function_call，程式就會在這行噴 TypeError，然後靜默進入 Step 3 的 except，回傳錯誤訊息，Places API 的結果從來沒有真正傳回給 Gemini。

正確寫法是直接建構 types.FunctionResponse：

# ✅ 正確
types.Part(
    function_response=types.FunctionResponse(
        id=fn.id,
        name=fn_name,
        response=result,
    )
)

用 python -c "from google.genai import types; help(types.Part.from_function_response)" 可以立刻確認參數清單。

❌ 坑 2：`include_server_side_tool_invocations=True` 讓 Pydantic 爆炸

看到官方文件範例加了這個參數覺得應該加：

# ❌ 錯誤
types.GenerateContentConfig(
    tools=[...],
    include_server_side_tool_invocations=True,  # ← 安裝的 SDK 版本不支援
)

在 google-genai 1.49.0 這個欄位還不在 GenerateContentConfig 的 model fields 裡，Pydantic 會直接噴 extra_forbidden 驗證錯誤。直接拿掉就好，功能完全正常。

❌ 坑 3：`textQuery` 是 `searchText` 的參數，不是 `searchNearby` 的

想說「有 keyword 就帶進 Places API」，直覺把它加進 request body：

# ❌ 錯誤——對 searchNearby endpoint 是無效欄位
if keyword:
    body["textQuery"] = keyword

searchNearby 只接受 includedTypes、locationRestriction 等欄位；textQuery 是 searchText endpoint 的參數。帶了這個欄位不會報錯（某些版本下），但 keyword 完全不生效。

正確的做法是把 keyword 留在 Function Declaration 的 description 裡給 Gemini 參考，讓模型把意圖轉譯到 enriched_query 上，讓 Maps Grounding 去處理關鍵字語意，Places API 只負責回傳真實評分資料。

❌ 坑 4：`response.candidates[0]` 沒有 guard

模型在遇到安全過濾、RECITATION、或其他非正常終止時，candidates 可能是空 list，這時直接 response.candidates[0] 就是 IndexError。

# ❌ 沒有 guard
history = [
    types.Content(role="user", parts=[types.Part(text=enriched_query)]),
    response.candidates[0].content,   # ← 如果 candidates 是空的就爆
]

# ✅ 加 guard
if not response.candidates:
    return response.text or "（無法取得回覆）"

history = [...]

Demo 展示

場景 1：「找評價 4 顆星以上的聚餐熱炒店」

用戶傳送：GPS 位置（台北市信義區，25.0441, 121.5598）

用戶輸入：「請找評價 4 顆星以上、適合多人聚餐的熱炒店，列出名稱、地址和評論摘要。」

[Step 1: Gemini 收到 query + 地圖情境]
  → 偵測到需要餐廳資料，emit function_call:
    search_nearby_restaurants(keyword="熱炒", min_rating=4.0)

[Step 2: Python 呼叫 Places API]
  → lat=25.0441, lng=121.5598 從 session 注入
  → 回傳 3 間評分 ≥ 4.0 的餐廳，含評論文字

[Step 3: Gemini 整合 Maps 情境 + Places 資料]
  → 「老王熱炒｜信義區市民大道100號｜⭐ 4.6（312則）
      評論摘要：份量大、CP值高，朋友聚餐首選；服務快，菜色新鮮。
     ...（共3間）」

場景 2：「有沒有 CP 值高的日式料理？」

用戶輸入：「附近有沒有 CP 值高的日式料理？」

[Step 1: Gemini]
  → function_call: search_nearby_restaurants(keyword="日式料理", min_rating=4.0)

[Step 2: Places API]
  → 回傳 2 間評分符合的日本料理店

[Step 3: Gemini]
  → 「有兩間推薦：
      和食処○○｜...｜⭐ 4.4｜評論：平日午間定食只要280元，新鮮度很高。
      ...」

Demo Script 快速測試

不需要 LINE Bot，直接在本機：

# 只測試 Tool Combo（主功能）
python demo.py combo

# 三個功能全跑
python demo.py all

舊架構 vs 新架構

	舊架構（Maps Grounding only）	新架構（Tool Combo）
工具	`google_maps`（built-in）	`google_maps` + `search_nearby_restaurants`（custom）
評分資料	Gemini 自行描述（可能不準）	Places API 真實數字
評論	AI 生成	真實用戶評論（最多3則）
API 呼叫次數	1次	1次（Step1）+ 1次（Step3）= 2次，但對用戶透明
準確度	中	高
自訂過濾	靠 prompt	`min_rating`、`radius_m` 精確控制

分析與展望

這次實作讓我對 Gemini Tool Combinations 的潛力有了更清楚的認識。

Tool Combinations 真正解決的問題，是讓 Grounding 和 Function Calling 不再是二選一。以前要做「有地圖情境 + 有真實外部資料」，只能自己在應用層手動串兩次 API，或是用 Gemini 的文字生成去「模擬」外部資料（不可靠）。現在模型自己知道何時該用地圖情境、何時該呼叫 Places API，開發者只需要把工具掛上去。

不過這次實作也有幾個值得注意的地方：

lat/lng 注入模式很重要：不能讓模型自己猜座標，一定要從 session 注入，否則定位精度會很差。這個模式也適用於所有「有 session 狀態」的 function calling 場景。
兩次 generate_content 的成本：Tool Combo 的 agentic loop 需要兩次模型呼叫，token 消耗大約是單次的 1.5–2 倍。對低延遲要求高的場景要特別考量。
SDK 版本差異：google-genai 各版本對 GenerateContentConfig 的欄位支援不同，include_server_side_tool_invocations 這類新欄位加版本號確認再用，否則 Pydantic 驗證錯誤很難追。

未來可以延伸的方向：

把 Postback 快速回覆（點「找餐廳」按鈕）也接上 Tool Combo，讓每個入口都能拿到真實評分
加入 searchText endpoint 支援更複雜的關鍵字搜尋（e.g. 米其林推薦）
Tool Combo 搭配其他 built-in 工具（如 google_search）實現更複雜的多工具串接

總結

這次改動的核心概念只有一句話：把 Google Maps grounding 和 Places API function tool 掛在同一個 types.Tool 裡，Gemini 就會在單次對話裡自己協調兩者。

關鍵程式只有這幾行：

# 這就是 Tool Combo 的全部魔法
types.Tool(
    google_maps=types.GoogleMaps(),                       # ← Maps 情境
    function_declarations=[SEARCH_NEARBY_RESTAURANTS_FN], # ← Places API
)

但要讓它真的 work，還需要注意：FunctionResponse 的建構方式、candidates 的 guard、Places API endpoint 的正確欄位、以及 lat/lng 從 session 注入而不是讓模型猜。

完整程式碼在 GitHub，歡迎 clone 來玩。

我們下次見！

AI Agent 的安全性宣告：深入探索 A2AS (Agent-to-Agent Security) 憑證機制

Wed, 25 Mar 2026 00:00:00 +0000

參考連結：

這篇文章記錄了我在維護 linebot-adk (LINE Bot Agent Development Kit) 時，收到的一個有趣 Pull Request：為專案加上 A2AS 安全憑證。這不只是一個 YAML 檔案，更是 2026 年 AI Agent 邁向「工業級安全」的重要里程碑。

前情提要

當我們在開發像 linebot-adk 這樣具備 Tool Use (Function Calling) 能力的 Agent 時，使用者最擔心的問題往往是：「這個 Agent 會不會背著我亂下指令？」或是「它到底能存取哪些資料？」。

傳統上我們只能在 README.md 寫寫說明，但那是給人看的，不是給系統驗證的。這就是為什麼 A2AS (Agent-to-Agent Security) 出現了——它被譽為「AI 界的 HTTPS」。

🛠️ 第一步：理解 A2AS 的 BASIC 模型

A2AS 不只是個名稱，它背後有一套完整的 BASIC 安全模型，旨在解決 AI Agent 之間的信任問題：

(B)ehavior Certificates: 宣告式憑證，明確定義 Agent 的行為邊界。
(A)uthenticated Prompts: 確保提示詞的來源可信且具備追蹤性。
(S)ecurity Boundaries: 利用結構化標籤（如 <a2as:user>）隔離不受信任的輸入。
(I)n-Context Defenses: 在 Prompt 中嵌入防禦邏輯，拒絕惡意注入。
(C)odified Policies: 將業務規則寫成程式碼，在推論時強制執行。

🎨 第二步：解構 a2as.yaml——Agent 的身份證

在 linebot-adk 收到 PR #1 中，最核心的變動就是新增了 a2as.yaml。這個檔案就像是 Agent 的「數位簽名」，將程式碼邏輯顯性化：

manifest:
  subject:
    name: kkdai/linebot-adk
    scope: [main.py, multi_tool_agent/agent.py]
  issued:
    by: A2AS.org
    url: https://a2as.org/certified/agents/kkdai/linebot-adk

agents:
  root_agent:
    type: instance
    models: [gemini-2.5-flash]
    tools: [get_weather, get_current_time]

為什麼這很重要？

這份憑證直接與我們的 main.py 內容掛鉤。當憑證宣告了 tools: [get_weather, get_current_time]，就代表這是一個有限授權的 Agent。如果它試圖執行 delete_database，安全性監控系統就能立刻發現這超出了憑證範圍。

🌐 第三步：結合程式碼邏輯

在 linebot-adk 中，我們使用了 Google 的 ADK (Agent Development Kit) 來建構 Agent。A2AS 憑證能精準地映射我們的程式架構：

1. 工具宣告與實現

在 multi_tool_agent/agent.py 中，我們定義了兩個工具：

def get_weather(city: str) -> dict:
    # 實現獲取天氣的邏輯
    ...

def get_current_time(city: str) -> dict:
    # 實現獲取時間的邏輯
    ...

A2AS 憑證會將這些 function 註冊在 tools 區塊，確保 Agent 的能力邊界是透明且可審計的。

2. Runner 與執行循環

在 main.py 中，我們透過 Runner 來啟動 Agent：

runner = Runner(
    agent=root_agent,
    app_name=APP_NAME,
    session_service=session_service,
)

憑證中的 manifest.subject.scope 標註了 main.py，這意味著整個啟動流程（包含 FastAPI 的 Webhook 處理）都在 A2AS 的合規範圍內。

🚀 第四步：為什麼這是「AI 界的 HTTPS」？

想像一下，如果你要讓一個「旅遊代理 Agent」去跟「飯店預約 Agent」對話。

沒有 A2AS：旅遊 Agent 只能「盲目相信」飯店 Agent。
有了 A2AS：旅遊 Agent 可以先檢查對方的 a2as.yaml 憑證。如果對方宣稱有「修改訂單」的權限但憑證裡沒寫，旅遊 Agent 就可以拒絕交易。

這種 「先驗證，後執行」 的模式，正是 A2AS 想要建立的信任網路。

🛠️ 常見坑洞與故障排除

❓ 憑證過期或 Commit Hash 不符怎麼辦？

原因： A2AS 憑證是綁定特定 Git Commit 的。當你修改了 agent.py 的邏輯但沒更新憑證，驗證就會失效。 修正： 每次修改 Agent 的核心功能（如新增 Tool 或更換 Model）後，都必須重新產出並簽署 a2as.yaml。

❓ 使用 A2AS 會增加延遲嗎？

不會。A2AS 主要是「宣告式」與「結構化」的規範。在推論階段，它是透過結構化標籤（BASIC 模型中的 S）來幫助 LLM 區分指令與資料，反而能減少模型因混淆而產生的幻覺，提升執行效率。

🏁 總結

透過這次 A2AS 憑證的導入，linebot-adk 不再只是一個簡單的 LINE Bot 範例，它成為了一個符合 2026 年安全性標準的透明 Agent。在 AI 代理人逐漸滲透我們生活的時代，「透明」就是最好的防禦。

如果你也在開發 AI Agent，不妨去 A2AS.org 看看，為你的專案加上那枚象徵信任的勳章。Happy Coding! 🦞

打造 Agent Skill Hub：從技能開發到 GitHub Pages 多國語言文件自動化部署

Sat, 21 Mar 2026 00:00:00 +0000

參考連結：

這篇文章記錄了我在開發 Agent Skill Hub (2026 技能庫) 時，如何從零開始建構技能描述規範，並參考極簡美學打造出支援中英雙語的 GitHub Pages 文件站。

前情提要

隨著 AI Agent（如 OpenClaw 或 Gemini CLI）的普及，我們發現「如何讓 Agent 快速理解並執行特定任務」成為了關鍵。與其每次都寫長長的 Prompt，不如將常用的操作封裝成標準化的 Skills。

為了方便社群交流與 Agent 讀取，我建立了 agent-skill-hub。但只有程式碼是不夠的，我們還需要一個像樣的「門面」—— 一個既美觀又具備技術細節的文件網站。

🛠️ 第一步：標準化技能描述 (SKILL.md)

在 agent-skill-hub 中，每個技能（如 gcp-helper 或 n8n-executor）都擁有一個 SKILL.md。這個檔案的結構至關重要，因為它不只是給人看的，更是給 LLM 讀取的：

Name & Description: 讓 Agent 知道這是什麼。
When to Use: 定義觸發場景。
Core Pattern: 提供標準指令範例。
Common Mistakes: 減少 Agent 幻覺導致的錯誤。

🎨 第二步：設計風格——致敬極簡美學

在設計 docs 目錄下的網頁時，我參考了 whisperASR 的風格。那種深色背景搭配亮眼點綴色（Teal）的設計，非常符合現代開發者的審美：

視覺元素重點：

漸層標題：利用 linear-gradient 營造出高端的質感。
Teal 點綴色：使用 #14b8a6 作為關鍵按鈕與標題的強調色。
卡片式佈局：清楚呈現每個技能的圖示與簡介，具備良好的回應式設計（Responsive Design）。

🌐 第三步：多國語言支援與自動跳轉

為了讓全球開發者都能使用，我採用了目錄結構化的語系管理方式：

docs/
├── index.html (語言偵測與導向)
├── en/ (英文版本)
│   └── skills/
└── zh/ (繁體中文版本)
    └── skills/

我在根目錄的 index.html 加入了一段簡單的 JavaScript，會根據使用者的瀏覽器設定自動引導至正確的語系：

const lang = navigator.language || navigator.userLanguage;
if (lang.startsWith('zh')) {
    window.location.href = './zh/index.html';
} else {
    window.location.href = './en/index.html';
}

🚀 第四步：GitHub Pages 部署流程

在 2026 年，最推薦的部署方式是將內容放在主分支的 docs/ 目錄下，這樣可以保持 main 分支的整潔，同時讓開發與文件同步更新。

1. 準備目錄結構

透過指令一次建立所有需要的目錄：

mkdir -p docs/en/skills docs/zh/skills docs/assets/css

2. Git 提交與 Push

完成 HTML/CSS 開發後，執行標準的 Git 流程：

git add docs/
git commit -m "docs: add GitHub Pages documentation in English and Chinese"
git push origin main

3. 開啟 GitHub Pages 設定

進入 GitHub 儲存庫的 Settings > Pages。
在 Build and deployment 下的 Branch，選擇 main 分支與 /docs 資料夾。
點擊 Save，幾分鐘後網站就會上線。

成果

Web App: https://www.evanlin.com/agent-skill-hub/zh/index.html

Source code: https://github.com/kkdai/agent-skill-hub

🛠️ 常見坑洞與故障排除

❓ 為什麼網頁樣式（CSS）載不出來？

原因： 在子目錄（如 en/skills/）下的 HTML 檔案，引用的路徑必須正確使用相對路徑。 修正：

<!-- 在首頁 index.html -->
<link rel="stylesheet" href="../assets/css/style.css">
<!-- 在技能詳情頁 -->
<link rel="stylesheet" href="../../assets/css/style.css">

❓ 如何確保 Agent 能正確讀取文件？

我們在 HTML 中保留了大量的語意化標籤（article, h2, pre, code），這樣 Agent 在進行 RAG（檢索增強生成）或直接讀取網頁時，能更精準地抓取核心邏輯。

🏁 總結

透過這次開發，我體會到「文件即產品」的重要性。一個好的 AI 技能庫，除了強大的程式邏輯，更需要一個清晰、直覺且多國語言友好的導覽系統。

如果你也想為你的 AI 專案打造專業的門面，不妨參考這次的 docs/ 結構佈局。Happy Coding! 🦞

在 Google Cloud VM 部署 OpenClaw：避開 sudo-rs 權限與 NVM 路徑的技術坑

Sat, 28 Feb 2026 00:00:00 +0000

(Image generated by Nano Banana - Gemini Image Generation)

參考文章：

這篇文章記錄了在 Google Cloud Platform (GCP) 的 Debian/Ubuntu 環境下，安裝 OpenClaw (2026 最新版) 時遇到的權限、環境變數及進程持久化問題的完整解決流程。

前情提要

最近 AI Agent 領域非常熱門，OpenClaw 作為一個能 24 小時運作的開源 AI 代理，其強大的系統存取與瀏覽能力讓人印象深刻。為了安全起見，將它部署在雲端 VM (如 GCP GCE) 是最理想的作法，既能保證 24/7 在線，又能隔離本機的敏感資料。

但在 GCP 的預設 Debian/Ubuntu 環境中，由於權限機制與一般的 Desktop Linux 略有不同，照著官方腳本安裝往往會踩到不少坑。

🛠️ OpenClaw 在 GCP 的基本安裝流程

在進入故障排除之前，我們先快速跑一遍標準的安裝邏輯：

1. 建立 VM 執行個體

在 GCP Console 建立一個新的 VM：

機型：建議 e2-small 或 e2-medium（視您的 Agent 負載而定）。
作業系統：建議選用 Ubuntu 24.04 LTS 或 Debian 12。
硬碟：建議 20GB 以上。

2. 連線與基礎更新

透過 SSH 進入 VM 後，先執行系統更新：

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential

3. 正式安裝 OpenClaw

官方提供了一鍵安裝腳本：

curl -fsSL https://openclaw.ai/install.sh | bash

但是！ 如果您直接執行上述腳本，在 GCP 上通常會遇到以下兩個嚴重的權限與路徑問題。

🛠️ 問題一：sudo-rs 的「HAL 9000」式拒絕

現象： 當執行官方安裝腳本時，遇到 sudo-rs 報錯：

sudo-rs: I'm sorry evanslin. I'm afraid I can't do that

原因：

互動限制：透過 curl ... | bash 執行的腳本無法在需要 sudo 時從終端機獲取密碼輸入。
無密碼帳號：GCP 預設使用 SSH Key 登入，使用者帳號通常沒有設定實體密碼，導致 sudo 認證失敗。

解決方案： 改用 NVM (Node Version Manager) 安裝 Node.js，將環境建立在使用者目錄下，完全避開 sudo 需求。

# 1. 安裝 NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新載入 shell 配置
source ~/.bashrc

# 2. 安裝 Node.js
nvm install node # 建議版本 v25.7.0+

🛠️ 問題二：NVM 路徑與環境變數

在使用 NVM 後，雖然避開了 sudo，但新的問題隨之而來：當您重新登入或使用非互動式 Shell 執行命令時，系統可能找不到 node 或 openclaw 指令。

這是因為 NVM 的路徑是動態載入的，建議在 ~/.bashrc 中確保以下內容存在：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

🛠️ 問題三：如何讓 OpenClaw 24/7 穩定執行？

安裝完成後，為了讓 Agent 在關閉 SSH 視窗後繼續運行，我從原本的 GCP Web SSH 轉向使用本機的 gcloud CLI，但也因此發現了新的小坑。

1. 為什麼 gcloud ssh 找不到 openclaw？

這通常是因為 GCP 的 gcloud compute ssh 可能會根據您的本機帳號名稱建立一個新的使用者名稱，而不是延用您在 VM 上安裝時使用的帳號（例如 evanslin）。

驗證方法： 請在「網頁版 SSH」與「本機 gcloud SSH」兩個視窗分別輸入：

whoami

問題根源： 如果網頁版顯示的是 evanslin，但 gcloud 版顯示的是 evan_lin_yourdomain_com 之類的名稱，那麼兩者的家目錄（Home Directory）路徑完全不同，您的 NVM 與 OpenClaw 設定當然會「消失」。

解決方案： 在執行 gcloud 指令時，明確指定要登入的帳號：

gcloud compute ssh evanslin@openclaw-evanlin

這樣就能確保您回到正確的環境！

2. 使用 tmux 與啟動腳本實現完美執行

為了確保環境變數在任何 SSH 會話（網頁版或 gcloud 版）都能正確載入，並讓 OpenClaw 在背景穩定運行，建議採用以下「腳本化」的啟動方式。

步驟 1：建立啟動腳本

在您能正常執行 openclaw 的視窗（通常是網頁版 SSH）中，建立一個啟動腳本：

cat << 'EOF' > ~/start_openclaw.sh
#!/bin/bash
# 1. 強制載入 NVM 路徑
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 2. 自動修正 PATH (請根據您的 Node 版本調整路徑)
export PATH="$HOME/.nvm/versions/node/v25.7.0/bin:$PATH"

# 3. 執行指令
openclaw "$@"
EOF

# 賦予執行權限
chmod +x ~/start_openclaw.sh

步驟 2：驗證腳本

以後不論從哪裡登入，請統一使用此腳本。在 gcloud ssh 視窗中測試：

~/start_openclaw.sh gateway

如果能成功跑起來，代表路徑已手動接通！

步驟 3：結合 tmux 解決斷線問題

現在我們把腳本跟 tmux 結合，實現真正的 24/7 背景運行：

開啟新會話：tmux new -s openclaw
在裡面執行腳本：~/start_openclaw.sh gateway
完美分離 (Detach)：按下 Ctrl + B 後放開，再按下 D。
隨時重連：下次登入執行 tmux a -t openclaw 即可。

🛠️ 問題四：更新到一半硬碟爆了怎麼辦？

❓ 為什麼 `openclaw` 指令會突然消失？

如果你在執行過程中遇到 -bash: openclaw: command not found，通常有兩個原因：

NVM 未載入：NVM 安裝在使用者目錄下，非互動式 Shell 可能不會自動執行 nvm.sh。
磁碟滿載導致設定損壞：當磁碟 100% 時，系統可能無法讀取或寫入環境變數設定。

快速修復指令：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
export PATH="$HOME/.nvm/versions/node/v25.7.0/bin:$PATH"

接下來的檢查清單：

空間確認：df -h 看到 /dev/sda1 還有空間嗎？
指令確認：which openclaw 有噴路徑出來嗎？
服務確認：openclaw gateway 跑起來後，有沒有看到 Gateway is listening on port 18789？

如果以上都 OK，你的 AI Agent 就正式復活了！需要我幫你把這整段「復活流程」也補進你的 MD 檔案中嗎？

💡 為什麼改了 GCP 磁碟大小，`df -h` 卻沒變？

在雲端控制台調整磁碟大小後，必須進入系統手動執行「磁碟擴張」兩部曲，空間才會真正釋放：

擴展分割區：使用 growpart 指令將分割區邊界推至實體磁碟極限。
擴展檔案系統：使用 resize2fs 指令讓檔案系統填充剩餘空間。

指令範例：

sudo growpart /dev/sda 1
sudo resize2fs /dev/sda1

🏁 最終章：當 AI 也會「累」的時候

當你看到 The AI service is temporarily overloaded 時，恭喜你，你的基礎設施（GCP, OpenClaw, Path）已經完全健康了！這剩下的 1% 屬於 AI 供應商的範疇。

如何優化 AI 回應穩定性？

備用模型：在 models configure 中設定多個模型，當 Pro 版過載時切換到 Flash 版。
重試機制：OpenClaw 內建了基本的重試邏輯，但遇到 Overload 時，最好的方式是「冷靜 30 秒」。
區域選擇：如果你使用 Vertex AI，可以嘗試切換不同的區域（Region），例如從 us-central1 切換到 asia-east1。

結語：從 sudo-rs 的拒絕、NVM 的迷蹤、GCP 磁碟的炸裂，到最後的 AI 過載，我們成功在雲端建立了一個強大的 AI Agent 基地。Happy Coding! 🦞

總結

在 GCP 部署 OpenClaw 的關鍵在於 「使用者目錄優先」。透過 NVM 避開系統層級的 sudo-rs 限制，不僅安裝過程更流暢，也能更方便地切換 Node.js 版本以符合 OpenClaw 的最新需求。

部署成功後，別忘了使用 openclaw onboard 開始配置您的 API Keys 與通訊頻道（如 Telegram 或 Discord）。

希望這篇筆記能幫到同樣在 GCP 上奮鬥的開發者們。我們下次見！

[Gemini] Multimodal Function Response 實戰：打造能「看圖說故事」的 LINE 電商客服機器人

Sun, 22 Feb 2026 00:00:00 +0000

參考文章：

前情提要

相信很多人都用過 LINE Bot + Function Calling 的組合。當用戶問「我上個月買了什麼衣服？」時，Bot 呼叫資料庫查詢函式，取回訂單資料，然後 Gemini 根據那份 JSON 回答：

開發者設計的傳統流程：

用戶: "幫我看看我之前買過的那件外套"
Bot: [呼叫 get_order_history()]
函式回傳: {"product_name": "棕色飛行員外套", "order_date": "2026-01-15", ...}
Gemini: "您在 1 月 15 日購買了棕色飛行員外套，金額 NT$1,890。"

回答完全正確，但總覺得少了什麼——用戶說的是「那件外套」，Gemini 只是轉述 JSON 裡的文字，完全沒有辦法「確認」那件衣服長什麼樣子。如果資料庫裡剛好有三件外套，AI 根本無法判斷哪件才是用戶記憶中的那件。

AI 能讀懂文字，但看不到圖片——這個限制在傳統 Function Calling 架構下一直是死角。

直到 Gemini 推出了 Multimodal Function Response，這個問題才被真正解決。

什麼是 Multimodal Function Response？

傳統的 Function Calling 流程是這樣的：

[用戶訊息] → Gemini → [function_call] → [執行函式] → [回傳 JSON] → Gemini → [文字回答]

Multimodal Function Response 改變了中間那一步。函式不只能回傳 JSON，還能在同一個回應中夾帶圖片（JPEG/PNG/WebP）或文件（PDF）：

[用戶訊息] → Gemini → [function_call] → [執行函式] → [回傳 JSON + 圖片 bytes] → Gemini → [看過圖片的文字回答]

Gemini 在下一輪生成回答時，能同時「看到」函式回傳的結構化資料和圖片，從而生成更豐富、更精準的回應。

官方目前支援的媒體格式：

類別	支援格式
圖片	`image/jpeg`, `image/png`, `image/webp`
文件	`application/pdf`, `text/plain`

這個功能的應用場景非常廣泛：電商客服（辨識商品圖片）、醫療諮詢（分析檢驗報告 PDF）、設計評審（看截圖給建議）……幾乎所有需要「函式回傳視覺資料給 AI 分析」的場景都適用。

專案目標

這次我用 Multimodal Function Response 打造了一個 LINE 電商客服機器人，示範以下場景：

用戶：「幫我看看我之前買過的那件外套」 Bot（傳統）：「您購買了棕色飛行員外套。」 Bot（Multimodal）：「從照片中可以看到這是一件棕色飛行員外套，輕量尼龍材質，側邊有金屬拉鏈裝飾口袋。這是您 1 月 15 日的訂單 ORD-2026-0115，共 NT$1,890，已送達。」+ 商品照片

差別顯而易見：Gemini 真的「看了」那件衣服，而不只是轉述資料庫裡的文字。

架構設計

為什麼不用 Google ADK？

原本這個 repo 是用 Google ADK（Agent Development Kit）來管理 Agent，ADK 的 Runner 和 Agent 封裝了 Function Calling 的整個流程，非常方便。

但 Multimodal Function Response 需要在函式回應的 parts 裡手動夾帶圖片 bytes，ADK 在這一層完全封裝掉了，沒辦法插手。

所以這次直接用 google.genai.Client 自己實作函式呼叫的迭代循環：

# 舊架構（ADK）
runner = Runner(agent=root_agent, ...)
async for event in runner.run_async(...):
    ...  # ADK 幫你處理所有 function call，但你無法控制回應內容

# 新架構（直接用 google.genai）
response = await client.aio.models.generate_content(
    model=model,
    contents=contents,
    config=types.GenerateContentConfig(tools=ECOMMERCE_TOOLS),
)
# 自己處理 function call，自己夾帶圖片

整體架構

LINE User
    │
    ▼ POST /
FastAPI Webhook Handler
    │
    ▼
EcommerceAgent.process_message(text, line_user_id)
    │
    ├─ ① 呼叫 Gemini（帶入對話歷史）
    │
    ├─ ② Gemini 決定呼叫工具 → function_call
    │
    ├─ ③ _execute_tool()
    │       ├─ 執行查詢函式（search_products / get_order_history / get_product_details）
    │       └─ 讀取 img/ 目錄中的真實商品照片（Unsplash JPEG）
    │
    ├─ ④ 建構 Multimodal Function Response
    │       └─ FunctionResponsePart(inline_data=FunctionResponseBlob(data=image_bytes))
    │
    ├─ ⑤ 再次呼叫 Gemini（Gemini 看到圖片 + 資料）
    │
    └─ ⑥ 回傳 (ai_text, image_bytes)
    │
    ▼
LINE Reply:
  TextSendMessage(text=ai_text)
  ImageSendMessage(url=BOT_HOST_URL/images/{uuid})   ← FastAPI /images 端點提供

商品圖片怎麼來？

這個 demo 使用真實的 Unsplash 服飾攝影照片，五件商品各對應一張實際拍攝的衣物照片，儲存在 img/ 目錄。讀取邏輯非常簡單：

def generate_product_image(product: dict) -> bytes:
    """讀取商品圖片並返回 JPEG bytes。"""
    with open(product["image_path"], "rb") as f:
        return f.read()

PRODUCTS_DB 裡每件商品都有 image_path 欄位指向對應的圖片檔案：

商品 ID	名稱	圖片
P001	棕色飛行員外套	tobias-tullius-…-unsplash.jpg
P002	白色棉質大學T	mediamodifier-…-unsplash.jpg
P003	深藍色牛仔外套	caio-coelho-…-unsplash.jpg
P004	米白色針織披肩	milada-vigerova-…-unsplash.jpg
P005	淺藍色簡約T恤	cristofer-maximilian-…-unsplash.jpg

讀到的圖片 bytes 有兩個用途：

作為 FunctionResponseBlob 夾帶給 Gemini 分析——真實照片讓 Gemini 能描述實際的布料質感、剪裁細節
暫存在 image_cache dict，透過 FastAPI /images/{uuid} 端點提供給 LINE Bot 顯示

核心程式碼詳解

Step 1：定義工具（FunctionDeclaration）

from google.genai import types

ECOMMERCE_TOOLS = [
    types.Tool(function_declarations=[
        types.FunctionDeclaration(
            name="get_order_history",
            description="查詢當前用戶的訂單歷史記錄",
            parameters=types.Schema(
                type=types.Type.OBJECT,
                properties={
                    "time_range": types.Schema(
                        type=types.Type.STRING,
                        description="時間範圍：all / last_month / last_3_months",
                        enum=["all", "last_month", "last_3_months"],
                    ),
                },
                required=[],
            ),
        ),
        # ... search_products, get_product_details
    ])
]

Step 2：函式呼叫循環（最多 5 次迭代）

async def process_message(self, text: str, line_user_id: str):
    contents = self._get_history(line_user_id) + [
        types.Content(role="user", parts=[types.Part(text=text)])
    ]

    for _iteration in range(5):  # 最多 5 次，防止無限循環
        response = await self._client.aio.models.generate_content(
            model=self._model,
            contents=contents,
            config=types.GenerateContentConfig(
                system_instruction=_SYSTEM_INSTRUCTION,
                tools=ECOMMERCE_TOOLS,
            ),
        )

        model_content = response.candidates[0].content
        contents.append(model_content)

        # 找出所有 function_call parts
        fc_parts = [p for p in model_content.parts if p.function_call and p.function_call.name]

        if not fc_parts:
            # 沒有 function call → 最終文字回應
            final_text = "".join(p.text for p in model_content.parts if p.text)
            break

        # 有 function call → 執行工具、夾帶圖片
        tool_parts = []
        for fc_part in fc_parts:
            result_dict, image_bytes = _execute_tool(
                fc_part.function_call.name,
                dict(fc_part.function_call.args),
                line_user_id,
            )
            tool_parts.append(
                self._build_multimodal_response(fc_part.function_call.name, result_dict, image_bytes)
            )

        contents.append(types.Content(role="tool", parts=tool_parts))

Step 3：建構 Multimodal Function Response（最關鍵的步驟）

def _build_multimodal_response(self, func_name, result_dict, image_bytes):
    multimodal_parts = []

    if image_bytes:
        # ⚠️ 注意：這裡要用 FunctionResponseBlob，不是 types.Blob！
        multimodal_parts.append(
            types.FunctionResponsePart(
                inline_data=types.FunctionResponseBlob(
                    mime_type="image/jpeg",
                    data=image_bytes,  # raw bytes，SDK 內部自動處理 base64
                )
            )
        )

    return types.Part.from_function_response(
        name=func_name,
        response=result_dict,          # 結構化 JSON 資料
        parts=multimodal_parts or None, # ← 圖片在這裡！Gemini 收到後能「看見」
    )

Gemini 在下一次 generate_content 呼叫中，會同時接收到 result_dict（訂單 JSON）和 image_bytes（商品圖片），生成的回答因此能描述圖片視覺內容。

Step 4：LINE Bot 同時回傳文字 + 圖片

# main.py

ai_text, image_bytes = await ecommerce_agent.process_message(msg_text, line_user_id)

reply_messages = [TextSendMessage(text=ai_text)]

if image_bytes:
    image_id = str(uuid.uuid4())
    image_cache[image_id] = image_bytes              # 暫存
    image_url = f"{BOT_HOST_URL}/images/{image_id}"  # FastAPI 提供服務
    reply_messages.append(
        ImageSendMessage(
            original_content_url=image_url,
            preview_image_url=image_url,
        )
    )

await get_line_bot_api().reply_message(event.reply_token, reply_messages)

LINE Bot 的 reply_message 支援一次回傳多則訊息（最多 5 則），所以文字和圖片可以同時送出。

踩過的坑

❌ 坑 1：`FunctionResponseBlob` 不是 `Blob`

最容易踩的坑：建構多模態圖片部件時，不能用 types.Blob，要用 types.FunctionResponseBlob：

# ❌ 錯誤（會 TypeError）
types.FunctionResponsePart(
    inline_data=types.Blob(mime_type="image/jpeg", data=image_bytes)
)

# ✅ 正確
types.FunctionResponsePart(
    inline_data=types.FunctionResponseBlob(mime_type="image/jpeg", data=image_bytes)
)

雖然兩者都有 mime_type 和 data 欄位，但 FunctionResponsePart 的 inline_data 欄位型別是 FunctionResponseBlob，Pydantic 驗證會直接拒絕 Blob。用 python -c "from google.genai import types; print(types.FunctionResponsePart.model_fields)" 就能確認。

❌ 坑 2：`aiohttp.ClientSession` 不能在 module level 建立

原本的程式碼在模組層級直接建立 aiohttp.ClientSession()：

# ❌ 舊寫法：module level
session = aiohttp.ClientSession()  # 如果沒有 running event loop 就會警告或出錯
async_http_client = AiohttpAsyncHttpClient(session)

在 pytest 測試中 import main.py 時，因為還沒有 running event loop 就會出現 RuntimeError: no running event loop。解法是改成 lazy initialization，第一次真正需要時才建立：

# ✅ 新寫法：lazy init
_line_bot_api = None

def get_line_bot_api():
    global _line_bot_api
    if _line_bot_api is None:
        session = aiohttp.ClientSession()  # 在 async route handler 內呼叫，保證有 event loop
        _line_bot_api = AsyncLineBotApi(channel_access_token, AiohttpAsyncHttpClient(session))
    return _line_bot_api

❌ 坑 3：LINE Bot 發圖片需要 HTTPS URL

Gemini 收到的是 raw bytes，但 LINE Bot 的 ImageSendMessage 需要 公開可訪問的 HTTPS URL。

解法是在 FastAPI 加一個 /images/{image_id} 端點，把讀取到的圖片 bytes 暫存在 image_cache dict，LINE 透過這個端點取圖：

@app.get("/images/{image_id}")
async def serve_image(image_id: str):
    image_bytes = image_cache.get(image_id)
    if image_bytes is None:
        raise HTTPException(status_code=404, detail="Image not found")
    return Response(content=image_bytes, media_type="image/jpeg")

本機開發用 ngrok 把 8000 port 暴露出去，Cloud Run 部署後直接用服務 URL。

Demo 展示

Mock 資料庫（Demo 用預設資料）

系統內建 5 件商品（均附有真實 Unsplash 照片），每位 LINE 用戶第一次查詢訂單時，自動綁定兩筆 demo 訂單：

訂單編號	日期	商品
ORD-2026-0115	2026-01-15	P001 棕色飛行員外套
ORD-2026-0108	2026-01-08	P003 深藍色牛仔外套

場景 1：「幫我看看我之前買過的外套」

用戶傳送: "幫我看看我之前買過的外套"

[Gemini → function_call]
  get_order_history(time_range="all")

[_execute_tool 執行]
  - get_order_history() 回傳兩筆訂單（P001、P003）
  - 讀取 img/tobias-tullius-...-unsplash.jpg → 棕色飛行員外套真實照片 bytes

[Multimodal Function Response]
  Part.from_function_response(
    name="get_order_history",
    response={"orders": [...], "order_count": 2},
    parts=[FunctionResponsePart(inline_data=FunctionResponseBlob(data=<照片>))]
  )

[Gemini 看到真實照片後回應]
  "從照片中可以看到這是一件棕色飛行員外套，輕量尼龍材質帶有
   光澤感，左袖有金屬拉鏈裝飾口袋。這是您 2026 年 1 月 15 日
   的訂單 ORD-2026-0115，共 NT$1,890，狀態：已送達。"

LINE 顯示: [文字] + [棕色飛行員外套真實照片]

場景 2：「有沒有深藍色的外套？」

[Gemini → function_call]
  search_products(description="深藍色外套", color="深藍色")

[Gemini 看到 P003 深藍色牛仔外套真實照片後]
  "有！照片中這件深藍色牛仔外套（P003）採復古縫線設計，
   翻領搭配金屬鈕扣，整體成衣感十足，售價 NT$1,490，庫存 8 件。"

場景 3：「P004 的針織披肩有什麼特色？」

[Gemini → function_call]
  get_product_details(product_id="P004")

[Gemini 看到米白色針織披肩真實照片後]
  "照片中是一件米白色手工鉤針編織披肩，V 領設計搭配底部流蘇，
   可以看到輕盈的蕾絲感網格編織紋路，質感優雅，售價 NT$1,290。"

傳統 Function Response vs Multimodal Function Response

	傳統	Multimodal
函式回傳	純 JSON	JSON + 圖片/PDF bytes
Gemini 感知	文字資料	文字 + 視覺內容
回答品質	「您購買了棕色飛行員外套」	「照片中可以看到尼龍材質光澤，左袖有拉鏈口袋…」
API 差異	`Part.from_function_response(name, response)`	`Part.from_function_response(name, response, parts=[...])`
適用場景	純文字資料查詢	需要視覺辨識/確認的場景

分析與展望

這次實作讓我對 Gemini 的 Function Calling 能力有了新的認識。

Multimodal Function Response 真正解決的問題，是讓 AI 代理能夠在「呼叫外部系統」這個動作本身就帶入視覺資訊，而不是先查文字、再另外上傳圖片。這在電商、醫療、設計等視覺高度相關的領域，會是一個重要的基礎能力。

不過目前還有幾個值得注意的限制：

圖片 URL 不能直接用：Gemini 的 FunctionResponseBlob 需要 raw bytes，不能直接填 URL（這點跟直接在 prompt 裡帶圖片不同）。如果圖片本來就是 URL，需要先用 requests.get() 下載成 bytes 再傳入。
沒有 display_name 也能用：官方文件的範例有 display_name 和 $ref JSON reference，但實測在 google-genai 1.49.0 中，不填 display_name 也可以正常運作，Gemini 仍然能看到並分析圖片。
模型限制：官方標示支援 Gemini 3 系列，但 gemini-2.0-flash 在實測中也能正常處理，API 結構相同。

未來可以延伸的方向很多：讓用戶傳送自己的商品照片讓 Bot 比對、在函式回應中夾帶 PDF 型錄讓 Gemini 直接閱讀、或者在醫療場景中讓 Bot 分析函式從 DICOM 轉換出的報告圖片……只要能從外部系統取得視覺資料，Multimodal Function Response 都能讓 AI 的回答更有深度。

總結

這次的 LINE Bot 實作重點只有一句話：讓函式回應帶著圖片，Gemini 的回答就會從「轉述資料」升級成「看圖說故事」。

核心 API 就這幾行，但打通整個流程需要不少細節：

# Gemini 看到函式回傳圖片的完整寫法
types.Part.from_function_response(
    name="get_order_history",
    response={"orders": [...]},
    parts=[
        types.FunctionResponsePart(
            inline_data=types.FunctionResponseBlob(  # ← 不是 types.Blob！
                mime_type="image/jpeg",
                data=image_bytes,
            )
        )
    ],
)

完整程式碼在 GitHub，歡迎 clone 來玩。

我們下次見！

[Gemini CLI] Google Developer Knowledge API 與 MCP Server：為你的 AI 助手裝上官方知識庫

Sat, 07 Feb 2026 00:00:00 +0000

參考文章：

前情提要

還記得上週我用 Gemini CLI 寫 Gemini API 整合時，它信心滿滿地告訴我：「這個 API 參數是這樣用的」。結果執行後噴了一堆錯誤，原來 Google 三個月前就改了 API 格式。這不是 AI 的錯，它的訓練資料截止日期就在那裡，面對日新月異的技術文件，再強的模型也會「過時」。

過去我們遇到的典型場景：

開發者: "Gemini，幫我寫一個 Gemini Function Calling 的範例"
AI: "好的，你可以這樣寫..." [產生基於 2024 年 6 月文件的程式碼]
開發者: [複製貼上，執行]
終端機: ❌ Error: Parameter 'tools' format has changed in v2
開發者: 😤 "又要去翻官網文件了..."

（以上就是一個範例， LLM 不清楚的部分只能去找網路。但是卻不能保證答案一定是正確且最新的用法）

這樣的循環你是不是很熟悉？即便是 Gemini 1.5 Pro，有時也會因為自己的 API 更新太快而給出舊版建議。AI 的知識是靜態的，但技術文件是動態的，這個矛盾一直困擾著我們。

為了徹底解決這個問題，Google 在 2025 年初釋出了兩大殺手級工具：

Developer Knowledge API - 機器可讀的官方文件 API
Knowledge MCP Server - 基於 Model Context Protocol 的即時文件查詢服務

這意味著你的 AI 助手現在不再只是「憑記憶」寫程式，而是可以在需要時主動「翻閱最新官方文件」，成為一個真正擁有官方掛保證、永不過時的開發專家。

什麼是 Developer Knowledge API？

過去 AI 學習文件的方式：網頁爬蟲的困境

傳統上，AI 模型是透過爬蟲抓取網頁來學習文件的。但這種方式有幾個致命問題：

❌ 雜訊干擾

<!-- AI 看到的實際內容 -->
<nav>...</nav>  <!-- 導覽列 -->
<ad>...</ad>    <!-- 廣告 -->
<cookie-banner>...</cookie-banner>  <!-- Cookie 提示 -->
<div class="content">
  <!-- 真正的文件內容只佔 30% -->
  這是 Gemini API 的使用方式...
</div>
<footer>...</footer>  <!-- 頁尾 -->

AI 必須從這堆 HTML 中「猜測」哪些才是真正的文件內容。

❌ 格式不一致

有些用 <code> 標籤，有些用 <pre>
有些用 Markdown 渲染，有些用自訂語法
圖片說明可能在 alt、title 或 figcaption 裡

❌ 更新延遲

爬蟲可能幾個月才抓一次
新增的 API 參數要等下次訓練才知道
訓練資料截止日期成為永遠的痛

Developer Knowledge API：機器優先的文件系統

Developer Knowledge API 徹底改變了這個遊戲規則，它提供了：

✅ 機器可讀的真理來源：
- 直接提供純淨的 Markdown 格式
- 無雜訊、無廣告、無導覽列
- 結構化的 metadata（作者、更新時間、版本）
✅ 即時性：
- 與 Google 官方文件同步更新（延遲 < 1 小時）
- API 改了，AI 就能立刻讀到新文件
- 永遠不會有「訓練資料過時」的問題
✅ 全面性：它能直接檢索並獲取以下 Google 官方網域的文檔，如果你的開發領域與這些相關，強烈建議開啟這個 MCP：
- ai.google.dev
- developer.android.com
- developer.chrome.com
- developers.home.google.com
- developers.google.com
- docs.cloud.google.com
- docs.apigee.com
- firebase.google.com
- fuchsia.dev
- web.dev
- www.tensorflow.org

MCP Server：讓 AI 更有「常識」

Model Context Protocol (MCP) 是一個開放標準，它就像是 AI 工具的「外掛插槽」。Google 這次推出的 Knowledge MCP Server，讓各種支援 MCP 的工具（如 Claude Code, Cursor, 甚至是我們最愛的 Gemini CLI）都能輕鬆整合。

透過這個 MCP Server，AI 不再只是憑記憶寫 Code，而是可以針對特定問題去「翻書」：

實作指引：詢問某個新功能的最佳實作方式。
故障排除：直接根據最新的 Error Code 文件進行診斷。
版本比較：了解不同版本 API 之間的差異。

如果你對於特定領域的 MCP 應用感興趣，我也在之前的文章分享過 Google Maps Platform Assist MCP：讓 AI 幫你寫出更精準的地圖應用，這也是一個非常強大的工具，能讓 AI 助手在開發地圖功能時更具優勢。

實戰：讓 AI 助手導入官方知識庫

要讓 AI 助手能讀取官方文件，我們需要先在 Google Cloud 完成簡單的準備工作。

第一步：啟用 Developer Knowledge API

前往 Google API 程式庫中的 Developer Knowledge API 頁面。
確認你選擇了正確的專案。
點擊「啟用 (Enable)」。這個 API 不需要特殊的 IAM 權限即可使用。

第二步：建立並保護你的 API 金鑰

為了確保安全，建議對金鑰進行限制：

在 Google Cloud 控制台導覽至「憑證 (Credentials)」頁面。
點擊「建立憑證」，然後選擇「API 金鑰」。
點擊「編輯 API 金鑰」。
在名稱欄位輸入好辨識的名字（例如：Dev-Knowledge-Key）。
在「API 限制」下，選擇「限制金鑰」。
從 API 清單中選擇「Developer Knowledge API」，然後點擊確定。
點擊「儲存」。

建立完成後，點擊「顯示金鑰」並將其記下來，這就是我們接下來要使用的憑證。

如果你正在使用 Claude Code 或 Gemini CLI，現在只需要簡單的配置就能讓它變強。

配置範例 (以 Gemini CLI 為例)

你只需要在設定中加入 Google 的 MCP Server 位址，並附上你的 API Key：

# 加入 Google Developer Knowledge MCP Server
gemini mcp add -t http -H "X-Goog-Api-Key: YOUR_API_KEY" google-developer-knowledge https://developerknowledge.googleapis.com/mcp --scope user

一旦設定完成，你在詢問「如何使用最新的 Gemini API 進行 Function Calling」時，AI 就會主動調用 MCP Server，去抓取目前官網上最準確、最即時的文件內容來回答你。

分析與展望：為什麼這很重要？

這項技術的推出，標誌著開發流程中的兩個重大轉變：

從「依賴記憶」轉向「即時查詢」 過去我們追求讓模型變得更大，記住更多東西。現在，我們透過 MCP 讓模型學會「查資料」。這不僅大幅減少了幻覺，也減輕了模型需要頻繁重新訓練的壓力。
更強大的開發代理 (AI Agents) 當 AI 助手能讀取文件、執行指令、並進行版本控制時，它就真正進化成了一個能獨立處理任務的「數位同僚」。Developer Knowledge API 提供的結構化資訊，正是 AI Agent 進行複雜推理所需的燃料。

總結

Google 這次不僅提供了強大的模型，更提供了優質的「數據接口」。對於追求效率的開發者來說，配置好 Developer Knowledge MCP Server 絕對是值得投資的 5 分鐘。

以後寫 Code 時，AI 助手不再只是個會寫程式的機器，而是一個隨時翻閱著最新官網文件、給你最精準建議的技術顧問。還不趕快去申請一個 API Key 來試試看？

我們下次見！

[Recap] Google Developer Year-end 2025：Gemini 2025 新功能回顧與 LINE Bot 的完美結合

Fri, 06 Feb 2026 00:00:00 +0000

前情提要

昨天參加了 Google 舉辦的開發者尾牙聚會（Google Developer Year-end 2025），也順便參觀了 Google 板橋辦公室。很開心能以 LINE Taiwan Developer Relations 的身份，跟大家分享我在 2025 年一整年觀察到的 Gemini 技術演進心得。

在熱門動畫《葬送的芙莉蓮》中，我很喜歡一級魔法使測驗篇的角色「尤蓓爾」。她有一個獨特的能力概念：「只要能想像切得開，就一定能切得開」。

這句話完美呼應了現在的 AI 時代——想像力與理解力變得比以往更加重要。如何「精準地想像出解決問題的方式」，成為了讓 AI 能精準協助你的關鍵。這篇文章將整理當天分享的 Gemini 2025 重點功能，以及我對「軟體工程師」在 AI 浪潮下核心能力的看法。

### 2025 Gemini 功能演進回顧

回顧 2025 年，Gemini 與 LINE Bot 的結合在多個時間點都有突破性的更新。以下是重新審視這一年來的技術節點：

時間點	功能更新	說明
2025.04	Google ADK	Agent 與 Messaging API 的初步結合，展示了天氣查詢等基礎 Agent 應用。
2025.06	Gemini CLI	開發者體驗大升級，直接在終端機與 AI 協作，進行檔案操作與程式撰寫。
2025.08	Video Understanding	支援 YouTube 影片理解。透過 Gemini 2.5 直接抓取字幕與影像內容進行摘要與互動。
2025.11	File Search	強化檔案搜尋能力，支援 JSON、JS、PDF、Python 等多種格式的 RAG 應用。
2025.12	Map Grounding	結合 Google Maps Platform，讓 Bot 能回答「最近的地震資訊」或「附近的餐廳」等地理資訊問題。

#### 技術亮點詳解

##### 1. Gemini CLI 與 Vibe Coding

在六月推出的 Gemini CLI 改變了許多開發者的習慣。不僅僅是印出 “Hello World”，它整合了 Git、Gcloud 等工具。這帶出了一個新的開發概念：Vibe Coding。

定義：這不僅是寫程式，而是透過 Gemini CLI、Vertex AI Studio 和 Antigravity 等工具，讓開發流程進入一種「心流」狀態。
關鍵：重點在於開發者如何指揮這些工具串接，而非手刻每一行代碼。

##### 2. 視覺與地理資訊的整合 (Video & Map)

八月的 Video Understanding 讓我們能直接丟入 YouTube 連結，Gemini 就能生成摘要甚至回答影片細節。到了年底的 Map Grounding，則是補足了 LLM 最缺乏的「實時地理資訊」。

應用場景：用戶問「找餐廳」，Bot 透過 Map Grounding 找出附近的 “CHILLAX” 或 “博感情” 等餐廳，並附上地址與類型。
資料來源：結合了 World Knowledge (Google Search) 與 Private Knowledge (Your Data/RAG)，讓回答更具落地性。

### 重新審視：卓越人才的三大支柱

在技術工具日新月異的同時，我也在思考，什麼樣的能力是 AI 無法取代的？就像前面提到的「尤蓓爾」的想像力，我認為卓越人才需要具備三大支柱：

#### 1. AI 協作力 (AI Collaboration)

這不僅僅是會用工具，而是具備 Prompt Engineering 的能力。

差異：懂得如何與 AI 對話、引導 AI 產出結果的人，生產速度可以提升 10 倍。
重點：AI 是你的 Copilot，但你是機長。

#### 2. 專業深度 (Domain Depth)

在 AI 氾濫的時代，Domain Knowledge（領域知識） 是你最強的護城河。

價值：AI 可以寫出語法正確的程式碼，但「解決複雜問題的經驗」與「對業務邏輯的深刻理解」，是 AI 難以模仿的。

#### 3. 同理與創意 (Empathy & Creativity)

將「熱情」轉化為人類特有的 批判性思考 與 同理心。

核心：這是建立人脈與管理決策的核心。AI 可以處理數據，但無法理解人的情感與需求背後的真正動機。

### 結語

這次的 Google Developer Year-end 讓我再次確認，系統的理解與對問題的認知，是軟體工程師最重要的能力。

AI 時代下的開發，不再只是單純的 Coding，而是像設計 AP2 協議一樣，需要考慮整體的架構與安全性。若我們只是快速地 Vibe Coding 而忽略了底層原理（例如忘記考慮 Token 的時效性或資料的正確性），很容易就會產出有漏洞的系統。

所以，保持對技術的好奇心，同時深化自己的領域知識，這才是我們證明 AI 無法取代我們的重要原因。

投影片下載：有興趣的朋友可以參考當天的投影片： https://speakerdeck.com/line_developers_tw/2025-features-recap-perfect-integration-linebot

(如果覺得有幫助，歡迎分享這篇文章！)

Blog E

[GCP 實戰] LINE Bot 遷移大作戰：從 AI Studio 轉向 Vertex AI 解決 429 額度危機

前情提要

身份驗證升級：推薦使用 Workload Identity

程式碼升級：從 AI Studio 轉向 Vertex AI

遷移過程中的血淚踩坑：模型都很笨？還是 Vertex AI 資訊太少？

踩坑一：殘留的舊 SDK 導致 Cloud Run 啟動失敗

踩坑二：Region 必須選 global 才有最多跟最新模型

踩坑三：Model 名稱選錯，造成來來回回錯誤

總結：Vertex AI 帶來的改變

[Gemini 3.1] Gemini-3.1-flash TTS 實戰：更簡單、更強大的朗讀摘要功能

前情提要

技術升級：從 Live API 轉向 Native TTS

核心程式碼進化（tools/tts_tool.py）

踩過的坑：那個消失的 await

❌ 錯誤寫法

✅ 正確解法

在地化調整：讓 Bot 說「台灣話」

總結：Native TTS 帶來的改變

[Gemini 3.1] Flash Live 語音辨識實戰：讓 LINE Bot 聽懂你說的話

前情提要

設計決策：Flash Live 還是標準 Gemini API？

架構設計

整合思路

完整流程

為什麼要兩段回覆？

核心程式碼詳解

Step 1：音訊轉錄工具（tools/audio_tool.py）

Step 2：handler 主流程（main.py）

Step 3：讓 Orchestrator 支援外部傳入文字

踩過的坑

❌ 坑 1：Part.from_text() 不接受 positional argument

❌ 坑 2：LINE reply token 只能用一次

❌ 坑 3：Gemini Flash Live 不適合預錄檔案

效果展示

場景 1：語音指令查詢

場景 2：語音問問題

場景 3：語音發 URL

傳統文字輸入 vs 語音輸入

分析與展望

延伸：🔊 朗讀摘要——讓 Bot 說話

功能設計

核心程式碼（tools/tts_tool.py）

朗讀功能踩的坑

❌ 坑 4：模型名稱完全不同

❌ 坑 5：GOOGLE_CLOUD_LOCATION=global 讓 Live API 失聯

語音辨識 vs 朗讀摘要

總結

[Gemini] Tool Combo 實戰：在單次 API 呼叫中結合 Maps Grounding 與 Places API 打造 LINE 聚會地點小幫手

前情提要

什麼是 Tool Combinations？

專案目標

架構設計

整體訊息流程

Tool Combo Agentic Loop

為什麼 lat/lng 不放在 Function Declaration 裡？

核心程式碼詳解

Step 1：定義 Function Declaration

Step 2：Places API 呼叫

Step 3：Tool Combo 主函式（Agentic Loop）

踩過的坑

❌ 坑 1：Part.from_function_response() 不接受 id 參數

❌ 坑 2：include_server_side_tool_invocations=True 讓 Pydantic 爆炸

❌ 坑 3：textQuery 是 searchText 的參數，不是 searchNearby 的

❌ 坑 4：response.candidates[0] 沒有 guard

Demo 展示

場景 1：「找評價 4 顆星以上的聚餐熱炒店」

場景 2：「有沒有 CP 值高的日式料理？」

Demo Script 快速測試

舊架構 vs 新架構

分析與展望

總結

AI Agent 的安全性宣告：深入探索 A2AS (Agent-to-Agent Security) 憑證機制

前情提要

🛠️ 第一步：理解 A2AS 的 BASIC 模型

🎨 第二步：解構 a2as.yaml——Agent 的身份證

為什麼這很重要？

🌐 第三步：結合程式碼邏輯

1. 工具宣告與實現

2. Runner 與執行循環

踩過的坑：那個消失的 `await`

❌ 坑 1：`Part.from_text()` 不接受 positional argument

❌ 坑 5：`GOOGLE_CLOUD_LOCATION=global` 讓 Live API 失聯

❌ 坑 1：`Part.from_function_response()` 不接受 `id` 參數

❌ 坑 2：`include_server_side_tool_invocations=True` 讓 Pydantic 爆炸

❌ 坑 3：`textQuery` 是 `searchText` 的參數，不是 `searchNearby` 的

❌ 坑 4：`response.candidates[0]` 沒有 guard

❓ 為什麼 `openclaw` 指令會突然消失？

💡 為什麼改了 GCP 磁碟大小，`df -h` 卻沒變？

❌ 坑 1：`FunctionResponseBlob` 不是 `Blob`

❌ 坑 2：`aiohttp.ClientSession` 不能在 module level 建立