# find_agent_v2

`find_agent_v2` 是完全自包含的新实现。它不导入旧寻找 Agent 的提示词、工具、provider、画像
归一化、门禁、数据服务或日志模块，也不共享运行、搜索、候选或证据表。

完整流程图、状态机、工具权限和数据流说明见 [AGENT_FLOW.md](./AGENT_FLOW.md)。

## 结构

```text
Python 外循环（最多 N 个业务轮次）
  └─ 单轮 LangGraph
      supervisor ⇄ search / evidence / evaluator → END
  └─ 宿主代码校验并写终态
  └─ report（只读）
```

每个 ReAct 节点只注册本阶段工具；业务重数据在独立数据库表中，内存 state 只保存轮次、阶段、
计划和小型快照。

V2 表之间不使用数据库外键；`run_id`、`first_search_id`、`candidate_id` 都是应用层维护的逻辑引用。

节点运行时使用 LangChain `create_agent`，提供模型/工具重试、可选 fallback、Token/费用汇总和
同阶段受控子 Agent 并发委派。单轮拓扑由真实 `StateGraph` 编译，Obagent 从编译图生成 spec。

## 可视化

v2 只使用 obagent，不写项目原有的 `logs/*.jsonl`、本地可视化产物或 OSS 日志：

```text
observe.run(project=find_agent_v2)
  ├─ graph（第 1 轮）
  │   ├─ supervisor
  │   ├─ search
  │   ├─ evidence
  │   └─ evaluator
  ├─ graph（第 2 轮）
  │   └─ ...
  └─ report
```

节点通过固定 `InputSlot` 声明输入，`ctx.declare()` 的返回值直接作为真实模型输入。自研 ReAct
运行时的完整 LLM 输入/输出、usage、工具调用和消息链会汇总到各节点稳定的 `react` stage。
`find_agent_v2_run.obagent_run_uid` 保存观测台深链 UID。

配置环境变量：`OBAGENT_ENDPOINT`、`OBAGENT_API_KEY`、`OBAGENT_WAL_DIR`、
`OBAGENT_ENABLED`、`OBAGENT_TIMEOUT`、`OBAGENT_TIMEOUT_PER_OP`。

## 独立表

- `find_agent_v2_run`
- `find_agent_v2_round`
- `find_agent_v2_search`
- `find_agent_v2_candidate`
- `find_agent_v2_evidence`

迁移：

```bash
.venv/bin/alembic upgrade head
```

## 调用

```python
from find_agent_v2 import create_find_agent_v2_run, run_find_agent_v2

user_input = "...完整需求和 reference_videos..."
run_id = create_find_agent_v2_run(
    user_input=user_input,
    demand_word="手机防诈骗",
    demand_grade_id=123,
)
result = run_find_agent_v2(user_input, run_id=run_id)
```

`run_id` 必须来自 `find_agent_v2_run`，不会隐式接受或写入旧 `video_discovery_run`。

测试入口只接收一个需求词。程序会在 `demand_grade.demand_name` 中精确匹配，并按
`biz_dt DESC, create_time DESC, id DESC` 取最新一条，再查询视频和点位生成完整输入，最后直接
执行寻找 Agent：

```bash
.venv/bin/python -m find_agent_v2.test_entry "照顾父母"
```

## 复用边界

新包拥有自己的外部接口客户端、响应解析、年龄画像标准化、门禁和提示词。需求测试上下文只读取
通用数据模型；搜索结果、详情、画像和评估结果均由 `FindAgentV2Service` 写入独立表。
