refactor: 简化 AgentScope 运行时模块与事件处理

- 移除冗余的 user_token 参数传递 - 重构 tool.result 事件使用 ToolAgentOutput 模型 - 重构 text.end 事件使用 WorkerAgentOutput 模型 - 简化 store 模块的 tool result 处理逻辑 - 更新 router/service 适配新事件结构 - 清理废弃的测试文件与设计文档 - 新增 AgentRuns 多模态存储设计文档
2026-03-13 17:27:18 +08:00
parent 3273d63b23
commit 1c02503d1d
29 changed files with 1259 additions and 2725 deletions
@@ -0,0 +1,239 @@
+# Agent Runs Events and History Route Protocol
+
+> **NOTE**: This document is the single source of truth for agent runs event streaming and history snapshot routes.
+
+## Overview
+
+Defines the transport format for:
+
+- `POST /api/v1/agent/runs`
+- `GET /api/v1/agent/runs/{thread_id}/events`
+- `GET /api/v1/agent/history`
+- `GET /api/v1/agent/attachments/signed-url`
+
+## Version
+
+- **Current**: `1.0`
+- **Status**: Draft (pending full backend/frontend alignment)
+
+---
+
+## Route Semantics
+
+### `GET /api/v1/agent/history`
+
+- Unified history endpoint.
+- Query params:
+  - `threadId` (optional): target thread id.
+  - `before` (optional, `YYYY-MM-DD`): paginate by day.
+- Behavior:
+  - With `threadId`: returns that thread's day snapshot.
+  - Without `threadId`: returns latest available thread snapshot for current user.
+
+### `GET /api/v1/agent/attachments/signed-url`
+
+- Generate temporary signed URL for attachment rendering.
+- Query params:
+  - `bucket` (required)
+  - `path` (required)
+- Scope rule:
+  - `bucket` must match current storage bucket.
+  - `path` must be within current user prefix `agent-inputs/{user_id}/`.
+
+---
+
+## SSE Envelope (`/events`)
+
+`GET /api/v1/agent/runs/{thread_id}/events` uses `text/event-stream`.
+
+Each SSE frame format:
+
+```text
+id: <stream-id>
+event: <EVENT_TYPE>
+data: <JSON payload>
+
+```
+
+---
+
+## Event Type Set
+
+- `RUN_STARTED`
+- `STEP_STARTED`
+- `STEP_FINISHED`
+- `TEXT_MESSAGE_START`
+- `TEXT_MESSAGE_CONTENT`
+- `TEXT_MESSAGE_END`
+- `TOOL_CALL_RESULT`
+- `RUN_FINISHED`
+- `RUN_ERROR`
+
+---
+
+## Common Event Fields
+
+```typescript
+interface EventBase {
+  type: string;
+  threadId: string;
+  runId?: string;
+}
+```
+
+---
+
+## Event Payload Schemas
+
+### Run Lifecycle
+
+```typescript
+interface RunStartedEvent extends EventBase {
+  type: "RUN_STARTED";
+  runId: string;
+}
+
+interface RunFinishedEvent extends EventBase {
+  type: "RUN_FINISHED";
+  runId: string;
+}
+
+interface RunErrorEvent extends EventBase {
+  type: "RUN_ERROR";
+  runId: string;
+  message: string;
+}
+```
+
+### Step Lifecycle
+
+```typescript
+interface StepStartedEvent extends EventBase {
+  type: "STEP_STARTED";
+  runId: string;
+  stepName: string;
+}
+
+interface StepFinishedEvent extends EventBase {
+  type: "STEP_FINISHED";
+  runId: string;
+  stepName: string;
+}
+```
+
+### Text Streaming
+
+```typescript
+interface TextMessageStartEvent extends EventBase {
+  type: "TEXT_MESSAGE_START";
+  runId: string;
+  messageId: string;
+  role: "assistant" | "system" | "user" | "tool";
+  stage?: string;
+}
+
+interface TextMessageContentEvent extends EventBase {
+  type: "TEXT_MESSAGE_CONTENT";
+  runId: string;
+  messageId: string;
+  delta: string; // incremental text chunk
+}
+
+interface TextMessageEndEvent extends EventBase {
+  type: "TEXT_MESSAGE_END";
+  runId: string;
+  messageId: string;
+  workerAgentOutput: WorkerAgentOutput;
+  // stage/model are intentionally excluded from this event
+}
+```
+
+### Tool Result
+
+```typescript
+interface ToolCallResultEvent extends EventBase {
+  type: "TOOL_CALL_RESULT";
+  messageId: string;
+  toolCallId: string;
+  toolAgentOutput: ToolAgentOutput; // required
+}
+```
+
+### Worker/Tool Payloads
+
+```typescript
+interface WorkerAgentOutput {
+  status: "success" | "partial_success" | "failed";
+  answer: string;
+  key_points?: string[];
+  result_type?: string;
+  suggested_actions?: string[];
+  error?: {
+    code: string;
+    message: string;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+  };
+  ui_hints?: Record<string, unknown>;
+}
+
+interface ToolAgentOutput {
+  tool_name: string;
+  tool_call_id: string;
+  tool_call_args?: Record<string, unknown>;
+  status: "success" | "partial" | "failure";
+  result_summary: string;
+  ui_hints?: Record<string, unknown>;
+  error?: {
+    code: string;
+    message: string;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+  };
+}
+```
+
+---
+
+## History Response Schema
+
+`GET /api/v1/agent/history` returns `STATE_SNAPSHOT` payload.
+
+```typescript
+interface AgentHistoryResponse {
+  type: "STATE_SNAPSHOT";
+  threadId?: string;
+  snapshot: {
+    scope: "history_day";
+    threadId: string | null;
+    day: string | null; // YYYY-MM-DD
+    hasMore: boolean;
+    messages: SnapshotMessage[];
+  };
+}
+
+interface SnapshotMessage {
+  id: string;
+  seq: number;
+  role: "user" | "assistant" | "system" | "tool";
+  content: string;
+  metadata?: Record<string, unknown>;
+  timestamp: string; // ISO-8601
+}
+
+interface AttachmentSignedUrlResponse {
+  bucket: string;
+  path: string;
+  url: string;
+}
+```
+
+---
+
+## Compatibility Notes
+
+- For `TOOL_CALL_RESULT`, clients should treat `toolAgentOutput` as canonical payload.
+- `TEXT_MESSAGE_CONTENT.delta` is defined as incremental text chunk. Implementations should emit multiple chunks for real streaming UX.
+- `TEXT_MESSAGE_END` must not include `stage` or `model` in this protocol version.
+- History snapshot `messages[]` strictly follows `backend/src/schemas/messages/chat_message.py` `AgentChatMessage` schema.
+- Attachment URL rendering is decoupled from history; client should call `/api/v1/agent/attachments/signed-url` using metadata fields.