首页
/ IncomeStreamSurfer项目:多智能体系统实现研究助手与邮件草稿子智能体

IncomeStreamSurfer项目:多智能体系统实现研究助手与邮件草稿子智能体

2025-07-09 19:19:51作者:平淮齐Percy

项目概述

IncomeStreamSurfer项目中的多智能体系统实现展示了一个高度集成的AI工作流,通过主研究智能体(Research Agent)和邮件草稿子智能体(Email Draft Agent)的协作,实现了从信息检索到邮件起草的完整自动化流程。该系统采用Pydantic AI框架构建,集成了Brave搜索API和Gmail API,是研究上下文工程和智能体协作模式的优秀实践案例。

核心架构设计

1. 系统组件

该系统采用模块化设计,主要包含以下核心组件:

  • 研究智能体:负责接收用户查询,通过Brave搜索API获取相关信息
  • 邮件草稿智能体:作为研究智能体的工具被调用,处理邮件起草任务
  • API工具层:封装了Brave搜索和Gmail API的具体实现细节
  • 数据模型层:使用Pydantic模型确保数据一致性和类型安全
  • 配置管理层:集中管理环境变量和系统配置

2. 工作流程

  1. 用户通过CLI输入研究主题
  2. 研究智能体调用Brave搜索工具获取相关信息
  3. 用户可选择将研究结果通过邮件分享
  4. 研究智能体调用邮件草稿智能体创建Gmail草稿
  5. 系统将操作结果实时反馈给用户

关键技术实现

1. 智能体间协作模式

系统采用了"智能体即工具"(agent-as-tool)的设计模式,邮件草稿智能体作为研究智能体的一个工具被注册和调用。这种模式的关键在于:

@research_agent.tool
async def create_email_draft(
    ctx: RunContext[AgentDependencies],
    recipient: str,
    subject: str,
    context: str
) -> str:
    # 关键:传递usage对象以跟踪token消耗
    result = await email_agent.run(
        f"Create an email to {recipient} about: {context}",
        deps=EmailAgentDeps(subject=subject),
        usage=ctx.usage
    )
    return f"Draft created with ID: {result.data}"

2. API集成实现

Brave搜索集成

async def search_brave(query: str, api_key: str, count: int = 10) -> List[BraveSearchResult]:
    async with httpx.AsyncClient() as client:
        headers = {"X-Subscription-Token": api_key}
        params = {"q": query, "count": count}
        
        # 关键:设置超时避免请求挂起
        response = await client.get(
            "https://api.search.brave.com/res/v1/web/search",
            headers=headers,
            params=params,
            timeout=30.0
        )
        
        # 使用Pydantic模型验证返回数据
        data = response.json()
        return [BraveSearchResult(**result) for result in data.get("web", {}).get("results", [])]

Gmail集成

Gmail API集成的关键点在于OAuth2认证流程和草稿创建:

  1. 首次运行时启动浏览器完成OAuth2授权
  2. 将获得的token存储在credentials目录下
  3. 创建草稿时需要正确处理MIME编码

3. 数据模型设计

系统使用Pydantic模型确保数据一致性和类型安全:

class ResearchQuery(BaseModel):
    query: str = Field(..., description="研究主题")
    max_results: int = Field(10, ge=1, le=50)
    include_summary: bool = Field(True)

class EmailDraft(BaseModel):
    to: List[str] = Field(..., min_items=1)
    subject: str = Field(..., min_length=1)
    body: str = Field(..., min_length=1)
    cc: Optional[List[str]] = None
    bcc: Optional[List[str]] = None

开发实践指南

1. 环境配置

项目使用环境变量管理敏感信息,开发者需要:

  1. 复制.env.example为.env文件
  2. 填写必要的API密钥和配置
  3. 确保credentials目录存在并包含Gmail凭证

