warden-agent-builder

为 Warden Protocol 构建原始 LangGraph 代理并准备在 Warden Studio 中发布。当用户想要：(1) 创建新的 Warden 代理（不是社区示例），(2) 构建基于 LangGraph 的加密/Web3 代理，(3) 通过 LangSmith 部署或自定义基础设施部署代理，(4) 参与 Warden Agent Builder 激励计划（向 OpenClaw 代理开放），或 (5) 与 Warden Studio 集成以进行代理中心发布。

## 概述（中文）

为 Warden Protocol 构建原始 LangGraph 代理并准备在 Warden Studio 中发布。当用户想要：(1) 创建新的 Warden 代理（不是社区示例），(2) 构建基于 LangGraph 的加密/Web3 代理，(3) 通过 LangSmith 部署或自定义基础设施部署代理，(4) 参与 Warden Agent Builder 激励计划（向 OpenClaw 代理开放），或 (5) 与 Warden Studio 集成以进行代理中心发布。

## 原文

# Warden Agent Builder

Build and deploy LangGraph agents for Warden Protocol's Agentic Wallet ecosystem.

## ⚠️ IMPORTANT: About Example Agents

The Warden community repository contains **example agents for learning**, not templates to recreate:

- **Weather Agent** - Study this to learn simple data fetching patterns
- **CoinGecko Agent** - Study this to learn Schema-Guided Reasoning (SGR)
- **Portfolio Agent** - Study this to learn complex multi-source integration

**DO NOT BUILD THESE AGENTS** - they already exist. Instead:
1. **Study** their code to understand patterns
2. **Learn** from their architecture and workflows  
3. **Build** something NEW and original for the incentive programme

Your agent must be **unique and solve a different problem** to be eligible for the incentive programme.

## Overview

Warden Protocol is an "Agentic Wallet for the Do-It-For-Me economy" with an active Agent Builder Incentive Programme open to OpenClaw agents that deploy to Warden. All agents must be LangGraph-based and API-accessible.

**Key Resources:**
- Community Agents Repository: https://github.com/warden-protocol/community-agents
- Documentation: https://docs.wardenprotocol.org
- Discord: #developers channel for support

## Requirements Checklist

Before building, ensure your agent meets these mandatory requirements:

✓ **Framework**: Built with LangGraph (TypeScript or Python)
✓ **Deployment**: LangSmith Deployments OR custom infrastructure
✓ **Access**: API-accessible (no UI required - Warden provides UI)
✓ **Isolation**: One agent per LangGraph instance
✓ **Security Limitations** (Phase 1):
  - Cannot access user wallets
  - Cannot store data on Warden infrastructure

✓ **Functionality**: Can implement any workflow:
  - Web3/Web2 automation
  - API integrations
  - Database connections
  - External tool interactions

## Understanding the Example Agents

The community-agents repository contains **reference examples** to learn from, NOT templates to recreate:

### Example Agent 1: LangGraph Quick Start (Study for Basics)
**Location**: `agents/langgraph-quick-start` (TypeScript) or `agents/langgraph-quick-start-py` (Python)
**Learn**: LangGraph fundamentals, minimal agent structure
**Study**: Single-node chatbot with OpenAI integration

```bash
git clone https://github.com/warden-protocol/community-agents.git
cd community-agents/agents/langgraph-quick-start
```

### Example Agent 2: Weather Agent (Study for Structure)
**Location**: `agents/weather-agent`
**Learn**: Simple data fetching, API integration, user-friendly responses
**Study**: 
- How to fetch data from external APIs (WeatherAPI)
- Processing and formatting results
- Clear scope and structure
**⚠️ DO NOT BUILD**: This already exists. Study it, then build something NEW.

### Example Agent 3: CoinGecko Agent (Study for SGR Pattern)
**Location**: `agents/coingecko-agent`
**Learn**: Schema-Guided Reasoning, complex workflows
**Study**:
- 5-step SGR workflow: Validate → Extract → Fetch → Validate → Analyze
- Comparative analysis patterns
- Error handling and data validation
**⚠️ DO NOT BUILD**: This already exists. Study the pattern, apply to new use cases.

### Example Agent 4: Portfolio Analysis Agent (Study for Advanced Patterns)
**Location**: `agents/portfolio-agent`
**Learn**: Multi-source data synthesis, production architecture
**Study**:
- Integrating multiple APIs (CoinGecko + Alchemy)
- Multi-chain support (EVM and Solana)
- Complex SGR workflows
- Comprehensive reporting
**⚠️ DO NOT BUILD**: This already exists. Study the architecture for your own complex agent.

