用 agents-cli 部署企業級 AI 代理工作流

📌 本文重點

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 個常用服務，草擬對應的 Skill YAML 定義

使用 agents init 建立試驗專案，先在本地用 agents run 模擬一條簡單工作流

把這條工作流接入 GitHub Actions 或 GitLab CI，測試以 infra-as-code 管理 Agent 部署與更新

用 agents-cli 打造可運維的企業級 AI 代理

重點說明

1. 架構：技能（Skill）與工作流（Agent Workflow）的抽象

2. 本地開發到雲端部署的標準流程

3. 多工具調用、狀態與長任務管理

4. 把 Agent 當「基礎設施」接入 CI/CD

實作範例

1. 資料管線自動化（ETL / 報表）

2. 內部客服流程

3. 自動 Code Review／Release Checklist

建議與注意事項

1. IAM / Service Account 權限邊界

2. 成本與 LLM 調用暴衝

3. 錯誤恢復與重試策略

4. Agent 邊界與隱私風險

留言

發佈留言 取消回覆

更多文章

Qwen3.8-Max 長任務實戰與部署攻略

用 loopx＋Cloudflare computer 組一支 AI 遠端團隊

用手機跑 128K AI 小助手：LFM2.5 實戰

Google 把手機交給 Gemini，是升級還是賭博？

發佈留言取消回覆