diff --git a/docs/gns3-copilot/implemented/ai-assistant-overview.en.md b/docs/gns3-copilot/implemented/ai-assistant-overview.en.md index 9813c59a3..17e0ff972 100644 --- a/docs/gns3-copilot/implemented/ai-assistant-overview.en.md +++ b/docs/gns3-copilot/implemented/ai-assistant-overview.en.md @@ -101,21 +101,29 @@ sequenceDiagram | Tool | teaching_assistant | lab_automation_assistant | troubleshooting_injection | |---|---|---|---| -| `template_list` get templates | ✓ | ✓ | | +| `template_list` / `template_get` templates | ✓ | ✓ | | | `node_create` create nodes | ✓ | ✓ | | -| `link_create` create links (native) | ✓ | ✓ | | -| `node_start` start nodes | ✓ | ✓ | | +| `node_list` / `node_get` inspect nodes | ✓ | ✓ | | | `node_update` rename | ✓ | ✓ | | -| `node_stop` stop nodes | | ✓ | | -| `node_suspend` suspend nodes | | ✓ | | +| `node_start` start nodes | ✓ | ✓ | | +| `node_stop` / `node_suspend` stop/suspend | | ✓ | | +| `node_console_exec` raw console access | | ✓ | | +| `link_create` create links (native, port names) | ✓ | ✓ | | +| `link_list` inspect links | ✓ | | | +| `link_marker` traffic-insight markers | ✓ | | | +| `drawing_create_*` canvas annotations | ✓ | ✓ | | | `device_show_run` read-only commands | ✓ | ✓ | ✓ | | `device_config_send` config commands | | ✓ | ✓ | | `vpcs_config_set` VPCS commands | | ✓ | | +| `device_skill_get` device skills | ✓ | ✓ | | +| `snapshot_list` / `snapshot_create` / `snapshot_delete` / `snapshot_restore` snapshots | | ✓ | | +| `link_update` / `link_available_filters` fault filters | | | ✓ | +| `link_capture_start` / `link_capture_stop` / `link_capture_download` capture | | | ✓ | +| `marker_definition` project-wide markers | | | ✓ | +| `injection_skill_get` fault injection skills | | | ✓ | +| `wait_seconds` boot wait (native) | ✓ | ✓ | | | `packet_analysis` live packet analysis (native) | ✓ | ✓ | | | `packet_analysis_skills` protocol knowledge (native) | ✓ | ✓ | | -| `device_skill_get` device skills | ✓ | ✓ | | -| `link_update` link filters | | | ✓ | -| `injection_skill_get` fault injection skills | | | ✓ | | `gns3_topology_reader` topology info (native) | | | ✓ | The mode is selected in the `llm_call` node via `copilot_mode`, which picks the corresponding tool list and binds it to the LLM model instance through `create_base_model_with_tools(mode_tools, llm_config)`. diff --git a/docs/gns3-copilot/implemented/node-control-tools.md b/docs/gns3-copilot/implemented/node-control-tools.md index 9a39198b9..9ba6f295e 100644 --- a/docs/gns3-copilot/implemented/node-control-tools.md +++ b/docs/gns3-copilot/implemented/node-control-tools.md @@ -618,43 +618,51 @@ Note: These special node types are filtered out by template_list and won't appea ### Teaching Assistant Mode **Tools Available:** -- `template_list` - List available device templates 🆕 -- `node_create` - Create nodes in topology 🆕 -- `GNS3LinkTool` - Create links between nodes 🆕 -- `node_update` - Rename nodes 🆕 +- `template_list` / `template_get` - List and inspect device templates +- `node_create` - Create nodes in topology +- `node_list` / `node_get` - Inspect nodes (field projection keeps responses small) +- `node_update` - Rename nodes - `node_start` - For diagnostics requiring started nodes +- `link_create` - Create links between nodes (native: port-name resolution) +- `link_list` - Inspect links +- `link_marker` - Traffic-insight markers (highlight matching packets) +- `drawing_create_*` - Canvas annotations (text, rectangle, ellipse) - `device_show_run` - Execute show/display/debug commands (READ-ONLY) -- `PacketCaptureTool` - Analyze packets from active capture -- `DeviceSkillsTool` - Get device-specific skills and command knowledge +- `device_skill_get` - Get device-specific skills and command knowledge +- `wait_seconds` - Boot wait timer +- `packet_analysis` / `packet_analysis_skills` - Analyze packets and query protocol knowledge **Capabilities:** -- READ-ONLY diagnostic tools -- Can create and manage topology (nodes, links, names) +- READ-ONLY device diagnostics +- Can create and manage topology (nodes, links, names, annotations) +- Traffic-insight markers for teaching scenarios - Cannot stop or suspend nodes (prevents disruption of active labs) - Cannot execute configuration commands ### Lab Automation Assistant Mode **Tools Available:** -- `template_list` - List available device templates 🆕 -- `node_create` - Create nodes in topology 🆕 -- `GNS3LinkTool` - Create links between nodes 🆕 -- `node_update` - Rename nodes 🆕 -- `node_start` - Full lab deployment -- `node_stop` - Full lab shutdown -- `node_suspend` - Lab pause with state preservation +- `template_list` / `template_get` - List and inspect device templates +- `node_create` / `node_update` / `node_list` - Create, rename, inspect nodes +- `node_start` / `node_stop` / `node_suspend` - Full lifecycle control +- `node_console_exec` - Raw console access (works without a device_type tag) +- `link_create` - Create links between nodes (native: port-name resolution) +- `drawing_create_*` - Canvas annotations (text, rectangle, ellipse) - `device_show_run` - Execute show/display/debug commands (READ-ONLY) -- `device_config_send` - Execute configuration commands +- `device_config_send` - Execute configuration commands (Jinja2 templates supported) - `vpcs_config_set` - Execute VPCS commands using Netmiko -- `PacketCaptureTool` - Analyze packets from active capture -- `DeviceSkillsTool` - Get device-specific skills and command knowledge +- `device_skill_get` - Get device-specific skills and command knowledge +- `snapshot_list` / `snapshot_create` / `snapshot_delete` / `snapshot_restore` - Project snapshots +- `wait_seconds` - Boot wait timer +- `packet_analysis` / `packet_analysis_skills` - Analyze packets and query protocol knowledge **Capabilities:** - Full diagnostic and configuration tools - Complete topology and lifecycle management (create, connect, start/stop/suspend) -- Device configuration via Nornir/Netmiko +- Device configuration via Nornir/Netmiko (Jinja2 template batch mode) +- Generic console access for Docker/Linux/VPCS nodes - Automated workflows with state preservation -- Lab snapshot capabilities for later resumption +- Project snapshot save/restore ## Usage Examples diff --git a/gns3server/agent/gns3_copilot/agent/gns3_copilot.py b/gns3server/agent/gns3_copilot/agent/gns3_copilot.py index 9868040d8..ac65101b6 100644 --- a/gns3server/agent/gns3_copilot/agent/gns3_copilot.py +++ b/gns3server/agent/gns3_copilot/agent/gns3_copilot.py @@ -104,7 +104,8 @@ logger = logging.getLogger(__name__) # counterpart by design (server-side pcap analysis was rejected) # - GNS3TopologyTool: aggregated nodes+links+ports view in one call -# Teaching assistant mode: READ-ONLY diagnostics plus topology building +# Teaching assistant mode: read-only diagnostics, topology building and +# traffic-insight visibility (markers highlight packets on links) TEACHING_ASSISTANT_MODE_TOOLS = [ *adapted_mcp_tools( names=[ @@ -112,10 +113,14 @@ TEACHING_ASSISTANT_MODE_TOOLS = [ "template_get", "node_create", "node_update", + "node_list", + "node_get", "drawing_create_text", "drawing_create_rectangle", "drawing_create_ellipse", "node_start", + "link_list", + "link_marker", "device_show_run", "device_skill_get", ] @@ -126,7 +131,9 @@ TEACHING_ASSISTANT_MODE_TOOLS = [ PacketAnalysisSkillsTool(), # query packet analysis protocol definitions ] -# Lab automation assistant mode: Full diagnostic AND configuration tools +# Lab automation assistant mode: full diagnostic AND configuration tools, +# plus generic console access (node_console_exec works without a +# device_type tag — Docker/Linux/VPCS nodes) and project snapshots LAB_AUTOMATION_ASSISTANT_MODE_TOOLS = [ *adapted_mcp_tools( names=[ @@ -134,16 +141,22 @@ LAB_AUTOMATION_ASSISTANT_MODE_TOOLS = [ "template_get", "node_create", "node_update", - "drawing_create_text", - "drawing_create_rectangle", - "drawing_create_ellipse", + "node_list", "node_start", "node_stop", "node_suspend", + "node_console_exec", + "drawing_create_text", + "drawing_create_rectangle", + "drawing_create_ellipse", "device_show_run", "device_config_send", "vpcs_config_set", "device_skill_get", + "snapshot_list", + "snapshot_create", + "snapshot_delete", + "snapshot_restore", ] ), GNS3LinkTool(), # native: port-name resolution @@ -152,8 +165,8 @@ LAB_AUTOMATION_ASSISTANT_MODE_TOOLS = [ PacketAnalysisSkillsTool(), # query packet analysis protocol definitions ] -# Troubleshooting injection mode: Tools for injecting network faults -# Focused on configuration commands and injection skills for fault injection +# Troubleshooting injection mode: fault injection plus the capture loop +# (inject → capture the link → verify with the downloaded pcap) TROUBLESHOOTING_INJECTION_MODE_TOOLS = [ *adapted_mcp_tools( names=[ @@ -161,6 +174,10 @@ TROUBLESHOOTING_INJECTION_MODE_TOOLS = [ "device_config_send", "link_update", "link_available_filters", + "link_capture_start", + "link_capture_stop", + "link_capture_download", + "marker_definition", "injection_skill_get", ] ), @@ -172,13 +189,12 @@ tools = LAB_AUTOMATION_ASSISTANT_MODE_TOOLS # Create combined tool lookup for tool_node (supports all modes) # tool_node will receive tool calls based on mode-specific tools bound to the -# model -# Combine all tools from all modes and deduplicate by tool name +# model. The registry must cover every mode: a tool bound to the model but +# missing here would raise KeyError when the LLM calls it. ALL_TOOLS = LAB_AUTOMATION_ASSISTANT_MODE_TOOLS tools_by_name = {tool.name: tool for tool in ALL_TOOLS} -# Add troubleshooting injection tools to the global tool registry -for tool in TROUBLESHOOTING_INJECTION_MODE_TOOLS: +for tool in TEACHING_ASSISTANT_MODE_TOOLS + TROUBLESHOOTING_INJECTION_MODE_TOOLS: if tool.name not in tools_by_name: tools_by_name[tool.name] = tool diff --git a/tests/agent/test_mcp_bridge.py b/tests/agent/test_mcp_bridge.py index c3040bd2f..ce674c25b 100644 --- a/tests/agent/test_mcp_bridge.py +++ b/tests/agent/test_mcp_bridge.py @@ -194,3 +194,112 @@ def test_invoke_without_token_returns_error(monkeypatch: pytest.MonkeyPatch) -> result = tool.invoke({"x": 5}) assert "error" in result + + +class TestModeToolsets: + """Pin the exact copilot mode toolset composition. + + The mode tables are the visible capability contract of the copilot: + adapted MCP tools plus a few copilot-native ones. Any change here is a + deliberate product decision and must update this test. + """ + + @staticmethod + def _names(tools: list) -> set[str]: + return {tool.name for tool in tools} + + @pytest.fixture(scope="class") + def modes(self) -> dict[str, set[str]]: + from gns3server.agent.gns3_copilot.agent.gns3_copilot import ( + LAB_AUTOMATION_ASSISTANT_MODE_TOOLS, + TEACHING_ASSISTANT_MODE_TOOLS, + TROUBLESHOOTING_INJECTION_MODE_TOOLS, + ) + + return { + "teaching": self._names(TEACHING_ASSISTANT_MODE_TOOLS), + "lab": self._names(LAB_AUTOMATION_ASSISTANT_MODE_TOOLS), + "injection": self._names(TROUBLESHOOTING_INJECTION_MODE_TOOLS), + } + + def test_teaching_assistant(self, modes: dict[str, set[str]]) -> None: + assert modes["teaching"] == { + "template_list", + "template_get", + "node_create", + "node_update", + "node_list", + "node_get", + "drawing_create_text", + "drawing_create_rectangle", + "drawing_create_ellipse", + "node_start", + "link_list", + "link_marker", + "device_show_run", + "device_skill_get", + # copilot-native + "link_create", + "wait_seconds", + "packet_analysis", + "packet_analysis_skills", + } + + def test_lab_automation_assistant(self, modes: dict[str, set[str]]) -> None: + assert modes["lab"] == { + "template_list", + "template_get", + "node_create", + "node_update", + "node_list", + "node_start", + "node_stop", + "node_suspend", + "node_console_exec", + "drawing_create_text", + "drawing_create_rectangle", + "drawing_create_ellipse", + "device_show_run", + "device_config_send", + "vpcs_config_set", + "device_skill_get", + "snapshot_list", + "snapshot_create", + "snapshot_delete", + "snapshot_restore", + # copilot-native + "link_create", + "wait_seconds", + "packet_analysis", + "packet_analysis_skills", + } + + def test_troubleshooting_injection(self, modes: dict[str, set[str]]) -> None: + assert modes["injection"] == { + "device_show_run", + "device_config_send", + "link_update", + "link_available_filters", + "link_capture_start", + "link_capture_stop", + "link_capture_download", + "marker_definition", + "injection_skill_get", + # copilot-native + "gns3_topology_reader", + } + + def test_no_administration_tools_leak_into_any_mode(self, modes: dict[str, set[str]]) -> None: + banned_prefixes = ("project_", "compute_", "appliance_", "image_", "server_") + banned = {"template_create", "template_update", "template_delete"} + for mode_name, names in modes.items(): + leaked = {n for n in names if n.startswith(banned_prefixes)} | (names & banned) + assert not leaked, f"{mode_name} mode leaks administration tools: {leaked}" + + def test_every_mode_tool_is_resolvable(self, modes: dict[str, set[str]]) -> None: + """Every tool name in every mode must be constructible (no typos).""" + from gns3server.agent.gns3_copilot.agent.gns3_copilot import tools_by_name + + for mode_name, names in modes.items(): + missing = names - set(tools_by_name) + assert not missing, f"{mode_name} mode references unknown tools: {missing}"