Enhance workflow routing and agent configuration management

- Introduce WorkflowLLMRouter for pre-response LLM routing, allowing agents to determine the appropriate function to call based on user input.
- Implement UserTurnRoutingProcessor to manage user turns before reaching the LLM, ensuring proper routing and handling of user messages.
- Refactor WorkflowBrain to integrate new routing logic and enhance agent stage configuration, including entry modes and resource management.
- Update service factory to support dynamic LLM resource configuration based on workflow settings.
- Add tests for new routing functionality and ensure proper handling of user messages in various scenarios.

backend/tests/test_workflow_v3.py

@@ -4,7 +4,7 @@ import unittest
 
 from models import AssistantConfig, RuntimeModelResource
 from services.pipecat.service_factory import config_with_resource
-from services.node_specs import normalize_graph, validate_graph
+from services.node_specs import graph_references, normalize_graph, validate_graph
 from services.runtime_variables import DynamicVariableStore, prepare_dynamic_config
 from services.workflow_engine import WorkflowEngine
 
@@ -49,6 +49,22 @@ def valid_graph():
 
 
 class WorkflowGraphTests(unittest.TestCase):
+    def test_agent_entry_mode_defaults_and_validation(self):
+        graph = valid_graph()
+        normalized = normalize_graph(graph)
+        agent = next(node for node in normalized["nodes"] if node["type"] == "agent")
+        self.assertEqual(agent["data"]["entryMode"], "wait_user")
+        self.assertEqual(agent["data"]["entrySpeech"], "")
+        self.assertTrue(agent["data"]["inheritGlobalConfig"])
+        self.assertEqual(agent["data"]["contextPolicy"], "fresh")
+
+        agent["data"]["entryMode"] = "fixed_speech"
+        self.assertTrue(
+            any("固定进入语不能为空" in error for error in validate_graph(normalized))
+        )
+        agent["data"]["entrySpeech"] = "您好，{{customer}}"
+        self.assertEqual(validate_graph(normalized), [])
+
     def test_voice_resource_creates_isolated_runtime_config(self):
         base = AssistantConfig(type="workflow", asr="default", voice="default")
         asr = RuntimeModelResource(
@@ -63,6 +79,191 @@ class WorkflowGraphTests(unittest.TestCase):
         self.assertEqual(resolved.stt_api_key, "secret")
         self.assertEqual(base.asr, "default")
 
+        llm = RuntimeModelResource(
+            id="llm_1",
+            capability="LLM",
+            interface_type="openai-llm",
+            values={"modelId": "deepseek-chat", "apiUrl": "https://llm.test/v1"},
+            secrets={"apiKey": "llm-secret"},
+        )
+        llm_resolved = config_with_resource(base, llm)
+        self.assertEqual(llm_resolved.model, "deepseek-chat")
+        self.assertEqual(llm_resolved.llm_api_key, "llm-secret")
+
+    def test_global_and_custom_agent_references_are_preserved(self):
+        graph = valid_graph()
+        graph["settings"].update(
+            {
+                "defaultLlmResourceId": "llm_global",
+                "defaultAsrResourceId": "asr_global",
+                "defaultTtsResourceId": "tts_global",
+                "toolIds": ["tool_global"],
+                "knowledgeBaseId": "kb_global",
+            }
+        )
+        agent = next(node for node in graph["nodes"] if node["type"] == "agent")
+        agent["data"].update(
+            {
+                "inheritGlobalConfig": False,
+                "llmResourceId": "llm_agent",
+                "asrResourceId": "asr_agent",
+                "ttsResourceId": "tts_agent",
+                "toolIds": ["tool_agent"],
+                "knowledgeBaseId": "kb_agent",
+            }
+        )
+
+        refs = graph_references(graph)
+        self.assertEqual(
+            refs["model_resources"],
+            {
+                "llm_global",
+                "asr_global",
+                "tts_global",
+                "llm_agent",
+                "asr_agent",
+                "tts_agent",
+            },
+        )
+        self.assertEqual(refs["tools"], {"tool_global", "tool_agent"})
+        self.assertEqual(refs["knowledge_bases"], {"kb_global", "kb_agent"})
+
+    def test_existing_agent_override_disables_implicit_inheritance(self):
+        graph = valid_graph()
+        agent = next(node for node in graph["nodes"] if node["type"] == "agent")
+        agent["data"]["toolIds"] = ["legacy_tool"]
+        normalized = normalize_graph(graph)
+        normalized_agent = next(
+            node for node in normalized["nodes"] if node["type"] == "agent"
+        )
+        self.assertFalse(normalized_agent["data"]["inheritGlobalConfig"])
+
+    def test_inherited_agent_ignores_stale_custom_references(self):
+        graph = valid_graph()
+        agent = next(node for node in graph["nodes"] if node["type"] == "agent")
+        agent["data"].update(
+            {
+                "inheritGlobalConfig": True,
+                "llmResourceId": "stale_llm",
+                "asrResourceId": "stale_asr",
+                "ttsResourceId": "stale_tts",
+                "toolIds": ["stale_tool"],
+                "knowledgeBaseId": "stale_kb",
+            }
+        )
+
+        refs = graph_references(graph)
+
+        self.assertNotIn("stale_llm", refs["model_resources"])
+        self.assertNotIn("stale_tool", refs["tools"])
+        self.assertNotIn("stale_kb", refs["knowledge_bases"])
+
+    def test_agent_effective_config_inherits_then_switches_to_override(self):
+        graph = valid_graph()
+        graph["settings"].update(
+            {
+                "defaultLlmResourceId": "llm_global",
+                "defaultAsrResourceId": "asr_global",
+                "defaultTtsResourceId": "tts_global",
+                "toolIds": ["tool_global"],
+                "knowledgeBaseId": "kb_global",
+                "knowledgeMode": "on_demand",
+                "knowledgeTopN": 8,
+                "knowledgeScoreThreshold": 0.4,
+            }
+        )
+        engine = WorkflowEngine(graph)
+        inherited = engine.agent_stage_config("agent")
+        self.assertEqual(inherited.llm_resource_id, "llm_global")
+        self.assertEqual(inherited.tool_ids, ("tool_global",))
+        self.assertEqual(inherited.knowledge_mode, "on_demand")
+
+        engine.data("agent").update(
+            {
+                "inheritGlobalConfig": False,
+                "llmResourceId": "llm_agent",
+                "toolIds": ["tool_agent"],
+                "knowledgeBaseId": "",
+            }
+        )
+        custom = engine.agent_stage_config("agent")
+        self.assertEqual(custom.llm_resource_id, "llm_agent")
+        self.assertEqual(custom.tool_ids, ("tool_agent",))
+        self.assertEqual(custom.knowledge_mode, "disabled")
+
+    def test_start_agent_and_handoff_may_have_no_outgoing_edge(self):
+        terminal_graphs = [
+            {
+                "specVersion": 3,
+                "settings": {},
+                "nodes": [{"id": "start", "type": "start", "data": {}}],
+                "edges": [],
+            },
+            {
+                "specVersion": 3,
+                "settings": {},
+                "nodes": [
+                    {"id": "start", "type": "start", "data": {}},
+                    {
+                        "id": "agent",
+                        "type": "agent",
+                        "data": {"prompt": "持续处理用户问题"},
+                    },
+                ],
+                "edges": [
+                    {
+                        "id": "begin",
+                        "source": "start",
+                        "target": "agent",
+                        "data": {"mode": "always", "priority": 0},
+                    }
+                ],
+            },
+            {
+                "specVersion": 3,
+                "settings": {},
+                "nodes": [
+                    {"id": "start", "type": "start", "data": {}},
+                    {"id": "handoff", "type": "handoff", "data": {}},
+                ],
+                "edges": [
+                    {
+                        "id": "begin",
+                        "source": "start",
+                        "target": "handoff",
+                        "data": {"mode": "always", "priority": 0},
+                    }
+                ],
+            },
+        ]
+
+        for graph in terminal_graphs:
+            with self.subTest(node=graph["nodes"][-1]["type"]):
+                self.assertEqual(validate_graph(graph), [])
+
+        action_without_exit = {
+            "specVersion": 3,
+            "settings": {},
+            "nodes": [
+                {"id": "start", "type": "start", "data": {}},
+                {"id": "action", "type": "action", "data": {}},
+            ],
+            "edges": [
+                {
+                    "id": "begin",
+                    "source": "start",
+                    "target": "action",
+                    "data": {"mode": "always", "priority": 0},
+                }
+            ],
+        }
+        self.assertTrue(
+            any(
+                "action 的出边不能少于 1" in error
+                for error in validate_graph(action_without_exit)
+            )
+        )
+
     def test_v2_start_prompt_is_preserved_in_synthetic_agent(self):
         graph = normalize_graph(
             {
@@ -113,6 +314,15 @@ class WorkflowGraphTests(unittest.TestCase):
         )
         self.assertIn("王先生", engine.prompt_for("agent", store))
 
+        inherited_prompt = engine.prompt_for("agent", store)
+        self.assertIn("服务 王先生", inherited_prompt)
+        self.assertIn("处理订单", inherited_prompt)
+
+        engine.data("agent")["inheritGlobalConfig"] = False
+        custom_prompt = engine.prompt_for("agent", store)
+        self.assertNotIn("服务 王先生", custom_prompt)
+        self.assertIn("处理订单", custom_prompt)
+
 
 if __name__ == "__main__":
     unittest.main()