Warden Agent Builder - Warden 协议代理构建器

Warden Agent Builder - Warden 代理构建器

为 Warden Protocol 的代理钱包生态系统构建和部署 LangGraph 代理。

⚠️ 重要提示：关于示例代理

Warden 社区仓库包含用于学习的示例代理，而非可供复制的模板：

• 天气代理 (Weather Agent) — 学习此代理以掌握简单的数据获取模式
• CoinGecko 代理 (CoinGecko Agent) — 学习此代理以掌握模式引导推理 (SGR)
• 投资组合代理 (Portfolio Agent) — 学习此代理以掌握复杂的多源数据合成

不要构建这些代理——它们已经存在。相反地：

1. 学习它们的代码以理解模式
2. 从它们的架构和工作流中学习
3. 构建一个全新的、原创的代理以参与激励计划

您的代理必须独一无二且解决不同的问题，才有资格参与激励计划。

概述

Warden Protocol 是一个面向“为我执行”经济的代理钱包，设有活跃的代理构建者激励计划，对部署到 Warden 的 OpenClaw 代理开放。所有代理必须基于 LangGraph 并可通过 API 访问。

关键资源：

• 社区代理仓库：https://github.com/warden-protocol/community-agents
• 文档：https://docs.wardenprotocol.org
• Discord：用于支持的 #developers 频道

需求清单

在开始构建之前，请确保您的代理满足以下强制性要求：

✓ 框架：使用 LangGraph（TypeScript 或 Python）构建 ✓ 部署：LangSmith 部署或自定义基础设施 ✓ 访问方式：可通过 API 访问（无需 UI——Warden 会提供 UI） ✓ 隔离性：每个 LangGraph 实例只运行一个代理 ✓ 安全限制（第一阶段）：

• 无法访问用户钱包
• 无法在 Warden 基础设施上存储数据

✓ 功能：可实现任何工作流：

• Web3/Web2 自动化
• API 集成
• 数据库连接
• 外部工具交互

理解示例代理

社区代理仓库包含供参考的示例以供学习，而非可供复制的模板：

示例代理 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 学习：模式引导推理 (SGR)、复杂工作流 研究：

• 5 步 SGR 工作流：验证 → 提取 → 获取 → 验证 → 分析
• 比较分析模式
• 错误处理和输入验证 ⚠️ 不要构建：此代理已存在。学习其模式，应用于新的用例。

示例代理 4：投资组合分析代理（学习高级模式）

位置：agents/portfolio-agent 学习：多源数据合成、生产架构 研究：

• 集成多个 API（CoinGecko + Alchemy）
• 多链支持（EVM 和 Solana）
• 复杂 SGR 工作流
• 全面的报告生成 ⚠️ 不要构建：此代理已存在。学习其架构，用于构建您自己的复杂代理。

重要提示：构建全新的内容

这些示例的存在是为了教授模式及最佳实践。对于激励计划，您必须创建一个解决不同问题的原创、独特的代理。不要仅仅重新创建天气代理、CoinGecko 代理或投资组合代理。

构建您的原创代理

第一步：学习示例并选择您的方法

不要克隆示例并进行修改。 相反地：

1. 学习示例以理解模式：

   • 简单数据获取 → 学习天气代理
   • 复杂分析 → 学习 CoinGecko 代理
   • 多源数据合成 → 学习投资组合代理

2. 确定您独特的用例：

   • 您的代理将解决什么问题？
   • 它将使用哪些 API 或数据源？
   • 它与现有代理有何不同？

3. 规划代理的工作流：

   • 简单的请求-响应？
   • 模式引导推理 (SGR)？
   • 多步分析？

第二步：初始化您的新代理

使用初始化脚本创建一个全新的项目：

# 创建您独特的代理
python scripts/init-agent.py my-unique-agent \
  --template typescript \
  --description "描述您的代理的功能"

# 进入项目目录
cd my-unique-agent

# 安装依赖
npm install  # TypeScript
# 或
pip install -r requirements.txt  # Python

这将创建一个干净的起点，而非现有代理的副本。

第三步：理解 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

第四步：实现您的自定义代理逻辑

从示例中学习模式，应用于您的用例：

如果构建简单的数据获取器（如天气代理模式）：

// 定义工作流
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);

关键原则：

1. 保持工作流线性且可预测
2. 在每一阶段验证输入
3. 优雅地处理错误
4. 使用 OpenAI 进行自然语言生成
5. 响应结构保持一致

关键：这应该是您解决自身问题的实现，而非示例代理的副本。

第五步：配置环境

创建 .env 文件：

# 必需
OPENAI_API_KEY=your_openai_key

# 用于 LangSmith 部署（云）时必需
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 密钥：

1. 在 https://smith.langchain.com 创建账户
2. 导航至设置 → API 密钥
3. 创建新的 API 密钥
4. 添加到 .env 文件中

更新 langgraph.json：

{
  "agent_id": "[您-的-代理-名称]",
  "python_version": "3.11",  // 或为 TypeScript 省略
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/graph.ts"  // 或 .py
  },
  "env": ".env"
}

第六步：本地测试

# TypeScript
npm run dev

# Python
langgraph dev

测试您的代理 API：

curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": "test query"}'

部署选项

选项 1：LangSmith 部署（推荐）

优点：最快、最简单、托管基础设施 要求：LangSmith API 密钥

步骤：

1. 将您的代理仓库推送到 GitHub。
2. 在 LangSmith 部署中创建一个新部署。
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": "test query"}]
    }
  }'

选项 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 中注册：

1. 提供 API 详细信息：

   • API URL
   • API 密钥

2. 添加元数据：

   • 代理名称
   • 描述
   • 技能/能力列表
   • 头像图片

3. 发布：代理将在 Warden 的 Agent Hub 中向数百万用户显示

无需额外的设置——您的可通过 API 访问的代理已准备就绪！

下一步（作为单独的技能）： 如果用户要求在 Warden Studio 中发布或需要引导式 UI 步骤，请切换到 OpenClaw 技能 "在 Warden Studio 上部署代理"： https://www.clawhub.ai/Kryptopaid/warden-studio-deploy

最佳实践

1. 代理设计

• 学习天气代理的结构以掌握模式
• 对复杂工作流使用模式引导推理 (SGR)
• 保持响应简洁且可操作
• 优雅地处理 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 令牌使用量
• 考虑升级基础设施

激励计划提示

激励计划对部署到 Warden 的 OpenClaw 代理开放。

1. 保持原创：创建尚不存在的新内容

   • 不要重新创建天气代理、CoinGecko 代理或投资组合代理
   • 学习它们的模式，将其应用于不同的问题

2. 解决实际问题：专注于有用、独特的功能

   • Warden 生态系统中存在什么差距？
   • 用户真正需要什么？

3. 从简单开始：最好在某一方面做到极致

   • 不要试图一次构建所有内容
   • 简单、聚焦的代理往往更胜一筹

4. 质量优于功能：可靠性胜过复杂性

   • 全面测试
   • 优雅地处理错误
   • 提供清晰、有用的响应

5. 学习示例：学习模式，不要复制实现

   • 天气代理 → 简单数据获取模式
   • CoinGecko 代理 → SGR 工作流模式
   • 投资组合代理 → 多源集成模式

6. 文档完善：清晰的 README，包含示例和设置说明

7. 加入 Discord：在提交前到 #developers 频道获取反馈

示例代理创意（请构建这些！）

以下是尚不存在于 Warden 生态系统中的新代理创意。构建其中一个（或创建您自己的独特创意）：

Web3 用例：

• Gas 价格优化器（预测...（截断）