## IMPORTANT: Build Something NEW

These examples exist to teach patterns and best practices. For the incentive programme, you MUST create an **original, unique agent** that solves a different problem. Do NOT simply recreate the Weather Agent, CoinGecko Agent, or Portfolio Agent.

## Building Your Original Agent

### Step 1: Study Examples and Choose Your Approach

**DO NOT clone an example to modify it.** Instead:

1. **Study the examples** to understand patterns:
   - Simple data fetching → Study Weather Agent
   - Complex analysis → Study CoinGecko Agent  
   - Multi-source synthesis → Study Portfolio Agent

2. **Identify YOUR unique use case**:
   - What problem will your agent solve?
   - What APIs or data sources will it use?
   - What makes it different from existing agents?

3. **Plan your agent's workflow**:
   - Simple request-response?
   - Schema-Guided Reasoning (SGR)?
   - Multi-step analysis?

### Step 2: Initialize Your NEW Agent

Use the initialization script to create a fresh project:

```bash
# Create your unique agent
python scripts/init-agent.py my-unique-agent \
  --template typescript \
  --description "Description of what YOUR agent does"

# Navigate to project
cd my-unique-agent

# Install dependencies
npm install  # TypeScript
# OR
pip install -r requirements.txt  # Python
```

This creates a clean starting point, not a copy of existing agents.

### Step 3: Understand LangGraph Agent Structure

Every LangGraph agent follows this basic structure:

```
your-agent/
├── src/
│   ├── agent.ts/py          # Main agent logic (YOUR CODE)
│   ├── graph.ts/py          # LangGraph workflow definition (YOUR CODE)
│   └── tools.ts/py          # Tool implementations (YOUR CODE)
├── package.json / requirements.txt
├── langgraph.json           # LangGraph configuration
└── README.md
```

**Key files to implement:**
- `graph.ts/py` - Define your workflow (validate → process → respond)
- `agent.ts/py` - Implement your core logic
- `tools.ts/py` - Integrate external APIs specific to YOUR agent's purpose

### Step 4: Implement Your Custom Agent Logic

**Study patterns from examples, apply to YOUR use case:**

**If building a simple data fetcher** (like Weather Agent pattern):
```typescript
// Define workflow
const workflow = new StateGraph({
  channels: agentState
})
  .addNode("fetch", fetchYourData)      // YOUR API
  .addNode("process", processYourData)  // YOUR logic
  .addNode("respond", generateResponse);

workflow
  .addEdge(START, "fetch")
  .addEdge("fetch", "process")
  .addEdge("process", "respond")
  .addEdge("respond", END);
```

**If building complex analysis** (like CoinGecko Agent pattern - SGR):
```typescript
// Define 5-step SGR workflow
const workflow = new StateGraph({
  channels: agentState
})
  .addNode("validate", validateYourInput)     // YOUR validation
  .addNode("extract", extractYourParams)      // YOUR extraction
  .addNode("fetch", fetchYourData)            // YOUR APIs
  .addNode("analyze", analyzeYourData)        // YOUR analysis
  .addNode("generate", generateYourResponse); // YOUR formatting

workflow
  .addEdge(START, "validate")
  .addEdge("validate", "extract")
  .addEdge("extract", "fetch")
  .addEdge("fetch", "analyze")
  .addEdge("analyze", "generate")
  .addEdge("generate", END);
```

**Key Principles:**
1. Keep workflows linear and predictable
2. Validate inputs at each stage
3. Handle errors gracefully
4. Use OpenAI for natural language generation
5. Structure responses consistently

**CRITICAL**: This should be YOUR implementation solving YOUR problem, not a copy of the example agents.

### Step 5: Configure Environment

Create `.env` file:

```bash
# Required
OPENAI_API_KEY=your_openai_key

# Required for LangSmith Deployments (cloud)
LANGSMITH_API_KEY=your_langsmith_key

# Optional - based on your tools
WEATHER_API_KEY=your_weather_key
COINGECKO_API_KEY=your_coingecko_key
ALCHEMY_API_KEY=your_alchemy_key
```

**Getting LangSmith API Key:**
1. Create account at https://smith.langchain.com
2. Navigate to Settings → API Keys
3. Create new API key
4. Add to `.env` file

Update `langgraph.json`:

```json
{
  "agent_id": "[YOUR-AGEN