qzl
142 lines
6.5 KiB
Markdown
142 lines
6.5 KiB
Markdown
# AgentScope Agent Route Migration Handoff Plan
|
|
|
|
## 1) Reconfirmed Objective
|
|
|
|
- Keep external API paths unchanged under `/api/v1/agent/*`.
|
|
- Replace internal run/resume/events runtime path with `core/agentscope` modules.
|
|
- Use five modules only: `runtime`, `prompts`, `schemas`, `tools`, `events`.
|
|
- Put AG-UI event conversion + persistence + Redis export in `events`.
|
|
- Keep `/transcribe` under the same router prefix but independent from agent runtime.
|
|
- Continue migration until legacy `core/agent` is removable.
|
|
|
|
## 2) Current Progress Snapshot
|
|
|
|
### Completed
|
|
|
|
- Task 1 (schemas) finished:
|
|
- Added runtime-facing schemas in `core/agentscope/schemas/agent_runtime.py`.
|
|
- Exported aliases for compatibility (`AcceptedTaskResponse`, `TaskAcceptedResponse`, `TaskAccepted`).
|
|
- Task 2 (events) finished:
|
|
- Added `events` module with AG-UI conversion, SSE encoding, Redis stream bus, pipeline, and store abstraction.
|
|
- Security fixes applied:
|
|
- Prevent reserved key overwrite in AG-UI codec.
|
|
- Sanitize SSE stream id.
|
|
- Support Redis bytes payload decoding.
|
|
- SSE now reuses AG-UI protocol encoder (`EventEncoder`) instead of custom JSON-only logic.
|
|
- Task 3 (runtime adapter) finished:
|
|
- Added `AgentRouteRuntime` to emit internal events around orchestrator execution.
|
|
- Added step events for stage identification:
|
|
- `step.start/step.finish` for `intent`, `execution`, `report`.
|
|
- Error event payload no longer leaks raw exception text to clients.
|
|
- Task 4 (route/service wiring) largely finished:
|
|
- `/v1/agent/router.py` now uses `core.agentscope.events.to_sse_event`.
|
|
- `/v1/agent/dependencies.py` queue tasks switched to `core.agentscope.runtime.tasks`.
|
|
- `/v1/agent/dependencies.py` stream reads switched to `RedisStreamBus`.
|
|
- `/v1/agent/service.py` enqueue payload now carries `owner_id` and extracted `user_token`.
|
|
- Added tests for runtime task entrypoint dispatch/validation.
|
|
|
|
### In Progress / Not Finished
|
|
|
|
- Task 4 review wrap-up:
|
|
- One review already returned PASS for spec compliance after fixes.
|
|
- Final quality/security confirmation for latest delta should be re-run once before moving to Task 5.
|
|
- Task 5 (sessions/messages persistence ownership, cost/tokens/latency full persistence) not started.
|
|
- Task 6 (remove `core/agent` and clean imports) not started.
|
|
- Task 7 (frontend AG-UI contract and E2E validation) not started.
|
|
|
|
## 3) What Was Changed (Relevant Files)
|
|
|
|
### New Files
|
|
|
|
- `backend/src/core/agentscope/schemas/agent_runtime.py`
|
|
- `backend/src/core/agentscope/events/__init__.py`
|
|
- `backend/src/core/agentscope/events/agui_codec.py`
|
|
- `backend/src/core/agentscope/events/sse.py`
|
|
- `backend/src/core/agentscope/events/redis_bus.py`
|
|
- `backend/src/core/agentscope/events/store.py`
|
|
- `backend/src/core/agentscope/events/pipeline.py`
|
|
- `backend/src/core/agentscope/runtime/agent_route_runtime.py`
|
|
- `backend/src/core/agentscope/runtime/tasks.py`
|
|
- `backend/tests/unit/core/agentscope/schemas/test_agent_runtime_schemas.py`
|
|
- `backend/tests/unit/core/agentscope/events/test_agui_codec.py`
|
|
- `backend/tests/unit/core/agentscope/events/test_sse.py`
|
|
- `backend/tests/unit/core/agentscope/events/test_redis_bus.py`
|
|
- `backend/tests/unit/core/agentscope/events/test_pipeline.py`
|
|
- `backend/tests/unit/core/agentscope/runtime/test_agent_route_runtime.py`
|
|
- `backend/tests/unit/core/agentscope/runtime/test_tasks.py`
|
|
|
|
### Modified Files
|
|
|
|
- `backend/src/core/agentscope/runtime/__init__.py`
|
|
- `backend/src/core/agentscope/schemas/__init__.py`
|
|
- `backend/src/v1/agent/router.py`
|
|
- `backend/src/v1/agent/dependencies.py`
|
|
- `backend/src/v1/agent/service.py`
|
|
|
|
## 4) Key References Used
|
|
|
|
### In-repo references
|
|
|
|
- Current agent route/service contracts:
|
|
- `backend/src/v1/agent/router.py`
|
|
- `backend/src/v1/agent/service.py`
|
|
- `backend/src/v1/agent/dependencies.py`
|
|
- `backend/src/v1/agent/repository.py`
|
|
- Existing runtime/orchestrator basis:
|
|
- `backend/src/core/agentscope/runtime/orchestrator.py`
|
|
|
|
### External reference project
|
|
|
|
- DIVA-backend async stream/task patterns (for architecture guidance only):
|
|
- `/home/qzl/Code/DIVA-backend/src/diva/services/app/conversation/task_event_stream_service.py`
|
|
- `/home/qzl/Code/DIVA-backend/src/diva/services/app/conversation/tasks.py`
|
|
- `/home/qzl/Code/DIVA-backend/src/diva/utils/agui_events.py`
|
|
|
|
### Protocol/framework references
|
|
|
|
- AG-UI protocol skill docs (event naming/shape guidance)
|
|
- AgentScope skill docs (`ReActAgent`, model/runtime usage)
|
|
|
|
## 5) Next Execution Plan (Continue From Here)
|
|
|
|
### Step A: Close Task 4 gates (quick)
|
|
|
|
- Re-run targeted checks for the latest Task 4 code:
|
|
- `uv run pytest tests/unit/v1/agent/test_service.py tests/unit/core/agentscope/runtime/test_tasks.py tests/unit/core/agentscope/runtime/test_agent_route_runtime.py tests/unit/core/agentscope/events -q`
|
|
- `uv run ruff check src/v1/agent src/core/agentscope/runtime src/core/agentscope/events tests/unit/core/agentscope/runtime tests/unit/core/agentscope/events`
|
|
- `uv run basedpyright src/v1/agent src/core/agentscope/runtime src/core/agentscope/events tests/unit/core/agentscope/runtime tests/unit/core/agentscope/events`
|
|
- Run one explicit code/security review pass on Task 4 final diff.
|
|
|
|
### Step B: Execute Task 5 (persistence migration)
|
|
|
|
- Implement `events.store` real persistence (replace `NullEventStore` path in runtime task assembly):
|
|
- persist sessions/messages from AG-UI wire events.
|
|
- include tokens/cost/latency fields.
|
|
- maintain session aggregates.
|
|
- Add unit + integration tests for persistence correctness and aggregation.
|
|
|
|
### Step C: Execute Task 6 (remove legacy core/agent)
|
|
|
|
- Move remaining required data structures into `core/agentscope/schemas`.
|
|
- Replace all `core.agent.*` imports in active code paths.
|
|
- Delete `backend/src/core/agent/**` when no runtime path depends on it.
|
|
- Add guard test to ensure no legacy imports remain.
|
|
|
|
### Step D: Execute Task 7 (frontend contract validation)
|
|
|
|
- Validate AG-UI event stream compatibility with current Flutter parser and bloc flow.
|
|
- Run impacted frontend tests for chat/event handling.
|
|
|
|
## 6) Risks and Notes
|
|
|
|
- Workspace is currently dirty with many unrelated app/backend files; avoid mixing commits.
|
|
- This handoff only tracks the AgentScope migration subset above.
|
|
- `/transcribe` remains in `v1/agent/router.py` and intentionally independent.
|
|
|
|
## 7) Resume Checklist (first actions next session)
|
|
|
|
1. Read this handoff file.
|
|
2. Re-run Task 4 final checks and review gates.
|
|
3. Start Task 5 by replacing `NullEventStore` with real store implementation.
|
|
4. Keep route contract stable (`/api/v1/agent/*`) until Task 7 is verified.
|