Construtor de Agentes Warden
Construa e implante agentes LangGraph para o ecossistema Agentic Wallet do Protocolo Warden.
⚠️ IMPORTANTE: Sobre os Agentes de Exemplo
O repositório da comunidade Warden contém agentes de exemplo para aprendizado, não modelos para recriar:
- Agente Meteorológico – Estude-o para aprender padrões simples de busca de dados
- Agente CoinGecko – Estude-o para aprender Raciocínio Guiado por Esquema (SGR)
- Agente de Portfólio – Estude-o para aprender integração complexa de múltiplas fontes
NÃO CONSTRUA ESTES AGENTES – eles já existem. Em vez disso:
- Estude o código deles para entender os padrões
- Aprenda com sua arquitetura e fluxos de trabalho
- Construa algo NOVO e original para o programa de incentivo
Seu agente deve ser único e resolver um problema diferente para ser elegível ao programa de incentivo.
Visão Geral
O Protocolo Warden é uma "Carteira Agente para a economia Faça-Por-Mim" com um Programa de Incentivo ao Construtor de Agentes ativo, aberto a agentes OpenClaw que implantam no Warden. Todos os agentes devem ser baseados em LangGraph e acessíveis via API.
Recursos Principais:
- Repositório de Agentes da Comunidade: https://github.com/warden-protocol/community-agents
- Documentação: https://docs.wardenprotocol.org
- Discord: canal #developers para suporte
Lista de Verificação de Requisitos
Antes de construir, certifique-se de que seu agente atenda a estes requisitos obrigatórios:
✓ Framework: Construído com LangGraph (TypeScript ou Python) ✓ Implantação: LangSmith Deployments OU infraestrutura personalizada ✓ Acesso: Acessível via API (nenhuma IU necessária – Warden fornece a IU) ✓ Isolamento: Um agente por instância LangGraph ✓ Limitações de Segurança (Fase 1):
- Não pode acessar carteiras de usuários
- Não pode armazenar dados na infraestrutura Warden
✓ Funcionalidade: Pode implementar qualquer fluxo de trabalho:
- Automação Web3/Web2
- Integrações de API
- Conexões de banco de dados
- Interações com ferramentas externas
Entendendo os Agentes de Exemplo
O repositório community-agents contém exemplos de referência para aprender, NÃO modelos para recriar:
Exemplo de Agente 1: LangGraph Quick Start (Estude para o Básico)
Localização: agents/langgraph-quick-start (TypeScript) ou agents/langgraph-quick-start-py (Python)
Aprenda: Fundamentos do LangGraph, estrutura mínima de agente
Estude: Chatbot de nó único com integração OpenAI
git clone https://github.com/warden-protocol/community-agents.git
cd community-agents/agents/langgraph-quick-start
Exemplo de Agente 2: Agente Meteorológico (Estude para a Estrutura)
Localização: agents/weather-agent
Aprenda: Busca de dados simples, integração de API, respostas amigáveis
Estude:
- Como buscar dados de APIs externas (WeatherAPI)
- Processamento e formatação de resultados
- Escopo e estrutura claros ⚠️ NÃO CONSTRUA: Isso já existe. Estude-o e construa algo NOVO.
Exemplo de Agente 3: Agente CoinGecko (Estude para o Padrão SGR)
Localização: agents/coingecko-agent
Aprenda: Raciocínio Guiado por Esquema (SGR), fluxos de trabalho complexos
Estude:
- Fluxo de trabalho SGR de 5 etapas: Validar → Extrair → Buscar → Validar → Analisar
- Padrões de análise comparativa
- Tratamento de erros e validação de dados ⚠️ NÃO CONSTRUA: Isso já existe. Estude o padrão e aplique a novos casos de uso.
Exemplo de Agente 4: Agente de Análise de Portfólio (Estude para Padrões Avançados)
Localização: agents/portfolio-agent
Aprenda: Síntese de dados de várias fontes, arquitetura de produção
Estude:
- Integração de múltiplas APIs (CoinGecko + Alchemy)
- Suporte a múltiplas cadeias (EVM e Solana)
- Fluxos de trabalho SGR complexos
- Relatórios abrangentes ⚠️ NÃO CONSTRUA: Isso já existe. Estude a arquitetura para seu próprio agente complexo.
IMPORTANTE: Construa Algo NOVO
Esses exemplos existem para ensinar padrões e melhores práticas. Para o programa de incentivo, você DEVE criar um agente original e único que resolva um problema diferente. Não recrie simplesmente o Agente Meteorológico, o Agente CoinGecko ou o Agente de Portfólio.
Construindo Seu Agente Original
Passo 1: Estude os Exemplos e Escolha Sua Abordagem
NÃO clone um exemplo para modificá-lo. Em vez disso:
-
Estude os exemplos para entender os padrões:
- Busca de dados simples → Estude o Agente Meteorológico
- Análise complexa → Estude o Agente CoinGecko
- Síntese de múltiplas fontes → Estude o Agente de Portfólio
-
Identifique SEU caso de uso único:
- Que problema seu agente resolverá?
- Quais APIs ou fontes de dados ele usará?
- O que o torna diferente dos agentes existentes?
-
Planeje o fluxo de trabalho do seu agente:
- Simples requisição-resposta?
- Raciocínio Guiado por Esquema (SGR)?
- Análise de múltiplas etapas?
Passo 2: Inicialize Seu NOVO Agente
Use o script de inicialização para criar um projeto novo:
# Crie seu agente único
python scripts/init-agent.py meu-agente-unico \
--template typescript \
--description "Descrição do que SEU agente faz"
# Navegue até o projeto
cd meu-agente-unico
# Instale dependências
npm install # TypeScript
# OR
pip install -r requirements.txt # Python
Isso cria um ponto de partida limpo, não uma cópia dos agentes existentes.
Passo 3: Entenda a Estrutura do Agente LangGraph
Todo agente LangGraph segue esta estrutura básica:
seu-agente/
├── src/
│ ├── agent.ts/py # Lógica principal do agente (SEU CÓDIGO)
│ ├── graph.ts/py # Definição do fluxo de trabalho LangGraph (SEU CÓDIGO)
│ └── tools.ts/py # Implementações de ferramentas (SEU CÓDIGO)
├── package.json / requirements.txt
├── langgraph.json # Configuração LangGraph
└── README.md
Arquivos principais a implementar:
graph.ts/py– Defina seu fluxo de trabalho (validar → processar → responder)agent.ts/py– Implemente sua lógica centraltools.ts/py– Integre APIs externas específicas para o propósito DO SEU agente
Passo 4: Implemente Sua Lógica de Agente Personalizada
Estude padrões dos exemplos, aplique ao SEU caso de uso:
Se construir um buscador de dados simples (como padrão do Agente Meteorológico):
// Defina o fluxo de trabalho
const workflow = new StateGraph({
channels: agentState
})
.addNode("fetch", fetchYourData) // SUA API
.addNode("process", processYourData) // SUA lógica
.addNode("respond", generateResponse);
workflow
.addEdge(START, "fetch")
.addEdge("fetch", "process")
.addEdge("process", "respond")
.addEdge("respond", END);
Se construir análise complexa (como padrão do Agente CoinGecko - SGR):
// Defina o fluxo de trabalho SGR de 5 etapas
const workflow = new StateGraph({
channels: agentState
})
.addNode("validate", validateYourInput) // SUA validação
.addNode("extract", extractYourParams) // SUA extração
.addNode("fetch", fetchYourData) // SUAS APIs
.addNode("analyze", analyzeYourData) // SUA análise
.addNode("generate", generateYourResponse); // SUA formatação
workflow
.addEdge(START, "validate")
.addEdge("validate", "extract")
.addEdge("extract", "fetch")
.addEdge("fetch", "analyze")
.addEdge("analyze", "generate")
.addEdge("generate", END);
Princípios Chave:
- Mantenha fluxos de trabalho lineares e previsíveis
- Valide entradas em cada etapa
- Trate erros com elegância
- Use OpenAI para geração de linguagem natural
- Estruture respostas de forma consistente
CRÍTICO: Esta deve ser SUA implementação resolvendo SEU problema, não uma cópia dos agentes de exemplo.
Passo 5: Configure o Ambiente
Crie o arquivo .env:
# Obrigatório
OPENAI_API_KEY=sua_chave_openai
# Obrigatório para LangSmith Deployments (nuvem)
LANGSMITH_API_KEY=sua_chave_langsmith
# Opcional – baseado em suas ferramentas
WEATHER_API_KEY=sua_chave_weather
COINGECKO_API_KEY=sua_chave_coingecko
ALCHEMY_API_KEY=sua_chave_alchemy
Obtendo a Chave da API LangSmith:
- Crie uma conta em https://smith.langchain.com
- Navegue até Configurações → Chaves de API
- Crie uma nova chave de API
- Adicione ao arquivo
.env
Atualize langgraph.json:
{
"agent_id": "[NOME-DO-SEU-AGENTE]",
"python_version": "3.11", // ou omita para TypeScript
"dependencies": ["."],
"graphs": {
"agent": "./src/graph.ts" // ou .py
},
"env": ".env"
}
Passo 6: Teste Localmente
# TypeScript
npm run dev
# Python
langgraph dev
Teste a API do seu agente:
curl -X POST http://localhost:8000/invoke \
-H "Content-Type: application/json" \
-d '{"input": "consulta de teste"}'
Opções de Implantação
Opção 1: LangSmith Deployments (Recomendado)
Prós: Mais rápido, mais simples, infraestrutura gerenciada Requisitos: Chave da API LangSmith
Passos:
1. Envie seu repositório de agente para o GitHub.
2. Crie uma nova implantação em LangSmith Deployments.
3. Conecte o repositório, defina variáveis de ambiente e implante.
Seu agente receberá:
- URL do endpoint da API
- Autenticação automática (usa sua chave da API LangSmith)
- Escalonamento e monitoramento automáticos
Autenticação para chamadas de API: Ao chamar seu agente implantado, inclua sua chave da API LangSmith:
curl AGENT_URL/runs/wait \
--request POST \
--header 'Content-Type: application/json' \
--header 'x-api-key: [SUA-CHAVE-LANGSMITH-API]' \
--data '{
"assistant_id": "[ID-DO-SEU-AGENTE]",
"input": {
"messages": [{"role": "user", "content": "consulta de teste"}]
}
}'
Opção 2: Infraestrutura Auto-Hospedada
Prós: Controle total sobre o runtime Requisitos:
- Hospedagem de contêiner Docker
- Endpoint de API exposto
- Certificado SSL (HTTPS)
- Monitoramento e registro de logs
Configuração Docker Básica:
FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 8000
CMD ["npm", "start"]
Implante e anote seu:
- URL da API:
https://seu-dominio.com/agent - Chave da API: Gerada para autenticação
Registrar no Warden Studio
Assim que seu agente estiver implantado e acessível via HTTPS, registre-o no Warden Studio:
-
Forneça Detalhes da API:
- URL da API
- Chave da API
-
Adicione Metadados:
- Nome do agente
- Descrição
- Lista de habilidades/capacidades
- Imagem do avatar
-
Publique: O agente aparece no Agent Hub do Warden para milhões de usuários
Nenhuma configuração adicional necessária – seu agente acessível via API está pronto!
Próximo passo (skill separada): Se o usuário pedir para publicar no Warden Studio ou precisar de etapas guiadas pela interface, mude para a skill OpenClaw "Implantar Agente no Warden Studio": https://www.clawhub.ai/Kryptopaid/warden-studio-deploy
Melhores Práticas
1. Design do Agente
- Estude a estrutura do Agente Meteorológico para aprender padrões
- Use Raciocínio Guiado por Esquema para fluxos de trabalho complexos
- Mantenha respostas concisas e acionáveis
- Trate falhas de API com elegância
- Valide todas as entradas
2. Integração de API
- Use variáveis de ambiente para chaves de API
- Implemente limitação de taxa
- Armazene respostas em cache quando apropriado
- Registre erros para depuração
- Retorne respostas JSON estruturadas
3. Testes
- Teste localmente antes de implantar
- Verifique se todos os endpoints da API funcionam
- Teste casos extremos e erros
- Garanta que as respostas sejam amigáveis
- Valide os requisitos do Warden
4. Documentação
- Escreva um README claro com:
- Propósito e capacidades do agente
- Chaves de API necessárias
- Instruções de configuração
- Consultas de exemplo
- Limitações conhecidas
Padrões Comuns
Padrão 1: Buscador de Dados Simples
// Buscar → Formatar → Responder
async function agent(input: string) {
const data = await fetchAPI(input);
const formatted = formatData(data);
return generateResponse(formatted);
}
Padrão 2: Análise de Múltiplas Etapas
// Validar → Extrair → Buscar → Analisar → Gerar
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);
}
Padrão 3: Análise Comparativa
// Analisar → Buscar Múltiplos → Comparar → Resumir
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);
}
Solução de Problemas
Problemas Comuns
"Agente não acessível via API"
- Verifique se a implantação foi concluída com sucesso
- Verifique as configurações de firewall/grupo de segurança
- Certifique-se de que o endpoint da API esteja publicamente acessível
- Teste com curl ou Postman
"Erros do LangGraph durante a construção"
- Verifique a versão do Node.js (18+) ou Python (3.11+)
- Verifique se todas as dependências estão instaladas
- Valide a sintaxe do langgraph.json
- Revise os logs de erro no console de implantação
"Erros da API OpenAI"
- Verifique se a chave da API é válida
- Verifique se os limites de taxa não foram excedidos
- Garanta créditos suficientes
- Revise mensagens de erro para detalhes
"Respostas do agente são lentas"
- Otimize chamadas de API (paralelize quando possível)
- Implemente cache para consultas repetidas
- Reduza o uso de tokens LLM
- Considere atualizar a infraestrutura
Dicas do Programa de Incentivo
O programa de incentivo está aberto a agentes OpenClaw que implantam no Warden.
-
Seja Original: Crie algo NOVO que ainda não exista
- Não recrie o Agente Meteorológico, Agente CoinGecko ou Agente de Portfólio
- Estude seus padrões, aplique a problemas diferentes
-
Resolva Problemas Reais: Foco em funcionalidade útil e única
- Que lacuna existe no ecossistema Warden?
- O que os usuários realmente gostariam?
-
Comece Simples: Melhor fazer uma coisa excepcionalmente bem
- Não tente construir tudo de uma vez
- Agentes simples e focados muitas vezes vencem
-
Qualidade Acima de Funcionalidades: Confiabilidade supera complexidade
- Teste minuciosamente
- Trate erros com elegância
- Forneça respostas claras e úteis
-
Estude os Exemplos: Aprenda padrões, não copie implementações
- Agente Meteorológico → Padrão de busca de dados simples
- Agente CoinGecko → Padrão de fluxo de trabalho SGR
- Agente de Portfólio → Padrão de integração de múltiplas fontes
-
Documente Bem: README claro com exemplos e instruções de configuração
-
Junte-se ao Discord: Obtenha feedback no canal #developers antes de enviar
Ideias de Agentes de Exemplo (Construa Estes!)
Estas são ideias de NOVOS agentes que ainda não existem no ecossistema Warden. Construa um deles (ou crie sua própria ideia única):
Casos de Uso Web3:
- Otimizador de preços de gas (prever e sugerir preços de gas ideais para transações)
- Rastreador de carteiras multi-cadeia (monitore saldos e histórico em Ethereum, Solana, etc.)
- Agregador de rendimento DeFi (compare taxas em protocolos de empréstimo e staking)
Casos de Uso Web2:
- Resumidor de artigos técnicos (busque, resuma e formate artigos de API)
- Gerador de boilerplate de contrato inteligente (gere código inicial para contratos com base no caso de uso)
- Monitor de preços com alertas (configure limites de preço e receba notificações)
Ferramentas para Desenvolvedores:
- Verificador de vulnerabilidades de segurança de contratos inteligentes
- Gerador de documentação de API a partir de código
- Assistente de configuração de ambiente de desenvolvimento
Análise de Dados:
- Explorador de dados on-chain com consultas em linguagem natural
- Painel de análise de sentimento social para criptomoedas
- Ferramenta de comparação de taxas de transação entre cadeias