AgentTrace

项目简介

AgentTrace 是一个开源的端到端可观测性 SDK 与仪表板，专为自主 AI 代理流水线设计。该项目解决了一个实际痛点：大语言模型在多步代理运行中经常生成格式错误或类型错误的工具参数（如将数字 "1200" 写成字符串 "1200 INR"、自造不存在的键名 "user_identifier" 而非标准的 "user_id"），这些问题在传统架构中会导致工作流直接崩溃。AgentTrace 不仅能监控这些问题，还能通过 Groq 在运行时自动修复错误参数，让工作流继续执行而不中断。

核心功能

AgentTrace 提供以下核心功能：

• Decorator SDK：Python + Pydantic，验证工具 schema 后才执行工具调用，截获参数错误
• Self-Healing Layer：调用 Groq 推理修复错误的工具参数，修复后重新执行，无需人工介入
• Collector Backend：FastAPI + SQLite 持久化，跟踪所有轨迹数据到 traces.db
• 实时仪表板：Next.js + Tailwind CSS，可视化多步工具调用延迟瓶颈
• Payload Diff Inspector：对比修复前后的参数差异，帮助开发者理解模型犯错模式

技术实现

AgentTrace 的技术栈包含四个主要组件。SDK 部分使用 Python decorator 模式，在工具函数执行前通过 Pydantic 对输入参数进行 schema 校验，若校验失败则将原始参数和 schema 发送给 Self-Healing Layer。Self-Healing Layer 基于 Groq 的快速推理能力，对错误参数进行结构化修复——例如将字符串 "1200 INR" 转换为浮点数 1200.0，将 "user_identifier" 修正为 "user_id"。修复后的参数重新传入工具函数执行，结果由 Collector Backend 异步写入 SQLite 数据库。仪表板端通过 WebSocket 实时拉取轨迹数据，以时间线形式展示每步工具调用的延迟和参数修复过程。

快速上手

第一步：在项目根目录启动后端服务 python -m uvicorn main:app --reload --port 8000

第二步：访问交互式仪表板 https://agent-trace-zeta.vercel.app/

第三步：访问 FastAPI Swagger 文档查看 API https://agenttrace-api-cdav.onrender.com/docs

第四步：在 Python 代码中使用 AgentTrace SDK @agent_trace # 装饰器自动捕获工具参数错误并触发自愈 def your_tool(param: int, user_id: str): ...

适用人群

AgentTrace 适合以下用户群体：正在开发多步代理应用且被 LLM 参数幻觉问题困扰的开发者；需要对生产环境代理行为进行可观测性监控的 AI 工程团队；希望在不中断工作流的前提下自动修复运行时错误的自动化系统架构师；研究 LLM 工具调用错误模式的安全研究人员。