MedResearcher/example/subagent-example

SubAgent系统使用指南

📚 概述

SubAgent是基于Agno框架构建的智能代理系统，为MedResearcher项目提供强大的AI功能。它支持多种LLM提供商，提供动态prompt构建、JSON结构化输出和零容错解析等核心功能。

✨ 核心特性

🤖 智能代理核心

• 多提供商支持: 阿里云(qwen)、DeepSeek、OpenAI等主流LLM服务
• 动态Prompt: 支持模板变量替换的灵活prompt构建系统
• 结构化输出: 基于Pydantic模型的JSON格式化响应
• 零容错解析: 多策略JSON解析，确保即使不完美输出也能解析

🔧 配置管理

• YAML配置: 统一的配置文件管理，支持环境变量
• 模型工厂: 自动化的模型实例创建和参数管理
• 灵活配置: 支持运行时参数覆盖和动态配置

🛠 开发便利性

• 类型安全: 完整的类型提示支持
• 异常处理: 详细的错误信息和异常层级
• 调试支持: 内置日志和调试模式

🚀 快速开始

1. 基础设置

首先确保已安装依赖：

uv add agno pydantic pyyaml

2. 配置LLM服务

在src/config/llm_config.yaml中配置你的LLM服务：

aliyun:
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  api_key: "${DASHSCOPE_API_KEY}"
  models:
    qwen-max:
      class: "OpenAILike"
      params:
        id: "qwen-max"
        temperature: 0.3

3. 设置环境变量

创建.env文件或设置环境变量：

export DASHSCOPE_API_KEY="your_api_key_here"

4. 创建你的第一个Agent

from src.agent_system import SubAgent
from pydantic import BaseModel, Field

# 定义响应模型
class TaskResult(BaseModel):
    summary: str = Field(description="任务总结")
    confidence: float = Field(description="置信度", ge=0.0, le=1.0)

# 创建SubAgent
agent = SubAgent(
    provider="aliyun",
    model_name="qwen-max", 
    name="task_agent",
    instructions=["你是一个专业的任务处理专家"],
    prompt_template="请分析以下任务: {task_description}",
    response_model=TaskResult
)

# 执行任务
result = agent.run(template_vars={"task_description": "数据分析项目"})
print(f"总结: {result.summary}")
print(f"置信度: {result.confidence}")

📖 详细使用指南

SubAgent核心类

初始化参数

SubAgent(
    provider: str,              # LLM提供商名称
    model_name: str,            # 模型名称  
    instructions: List[str],    # 指令列表(可选)
    name: str,                  # Agent名称(可选)
    description: str,           # Agent描述(可选)
    prompt_template: str,       # 动态prompt模板(可选)
    response_model: BaseModel,  # Pydantic响应模型(可选)
    config: Dict[str, Any],     # 自定义配置(可选)
    **agent_kwargs              # 传递给Agno Agent的额外参数
)

核心方法

1. build_prompt() - 构建动态Prompt

# 设置带变量的prompt模板
agent.update_prompt_template("""
请分析以下{data_type}数据:

数据内容: {data_content}
分析目标: {analysis_goal}

请提供详细的分析结果。
""")

# 构建具体prompt
prompt = agent.build_prompt({
    "data_type": "销售",
    "data_content": "Q1销售数据...",
    "analysis_goal": "找出增长趋势"
})

2. run() - 执行推理

# 方式1: 使用模板变量
result = agent.run(template_vars={
    "input_text": "待分析的文本内容"
})

# 方式2: 直接提供prompt
result = agent.run(prompt="请分析这段文本的情感倾向")

# 方式3: 带额外参数
result = agent.run(
    template_vars={"data": "测试数据"},
    temperature=0.7,
    max_tokens=1000
)

3. get_model_info() - 获取模型信息

info = agent.get_model_info()
print(f"Agent名称: {info['name']}")
print(f"提供商: {info['provider']}")
print(f"模型: {info['model_name']}")
print(f"是否有prompt模板: {info['has_prompt_template']}")

Pydantic响应模型

基础模型定义

from pydantic import BaseModel, Field
from typing import List, Optional

class AnalysisResult(BaseModel):
    """分析结果模型"""
    
    summary: str = Field(description="分析总结")
    key_points: List[str] = Field(description="关键要点列表")  
    confidence: float = Field(description="置信度", ge=0.0, le=1.0)
    recommendations: Optional[List[str]] = Field(default=None, description="建议列表")
    
    class Config:
        json_encoders = {
            float: lambda v: round(v, 3) if v is not None else None
        }

复杂嵌套模型

class DetailedItem(BaseModel):
    name: str = Field(description="项目名称")
    value: float = Field(description="数值")
    category: str = Field(description="分类")

class ComprehensiveResult(BaseModel):
    items: List[DetailedItem] = Field(description="详细项目列表")
    total_count: int = Field(description="总数量", ge=0)
    summary: str = Field(description="整体总结")

配置管理详解

LLM配置文件结构 (llm_config.yaml)

# 阿里云配置
aliyun:
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  api_key: "${DASHSCOPE_API_KEY}"
  models:
    qwen-max:
      class: "OpenAILike"
      params:
        id: "qwen-max"
        temperature: 0.3
        max_tokens: 4000
    qwen-plus:
      class: "OpenAILike"  
      params:
        id: "qwen-plus"
        temperature: 0.5

