Warden Agent Builder
為 Warden Protocol 的代理錢包生態系統建置並部署 LangGraph 代理程式。
⚠️ 重要：關於範例代理程式
Warden 社群儲存庫中的範例代理用於學習，而非可複製的模板：
- 天氣代理 - 學習此範例以理解簡單的資料擷取模式
- CoinGecko 代理 - 學習此範例以理解 Schema-Guided Reasoning (SGR)
- 投資組合代理 - 學習此範例以理解複雜的多來源整合
請勿建置這些代理 - 它們已存在。相反地：
- 研究它們的程式碼以理解模式
- 學習它們的架構和工作流程
- 建置一個新的、原創的代理程式以參與激勵計劃
您的代理程式必須獨一無二且解決不同的問題，才有資格參與激勵計劃。
概述
Warden Protocol 是一個「為『替我完成』經濟而生的代理錢包」，並設有活躍的代理建置者激勵計劃，開放給部署到 Warden 的 OpenClaw 代理程式。所有代理程式必須基於 LangGraph 並可透過 API 存取。
關鍵資源：
- 社群代理儲存庫：https://github.com/warden-protocol/community-agents
- 文件：https://docs.wardenprotocol.org
- Discord：#developers 頻道以獲取支援
需求檢查清單
在開始建置之前，請確保您的代理符合以下強制性要求：
✓ 框架：使用 LangGraph（TypeScript 或 Python）建置 ✓ 部署：LangSmith Deployments 或自訂基礎設施 ✓ 存取：可透過 API 存取（無需 UI - Warden 提供 UI） ✓ 隔離：每個 LangGraph 實例對應一個代理 ✓ 安全限制（第 1 階段）：
- 無法存取用戶錢包
- 無法在 Warden 基礎設施上儲存資料
✓ 功能：可實作任何工作流程：
- Web3/Web2 自動化
- API 整合
- 資料庫連線
- 外部工具互動
了解範例代理
community-agents 儲存庫包含可學習的參考範例，而非可複製的模板：
範例代理 1：LangGraph 快速入門（學習基礎）
位置：agents/langgraph-quick-start（TypeScript）或 agents/langgraph-quick-start-py（Python）
學到：LangGraph 基礎知識、最小代理結構
研究：使用 OpenAI 整合的單節點聊天機器人
git clone https://github.com/warden-protocol/community-agents.git
cd community-agents/agents/langgraph-quick-start
範例代理 2：天氣代理（學習結構）
位置：agents/weather-agent
學到：簡單的資料擷取、API 整合、使用者友善的回應
研究：
- 如何從外部 API (WeatherAPI) 擷取資料
- 處理和格式化結果
- 清晰的範圍和結構 ⚠️ 請勿建置：此代理已存在。研究它，然後建置新的東西。
範例代理 3：CoinGecko 代理（學習 SGR 模式）
位置：agents/coingecko-agent
學到：Schema-Guided Reasoning、複雜工作流程
研究：
- 5 步驟 SGR 工作流程：驗證 → 擷取 → 擷取 → 驗證 → 分析
- 比較分析模式
- 錯誤處理和資料驗證 ⚠️ 請勿建置：此代理已存在。研究模式，應用於新的用例。
範例代理 4：投資組合分析代理（學習進階模式）
位置：agents/portfolio-agent
學到：多來源資料合成、生產架構
研究：
- 整合多個 API (CoinGecko + Alchemy)
- 多鏈支援 (EVM 和 Solana)
- 複雜的 SGR 工作流程
- 全面的報告 ⚠️ 請勿建置：此代理已存在。研究架構，為您自己的複雜代理提供參考。
重要：建置新的東西
這些範例的存在是為了教學模式與最佳實踐。對於激勵計劃，您必須建立一個原創、獨特的代理程式，解決不同的問題。請勿單純地重建天氣代理、CoinGecko 代理或投資組合代理。
建置您的原創代理
步驟 1：研究範例並選擇您的方法
請勿複製範例進行修改。 相反地：
-
研究範例以理解模式：
- 簡單的資料擷取 → 研究天氣代理
- 複雜分析 → 研究 CoinGecko 代理
- 多來源合成 → 研究投資組合代理
-
確定您獨特的用例：
- 您的代理將解決什麼問題？
- 它將使用哪些 API 或資料來源？
- 它與現有代理有何不同？
-
規劃您代理的工作流程：
- 簡單的請求和回應？
- Schema-Guided Reasoning (SGR)？
- 多步驟分析？
步驟 2：初始化您的新代理
使用初始化腳本建立一個全新的專案：
# 建立您的獨特代理
python scripts/init-agent.py my-unique-agent \
--template typescript \
--description "描述您的代理做什麼的說明"
# 導航到專案目錄
cd my-unique-agent
# 安裝依賴
npm install # TypeScript
# 或者
pip install -r requirements.txt # Python
這會建立一個乾淨的起點，而不是現有代理的副本。
步驟 3：了解 LangGraph 代理結構
每個 LangGraph 代理都遵循這個基本結構：
your-agent/
├── src/
│ ├── agent.ts/py # 主要代理邏輯（您的程式碼）
│ ├── graph.ts/py # LangGraph 工作流程定義（您的程式碼）
│ └── tools.ts/py # 工具實作（您的程式碼）
├── package.json / requirements.txt
├── langgraph.json # LangGraph 設定
└── README.md
需要實作的關鍵檔案：
graph.ts/py- 定義您的工作流程（驗證 → 處理 → 回應）agent.ts/py- 實作您的核心邏輯tools.ts/py- 整合與您代理用途相關的外部 API
步驟 4：實作您的自訂代理邏輯
從範例中研究模式，應用於您的用例：
如果建置簡單的資料擷取器（類似天氣代理模式）：
// 定義工作流程
const workflow = new StateGraph({
channels: agentState
})
.addNode("fetch", fetchYourData) // 您的 API
.addNode("process", processYourData) // 您的邏輯
.addNode("respond", generateResponse);
workflow
.addEdge(START, "fetch")
.addEdge("fetch", "process")
.addEdge("process", "respond")
.addEdge("respond", END);
如果建置複雜分析（類似 CoinGecko 代理模式 - SGR）：
// 定義 5 步驟 SGR 工作流程
const workflow = new StateGraph({
channels: agentState
})
.addNode("validate", validateYourInput) // 您的驗證
.addNode("extract", extractYourParams) // 您的擷取
.addNode("fetch", fetchYourData) // 您的 API
.addNode("analyze", analyzeYourData) // 您的分析
.addNode("generate", generateYourResponse); // 您的格式化
workflow
.addEdge(START, "validate")
.addEdge("validate", "extract")
.addEdge("extract", "fetch")
.addEdge("fetch", "analyze")
.addEdge("analyze", "generate")
.addEdge("generate", END);
關鍵原則：
- 保持工作流程線性且可預測
- 在每個階段驗證輸入
- 優雅地處理錯誤
- 使用 OpenAI 進行自然語言生成
- 一致地建構回應
關鍵：這應該是您的實作，解決您的問題，而不是範例代理的副本。
步驟 5：設定環境
建立 .env 檔案：
# 必要
OPENAI_API_KEY=your_openai_key
# 使用 LangSmith Deployments（雲端）需要
LANGSMITH_API_KEY=your_langsmith_key
# 選用 - 基於您的工具
WEATHER_API_KEY=your_weather_key
COINGECKO_API_KEY=your_coingecko_key
ALCHEMY_API_KEY=your_alchemy_key
取得 LangSmith API 金鑰：
- 在 https://smith.langchain.com 建立帳戶
- 導航至「設定」→「API 金鑰」
- 建立新的 API 金鑰
- 新增至
.env檔案
更新 langgraph.json：
{
"agent_id": "[您的代理名稱]",
"python_version": "3.11", // 若使用 TypeScript 則省略
"dependencies": ["."],
"graphs": {
"agent": "./src/graph.ts" // 或 .py
},
"env": ".env"
}
步驟 6：在本地測試
# TypeScript
npm run dev
# Python
langgraph dev
測試您代理的 API：
curl -X POST http://localhost:8000/invoke \
-H "Content-Type: application/json" \
-d '{"input": "測試查詢"}'
部署選項
選項 1：LangSmith Deployments（推薦）
優點：最快、最簡單、受管基礎設施 需求：LangSmith API 金鑰
步驟：
1. 將您的代理儲存庫推送到 GitHub。
2. 在 LangSmith Deployments 中建立新的部署。
3. 連接儲存庫、設定環境變數並部署。
您的代理將會獲得：
- API 端點 URL
- 自動驗證（使用您的 LangSmith API 金鑰）
- 自動擴展和監控
API 呼叫的驗證： 呼叫已部署的代理時，請包含您的 LangSmith API 金鑰：
curl AGENT_URL/runs/wait \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-api-key: [您的 LangSmith API 金鑰]' \
--data '{
"assistant_id": "[您的代理 ID]",
"input": {
"messages": [{"role": "user", "content": "測試查詢"}]
}
}'
選項 2：自託管基礎設施
優點：完全控制執行環境 需求：
- Docker 容器託管
- 公開的 API 端點
- SSL 憑證（HTTPS）
- 監控和日誌記錄
基本的 Docker 設定：
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8000
CMD ["npm", "start"]
部署並記錄您的：
- API URL：
https://your-domain.com/agent - API 金鑰：為驗證而產生
在 Warden Studio 中註冊
一旦您的代理已部署並可透過 HTTPS 存取，請在 Warden Studio 中註冊：
-
提供 API 詳細資訊：
- API URL
- API 金鑰
-
新增中繼資料：
- 代理名稱
- 說明
- 技能/功能清單
- 頭像圖片
-
發布：代理將會出現在 Warden 的 Agent Hub 中，供數百萬用戶使用
無需其他設定 - 您的 API 可存取代理已準備就緒！
下一步（另一個技能）： 如果使用者要求在 Warden Studio 中發布或需要引導式的 UI 步驟，請切換到 OpenClaw 技能 「在 Warden Studio 上部署代理」： https://www.clawhub.ai/Kryptopaid/warden-studio-deploy
最佳實踐
1. 代理設計
- 研究天氣代理結構以學習模式
- 對複雜工作流程使用 Schema-Guided Reasoning
- 保持回應簡潔且可執行
- 優雅地處理 API 失敗
- 驗證所有輸入
2. API 整合
- 使用環境變數儲存 API 金鑰
- 實作速率限制
- 適當時快取回應
- 記錄錯誤以便除錯
- 回傳結構化的 JSON 回應
3. 測試
- 在部署前在本地測試
- 驗證所有 API 端點是否正常運作
- 測試邊緣情況和錯誤
- 確保回應對使用者友善
- 根據 Warden 需求進行驗證
4. 文件
- 撰寫清晰的 README，包含：
- 代理用途與功能
- 所需的 API 金鑰
- 設定說明
- 範例查詢
- 已知的限制
常見模式
模式 1：簡單資料擷取器
// 擷取 → 格式化 → 回應
async function agent(input: string) {
const data = await fetchAPI(input);
const formatted = formatData(data);
return generateResponse(formatted);
}
模式 2：多步驟分析
// 驗證 → 擷取 → 擷取 → 分析 → 生成
async function agent(input: string) {
const validated = await validateInput(input);
const params = await extractParams(validated);
const data = await fetchData(params);
const analysis = await analyzeData(data);
return generateReport(analysis);
}
模式 3：比較分析
// 解析 → 多重擷取 → 比較 → 總結
async function agent(input: string) {
const items = await parseItems(input);
const dataArray = await Promise.all(
items.map(item => fetchData(item))
);
const comparison = compareData(dataArray);
return generateComparison(comparison);
}
故障排除
常見問題
「代理無法透過 API 存取」
- 確認部署已成功完成
- 檢查防火牆/安全群組設定
- 確保 API 端點可公開存取
- 使用 curl 或 Postman 進行測試
「建置時發生 LangGraph 錯誤」
- 確認 Node.js 版本 (18+) 或 Python (3.11+)
- 檢查所有依賴是否已安裝
- 驗證 langgraph.json 語法
- 檢視部署主控台中的錯誤日誌
「OpenAI API 錯誤」
- 確認 API 金鑰有效
- 檢查是否未超過速率限制
- 確保有足夠的額度
- 檢視錯誤訊息以了解詳細資訊
「代理回應緩慢」
- 最佳化 API 呼叫（盡可能平行化）
- 對重複查詢實作快取
- 減少 LLM Token 用量
- 考慮升級基礎設施
激勵計劃提示
激勵計劃開放給部署到 Warden 的 OpenClaw 代理。
-
保持原創：建立尚未存在的新東西
- 不要重建天氣代理、CoinGecko 代理或投資組合代理
- 研究它們的模式，應用於不同的問題
-
解決實際問題：專注於有用且獨特的功能
- Warden 生態系統中存在哪些缺口？
- 用戶真正想要的是什麼？
-
從簡單開始：與其一次做很多事情，不如把一件事做得非常好
- 不要試圖一次全部建立
- 簡單、專注的代理通常會勝出
-
品質重於功能：可靠性勝過複雜性
- 徹底測試
- 優雅地處理錯誤
- 提供清晰、有用的回應
-
研究範例：學習模式，不要複製實作
- 天氣代理 → 簡單資料擷取模式
- CoinGecko 代理 → SGR 工作流程模式
- 投資組合代理 → 多來源整合模式
-
文件完善：提供包含範例和設定說明的清晰 README
-
加入 Discord：在提交前透過 #developers 頻道獲取意見回饋
範例代理點子（建置這些！）
這些是 Warden 生態系統中尚未存在的新代理點子。建置其中一個（或建立您自己的獨特點子）：
Web3 用例：
- Gas 價格最佳化工具（預測...）