Agent Starter Pack (ASP) 完整教學

Google Cloud 生產級 AI Agent 模板工具 — 從原型到部署的一站式腳手架

⚠️ MAINTENANCE MODE 警告

Agent Starter Pack 已於 2026 年 4 月正式進入維護模式 (Maintenance Mode)。官方不再新增功能、模板或部署目標，僅接受關鍵修復。所有活躍開發已轉移至後繼專案 agents-cli。

• 新專案應直接使用 agents-cli
• 既有 ASP 專案建議評估遷移（遷移只需幾分鐘）
• 本教學仍完整介紹 ASP 架構，因為理解 ASP 有助於銜接 agents-cli

1. 專案定位 — ASP 是什麼？為什麼重要？

Agent Starter Pack (ASP; Agent 新手包) 是 Google Cloud Platform (GCP) 官方提供的 Python CLI 工具，用來快速產生生產級 (Production-Ready) AI Agent 專案模板。它解決了 GenAI 開發中最痛苦的「最後一哩路 (Last Mile)」問題：

graph LR
    A["🧪 原型階段
Prototype
幾天完成"] --> B["😰 生產化鴻溝
Production Gap
3-9 個月"]
    B --> C["🚀 生產環境
Production
基礎設施 + CI/CD + 監控"]
    
    D["Agent Starter Pack"] -->|"一鍵填補"| B
    
    style B fill:#ff6b6b,color:#fff
    style D fill:#4ecdc4,color:#fff

ASP 的角色定位

ASP 是 agents-cli 的前身。Google 團隊在實務經驗中發現，即使是經驗豐富的 GCP 開發者，要把一個簡單的 GenAI Agent 帶到生產環境也需要 3 個月以上。ASP 就是為了壓縮這段時間而誕生的。

ASP 的核心理念：「帶上你自己的 Agent (Bring Your Own Agent)」

• 你負責：Agent 邏輯、Prompt、工具定義、商業邏輯
• ASP 負責：基礎設施、CI/CD、可觀測性、安全性、部署、測試、前端 UI

ASP vs agents-cli 定位

📌 本段重點：ASP 是 Google Cloud 官方的 AI Agent 模板產生工具，已進入維護模式。新專案請用 agents-cli，但理解 ASP 架構對銜接 agents-cli 非常有幫助。

2. 安裝指南

前置需求

安裝方式（依推薦順序）

方式一：uvx（推薦，零安裝）

1# 單一指令，不需永久安裝
2uvx agent-starter-pack create

方式二：uv tool install（全域安裝）

1uv tool install agent-starter-pack
2agent-starter-pack create

方式三：pip + venv

1python -m venv .venv && source .venv/bin/activate
2pip install agent-starter-pack
3agent-starter-pack create

方式四：零設定雲端環境

• Firebase Studio — 瀏覽器內完整開發環境
• Cloud Shell — GCP 內建終端機

安裝驗證

1agent-starter-pack --version
2# 預期輸出：GCP Agent Starter Pack CLI version: 0.41.3
3
4agent-starter-pack --help
5# 列出所有可用子指令

升級與移除

📌 本段重點：推薦用 uvx 零安裝執行。前置需求包含 Python 3.10+、gcloud SDK、Terraform、Make。安裝後用 --version 驗證。

3. 核心架構

3.1 高層架構總覽

graph TB
    subgraph "Agent Starter Pack CLI"
        CLI["agent-starter-pack CLI
(Click + Cookiecutter)"]
        CLI --> CMD_CREATE["create"]
        CLI --> CMD_ENHANCE["enhance"]
        CLI --> CMD_SETUP["setup-cicd"]
        CLI --> CMD_UPGRADE["upgrade"]
        CLI --> CMD_EXTRACT["extract"]
        CLI --> CMD_LIST["list"]
    end
    
    subgraph "Agent Templates"
        T1["adk
ReAct Agent"]
        T2["adk_a2a
A2A Protocol"]
        T3["agentic_rag
RAG Agent"]
        T4["langgraph
LangGraph Agent"]
        T5["adk_live
即時多模態"]
        T6["adk_go / adk_ts / adk_java
多語言模板"]
    end

    subgraph "Generated Project"
        APP["app/
Agent 邏輯"]
        DEPLOY["deployment/
Terraform IaC"]
        CICD[".github/ 或 .cloudbuild/
CI/CD Pipelines"]
        TEST["tests/
單元 + 整合 + 負載"]
        FRONT["frontend/
Web UI"]
        NB["notebooks/
Jupyter 實驗"]
    end

    subgraph "Deployment Targets"
        CR["Cloud Run
(Serverless)"]
        GKE["GKE Autopilot
(Kubernetes)"]
        AE["Agent Engine
(Managed)"]
    end

    subgraph "Observability"
        CT["Cloud Trace
(OpenTelemetry)"]
        BQ["BigQuery
(Analytics)"]
        CL["Cloud Logging
(10 年保存)"]
    end

    CMD_CREATE --> T1 & T2 & T3 & T4 & T5 & T6
    T1 & T2 & T3 & T4 & T5 & T6 --> APP & DEPLOY & CICD & TEST & FRONT & NB
    APP --> CR & GKE & AE
    CR & GKE & AE --> CT & BQ & CL

3.2 CLI 指令架構

ASP 的 CLI 使用 Python Click 框架建構，透過 Cookiecutter 模板引擎生成專案：

3.3 Agent 模板比較

graph LR
    subgraph "Python 模板"
        ADK["adk
基礎 ReAct"]
        ADK_A2A["adk_a2a
A2A 分散式"]
        RAG["agentic_rag
文件 RAG"]
        LG["langgraph
圖結構 Agent"]
        LIVE["adk_live
即時多模態"]
    end
    
    subgraph "多語言模板"
        GO["adk_go
Go"]
        TS["adk_ts
TypeScript"]
        JAVA["adk_java
Java + Spring Boot"]
    end
    
    ADK -->|"+ A2A Protocol"| ADK_A2A
    ADK -->|"+ RAG Pipeline"| RAG
    ADK -->|"+ WebSocket + 音視訊"| LIVE
    
    style ADK fill:#4285f4,color:#fff
    style RAG fill:#34a853,color:#fff
    style LIVE fill:#ea4335,color:#fff
    style LG fill:#fbbc04,color:#000

3.4 生成的專案結構

 1my-agent/
 2├── app/                    # Agent 核心邏輯
 3│   ├── agent.py           #   root_agent 定義 + 工具
 4│   └── __init__.py
 5├── deployment/             # Terraform IaC
 6│   └── terraform/
 7│       ├── dev/           #   開發環境
 8│       ├── staging/       #   預備環境
 9│       └── prod/          #   生產環境
10├── .github/workflows/      # GitHub Actions CI/CD
11│   ├── pr_checks.yaml     #   PR 檢查
12│   ├── staging.yaml       #   合併到 main → 部署 staging
13│   └── deploy-to-prod.yaml#   手動核准 → 部署 production
14├── tests/
15│   ├── unit/              # 單元測試
16│   ├── integration/       # 整合測試
17│   └── load_test/         # 負載測試
18├── notebooks/              # Jupyter 評估筆記本
19├── frontend/               # Web UI (React)
20├── Makefile                # 開發指令入口
21├── pyproject.toml          # Python 套件設定
22├── GEMINI.md               # AI 助手上下文檔
23└── README.md               # 專案說明

3.5 部署管線流程

sequenceDiagram
    participant Dev as 開發者
    participant PR as Pull Request
    participant CI as CI Pipeline
    participant Staging as Staging 環境
    participant Approve as 人工審核
    participant Prod as Production 環境
    
    Dev->>PR: 建立 PR
    PR->>CI: 觸發 CI 檢查
    CI->>CI: 單元測試 + 整合測試
    CI-->>PR: ✅ 通過 / ❌ 失敗
    Dev->>PR: 合併到 main
    PR->>Staging: 自動部署到 Staging
    Staging->>Staging: 自動負載測試
    Staging->>Approve: 等待人工審核
    Approve->>Prod: 核准後部署到 Production

📌 本段重點：ASP 使用 Click + Cookiecutter 架構，提供 8 種 Agent 模板覆蓋 4 種語言，支援 3 個部署目標（Cloud Run / GKE / Agent Engine），內建完整 CI/CD 管線（staging → 人工審核 → production）。

4. 詳細用法

4.1 建立新專案

互動模式（推薦新手）

1uvx agent-starter-pack create
2# 互動式引導選擇：
3#   1. 專案名稱
4#   2. Agent 模板（adk / agentic_rag / langgraph / ...）
5#   3. 部署目標（cloud_run / gke / agent_engine）
6#   4. CI/CD 運行器（google_cloud_build / github_actions / skip）

指定參數模式

 1# Python ADK Agent 部署到 Cloud Run
 2uvx agent-starter-pack create my-agent -a adk -d cloud_run
 3
 4# RAG Agent 搭配 Vertex AI Search
 5uvx agent-starter-pack create my-rag-agent -a agentic_rag -ds vertex_ai_search
 6
 7# Go Agent
 8uvx agent-starter-pack create my-go-agent -a adk_go -d cloud_run
 9
10# TypeScript Agent
11uvx agent-starter-pack create my-ts-agent -a adk_ts -d cloud_run
12
13# 快速原型（跳過 CI/CD 和 Terraform）
14uvx agent-starter-pack create my-prototype -p -d agent_engine

使用遠端模板

1# ADK 範例模板
2uvx agent-starter-pack create my-agent -a adk@gemini-fullstack
3
4# GitHub 倉庫作為模板
5uvx agent-starter-pack create my-agent -a https://github.com/user/my-template
6
7# 用本地專案作為模板
8uvx agent-starter-pack create my-agent -a local@./my-project

4.2 本地開發

 1cd my-agent
 2
 3# 安裝依賴
 4make install
 5
 6# 啟動互動式 Playground（含 Hot Reload）
 7make playground
 8
 9# 執行測試
10make test
11
12# 程式碼品質檢查
13make lint

4.3 增強既有專案

已經有 Agent 程式碼？用 enhance 加入生產級基礎設施：

 1cd my-existing-agent
 2
 3# 加入 CI/CD + Terraform + 測試
 4uvx agent-starter-pack enhance
 5
 6# 指定部署目標
 7uvx agent-starter-pack enhance --deployment-target cloud_run
 8
 9# 加入 RAG 資料管線
10uvx agent-starter-pack enhance --datastore vertex_ai_search

enhance 會自動備份你的專案到 ~/.agent-starter-pack/backups/。

4.4 部署到 Google Cloud

階段一：開發環境部署

1# 設定 GCP 專案
2gcloud config set project YOUR_DEV_PROJECT_ID
3
4# 用 Terraform 建立開發環境基礎設施
5make setup-dev-env
6
7# 部署 Agent
8make deploy

階段二：完整 CI/CD 管線

1# 一鍵設定（互動式引導）
2uvx agent-starter-pack setup-cicd
3
4# 或指定參數
5uvx agent-starter-pack setup-cicd \
6  --staging-project my-staging-id \
7  --prod-project my-prod-id \
8  --repository-name my-agent-repo

setup-cicd 自動完成：

• 建立 / 連接 GitHub Repository
• 設定 Terraform 基礎設施（staging + production）
• 配置 CI/CD 觸發器（Cloud Build 或 GitHub Actions）
• 設定 Workload Identity Federation (WIF) 安全認證

觸發首次部署

1git add -A
2git commit -m "Initial commit of agent code"
3git push --set-upstream origin main

4.5 版本升級（3-Way Merge）

1# 預覽變更（不實際修改）
2uvx agent-starter-pack upgrade --dry-run
3
4# 執行升級
5uvx agent-starter-pack upgrade

3-Way Merge 智慧策略：

4.6 可觀測性 (Observability)

ASP 內建兩層可觀測性：

第一層：Cloud Trace 遙測（預設啟用）

• OpenTelemetry (OTel) 自動追蹤所有 Agent 操作
• 分散式追蹤 (Distributed Tracing)
• 延遲分析 (Latency Analysis)
• 錯誤追蹤

第二層：BigQuery Agent Analytics（選擇性啟用）

• 深度 LLM 互動記錄
• Token 用量分析
• BigQuery 對話式分析
• 自訂 Dashboard

 1-- 範例：分析過去 24 小時 Token 用量
 2SELECT
 3  model,
 4  service_namespace,
 5  COUNT(*) as request_count,
 6  SUM(input_tokens) as total_input_tokens,
 7  SUM(output_tokens) as total_output_tokens
 8FROM `project.telemetry.genai_telemetry`
 9WHERE timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 24 HOUR)
10GROUP BY model, service_namespace
11ORDER BY total_input_tokens DESC;

4.7 RAG 資料管線

支援兩種資料儲存方案：

1# 建立 RAG Agent 搭配 Vertex AI Search
2uvx agent-starter-pack create my-rag -a agentic_rag -ds vertex_ai_search
3
4cd my-rag
5make setup-datastore   # 建立 GCS bucket + Data Connector + Search Engine
6make sync-data         # 上傳文件並觸發同步

📌 本段重點：ASP 用法分五大步驟 — create（建立）→ develop（本地開發）→ enhance（增強）→ deploy（部署）→ observe（監控）。CI/CD 用 setup-cicd 一鍵完成，升級用 3-way merge 保留自訂修改。

5. 應用場景

5.1 典型使用場景

場景一：生技公司內部知識庫 Agent

你的 BD 團隊需要一個能查詢內部文件（臨床報告、藥物資料）的 AI 助手。

1# 用 RAG 模板建立
2uvx agent-starter-pack create pharma-qa -a agentic_rag -ds vertex_ai_search -d cloud_run
3
4# 上傳臨床文件到 sample_data/
5cp ~/clinical_reports/*.pdf my-agent/sample_data/
6
7# 設定資料儲存並部署
8cd pharma-qa && make install && make setup-datastore && make deploy

場景二：即時客服 Agent（音視訊）

1# 用 Live API 模板
2uvx agent-starter-pack create support-agent -a adk_live -d cloud_run

場景三：多 Agent 協作系統

1# 用 A2A Protocol 模板
2uvx agent-starter-pack create multi-agent -a adk_a2a -d cloud_run

5.2 何時該留在 ASP、何時該遷移到 agents-cli？

graph TD
    Q1{"你是否有既有的
ASP 專案？"}
    Q1 -->|"是"| Q2{"專案是否穩定運行
且不需新功能？"}
    Q1 -->|"否（全新專案）"| MIGRATE["✅ 直接用 agents-cli
uvx google-agents-cli setup"]
    
    Q2 -->|"是，穩定運行"| STAY["⏸️ 可以暫留 ASP
持續收到關鍵修復"]
    Q2 -->|"否，需要新功能"| Q3{"是否需要以下功能？"}
    
    Q3 --> F1["統一 CLI
(run/deploy/eval)"]
    Q3 --> F2["Coding-agent skills"]
    Q3 --> F3["Agent Platform 支援"]
    
    F1 & F2 & F3 --> MIGRATE
    
    style MIGRATE fill:#4ecdc4,color:#fff
    style STAY fill:#f9ca24,color:#000

留在 ASP 的條件（全部滿足）：

• 既有專案穩定運行中
• 不需要新的模板或部署目標
• 團隊暫時沒有遷移資源
• 只需要關鍵安全修復

應該遷移到 agents-cli 的條件（任一即可）：

• 新啟動的專案
• 需要統一 CLI（取代 Makefile）
• 需要 coding-agent skills 整合
• 需要 Agent Platform 原生支援
• 需要最新模板和功能更新
• 想要端到端生命週期工具（scaffold → eval → deploy → publish → observe）

📌 本段重點：ASP 適合生技公司快速建立知識庫 Agent、即時客服 Agent、多 Agent 系統。新專案直接用 agents-cli，既有穩定專案可暫留 ASP。

6. 資安掃描

6.1 供應鏈安全

6.2 生成專案的安全特性

6.3 需要注意的風險

📌 本段重點：ASP 由 Google 官方維護，授權友善。生成的專案內建 WIF、IAM 最小權限、隱私保護遙測等安全機制。主要風險是維護模式狀態，建議規劃遷移。

7. FAQ

Q1: ASP 和 agents-cli 可以同時安裝嗎？

可以。兩者是獨立套件。但建議新專案直接用 agents-cli，避免混淆。

Q2: make playground 開不起來？

常見原因：

1. 沒有設定 GCP 認證：gcloud auth application-default login
2. Python 版本不符：需要 3.10+
3. 依賴未安裝：先執行 make install

Q3: 遷移到 agents-cli 會影響既有部署嗎？

不會。遷移只影響開發工具鏈，你的 Agent 程式碼、Terraform 和 CI/CD 設定都會保留。

Q4: 可以在非 GCP 環境部署嗎？

ASP 深度整合 GCP 服務。雖然 Agent 邏輯可以在任何地方運行，但基礎設施模板（Terraform / CI/CD / Observability）都針對 GCP 設計。

Q5: agentic_rag 和一般 adk 有什麼差別？

agentic_rag 在 adk 基礎上加了：

• 資料管線 (Data Ingestion Pipeline)
• Vertex AI Search 或 Vector Search 整合
• 文件檢索工具定義
• 額外的 Terraform 設定（GCS bucket / Data Connector / Search Engine）

Q6: Java / Go / TypeScript 模板支援所有部署目標嗎？

目前僅支援 Cloud Run。Agent Engine 和 GKE 部署僅限 Python 模板。

Q7: 如何為 Agent 加入自訂工具？

在 app/agent.py 中定義 Python 函式，加上型別標註和 Docstring，然後加入 tools 清單：

 1def search_clinical_trials(query: str, phase: str = "Phase 3") -> str:
 2    """搜尋臨床試驗資料。
 3    
 4    Args:
 5        query: 搜尋關鍵字（疾病名、藥物名）
 6        phase: 臨床試驗階段（Phase 1/2/3）
 7    
 8    Returns:
 9        符合條件的臨床試驗摘要
10    """
11    # 你的搜尋邏輯
12    return results
13
14root_agent = Agent(
15    name="root_agent",
16    model=Gemini(model="gemini-3-flash-preview"),
17    instruction="你是臨床試驗查詢助手。",
18    tools=[search_clinical_trials],
19)

📌 本段重點：常見問題包括安裝疑難、遷移影響、模板差異、自訂工具方法。Java/Go/TS 模板目前僅支援 Cloud Run。

8. 進階技巧

8.1 遠端模板系統

你可以把自己的 Agent 包裝成可重用的模板，分享給團隊：

1# 建立模板
2uvx agent-starter-pack create my-agent -a local@./my-custom-agent
3
4# 從 GitHub 使用你的模板
5uvx agent-starter-pack create new-agent -a https://github.com/myorg/my-template
6
7# 搭配 Branch 指定
8uvx agent-starter-pack create new-agent -a github.com/myorg/template@develop

模板版本鎖定機制確保相容性：ASP 會讀取模板中的 asp_version 並使用對應版本生成。

8.2 原型到生產的漸進路徑

 1# 第一步：快速原型（無 CI/CD、無 Terraform）
 2uvx agent-starter-pack create my-agent --prototype
 3
 4# 第二步：加入 CI/CD 和基礎設施
 5cd my-agent
 6uvx agent-starter-pack enhance --cicd-runner github_actions
 7
 8# 第三步：一鍵部署完整管線
 9uvx agent-starter-pack setup-cicd \
10  --staging-project staging-123 \
11  --prod-project prod-456

8.3 BigQuery Agent Analytics

對 ADK Agent 啟用深度分析：

1# 建立時啟用
2uvx agent-starter-pack create my-agent -a adk --bq-analytics

啟用後可用 BigQuery 做：

• LLM-as-a-Judge 評估
• 對話分析 (Conversational Analytics)
• Token 用量追蹤
• 自訂 Dashboard

8.4 Gemini CLI 整合

生成的專案包含 GEMINI.md 上下文檔，可直接搭配 Gemini CLI 使用：

1# 在專案目錄中使用 Gemini CLI 詢問架構問題
2gemini "How do I add a new tool to my agent?"

8.5 extract 指令 — 提取最小 Agent

1# 從完整專案提取可分享的最小 Agent
2uvx agent-starter-pack extract

適合在團隊間分享 Agent 邏輯，去除基礎設施設定。

📌 本段重點：進階用法包含遠端模板分享、漸進式生產化（prototype → enhance → setup-cicd）、BigQuery 深度分析、Gemini CLI 整合。

9. 整合工作流 — 遷移到 agents-cli

9.1 遷移路徑總覽

graph LR
    subgraph "Before: ASP"
        ASP_CLI["agent-starter-pack CLI"]
        ASP_MAKE["Makefile 指令"]
        ASP_EVAL["notebooks/ 評估"]
    end
    
    subgraph "After: agents-cli"
        ACLI["google-agents-cli CLI"]
        ACLI_RUN["agents run"]
        ACLI_DEPLOY["agents deploy"]
        ACLI_EVAL["agents eval run / compare"]
        ACLI_PLAY["agents playground"]
        ACLI_LINT["agents lint"]
    end
    
    ASP_CLI -->|"遷移"| ACLI
    ASP_MAKE -->|"取代"| ACLI_RUN & ACLI_DEPLOY & ACLI_PLAY & ACLI_LINT
    ASP_EVAL -->|"升級"| ACLI_EVAL
    
    style ASP_CLI fill:#ff6b6b,color:#fff
    style ACLI fill:#4ecdc4,color:#fff

9.2 遷移步驟

1# 步驟一：安裝 agents-cli
2uvx google-agents-cli setup
3
4# 步驟二：在既有 ASP 專案中執行遷移
5cd my-asp-project
6# 參考官方遷移指南：
7# https://google.github.io/agents-cli/reference/from-agent-starter-pack/

9.3 指令對照表

9.4 保留的資產

遷移時以下資產會原樣保留，無需重寫：

• app/agent.py — Agent 邏輯
• deployment/terraform/ — Terraform IaC
• tests/ — 測試程式碼
• .github/workflows/ — CI/CD 管線
• frontend/ — Web UI

📌 本段重點：遷移到 agents-cli 只需幾分鐘，核心資產（Agent 邏輯、Terraform、CI/CD、測試）全部保留。主要差異是 Makefile 指令被統一 CLI 取代。

10. 重點摘要

一句話總結

Agent Starter Pack 是 Google Cloud 的 AI Agent 生產化腳手架，用一個指令生成含 CI/CD / Terraform / Observability / 前端 UI 的完整專案 — 已進入維護模式，後繼者是 agents-cli。

核心價值

指令速查

 1# 建立專案
 2uvx agent-starter-pack create my-agent -a adk -d cloud_run
 3
 4# 本地開發
 5cd my-agent && make install && make playground
 6
 7# 增強既有專案
 8uvx agent-starter-pack enhance
 9
10# 部署 CI/CD
11uvx agent-starter-pack setup-cicd
12
13# 版本升級
14uvx agent-starter-pack upgrade --dry-run
15
16# 遷移到 agents-cli
17uvx google-agents-cli setup

關鍵決策樹

📌 本段重點：ASP 一個指令省下數月工作。新專案用 agents-cli，既有專案評估遷移。指令速查表涵蓋完整生命週期。

11. 進一步閱讀

官方資源

影片教學

相關技術

本教學基於 Agent Starter Pack v0.41.3 (2026-04-25) 撰寫。因專案已進入維護模式，未來不會有重大功能更新。建議搭配 agents-cli 文件閱讀。