AgentTraceController.php 2.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051
  1. <?php
  2. namespace App\Http\Controllers\V3;
  3. use App\Http\Controllers\Concerns\ResolvesCurrentUser;
  4. use App\Http\Controllers\Controller;
  5. use App\Http\Requests\V3\StoreAgentTraceRequest;
  6. use App\Http\Resources\V3\AgentTraceResource;
  7. use App\Services\V3\AgentTraceService;
  8. /**
  9. * AI 对话的研究过程入库。只给 agent 服务调(`auth.agent-service`),不对客户端开放。
  10. *
  11. * 新资源,没有 v2 前身。
  12. */
  13. class AgentTraceController extends Controller
  14. {
  15. use ResolvesCurrentUser;
  16. public function __construct(private readonly AgentTraceService $traces) {}
  17. /**
  18. * 写入一次提问的研究过程(幂等)
  19. *
  20. * 请求头 `X-Agent-Service-Key` 证明调用方是 agent 服务;`Authorization: Bearer`
  21. * 是 agent 透传的终端用户 token(可选):有效的人类 token 记到账号下,
  22. * 没有 / 失效 / 是模型 token 都记为游客——此时 `device_id` 必填,并记 `client_ip`。
  23. * token 失效不拒绝,照样入库。
  24. *
  25. * 按 run_id 幂等:首次写入 201,重复提交返回已有记录 200,步骤不会重复写。
  26. *
  27. * @responseStatus 201 首次写入。响应体与 200 同形
  28. * @responseStatus 403 thread_id 已经属于别的账号
  29. *
  30. * @bodyParam run_id string required AG-UI runId(uuid)
  31. * @bodyParam thread_id string required AG-UI threadId(uuid)
  32. * @bodyParam device_id string 设备匿名 id(uuid)。游客必填,登录用户忽略
  33. * @bodyParam client_ip string 客户端 IP。只对游客记录
  34. * @bodyParam client string 客户端。Enum: mobile,web
  35. * @bodyParam question string required 用户的提问
  36. * @bodyParam status string required 运行结果(denied=额度不足被拦下)。Enum: ok,error,cancelled,denied
  37. * @bodyParam improve boolean 用户是否允许用于改进回答(提问那一刻的开关)。Default: true
  38. * @bodyParam steps array 每一步(LLM 调用、工具调用、节点事件),最多 500 条
  39. */
  40. public function store(StoreAgentTraceRequest $request)
  41. {
  42. return AgentTraceResource::make(
  43. $this->traces->record($this->currentUserUid($request), $request->validated())
  44. );
  45. }
  46. }