Parent Issue: #5759 — Plan: v0.2.0 — Intelligent Chat Agent (Microsoft Agent Framework)
🤖 Agent Task: speckit.implement
Implement the feature based on the specification, plan, and tasks. Write production-quality code with tests.
Parent Issue Context
Plan: v0.2.0 — Intelligent Chat Agent (Microsoft Agent Framework)
Replace the current completion-based AIAgentService (raw LLM calls + manual JSON parsing) with a Microsoft Agent Framework Agent that uses function tools to take actions, sessions for multi-turn memory, and middleware for logging/security. The priority-dispatch cascade in chat.py becomes the agent's natural reasoning — instead of hardcoded if/elif priority tiers, the agent decides which tool to call based on its instructions. The REST API contract stays the same so the frontend needs minimal changes.
Phase 1: Foundation — Agent Service & Tools
Step 1: Install packages (blocks steps 2-4)
Add agent-framework-core, agent-framework-github-copilot, agent-framework-azure-ai to pyproject.toml
Deprecate direct copilot SDK dependency (now wrapped by agent-framework-github-copilot)
Step 2: Create function tools — new src/services/agent_tools.py (parallel with steps 3-4)
Convert each current action into a @tool-decorated function:
Current method New tool
generate_task_from_description() create_task_proposal(title, description)
detect_feature_request_intent() + generate_issue_recommendation() create_issue_recommendation(title, user_story, ...)
parse_status_change_request() update_task_status(task_reference, target_status)
analyze_transcript() analyze_transcript(transcript_content)
(new) ask_clarifying_question(question)
(new) get_project_context(), get_pipeline_list()
Runtime context (project_id, github_token, session_id) injected via FunctionInvocationContext.kwargs — invisible to LLM schema
Step 3: Create agent provider factory — new src/services/agent_provider.py (parallel with step 2)
ai_provider="copilot" → GitHubCopilotAgent (from agent_framework.github)
ai_provider="azure_openai" → Agent with AzureOpenAIResponsesClient (from agent_framework.azure)
Replaces CopilotCompletionProvider + AzureOpenAICompletionProvider + CopilotClientPool
Step 4: Write system instructions — new src/prompts/agent_instructions.py (parallel with step 2)
Single comprehensive prompt replacing task_generation.py, issue_generation.py, transcript_analysis.py
Includes: clarifying-questions policy (2-3 questions before acting), difficulty assessment, tool usage guidance, dynamic project context injection
Phase 2: Integration — Chat API Refactor
Step 5: Create ChatAgentService — new src/services/chat_agent.py (depends on steps 1-4)
Holds singleton Agent instance, manages AgentSession ↔ Solune session_id mapping
Exposes run() and run_stream() methods returning ChatMessage
Passes runtime context via function_invocation_kwargs
Converts AgentResponse.messages → ChatMessage with action_type/action_data
Step 6: Refactor send_message in src/api/chat.py (depends on step 5)
Replace the 5-tier priority dispatch (_handle_feature_request, _handle_status_change, _handle_task_generation, _handle_transcript_upload) with a single agent_service.run() call
Keep: /agent command handling (meta-command), proposal confirm/reject endpoints, file upload
The agent chooses which tool to invoke based on reasoning
Step 7: Add streaming endpoint — POST /chat/messages/stream (parallel with step 6)
SSE endpoint using agent.run(..., stream=True)
Progressive token delivery via EventSourceResponse
Step 8: Update Signal chat in src/services/signal_chat.py (depends on step 5)
Replace direct ai_service.* calls with ChatAgentService.run() (non-streaming)
Phase 3: Middleware, Testing & Cleanup
Step 9: Add middleware — new src/services/agent_middleware.py (parallel with step 10)
LoggingAgentMiddleware (timing, token count)
SecurityMiddleware (prompt injection detection, tool argument validation)
Step 10: Tests (depends on steps 5-8)
New tests/unit/test_agent_tools.py — each tool tested with mocked FunctionInvocationContext
New tests/unit/test_chat_agent.py — mock Agent.run(), verify session mapping, response conversion
Update tests/unit/test_api_chat.py — mock targets change from ai_service.* to chat_agent_service.run
Step 11: Deprecate old layers (depends on step 10)
Add deprecation warnings to AIAgentService, CompletionProvider, old prompt modules
Keep identify_target_task() — reused by update_task_status tool
Step 12: Frontend streaming (parallel with steps 9-11)
Update chatApi.sendMessage() in frontend/src/services/api.ts to use /messages/stream via ReadableStream
Progressive rendering in MessageBubble; fallback to non-streaming endpoint
Relevant files
Create: src/services/agent_tools.py, src/services/agent_provider.py, src/services/chat_agent.py, src/services/agent_middleware.py, src/prompts/agent_instructions.py, tests/unit/test_agent_tools.py, tests/unit/test_chat_agent.py
Modify: pyproject.toml, src/api/chat.py, src/services/signal_chat.py, src/config.py, frontend/src/services/api.ts, frontend/src/components/chat/ChatInterface.tsx, tests/unit/test_api_chat.py
Deprecate: src/services/ai_agent.py, src/services/completion_providers.py, src/prompts/task_generation.py, src/prompts/issue_generation.py, src/prompts/transcript_analysis.py
Verification
pytest tests/unit/ — all existing + new tests pass
Manual chat — agent responds, clarifying questions work, tool calls produce proposals
Streaming — real-time tokens appear in browser
Signal — agent responds to text messages
AI_PROVIDER=azure_openai — same behavior with different backend
Proposal flow — create → confirm → GitHub issue created
Multi-turn — "My project uses React" → "What stack?" → agent remembers
Docker — docker compose up --build → healthy, end-to-end
Decisions
API contract stable — ChatMessage schema unchanged, frontend streaming is additive
Agent replaces priority dispatch — no hardcoded cascade
Tools return structured dicts → converted to action_data for confirm/reject flow
Deprecate, don't delete — old service layer gets warnings, removed in v0.3.0
ai_enhance=False — bypasses agent, uses simple title-only generation (preserves current behavior)
Further Considerations
MCP tool integration (v0.4.0 scope): Agent Framework supports mcp_servers natively — design tool registration to accommodate future MCP tools
Conversation history: Keep Solune's SQLite as source of truth, sync summaries into AgentSession.state — don't replace the storage layer
Per-user auth with Copilot provider: GitHubCopilotAgent may need per-run token passing — if not supported, use bounded ephemeral agent pool (similar to current CopilotClientPool)
https://learn.microsoft.com/en-us/agent-framework/agents/providers/github-copilot?pivots=programming-language-python
https://github.com/microsoft/agent-framework
https://learn.microsoft.com/en-us/agent-framework/overview/?pivots=programming-language-python
Sub-issue created for agent speckit.implement — see parent issue #5759 for full context
🤖 Agent Task:
speckit.implementImplement the feature based on the specification, plan, and tasks. Write production-quality code with tests.
Parent Issue Context
Plan: v0.2.0 — Intelligent Chat Agent (Microsoft Agent Framework)
Replace the current completion-based AIAgentService (raw LLM calls + manual JSON parsing) with a Microsoft Agent Framework Agent that uses function tools to take actions, sessions for multi-turn memory, and middleware for logging/security. The priority-dispatch cascade in chat.py becomes the agent's natural reasoning — instead of hardcoded if/elif priority tiers, the agent decides which tool to call based on its instructions. The REST API contract stays the same so the frontend needs minimal changes.
Phase 1: Foundation — Agent Service & Tools
Step 1: Install packages (blocks steps 2-4)
Add agent-framework-core, agent-framework-github-copilot, agent-framework-azure-ai to pyproject.toml
Deprecate direct copilot SDK dependency (now wrapped by agent-framework-github-copilot)
Step 2: Create function tools — new src/services/agent_tools.py (parallel with steps 3-4)
Convert each current action into a @tool-decorated function:
Current method New tool
generate_task_from_description() create_task_proposal(title, description)
detect_feature_request_intent() + generate_issue_recommendation() create_issue_recommendation(title, user_story, ...)
parse_status_change_request() update_task_status(task_reference, target_status)
analyze_transcript() analyze_transcript(transcript_content)
(new) ask_clarifying_question(question)
(new) get_project_context(), get_pipeline_list()
Runtime context (project_id, github_token, session_id) injected via FunctionInvocationContext.kwargs — invisible to LLM schema
Step 3: Create agent provider factory — new src/services/agent_provider.py (parallel with step 2)
ai_provider="copilot" → GitHubCopilotAgent (from agent_framework.github)
ai_provider="azure_openai" → Agent with AzureOpenAIResponsesClient (from agent_framework.azure)
Replaces CopilotCompletionProvider + AzureOpenAICompletionProvider + CopilotClientPool
Step 4: Write system instructions — new src/prompts/agent_instructions.py (parallel with step 2)
Single comprehensive prompt replacing task_generation.py, issue_generation.py, transcript_analysis.py
Includes: clarifying-questions policy (2-3 questions before acting), difficulty assessment, tool usage guidance, dynamic project context injection
Phase 2: Integration — Chat API Refactor
Step 5: Create ChatAgentService — new src/services/chat_agent.py (depends on steps 1-4)
Holds singleton Agent instance, manages AgentSession ↔ Solune session_id mapping
Exposes run() and run_stream() methods returning ChatMessage
Passes runtime context via function_invocation_kwargs
Converts AgentResponse.messages → ChatMessage with action_type/action_data
Step 6: Refactor send_message in src/api/chat.py (depends on step 5)
Replace the 5-tier priority dispatch (_handle_feature_request, _handle_status_change, _handle_task_generation, _handle_transcript_upload) with a single agent_service.run() call
Keep: /agent command handling (meta-command), proposal confirm/reject endpoints, file upload
The agent chooses which tool to invoke based on reasoning
Step 7: Add streaming endpoint — POST /chat/messages/stream (parallel with step 6)
SSE endpoint using agent.run(..., stream=True)
Progressive token delivery via EventSourceResponse
Step 8: Update Signal chat in src/services/signal_chat.py (depends on step 5)
Replace direct ai_service.* calls with ChatAgentService.run() (non-streaming)
Phase 3: Middleware, Testing & Cleanup
Step 9: Add middleware — new src/services/agent_middleware.py (parallel with step 10)
LoggingAgentMiddleware (timing, token count)
SecurityMiddleware (prompt injection detection, tool argument validation)
Step 10: Tests (depends on steps 5-8)
New tests/unit/test_agent_tools.py — each tool tested with mocked FunctionInvocationContext
New tests/unit/test_chat_agent.py — mock Agent.run(), verify session mapping, response conversion
Update tests/unit/test_api_chat.py — mock targets change from ai_service.* to chat_agent_service.run
Step 11: Deprecate old layers (depends on step 10)
Add deprecation warnings to AIAgentService, CompletionProvider, old prompt modules
Keep identify_target_task() — reused by update_task_status tool
Step 12: Frontend streaming (parallel with steps 9-11)
Update chatApi.sendMessage() in frontend/src/services/api.ts to use /messages/stream via ReadableStream
Progressive rendering in MessageBubble; fallback to non-streaming endpoint
Relevant files
Create: src/services/agent_tools.py, src/services/agent_provider.py, src/services/chat_agent.py, src/services/agent_middleware.py, src/prompts/agent_instructions.py, tests/unit/test_agent_tools.py, tests/unit/test_chat_agent.py
Modify: pyproject.toml, src/api/chat.py, src/services/signal_chat.py, src/config.py, frontend/src/services/api.ts, frontend/src/components/chat/ChatInterface.tsx, tests/unit/test_api_chat.py
Deprecate: src/services/ai_agent.py, src/services/completion_providers.py, src/prompts/task_generation.py, src/prompts/issue_generation.py, src/prompts/transcript_analysis.py
Verification
pytest tests/unit/ — all existing + new tests pass
Manual chat — agent responds, clarifying questions work, tool calls produce proposals
Streaming — real-time tokens appear in browser
Signal — agent responds to text messages
AI_PROVIDER=azure_openai — same behavior with different backend
Proposal flow — create → confirm → GitHub issue created
Multi-turn — "My project uses React" → "What stack?" → agent remembers
Docker — docker compose up --build → healthy, end-to-end
Decisions
API contract stable — ChatMessage schema unchanged, frontend streaming is additive
Agent replaces priority dispatch — no hardcoded cascade
Tools return structured dicts → converted to action_data for confirm/reject flow
Deprecate, don't delete — old service layer gets warnings, removed in v0.3.0
ai_enhance=False — bypasses agent, uses simple title-only generation (preserves current behavior)
Further Considerations
MCP tool integration (v0.4.0 scope): Agent Framework supports mcp_servers natively — design tool registration to accommodate future MCP tools
Conversation history: Keep Solune's SQLite as source of truth, sync summaries into AgentSession.state — don't replace the storage layer
Per-user auth with Copilot provider: GitHubCopilotAgent may need per-run token passing — if not supported, use bounded ephemeral agent pool (similar to current CopilotClientPool)
https://learn.microsoft.com/en-us/agent-framework/agents/providers/github-copilot?pivots=programming-language-python
https://github.com/microsoft/agent-framework
https://learn.microsoft.com/en-us/agent-framework/overview/?pivots=programming-language-python
Sub-issue created for agent
speckit.implement— see parent issue #5759 for full context