2. 开发流程建议

  1. 从简单开始:先实现基础搜索功能,再添加邮件功能
  2. 频繁验证:使用提供的验证循环确保代码质量
  3. 逐步增强:先确保核心功能,再考虑边缘情况和错误处理

3. 验证循环

项目提供了多层次的验证机制:

  1. 语法和风格检查

    ruff check . --fix
    mypy .
    
  2. 单元测试

    pytest tests/ -v --cov=agents --cov=tools --cov-report=term-missing
    
  3. 集成测试 通过CLI实际操作系统,验证端到端功能

常见问题与解决方案

1. Gmail OAuth流程问题

症状:首次运行时浏览器未弹出或授权失败
解决

  • 确保credentials目录存在
  • 检查GMAIL_CREDENTIALS_PATH环境变量指向正确的credentials.json
  • 验证项目已在Google Cloud Console中正确设置

2. Brave API返回401错误

症状:搜索请求返回401状态码
解决

  • 检查BRAVE_API_KEY环境变量是否正确
  • 确认API密钥未过期
  • 验证请求头中正确包含X-Subscription-Token

3. 智能体间通信问题

症状:研究智能体无法调用邮件智能体
解决

  • 确保正确传递了ctx.usage对象
  • 检查工具注册装饰器(@research_agent.tool)是否正确应用
  • 验证依赖注入配置

最佳实践

  1. 异步编程:始终使用async/await,避免在异步上下文中使用同步函数
  2. 敏感信息管理:永远不要将API密钥或凭证提交到版本控制
  3. 错误处理:为所有外部API调用实现健壮的错误处理
  4. 类型安全:充分利用Pydantic的模型验证功能
  5. 文档优先:为每个功能和工具编写清晰的文档字符串

项目扩展思路

  1. 增加更多智能体工具:如日历安排、文档生成等
  2. 支持更多搜索源:整合Google搜索、学术数据库等
  3. 增强邮件功能:支持附件、富文本格式等
  4. 改进用户界面:开发Web界面或移动应用
  5. 增加工作流自动化:实现基于条件的自动触发机制

通过IncomeStreamSurfer项目的这个多智能体系统实现,开发者可以学习到现代AI系统中智能体协作、API集成和上下文管理的最佳实践,为构建更复杂的AI应用打下坚实基础。

登录后查看全文
热门项目推荐

最新内容推荐

项目优选

收起
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
149
1.95 K
kernelkernel
deepin linux kernel
C
22
6
openHiTLSopenHiTLS
旨在打造算法先进、性能卓越、高效敏捷、安全可靠的密码套件,通过轻量级、可剪裁的软件技术架构满足各行业不同场景的多样化要求,让密码技术应用更简单,同时探索后量子等先进算法创新实践,构建密码前沿技术底座!
C
980
395
ohos_react_nativeohos_react_native
React Native鸿蒙化仓库
C++
192
274
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot,Spring Security,JWT,Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
931
555
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
145
190
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台,包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分,采用java语言实现,可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
8
0
金融AI编程实战金融AI编程实战
为非计算机科班出身 (例如财经类高校金融学院) 同学量身定制,新手友好,让学生以亲身实践开源开发的方式,学会使用计算机自动化自己的科研/创新工作。案例以量化投资为主线,涉及 Bash、Python、SQL、BI、AI 等全技术栈,培养面向未来的数智化人才 (如数据工程师、数据分析师、数据科学家、数据决策者、量化投资人)。
Jupyter Notebook
75
66
openHiTLS-examplesopenHiTLS-examples
本仓将为广大高校开发者提供开源实践和创新开发平台,收集和展示openHiTLS示例代码及创新应用,欢迎大家投稿,让全世界看到您的精巧密码实现设计,也让更多人通过您的优秀成果,理解、喜爱上密码技术。
C
65
518
CangjieCommunityCangjieCommunity
为仓颉编程语言开发者打造活跃、开放、高质量的社区环境
Markdown
1.11 K
0