social-app/docs/plans/2026-02-25-agent-chat-crewai-ag-ui-spike-notes.md

Agent Chat CrewAI + AG-UI Spike Notes

Scope

• 验证 CrewAI 依赖可用性与版本探测方式。
• 验证 AG-UI 官方 CrewAI 集成在当前仓库中的落地路径。
• 验证 DashScope FunASR 响应中的 usage 字段可得性与兜底策略。

Findings

CrewAI

• uv run python -m pip show crewai 在当前虚拟环境不可用（无 pip 模块）。
• uv pip show crewai 返回未安装，说明当前工作树尚未安装 CrewAI 依赖。
• 若需启用真实编排，需在 pyproject.toml 中声明依赖并执行 uv sync --extra dev。

AG-UI 官方 CrewAI 集成

• 目标对齐官方标准事件语义（如 message.delta、tool.started、tool.completed、run.completed、run.failed）。
• 当前仓库采取“适配层隔离”策略：由 agui_adapter.py 进行请求与事件映射，避免协议细节扩散到业务层。

DashScope FunASR

• 优先读取上游响应 usage 字段用于成本统计。
• 若 usage 缺失，落库时保持 raw_usage 与空标准字段，并标记 metadata.usage_missing=true 以便审计。

Fallback Strategy

• 当官方集成能力或版本存在不确定性时，启用最小兜底事件映射：
  • 仅输出标准 AG-UI 事件。
  • 不扩展私有协议字段。
  • 在 event_bridge.py 中统一做字段校验与错误转换。

Decision

• 继续按计划推进：先补齐编排与成本核心，再完善 AG-UI 适配、多模态与 E2E 闭环。