# DeepSeek配置
deepseek:
  base_url: "https://api.deepseek.com/v1"
  api_key: "${DEEPSEEK_API_KEY}"
  models:
    deepseek-v3:
      class: "OpenAILike"
      params:
        id: "deepseek-chat"
        temperature: 0.3

# OpenAI配置  
openai:
  api_key: "${OPENAI_API_KEY}"
  models:
    gpt-4o:
      class: "OpenAIChat"
      params:
        model: "gpt-4o"
        temperature: 0.3

环境变量配置 (.env)

# 阿里云API密钥
DASHSCOPE_API_KEY=sk-your-dashscope-key

# DeepSeek API密钥  
DEEPSEEK_API_KEY=sk-your-deepseek-key

# OpenAI API密钥
OPENAI_API_KEY=sk-your-openai-key

便捷函数使用

create_json_agent() - 快速创建JSON Agent

from src.agent_system import create_json_agent

# 快速创建支持JSON输出的Agent
agent = create_json_agent(
    provider="aliyun",
    model_name="qwen-max",
    name="json_extractor",
    prompt_template="从以下文本提取信息: {text}",
    response_model="MyModel",  # 可以是字符串或类
    instructions=["你是信息提取专家"]
)

🎯 实际应用示例

示例1: 情感分析Agent

from pydantic import BaseModel, Field
from typing import Literal
from src.agent_system import SubAgent

class SentimentResult(BaseModel):
    sentiment: Literal["positive", "negative", "neutral"] = Field(description="情感倾向")
    confidence: float = Field(description="置信度", ge=0.0, le=1.0)  
    explanation: str = Field(description="分析说明")

sentiment_agent = SubAgent(
    provider="aliyun",
    model_name="qwen-max",
    name="sentiment_analyzer", 
    instructions=[
        "你是专业的文本情感分析专家",
        "请准确识别文本的情感倾向",  
        "提供详细的分析依据"
    ],
    prompt_template="""
请分析以下文本的情感倾向:

文本内容: {text}

请识别情感倾向(positive/negative/neutral)、置信度(0-1)和分析说明。
""",
    response_model=SentimentResult
)

# 使用示例
result = sentiment_agent.run(template_vars={
    "text": "这个产品质量很好，我非常满意！"
})

print(f"情感: {result.sentiment}")
print(f"置信度: {result.confidence}")
print(f"说明: {result.explanation}")

示例2: 数据提取Agent

class DataExtraction(BaseModel):
    extracted_data: Dict[str, Any] = Field(description="提取的数据")
    extraction_count: int = Field(description="提取项目数量") 
    data_quality: Literal["high", "medium", "low"] = Field(description="数据质量评估")

extractor_agent = SubAgent(
    provider="aliyun",
    model_name="qwen-plus",
    name="data_extractor",
    instructions=[
        "你是数据提取专家",
        "从非结构化文本中提取结构化数据",
        "确保提取的数据准确完整"
    ],
    prompt_template="""
从以下{data_type}文档中提取关键数据:

文档内容:
{document}

提取要求:
{requirements}

请提取所有相关数据并评估数据质量。
""",
    response_model=DataExtraction
)

⚠️ 注意事项与最佳实践

1. 配置管理

• API密钥安全: 始终使用环境变量存储API密钥，切勿在代码中硬编码
• 配置验证: 程序启动时验证配置文件完整性
• 环境隔离: 开发、测试、生产环境使用不同的配置文件

2. Prompt设计

• 明确指令: 提供清晰、具体的任务指令
• 示例驱动: 在prompt中包含输入输出示例
• 结构化模板: 使用结构化的prompt模板提高一致性

3. 错误处理

• 异常捕获: 对Agent调用进行适当的异常处理
• 重试机制: 对网络错误实现重试逻辑
• 降级策略: 准备备用模型或简化输出格式

4. 性能优化

• 缓存机制: 对相同输入实现结果缓存
• 批处理: 将多个小任务合并为大任务处理
• 模型选择: 根据任务复杂度选择合适的模型

🔧 故障排除

常见问题

1. 配置文件不存在

错误: FileNotFoundError: LLM配置文件不存在
解决: 确保 src/config/llm_config.yaml 文件存在且格式正确

2. API密钥未设置

错误: 环境变量 DASHSCOPE_API_KEY 未定义
解决: 设置相应的环境变量或在.env文件中配置

3. JSON解析失败

错误: JSONParseError: 所有解析策略都失败了
解决: 检查prompt设计，确保要求明确的JSON格式输出

4. 模型验证失败

错误: Pydantic模型验证失败  
解决: 检查响应模型定义与实际输出是否匹配

调试技巧

启用调试模式

agent = SubAgent(
    provider="aliyun",
    model_name="qwen-max",
    debug_mode=True,  # 启用调试输出
    # ... 其他参数
)

查看生成的Prompt

# 构建并查看最终的prompt
prompt = agent.build_prompt({"key": "value"})
print(f"生成的prompt: {prompt}")

捕获详细错误信息

try:
    result = agent.run(template_vars={"text": "测试"})
except Exception as e:
    print(f"错误类型: {type(e)}")
    print(f"错误信息: {e}")
    import traceback
    traceback.print_exc()

🚦 版本信息

• 当前版本: 0.1.0
• 依赖要求:
  • Python >= 3.8
  • agno >= 0.1.0
  • pydantic >= 2.0.0
  • pyyaml >= 6.0.0

📞 支持与反馈

如遇到问题或有功能建议，请联系开发团队或提交issue。

---

MedResearcher SubAgent系统 - 让AI更智能，让开发更简单 🎉