social-app/docs/plans/2026-03-11-agentscope-agent-route-migration-handoff.md

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.