📌 本文重點
- agents-cli 把零散工具與 LLM 變成企業級代理工作流
- 從本地 YAML 到 Google Cloud，自動處理部署與運維
- 透過 Skill/Agent/Workflow 抽象設計長任務與多工具協作
- 以 infra-as-code 思維接入 CI/CD，強調安全、成本與邊界控制
agents-cli 解決的核心痛點很直接：把「一堆零散的工具 + LLM」變成「可觀測、可部署、可運維的企業級代理工作流」。從本地 YAML 設定開始，到在 Google Cloud 串 Cloud Run / Pub/Sub / Vertex AI，它幫你處理流程編排、狀態管理、重試機制與部署細節，讓 Agent 真正變成基礎設施，而不是一支難以維護的 side project。
重點說明
1. 架構：技能（Skill）與工作流（Agent Workflow）的抽象
agents-cli 把整個系統拆成三層：
- Skill：可被代理調用的「工具」，可以是
HTTP API、Cloud Run、自家微服務或腳本。 - Agent：具備目標與決策能力的 LLM，根據上下文決定要呼叫哪些
Skill。 - Workflow：如何觸發、排程、分派與監控 Agent 任務（多步、多工具、長流程）。
在專案結構上，你會看到類似：
agents-project/
skills/
bigquery_query.yaml
github_review.yaml
agents/
data-pipeline-agent.yaml
support-agent.yaml
workflows/
nightly-etl.yaml
release-checklist.yaml
envs/
dev.yaml
prod.yaml
Skill 定義了 輸入/輸出 schema、實體執行位置（Cloud Run URL / Pub/Sub topic）、權限需求；Agent 則描述 使用的 LLM（如：Vertex AI Gemini）、工具列表、記憶／狀態儲存方式。
💡 關鍵： Skill / Agent / Workflow 三層抽象，讓複雜代理系統可以用清晰結構拆開管理與維護。
2. 本地開發到雲端部署的標準流程
在 CLI 層面，agents-cli 抽象出一條典型路徑：
- 本地定義與模擬：用
YAML/JSON定義Skill、Agent，使用agents run在本地模擬工作流。 - 雲端資源生成：使用
agents deploy把設定轉成 Cloud Run / Pub/Sub / Vertex AI 的組合。 - 可觀測性與評估：透過內建 trace/log，或串接類似 LangSmith 的觀測平台，監控 LLM 行為與成本。
常見指令會長這樣：
# 初始化專案
agents init my-enterprise-agent
# 本地跑某個工作流
agents run workflows/nightly-etl.yaml --env envs/dev.yaml
# 部署到 Google Cloud
agents deploy --env envs/prod.yaml \
--project my-gcp-project \
--region asia-east1
# 檢查部署狀態
agents status --project my-gcp-project
env 的 YAML 會綁定 GCP 專案、Region、Service Account 等環境設定，讓同一套 Agent 設定可以跨 dev/stage/prod 運行。
3. 多工具調用、狀態與長任務管理
agents-cli 的工作流設計，基本上幫你處理三件事：
- 多工具選擇與調度：LLM 透過工具描述（
tool schema）和系統 prompt，決定當前步驟要用哪個Skill。 - 狀態記錄：把每步執行的輸入、輸出與決策 trace 下來，存到 Cloud Logging / BigQuery / 自訂 DB。
- 長任務處理：用 Pub/Sub + Cloud Run 做非同步排程、重試、錯誤恢復。
典型的 Skill 設定示例：
# skills/bigquery_query.yaml
name: bigquery_query
runtime: cloud_run
endpoint: https://bigquery-run-service-xxxx.run.app/query
input_schema:
type: object
properties:
sql:
type: string
dataset:
type: string
output_schema:
type: object
properties:
rows:
type: array
items:
type: object
retry_policy:
max_attempts: 3
backoff_seconds: 30
logging:
enabled: true
sink: bigquery
在 Agent 設定中會引用這個 Skill：
# agents/data-pipeline-agent.yaml
name: data-pipeline-agent
model: vertex_ai_gemini_1_5_pro
system_prompt: |
你是資料工程代理，負責每日 ETL 任務。
嚴格遵守工具輸入/輸出 schema，錯誤時優先重試或回報。
skills:
- bigquery_query
- gcs_file_writer
state_store:
type: firestore
collection: agent_states
Workflow 則決定觸發方式：
# workflows/nightly-etl.yaml
name: nightly-etl
agent: data-pipeline-agent
trigger:
type: schedule
cron: "0 2 * * *" # 每天 02:00
initial_input:
task: "跑昨日訂單 ETL，更新匯總表"
error_handling:
notify:
type: pubsub
topic: agent-errors
retry:
max_attempts: 2
delay_seconds: 300
這樣一來，長任務會由排程觸發 Pub/Sub，交給 Cloud Run 上的 Agent runtime 處理；錯誤時有自動重試與告警管道，不用自己寫排程器和重試邏輯。
💡 關鍵： 透過 retry 與 error_handling 設定，長任務可以安全自動重試並告警，而不用額外寫排程與錯誤恢復程式。
4. 把 Agent 當「基礎設施」接入 CI/CD
agents-cli 的另一個實用點是：部署過程本身就長得像 infra-as-code，非常適合放進 GitHub Actions 或 GitLab CI。
以 GitHub Actions 為例：
# .github/workflows/deploy-agent.yaml
name: Deploy Agents
on:
push:
branches: [ main ]
paths:
- "agents/**"
- "skills/**"
- "workflows/**"
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup gcloud
uses: google-github-actions/setup-gcloud@v2
with:
project_id: ${{ secrets.GCP_PROJECT_ID }}
service_account_key: ${{ secrets.GCP_SA_KEY }}
- name: Install agents-cli
run: pip install agents-cli
- name: Deploy agents
run: |
agents deploy \
--env envs/prod.yaml \
--project ${{ secrets.GCP_PROJECT_ID }} \
--region asia-east1
這樣做的好處：
- Agent 配置版本化，每次改動都有 commit 與審查。
- 部署流程可審核、可回滾，適合安全與合規要求（尤其是醫療、金融領域）。
- 搭配類似 Gemini Spark Workflow 的設計理念，可以明確設定 Agent 何時啟動、何種操作需要人工確認。
實作範例
1. 資料管線自動化（ETL / 報表）
場景：每天需要從 BigQuery 拉數據、轉換後寫回 GCS 或更新 Looker 報表。
Skill 組合：
- bigquery_query：查詢資料
- gcs_file_writer：寫檔到 Cloud Storage
- report_notifier：透過 Pub/Sub 通知 BI 團隊或觸發下游流程
Workflow 配置重點：
- 用
schedule觸發，搭配 錯誤告警 Pub/Sub topic。 - 在 Agent prompt 中明確要求：遇到資料不完整先記錄再通知，不要靜默失敗。
2. 內部客服流程
場景：員工在內部系統丟 ticket，Agent 自動分類、查 FAQ、串 Jira / ServiceNow 建單。
Skill 組合：
- faq_search（Vertex AI + 自家向量 DB）
- ticket_creator（Cloud Run microservice）
- slack_notifier
設計重點：
- 參考 Gemini Spark 的模式：重大操作（例如關閉工單）要經過使用者確認，在 Agent prompt 裡要求先生成「建議動作」，再透過
notifier skill要求人工點擊確認。 - 用
state_store記錄每個 ticket 的處理歷史，方便審計。
3. 自動 Code Review／Release Checklist
場景：PR 建立後，由 Agent 自動跑靜態檢查、變更摘要與 release checklist，最後用評論回寫到 GitHub。
Skill 組合：
- repo_diff_reader：抓取 PR diff
- static_analyzer：呼叫現有
lint / SAST工具 - github_commenter：寫回 GitHub PR 留言
Workflow：
# workflows/release-checklist.yaml
name: release-checklist
agent: release-agent
trigger:
type: webhook
source: github
event: pull_request
initial_input:
task: "分析這個 PR 的風險、受影響模組與 release checklist"
好處：
- 把原本散落在 CI pipeline 的檢查整合，由 Agent 產出有脈絡的總結與建議。
- 透過多
Skill組合（lint、測試結果、變更摘要），降低 reviewer 的認知負擔。
建議與注意事項
1. IAM / Service Account 權限邊界
常見坑：
- 把整個 Agent runtime 綁一個 過度授權的 Service Account，導致 Agent 有權限操作所有 GCP 資源。
建議：
- 每個
Skill使用 專用 Service Account，並在YAML中註記：
security:
service_account: bigquery-reader-sa@project.iam.gserviceaccount.com
iam_roles:
- roles/bigquery.dataViewer
- 用 VPC Service Controls / 資料邊界 設計出「有邊界的代理」，敏感資料必須經人工確認技能（如
human_approval）才能存取。
2. 成本與 LLM 調用暴衝
長流程 + 多工具，很容易引起：
- 太多決策回合（多次 model 呼叫）。
- 錯誤重試導致費用倍增。
最佳實踐：
- 為 Agent 設定
max_steps / max_tokens：
execution_limits:
max_steps: 20
max_model_calls: 10
max_tokens_per_call: 8000
- 用 成本監控儀表板：把 trace 寫到 BigQuery，做月度成本分析。
- 對純查詢型任務，考慮簡化：少用思維鏈、多用工具直接查資料。
💡 關鍵： 透過 execution_limits 和成本監控，把多步驟、多工具的代理流程費用控制在可預期範圍。
3. 錯誤恢復與重試策略
不要把「重試」交給 LLM 自己想。使用 agents-cli 的 retry_policy 與 error_handling 明確設定：
- 對 idempotent 的
Skill（如查詢、讀檔）可以多次重試。 - 對非 idempotent 操作（如寫入、付款）要先寫審計 log，再由人處理重試。
結合 LangSmith 類型的觀測工具：
- 對每次錯誤 trace 下來，標記是「工具錯誤」還是「LLM 誤用工具」，方便調整 prompt 或工具設計。
4. Agent 邊界與隱私風險
實務上最容易被忽略的是：Agent 存取範圍默默變大。
控制方法：
- 在 Agent 的
system_prompt明確寫出：哪些資料不可存取／不得持久化。 - 用
Skill層的邊界實作：敏感操作一律透過human_approval skill，例如：
# skills/human_approval.yaml
name: human_approval
runtime: pubsub
topic: approval-requests
required_for_actions:
- "刪除資料"
- "發送外部郵件"
- 參考 HIPAA Voice Agent 的做法：敏感資料永不出邊界，必要時用本地模型或受控環境中的 Vertex AI。
結論：agents-cli 把「AI 代理」拉回工程實務的語境——YAML 設定、CLI 部署、IAM 邊界、觀測與成本控制。如果你已經有一堆工具和 LLM 能力，但遲遲不能在企業落地成正式工作流，這套工具很適合直接試著把現有程式包成 Skill，從一個小型工作流開始，把 Agent 當作基礎設施來運維。
🚀 你現在可以做的事
- 在現有專案中列出 3–5 個常用服務，草擬對應的
SkillYAML 定義- 使用
agents init建立試驗專案，先在本地用agents run模擬一條簡單工作流- 把這條工作流接入 GitHub Actions 或 GitLab CI，測試以 infra-as-code 管理 Agent 部署與更新
