# 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 闭环。