OpenJiuwen Agent-Store 技术教程

概述

agent-store 是 AI Agent 实现的精选集合，包含模板和示例。它作为现成 Agent 的市场，覆盖不同领域的应用场景。

技术栈

• 编程语言: 混合 (Python, TypeScript/JavaScript)
• 结构: 社区驱动的仓库
• 包管理器: uv (Python), npm (JavaScript)

核心特性

1. Agent 分类

Community Agents (社区 Agent)

活跃维护的 Agent 实现，可直接使用或作为参考。

Templates (模板)

创建新 Agent 的起点，包含基础结构和最佳实践。

Archived (归档)

参考实现，用于学习和研究。

2. 可用 Agent

deepcode

代码分析和研究 Agent，提供深度代码理解能力。

# 安装
cd agent-store/community/deepcode
uv pip install -e .

# 使用
deepcode analyze /path/to/project

功能特点:

• 代码质量分析
• 架构模式识别
• 性能瓶颈检测
• 安全漏洞扫描

finsight-agent

金融洞察和分析 Agent，专注于金融数据处理。

# 安装
cd agent-store/community/finsight-agent
uv pip install -e .

# 使用
finsight analyze --market stock --symbol AAPL

功能特点:

• 市场趋势分析
• 财务数据处理
• 风险评估
• 投资建议生成

super-agent

通用 ToC/ToB Agent，适用于多种业务场景。

# 安装
cd agent-store/community/super-agent
uv pip install -e .

# 使用
super-agent run --config config.yaml

功能特点:

• 多场景适配
• 灵活配置
• 插件扩展
• 自定义工作流

vibe-agent

工作流自动化 Agent，专注于流程自动化。

# 安装
cd agent-store/community/vibe-agent
uv pip install -e .

# 使用
vibe automate --workflow workflow.yaml

功能特点:

• 可视化工作流设计
• 任务调度
• 条件分支
• 错误处理

架构设计

agent-store/
├── community/              # 活跃 Agent 实现
│   ├── deepcode/
│   │   ├── src/
│   │   ├── tests/
│   │   ├── metadata.json
│   │   ├── README.md
│   │   └── .env.example
│   ├── finsight-agent/
│   ├── super-agent/
│   └── vibe-agent/
├── templates/              # Agent 模板
│   ├── coded-agents/      # 编码型 Agent 模板
│   └── no-code-agents/    # 无代码 Agent 模板
├── AGENTS.md              # 开发指南
└── AGNET_GUIDELINES.md    # 创建指南

Agent 开发指南

1. Agent 必需文件

每个 Agent 必须包含以下文件:

metadata.json

Agent 元数据配置

{
  "name": "my-agent",
  "version": "1.0.0",
  "description": "我的自定义 Agent",
  "author": "your-name",
  "tags": ["automation", "productivity"],
  "requirements": {
    "python": ">=3.11",
    "dependencies": [
      "openjiuwen>=0.1.9",
      "aiohttp>=3.8.0"
    ]
  },
  "entry_point": "main.py",
  "config_schema": {
    "llm_model": {
      "type": "string",
      "default": "gpt-4"
    }
  }
}

README.md

详细的 Agent 文档

# My Agent

## 功能描述
描述 Agent 的主要功能和用途

## 安装
\`\`\`bash
uv pip install -e .
\`\`\`

## 使用方法
\`\`\`bash
my-agent run --task "任务描述"
\`\`\`

## 配置说明
说明配置项的含义和使用方法

## 示例
提供使用示例

.env.example

配置模板，不包含真实密钥

# LLM 配置
LLM_API_KEY=your-api-key-here
LLM_MODEL=gpt-4

# 数据库配置
DATABASE_URL=postgresql://user:pass@localhost/db

# 其他配置
LOG_LEVEL=INFO

2. 创建新 Agent

使用模板

# 从模板创建
cp -r agent-store/templates/coded-agents agent-store/community/my-agent
cd agent-store/community/my-agent

# 修改 metadata.json
# 实现 Agent 逻辑
# 编写测试

从零开始

# main.py
import asyncio
from openjiuwen import ReActAgent

class MyAgent:
    def __init__(self, config):
        self.config = config
        self.agent = ReActAgent(
            name="my-agent",
            llm_config=config.llm_config
        )
    
    async def run(self, task):
        result = await self.agent.run(task)
        return result

async def main():
    agent = MyAgent(config)
    result = await agent.run("执行任务")
    print(result)

if __name__ == "__main__":
    asyncio.run(main())

3. Agent 测试

# tests/test_agent.py
import pytest
from my_agent import MyAgent

@pytest.fixture
async def agent():
    config = load_test_config()
    return MyAgent(config)

@pytest.mark.asyncio
async def test_agent_basic(agent):
    result = await agent.run("测试任务")
    assert result is not None
    assert "success" in result.status

设计模式

1. 插件架构

每个 Agent 是独立的模块，可单独部署和使用。

2. 元数据驱动

通过 JSON 配置管理 Agent 元信息，便于发现和管理。

3. 安全优先

• 不在代码中硬编码 API 密钥
• 使用环境变量管理敏感信息
• 提供配置验证机制

最佳实践

1. 配置管理

from pydantic import BaseSettings

class Settings(BaseSettings):
    llm_api_key: str
    llm_model: str = "gpt-4"
    log_level: str = "INFO"
    
    class Config:
        env_file = ".env"

settings = Settings()

2. 错误处理

from openjiuwen.core.foundation import AgentException

try:
    result = await agent.run(task)
except AgentException as e:
    logger.error(f"Agent 执行失败: {e}")
    # 优雅降级或重试

3. 日志记录

import logging

logger = logging.getLogger(__name__)

async def run_with_logging(agent, task):
    logger.info(f"开始执行任务: {task}")
    try:
        result = await agent.run(task)
        logger.info(f"任务执行成功")
        return result
    except Exception as e:
        logger.error(f"任务执行失败: {e}")
        raise

4. 性能监控

import time
from contextlib import asynccontextmanager

@asynccontextmanager
async def timer(operation_name):
    start = time.time()
    yield
    duration = time.time() - start
    logger.info(f"{operation_name} 耗时: {duration:.2f}s")

async def run_with_monitoring(agent, task):
    async with timer("agent_execution"):
        result = await agent.run(task)
    return result

Agent 发布流程

1. 准备工作

# 确保所有测试通过
pytest tests/

# 检查代码质量
ruff check .
mypy .

# 更新文档
# 更新 CHANGELOG

2. 提交审核

# 创建 PR
git checkout -b feature/my-agent
git add .
git commit -m "Add my-agent implementation"
git push origin feature/my-agent

# 在 GitCode 创建 Pull Request

3. 审核标准

•  代码质量符合规范
•  测试覆盖率 > 80%
•  文档完整清晰
•  配置示例完整
•  无安全漏洞
•  性能测试通过

常见问题

Q: 如何选择合适的 Agent 模板?

A: 根据任务类型选择:

• 需要推理决策 → coded-agents
• 流程固定 → no-code-agents
• 特定领域 → 参考类似 Agent

Q: Agent 之间如何协作?

A: 使用 agent-core 的 MultiAgentSystem，定义协作工作流。

Q: 如何处理 Agent 依赖冲突?

A: 使用 uv 或 poetry 管理虚拟环境，每个 Agent 独立环境。

相关资源

• Agent 开发指南
• 模板仓库
• 社区 Agent

总结

agent-store 提供了丰富的 Agent 实现和模板，是快速启动 AI Agent 项目的理想起点。通过遵循开发指南和最佳实践，可以创建高质量、可复用的 Agent。