docs: 添加 AG-UI 协议规则约束到 apps/AGENTS.md

2026-03-02 11:17:20 +08:00
parent 99d540a18d
commit 87b8727ca4
5 changed files with 279 additions and 1 deletions
@@ -122,6 +122,46 @@ AppBanner(message: '请检查输入', type: ToastType.warning)
 - DO NOT create custom SnackBar, Dialog, or Banner components
 - DO NOT use raw `ScaffoldMessenger`

+## Agent Chat (AG-UI Protocol)
+
+**Agent chat functionality MUST follow the AG-UI protocol**, reference `docs/knowledges/ag-ui-llms-full.txt`.
+
+### Core Requirements
+
+1. **Event-Driven Architecture**: Implement event-driven streaming responses
+2. **Event Types**: Must support the 16 standard event types:
+   - **Lifecycle**: `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`, `STEP_STARTED`, `STEP_FINISHED`
+   - **Text Message**: `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`
+   - **Tool Call**: `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, `TOOL_CALL_RESULT`
+   - **State Management**: `STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT`
+   - **Special**: `RAW`, `CUSTOM`
+
+3. **Transport**: Use Server-Sent Events (SSE) for streaming
+
+4. **Event Flow**: Follow the standard pattern:
+   - `RUN_STARTED` (required) → [optional events] → `RUN_FINISHED` or `RUN_ERROR` (required)
+   - Text messages: `TEXT_MESSAGE_START` → `TEXT_MESSAGE_CONTENT` (delta) → `TEXT_MESSAGE_END`
+
+5. **Frontend Integration**: Use AG-UI compatible client libraries
+
+### Event Reference
+
+| Event | Description |
+|-------|-------------|
+| `RUN_STARTED` | Signals the start of an agent run |
+| `RUN_FINISHED` | Signals successful completion |
+| `RUN_ERROR` | Signals an error during execution |
+| `TEXT_MESSAGE_START` | Initializes a new text message with unique messageId |
+| `TEXT_MESSAGE_CONTENT` | Delivers incremental text chunks (delta) |
+| `TEXT_MESSAGE_END` | Marks message completion |
+
+### Prohibitions
+
+- DO NOT return non-streaming responses for agent chat
+- DO NOT skip required lifecycle events (RUN_STARTED, RUN_FINISHED/RUN_ERROR)
+- DO NOT use custom event formats outside of AG-UI specification
+
+
 ## App Debugging

 **DO NOT automatically start Flutter app debugging.**