05 — 擴充

專家 Agent

Agent 是 Manager 透過 A2A 派工的容器化專家。從 GitHub、本地路徑、遠端 URL 都能加。

官方 Agent

官方 Agent 放在 costaff-ai GitHub 組織。目前陣容（完整介紹見 AI 員工）：

Agent	Repo	做什麼
商業分析	`costaff-agent-business-analysis`	自動選圖表 + 寫敘事；輸出排版完整的 PDF / PPT / PNG（完整 CJK 字型支援）。
程式開發	`costaff-agent-coding`	在沙盒裡寫並執行 Python — 資料清理、格式轉換、批次工作。
資料庫	`costaff-agent-database`	自然語言查 PostgreSQL / MySQL，schema 自動探索。
Twinkle Hub	`costaff-agent-twinkle-hub`	政府開放資料：52,960+ 資料集，DuckDB 在源頭過濾。
Template	`costaff-agent-template`	自己寫專家 Agent 的起點（ADK + MCP + manifest）。

從 GitHub 安裝（官方與社群）

用 repo URL 加：

# 商業分析專家
costaff agent add business-analysis \
  --github https://github.com/costaff-ai/costaff-agent-business-analysis

# 程式開發專家
costaff agent add coding \
  --github https://github.com/costaff-ai/costaff-agent-coding

CLI 會把 repo clone 到 ~/.costaff/costaff-agent/<name>/src/，驗證 manifest（加 --strict 可強制過完整 Agent Protocol JSON Schema），詢問必要的 env var（或用 -e KEY=VAL 預先帶入），build image 並起容器，然後重啟 Manager 讓它看到新 Agent。

工具清單預設就是精簡的

agent add 會自動只開放新 Agent 需要的 4 個平台核心 MCP 工具（send_message_now、add_task_comment、move_to_shared、list_data_files）— 而不是全部 ~40 個。工具規格更小、token 更省、選錯工具更少。之後可在 config.json → agent_mcp_filters 自訂。

從本地路徑（開發用）

costaff agent add my-agent --local /path/to/my-agent

適合 fork 之後在本機改、或自己寫一個 Agent 的時候。CLI 直接用該目錄，不會 copy。

註冊遠端 A2A endpoint

已經有 A2A server 跑在別處？跳過 clone，直接用 URL：

costaff agent add partner-agent --url http://partner.example.com:8081

管理 Agent

指令	作用
`costaff agent list`	列出所有已註冊 Agent、A2A URL、健康檢查結果。
`costaff agent restart <name>`	重啟容器，不 rebuild image，快。
`costaff agent rebuild <name>`	Rebuild image 並重啟。改 code 或 `.env` 後需要。
`costaff agent remove <name>`	停掉、移除、unregister。
`costaff agent enable / disable <name>`	切換 Manager 要不要派工給它（不移除）。
`costaff agent model <name>`	查詢或設定某個 Agent 的 LLM model。
`costaff agent tags <name>`	列出該 Agent repo 可用的 release tag（pin 版本用）。

Pin 版本

把 Agent 釘在某個 git tag / branch / SHA，rebuild 就不會偷偷拉到最新。上 production 之後想讓每次發版都是刻意的，就用這個。

# 裝的時候直接 pin
costaff agent add coding \
  --github https://github.com/costaff-ai/costaff-agent-coding \
  --tag v0.1.0-alpha-2

# 之後 rebuild 會停在 pin 的 ref
costaff agent rebuild coding

# 換 pin
costaff agent rebuild coding --tag v0.2.0

# 跳過 git，直接用工作樹現有內容 build
costaff agent rebuild coding --no-pull

costaff agent list 的 Ref 欄會顯示目前的 ref。完整說明見 CLI → 版本 pin。

每個 Agent 用不同 model

每個專家可以跑不同 model。把 coding agent 指到 gemini-3-flash-preview、BA agent 留在比較小的 model，或把某個 Agent 接到本機 Ollama 透過 LiteLLM。

自己寫一個 Agent

Fork costaff-agent-template — 內含 ADK agent 骨架、MCP server、costaff.agent.json manifest、compose fragment。Agent 必須遵守的契約（manifest schema、A2A 行為、4 個核心 MCP 工具、workspace 慣例）規範在 Agent Protocol v1.0。開發時用 costaff agent add my-agent --local /path/to/my-agent，成熟後再發佈到 GitHub。