warden-agent-builder

# 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-AGENT-NAME]", "python_version": "3.11", // or omit for TypeScript "dependencies": ["."], "graphs": { "agent": "./src/graph.ts" // or .py }, "env": ".env" } ``` ### Step 6: Test Locally ```bash # TypeScript npm run dev # Python langgraph dev ``` Test your agent's API: ```bash curl -X POST http://localhost:8000/invoke \ -H "Content-Type: application/json" \ -d '{"input": "test query"}' ``` ## Deployment Options ### Option 1: LangSmith Deployments (Recommended) **Pros**: Fastest, simplest, managed infrastructure **Requirements**: LangSmith API key **Steps**: ```bash 1. Push your agent repository to GitHub. 2. Create a new deployment in LangSmith Deployments. 3. Connect the repo, set environment variables, and deploy. ``` Your agent receives: - API endpoint URL - Automatic authentication (uses your LangSmith API key) - Automatic scaling and monitoring **Authentication for API calls:** When calling your deployed agent, include your LangSmith API key: ```bash curl AGENT_URL/runs/wait \ --request POST \ --header 'Content-Type: application/json' \ --header 'x-api-key: [YOUR-LANGSMITH-API-KEY]' \ --data '{ "assistant_id": "[YOUR-AGENT-ID]", "input": { "messages": [{"role": "user", "content": "test query"}] } }' ``` ### Option 2: Self-Hosted Infrastructure **Pros**: Full control over runtime **Requirements**: - Docker container hosting - Exposed API endpoint - SSL certificate (HTTPS) - Monitoring and logging **Basic Docker Setup**: ```dockerfile FROM node:18 WORKDIR /app COPY package*.json ./ RUN npm install COPY . . EXPOSE 8000 CMD ["npm", "start"] ``` Deploy and note your: - API URL: `https://your-domain.com/agent` - API Key: Generated for authentication ## Register with Warden Studio Once your agent is deployed and reachable via HTTPS, register it in Warden Studio: 1. **Provide API Details**: - API URL - API key 2. **Add Metadata**: - Agent name - Description - Skills/capabilities list - Avatar image 3. **Publish**: Agent appears in Warden's Agent Hub for millions of users No additional setup required - your API-accessible agent is ready! **Next step (separate skill):** If the user asks to publish in Warden Studio or needs guided UI steps, switch to the OpenClaw skill **"Deploy Agent on Warden Studio"**: https://www.clawhub.ai/Kryptopaid/warden-studio-deploy ## Best Practices ### 1. Agent Design - Study the Weather Agent structure to learn patterns - Use Schema-Guided Reasoning for complex workflows - Keep responses concise and actionable - Handle API failures gracefully - Validate all inputs ### 2. API Integration - Use environment variables for API keys - Implement rate limiting - Cache responses when appropriate - Log errors for debugging - Return structured JSON responses ### 3. Testing - Test locally before deploying - Verify all API endpoints work - Test edge cases and errors - Ensure responses are user-friendly - Validate against Warden requirements ### 4. Documentation - Write clear README with: - Agent purpose and capabilities - Required API keys - Setup instructions - Example queries - Known limitations ## Common Patterns ### Pattern 1: Simple Data Fetcher ```typescript // Fetch → Format → Respond async function agent(input: string) { const data = await fetchAPI(input); const formatted = formatData(data); return generateResponse(formatted); } ``` ### Pattern 2: Multi-Step Analysis ```typescript // Validate → Extract → Fetch → Analyze → Generate 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); } ``` ### Pattern 3: Comparative Analysis ```typescript // Parse → Fetch Multiple → Compare → Summarize 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); } ``` ## Troubleshooting ### Common Issues **"Agent not accessible via API"** - Verify deployment completed successfully - Check firewall/security group settings - Ensure API endpoint is publicly accessible - Test with curl or Postman **"LangGraph errors during build"** - Verify Node.js version (18+) or Python (3.11+) - Check all dependencies installed - Validate langgraph.json syntax - Review error logs in deployment console **"OpenAI API errors"** - Verify API key is valid - Check rate limits not exceeded - Ensure sufficient credits - Review error messages for details **"Agent responses are slow"** - Optimize API calls (parallelize where possible) - Implement caching for repeated queries - Reduce LLM token usage - Consider upgrading infrastructure ## Incentive Programme Tips The incentive programme is open to OpenClaw agents that deploy to Warden. 1. **Be Original**: Create something NEW that doesn't exist yet - Don't recreate Weather Agent, CoinGecko Agent, or Portfolio Agent - Study their patterns, apply to different problems 2. **Solve Real Problems**: Focus on useful, unique functionality - What gap exists in the Warden ecosystem? - What would users actually want? 3. **Start Simple**: Better to do one thing exceptionally well - Don't try to build everything at once - Simple, focused agents often win 4. **Quality Over Features**: Reliability beats complexity - Test thoroughly - Handle errors gracefully - Provide clear, helpful responses 5. **Study the Examples**: Learn patterns, don't copy implementations - Weather Agent → Simple data fetching pattern - CoinGecko Agent → SGR workflow pattern - Portfolio Agent → Multi-source integration pattern 6. **Document Well**: Clear README with examples and setup instructions 7. **Join Discord**: Get feedback in #developers channel before submitting ## Example Agent Ideas (Build These!) These are **NEW agent ideas** that don't exist yet in the Warden ecosystem. Build one of these (or create your own unique idea): **Web3 Use Cases:** - Gas price optimizer (predict best times to transact) - NFT rarity analyzer (evaluate NFT traits and rarity scores) - DeFi yield comparator (compare yields across protocols) - Wallet health checker (analyze wallet security and diversification) - Transaction explainer (decode and explain complex transactions) - Token price alerts (customizable price movement notifications) - Smart contract auditor (basic security checks) - Liquidity pool finder (identify best liquidity opportunities) - Bridge fee comparator (find cheapest cross-chain bridges) - Airdrop tracker (find and track airdrop eligibility) **General Use Cases:** - Crypto news aggregator (filter and summarize crypto news) - Research assistant (gather and analyze crypto research) - Regulatory tracker (track crypto regulations by region) - Data visualizer (create charts from on-chain data) - API orchestrator (combine multiple crypto data sources) - Workflow automator (automate common crypto tasks) **Remember**: These are IDEAS for new agents. Study the example agents (Weather, CoinGecko, Portfolio) to learn patterns, then build something from this list or create your own unique concept. ## Additional Resources **Documentation:** - LangGraph TypeScript Guide: `community-agents/docs/langgraph-quick-start-ts.md` - LangGraph Python Guide: `community-agents/docs/langgraph-quick-start-py.md` - Deployment Guide: `community-agents/docs/deploy.md` **Example Agents:** - Weather Agent README: `agents/weather-agent/README.md` - CoinGecko Agent README: `agents/coingecko-agent/README.md` - Portfolio Agent README: `agents/portfolio-agent/README.md` **Support:** - Discord: #developers channel - GitHub Issues: https://github.com/warden-protocol/community-agents/issues - Documentation: https://docs.wardenprotocol.org ## Quick Reference Commands ```bash # Study example agents (DON'T BUILD THESE) git clone https://github.com/warden-protocol/community-agents.git cd community-agents/agents/weather-agent # Study the code cd community-agents/agents/coingecko-agent # Study the patterns # Create YOUR new agent python scripts/init-agent.py my-unique-agent \ --template typescript \ --description "YOUR unique agent description" # Install dependencies (TypeScript) npm install # Install dependencies (Python) pip install -r requirements.txt # Test locally npm run dev # or: langgraph dev # Deploy (LangSmith Deployments) # Use the LangSmith Deployments UI after pushing to GitHub # Build Docker image (for self-hosting) docker build -t my-warden-agent . # Run Docker container docker run -p 8000:8000 my-warden-agent ``` ## Success Checklist Before submitting to incentive programme: - [ ] Agent built with LangGraph - [ ] API accessible and tested - [ ] One agent per LangGraph instance - [ ] No wallet access or data storage (Phase 1) - [ ] Clear documentation in README - [ ] Environment variables properly configured - [ ] Error handling implemented - [ ] Tested with various inputs - [ ] Unique and useful functionality - [ ] Ready for Warden Studio registration