The bridge made 49 project-scoped MCP tools available, but the mode tables still mirrored the old copilot capability set. Expand them: - lab_automation_assistant: node_console_exec (raw console for nodes without a device_type tag), node_list, snapshot_list/create/delete/ restore - teaching_assistant: node_list/node_get, link_list, link_marker (read-only diagnostics plus traffic-insight markers) - troubleshooting_injection: link_capture_start/stop/download and marker_definition (inject -> capture -> verify loop) Also fix the tools_by_name registry: it was built from the lab and injection tables only, which worked while teaching was a strict subset of lab. Teaching-only tools would have raised KeyError in tool_node when the LLM called them; the registry now unions all three mode tables. A new test pins each mode's exact toolset, checks that no administration tool leaks in, and asserts every referenced name is resolvable.
31 KiB
This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.
Node and Topology Management Tools
Overview
GNS3-Copilot provides tools for managing the lifecycle of network devices and topology in GNS3 projects. These tools enable AI agents to create, connect, start, stop, suspend, and manage nodes as part of automated lab management workflows.
Tool source (single source of truth): most copilot tools are no longer hand-written LangChain wrappers. They are adapted from the MCP server's tool registration by
tools_v2/mcp_bridge.py— tool names, descriptions and argument schemas are identical to the MCP tools (node_create,node_start,device_show_run, ...). The bridge filters the MCP registration down to project-scoped tools (the copilot runs inside one open project;project_*,compute_*,appliance_*,image_*and server administration tools are excluded) and bridges the copilot's request JWT into the MCP context. Copilot-native tools remain only where they add value:link_create(port-name resolution),wait_seconds,packet_analysis,packet_analysis_skills,gns3_topology_reader.
Available Tools
template_list 🆕
Tool Name: template_list
Description: Retrieves all available device templates from the GNS3 server, including template names, IDs, and types. Filters out built-in utility templates that are not useful for network device configuration.
Input:
{}
Output:
{
"templates": [
{
"name": "Cisco IOSv",
"template_id": "uuid-of-template",
"template_type": "qemu"
},
{
"name": "VPCS",
"template_id": "uuid-of-template2",
"template_type": "vpcs"
}
]
}
Features:
- Lists all available device templates for network labs
- Filters out built-in utility templates (see filtered list below)
- No input required (connects to configured GNS3 server)
- Returns template_id needed for node creation
- Logs total templates, filtered count, and remaining count
Filtered Templates: The following built-in utility templates are excluded as they are not actual network devices:
atm_switch- ATM switchcloud- Cloudethernet_hub- Ethernet hubethernet_switch- Ethernet switch (built-in, not user appliances)frame_relay_switch- Frame Relay switchnat- NAT device
Retained Template Types:
vpcs- Virtual PC Simulatordynamips- Cisco router simulator (IOSv, IOSv-L2, etc.)iou- Cisco IOS on Unixqemu- QEMU virtual machinesdocker- Docker containersvirtualbox- VirtualBox VMsvmware- VMware VMs
Use Cases:
- Discover available device types before creating nodes
- Get template_id for node_create
- Template inventory management
- Focus on network devices rather than utility templates
node_create 🆕
Tool Name: node_create
Description: Creates multiple nodes in a GNS3 project using specified templates and coordinates.
Input:
{
"project_id": "uuid-of-project",
"nodes": [
{
"template_id": "uuid-of-template",
"x": 100,
"y": -200,
"name": "R1"
},
{
"template_id": "uuid-of-template2",
"x": -200,
"y": 300,
"compute_id": "uuid-of-remote-compute"
}
]
}
Output:
{
"project_id": "uuid-of-project",
"created_nodes": [
{
"node_id": "uuid-of-node1",
"name": "R1",
"status": "success"
},
{
"node_id": "uuid-of-node2",
"name": "NodeName2",
"status": "success"
}
],
"total_nodes": 2,
"successful_nodes": 2,
"failed_nodes": 0
}
Features:
- Batch create multiple nodes
- Uses templates for consistent node configuration
- X/Y coordinate positioning for topology layout
- Optional
namefield to set node name directly (if omitted, GNS3 assigns default name) - Optional
compute_idfield to place the node on a remote compute (if omitted,local) - Important: Ensure distance between any two nodes is greater than 250px for clear interface labels
Use Cases:
- Automated topology deployment
- Multi-node lab initialization
- Programmatic topology creation
Implementation Details:
- Calls
POST /projects/{project_id}/nodesfor each node - Uses template_id from template_list
- Assigns default names sequentially (e.g., R1, R2, R3)
GNS3LinkTool 🆕
Tool Name: link_create
Description: Creates one or more links between nodes in a GNS3 project by connecting their network ports.
Input:
{
"project_id": "uuid-of-project",
"links": [
{
"node_id1": "uuid-of-node1",
"port1": "Ethernet0/0",
"node_id2": "uuid-of-node2",
"port2": "Ethernet0/0"
},
{
"node_id1": "uuid-of-node2",
"port1": "Serial0/0/0",
"node_id2": "uuid-of-node3",
"port2": "Serial0/0/0",
"link_type": "serial"
}
]
}
Output:
[
{
"link_id": "uuid-of-link",
"node_id1": "uuid-of-node1",
"port1": "Ethernet0/0",
"node_id2": "uuid-of-node2",
"port2": "Ethernet0/0"
}
]
Features:
- Batch create multiple links
- Automatic port discovery by name
- Optional
link_typefield per link (ethernetdefault, orserial) - Error handling for individual link failures
- Port names must match topology data
Use Cases:
- Automated topology wiring
- Multi-link connection setup
- Network infrastructure deployment
Implementation Details:
- Calls
POST /projects/{project_id}/linksfor each link - Port names must match those from
gns3_topology_readertool - Uses adapter_number and port_number for port identification
- Supports both physical and virtual interfaces
node_update 🆕
Tool Name: node_update
Description: Updates the name of one or multiple nodes in a GNS3 project.
Input:
{
"project_id": "uuid-of-project",
"nodes": [
{"node_id": "uuid-of-node-1", "new_name": "Router1"},
{"node_id": "uuid-of-node-2", "new_name": "Switch1"}
]
}
Output:
{
"project_id": "...",
"total_nodes": 2,
"successful": 2,
"failed": 0,
"nodes": [
{
"node_id": "...",
"old_name": "...",
"new_name": "Router1",
"status": "success"
}
]
}
Features:
- Batch rename multiple nodes
- Verification of name change
- Comprehensive error handling
Use Cases:
- Apply naming conventions to topology
- Rename nodes for better organization
- Update node names after topology creation
Implementation Details:
- Calls
PUT /projects/{project_id}/nodes/{node_id} - Cannot rename while node is started (except special node types)
- CAN rename while node is suspended
node_start
Tool Name: node_start
Description: Starts one or multiple nodes in a GNS3 project with progress tracking and status monitoring. Features dynamic wait time calculation based on device types for optimal performance.
Input:
{
"project_id": "uuid-of-project",
"node_ids": ["uuid-of-node-1", "uuid-of-node-2"]
}
Output:
{
"project_id": "...",
"total_nodes": 2,
"successful": 2,
"failed": 0,
"nodes": [
{"node_id": "...", "name": "...", "status": "started"},
{"node_id": "...", "name": "...", "status": "started"}
]
}
Features:
- Batch start multiple nodes
- Progress bar with visual feedback
- Automatic status verification
- Comprehensive error handling
- Dynamic wait time based on device types 🆕
Dynamic Wait Time Strategy:
The tool automatically detects node types and calculates optimal wait times:
| Device Type | Base Time | Per Additional Node | Example (5 nodes) |
|---|---|---|---|
| VPCS | 15s | +2s | 23s total |
| IOU | 25s | +3s | 37s total |
| Mixed VPCS/IOU | 25s | +2s | 33s total |
| QEMU/Dynamips/Docker/VMs | 120s | +10s | 160s total |
| Mixed (any slow device) | 120s | +10s | 160s total |
How It Works:
- Retrieves node information including
node_type - Checks if all nodes are fast devices (VPCS/IOU only)
- If all fast: Uses max(15s, 25s) base + 2s per extra node
- If any slow device present: Uses 120s base + 10s per extra node
- Logs the detected device types and chosen strategy
Performance Improvements:
- ⚡ 1 VPCS node: 140s → 15s (89% faster)
- ⚡ 5 VPCS nodes: 180s → 23s (87% faster)
- ⚡ 1 IOU node: 140s → 25s (82% faster)
- ⚡ 5 IOU nodes: 180s → 37s (79% faster)
- ⚡ Mixed VPCS/IOU: 180s → 33s (82% faster)
Use Cases:
- Automated lab deployment
- Multi-node topology initialization
- Lab startup automation
- Fast VPCS/IOU lab deployment
Implementation Details:
- Retrieves node type via
node.get()before starting - Calculates wait time using
calculate_startup_time()function - Uses device-specific
NODE_STARTUP_TIMEconfiguration- VPCS: 15s base + 2s per node (conservative for slower hardware)
- IOU: 25s base + 3s per node (accounts for IOU initialization overhead)
- Other: 120s base + 10s per node (conservative for full emulators)
- Logs device types and selected wait strategy
- Progress bar displays calculated wait time
node_start 🆕
Tool Name: start_gns3_node_quick
Description: Starts one or multiple nodes in a GNS3 project WITHOUT waiting for startup completion. Suitable for automated deployment workflows where long waits would cause HTTP timeouts.
Input:
{
"project_id": "uuid-of-project",
"node_ids": ["uuid-of-node-1", "uuid-of-node-2"]
}
Output:
{
"project_id": "...",
"total_nodes": 2,
"successful": 2,
"failed": 0,
"nodes": [
{"node_id": "...", "name": "...", "status": "started"},
{"node_id": "...", "name": "...", "status": "started"}
],
"note": "Start commands sent. Nodes are booting in background. Check node status later."
}
Features:
- Batch start multiple nodes
- No progress bar or wait time
- Immediate API response
- Nodes boot in background after tool returns
- Comprehensive error handling
When to Use Quick vs Regular Start:
| Scenario | Use node_start |
Use start_gns3_node_quick |
|---|---|---|
| Interactive lab startup | ✅ | ❌ |
| CI/CD pipeline | ❌ | ✅ |
| HTTP timeout risk | ❌ | ✅ |
| Need verified status | ✅ | ❌ |
| Automated bulk deployment | ❌ | ✅ |
Implementation Details:
- Calls
POST /projects/{project_id}/nodes/{node_id}/startfor each node - Returns immediately after sending start commands (no progress bar)
- Status reflects command send result, not boot completion
- Source: MCP tool
node_start, adapted viatools_v2/mcp_bridge.py
node_stop
Tool Name: node_stop
Description: Stops one or multiple nodes in a GNS3 project.
Input:
{
"project_id": "uuid-of-project",
"node_ids": ["uuid-of-node-1", "uuid-of-node-2"]
}
Output:
{
"project_id": "...",
"total_nodes": 2,
"successful": 2,
"failed": 0,
"nodes": [
{"node_id": "...", "name": "...", "status": "stopped"},
{"node_id": "...", "name": "...", "status": "stopped"}
]
}
Features:
- Batch stop multiple nodes
- Immediate API response (no waiting)
- Automatic status verification
- Comprehensive error handling
- Synchronous operation
Use Cases:
- Lab shutdown automation
- Resource management
- Energy-saving workflows
- Test cleanup procedures
Implementation Details:
- Calls
POST /projects/{project_id}/nodes/{node_id}/stop - Verifies node existence before stopping
- Retrieves updated status after stop command
- Returns detailed results for each node
node_suspend
Tool Name: node_suspend
Description: Suspends one or multiple nodes in a GNS3 project. Suspended nodes preserve their state in memory and can be quickly resumed.
Input:
{
"project_id": "uuid-of-project",
"node_ids": ["uuid-of-node-1", "uuid-of-node-2"]
}
Output:
{
"project_id": "...",
"total_nodes": 2,
"successful": 2,
"failed": 0,
"nodes": [
{"node_id": "...", "name": "...", "status": "suspended"},
{"node_id": "...", "name": "...", "status": "suspended"}
],
"note": "Suspended nodes preserve their state in memory. Use resume to continue where you left off."
}
Features:
- Batch suspend multiple nodes
- Preserves device state in memory
- Immediate API response (no waiting)
- Fast resume capability
- Automatic status verification
- Comprehensive error handling
Use Cases:
- Temporary lab pause (continue later)
- Save experimental state
- Quick context switching
- Resource optimization without losing work
Key Benefits:
- Fast Resume: Resumes in seconds vs. minutes for full restart
- State Preservation: All configurations, connections, and runtime state saved
- Resource Efficiency: Pauses devices without releasing memory
- Lab Snapshots: Save intermediate states for later analysis
Implementation Details:
- Calls
POST /projects/{project_id}/nodes/{node_id}/suspend - Verifies node existence before suspending
- Retrieves updated status after suspend command
- Returns detailed results for each node
- Node name can be changed while suspended (unlike started state)
State Comparison:
| Operation | Result | Recovery Time | State Preserved? | Resource Usage |
|---|---|---|---|---|
| Stop | Powered off | Slow (full boot) | ❌ No | Minimal |
| Suspend | Paused | Fast (seconds) | ✅ Yes | Medium (memory) |
| Start | Running | N/A | N/A | High |
When to Use Suspend vs Stop:
# ✅ Use SUSPEND when:
# - Taking a break and continuing later today
# - Need to test something else temporarily
# - Want to preserve complex configuration state
# - Quick switching between lab scenarios
# ✅ Use STOP when:
# - Done with the lab for now
# - Need to free up system resources
# - Finishing a complete test session
# - Won't need the lab for a while
Technical Implementation
Module Structure
gns3server/agent/gns3_copilot/tools_v2/
├── mcp_bridge.py # Adapts MCP server tools into LangChain tools (most tools)
├── gns3_create_link.py # Native link_create (port-name resolution)
├── gns3_wait.py # Native wait_seconds (boot wait timer)
├── packet_analysis_tool.py # Native packet_analysis (tshark)
├── device_config_commands.py # Shared runner behind MCP device_config_send
├── device_show_commands.py # Shared runner behind MCP device_show_run
└── vpcs_commands.py # Shared runner behind MCP vpcs_config_set
API Integration
Most tools are generated from the MCP server registration (agent/mcp/__init__.py) by mcp_bridge.adapted_mcp_tools() — the MCP registration is the single source of truth for names, descriptions and argument schemas. Underneath, both the MCP tools and the copilot-native tools call the shared REST handler layer (gns3_copilot.gns3_client.api_handlers):
from gns3server.agent.gns3_copilot.gns3_client.api_handlers import (
build_gns3_ctx,
create_node_handler,
create_link_handler,
get_nodes_handler,
start_node_handler,
stop_node_handler,
suspend_node_handler,
update_node_handler,
)
gns3_ctx = build_gns3_ctx() # JWT + server URL from the request context
# Create node (single POST, batch mode is parallel)
created = create_node_handler(
{"project_id": project_id, "template_id": template_id, "x": x, "y": y, "name": name},
gns3_ctx,
)
# Create link
link = create_link_handler(
{"project_id": project_id, "nodes": [{"node_id": nid, "adapter_number": 0, "port_number": 0}, ...]},
gns3_ctx,
)
# Update node name — the PUT response is the updated node
updated = update_node_handler({"project_id": project_id, "node_id": node_id, "name": new_name}, gns3_ctx)
# Start/stop/suspend nodes (node_ids batch runs in parallel)
start_node_handler({"project_id": project_id, "node_ids": [nid1, nid2]}, gns3_ctx)
stop_node_handler({"project_id": project_id, "node_ids": [nid1, nid2]}, gns3_ctx)
suspend_node_handler({"project_id": project_id, "node_ids": [nid1, nid2]}, gns3_ctx)
# Node listing/status (single call for the whole project)
listing = get_nodes_handler({"project_id": project_id}, gns3_ctx)
Progress Tracking
node_start includes visual progress bar with dynamic wait time:
Starting 3 node(s), please wait...
[===========> ] 35.0%
Wait time is calculated by calculate_startup_time() based on node types (see Dynamic Wait Time Strategy above). No hardcoded duration.
node_start does NOT include progress tracking:
- Returns immediately after sending start commands
- Nodes boot in background
node_stop does not include progress tracking:
- Stop operations are typically fast (< 5 seconds)
- Immediate API response provides status feedback
node_suspend does not include progress tracking:
- Suspend operations are typically fast (< 10 seconds)
- Immediate API response provides status feedback
Node State Transitions
stateDiagram-v2
[*] --> Stopped
Stopped --> Started : start()
Started --> Stopped : stop()
Started --> Suspended : suspend()
Suspended --> Started : start() [resume]
Suspended --> Stopped : stop()
Note: Resuming a suspended node uses
start()— there is no separateresume()method.
State Change Allowed Operations:
| Current State | Can Start? | Can Stop? | Can Suspend? | Can Rename? |
|---|---|---|---|---|
| Stopped | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
| Started | ❌ No | ✅ Yes | ✅ Yes | ❌ No* |
| Suspended | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
*Except special node types: cloud, nat, ethernet_switch, ethernet_hub, frame_relay_switch, atm_switch Note: These special node types are filtered out by template_list and won't appear in template listings for network lab creation.
Copilot Mode Integration
Teaching Assistant Mode
Tools Available:
template_list/template_get- List and inspect device templatesnode_create- Create nodes in topologynode_list/node_get- Inspect nodes (field projection keeps responses small)node_update- Rename nodesnode_start- For diagnostics requiring started nodeslink_create- Create links between nodes (native: port-name resolution)link_list- Inspect linkslink_marker- Traffic-insight markers (highlight matching packets)drawing_create_*- Canvas annotations (text, rectangle, ellipse)device_show_run- Execute show/display/debug commands (READ-ONLY)device_skill_get- Get device-specific skills and command knowledgewait_seconds- Boot wait timerpacket_analysis/packet_analysis_skills- Analyze packets and query protocol knowledge
Capabilities:
- 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/template_get- List and inspect device templatesnode_create/node_update/node_list- Create, rename, inspect nodesnode_start/node_stop/node_suspend- Full lifecycle controlnode_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 (Jinja2 templates supported)vpcs_config_set- Execute VPCS commands using Netmikodevice_skill_get- Get device-specific skills and command knowledgesnapshot_list/snapshot_create/snapshot_delete/snapshot_restore- Project snapshotswait_seconds- Boot wait timerpacket_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 (Jinja2 template batch mode)
- Generic console access for Docker/Linux/VPCS nodes
- Automated workflows with state preservation
- Project snapshot save/restore
Usage Examples
Example 1: Start Nodes with Progress
from gns3server.agent.gns3_copilot.tools_v2 import node_start
tool = node_start()
result = tool._run(json.dumps({"project_id": "abc-123-def", "node_ids": ["node-1", "node-2", "node-3"]}))
# Output includes progress bar and final status
Example 2: Stop Nodes
from gns3server.agent.gns3_copilot.tools_v2 import node_stop
tool = node_stop()
result = tool._run(json.dumps({"project_id": "abc-123-def", "node_ids": ["node-1", "node-2"]}))
# Immediate return with stop status
Example 3: Automated Lab Lifecycle
# Lab deployment
start_tool = node_start()
start_result = start_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
# ... Run tests ...
# Lab shutdown
stop_tool = node_stop()
stop_result = stop_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
Example 4: Lab Pause and Resume
from gns3server.agent.gns3_copilot.tools_v2 import node_suspend
# Start lab
start_tool = node_start()
start_result = start_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
# ... Configure devices ...
# ... Run some tests ...
# Suspend lab (preserves all state)
suspend_tool = node_suspend()
suspend_result = suspend_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
# Nodes suspended - state preserved in memory
# ... Take a break, work on something else ...
# Resume lab (quick recovery)
start_result = start_tool._run(json.dumps({"project_id": project_id, "node_ids": all_node_ids}))
# Back to previous state in seconds!
Example 5: Suspend While Renaming Nodes
from gns3server.agent.gns3_copilot.tools_v2 import node_suspend, node_update
# Suspend nodes first (allows renaming)
suspend_tool = node_suspend()
suspend_result = suspend_tool._run(json.dumps({"project_id": project_id, "node_ids": node_ids}))
# Now rename nodes (possible while suspended!)
rename_tool = node_update()
rename_result = rename_tool._run(
json.dumps(
{
"project_id": project_id,
"nodes": [
{"node_id": "node-1", "new_name": "Router-Primary"},
{"node_id": "node-2", "new_name": "Router-Backup"},
],
}
)
)
# Resume when ready
# Note: Cannot rename while started, but CAN rename while suspended!
Example 6: Get Available Templates 🆕
from gns3server.agent.gns3_copilot.tools_v2 import template_list
tool = template_list()
result = tool._run("")
# Returns all available device templates
# {
# "templates": [
# {"name": "Cisco IOSv", "template_id": "...", "template_type": "router"},
# {"name": "Ethernet switch", "template_id": "...", "template_type": "switch"}
# ]
# }
Example 7: Create Topology Nodes 🆕
from gns3server.agent.gns3_copilot.tools_v2 import node_create
tool = node_create()
result = tool._run(
json.dumps(
{
"project_id": "abc-123-def",
"nodes": [
{"template_id": "uuid-of-router-template", "x": 100, "y": -200},
{"template_id": "uuid-of-switch-template", "x": -200, "y": 300},
],
}
)
)
# Creates two nodes with specified templates and positions
Example 8: Connect Nodes with Links 🆕
from gns3server.agent.gns3_copilot.tools_v2 import GNS3LinkTool
tool = GNS3LinkTool()
result = tool._run(
json.dumps(
{
"project_id": "abc-123-def",
"links": [
{
"node_id1": "uuid-of-node1",
"port1": "Ethernet0/0",
"node_id2": "uuid-of-node2",
"port2": "Ethernet0/0",
},
{
"node_id1": "uuid-of-node1",
"port1": "Ethernet0/1",
"node_id2": "uuid-of-node3",
"port2": "Ethernet0/0",
},
],
}
)
)
# Creates two links connecting the nodes
Example 9: Apply Naming Convention 🆕
from gns3server.agent.gns3_copilot.tools_v2 import node_update
tool = node_update()
result = tool._run(
json.dumps(
{
"project_id": "abc-123-def",
"nodes": [
{"node_id": "node-1", "new_name": "R1-Core"},
{"node_id": "node-2", "new_name": "R2-Core"},
{"node_id": "node-3", "new_name": "S1-Access"},
{"node_id": "node-4", "new_name": "S2-Access"},
],
}
)
)
# Applies consistent naming to all nodes
Example 10: Complete Topology Creation Workflow 🆕
from gns3server.agent.gns3_copilot.tools_v2 import (
template_list,
node_create,
GNS3LinkTool,
node_update,
node_start,
)
# Step 1: Get available templates
template_tool = template_list()
templates = template_tool._run("")
# Find router and switch template_ids...
# Step 2: Create nodes
create_tool = node_create()
nodes = create_tool._run(
json.dumps(
{
"project_id": project_id,
"nodes": [
{"template_id": router_template_id, "x": 0, "y": -200},
{"template_id": router_template_id, "x": 200, "y": -200},
{"template_id": switch_template_id, "x": 100, "y": 0},
],
}
)
)
# Step 3: Connect nodes
link_tool = GNS3LinkTool()
links = link_tool._run(
json.dumps(
{
"project_id": project_id,
"links": [
{
"node_id1": nodes["created_nodes"][0]["node_id"],
"port1": "Ethernet0/0",
"node_id2": nodes["created_nodes"][2]["node_id"],
"port2": "Ethernet0/0",
},
{
"node_id1": nodes["created_nodes"][1]["node_id"],
"port1": "Ethernet0/0",
"node_id2": nodes["created_nodes"][2]["node_id"],
"port2": "Ethernet0/1",
},
],
}
)
)
# Step 4: Apply naming
name_tool = node_update()
names = name_tool._run(
json.dumps(
{
"project_id": project_id,
"nodes": [
{"node_id": nodes["created_nodes"][0]["node_id"], "new_name": "R1"},
{"node_id": nodes["created_nodes"][1]["node_id"], "new_name": "R2"},
{"node_id": nodes["created_nodes"][2]["node_id"], "new_name": "SW1"},
],
}
)
)
# Step 5: Start nodes
start_tool = node_start()
start_result = start_tool._run(
json.dumps({"project_id": project_id, "node_ids": [n["node_id"] for n in nodes["created_nodes"]]})
)
Error Handling
All tools include comprehensive error handling:
Missing Required Fields
{
"error": "Missing required fields: project_id and node_ids."
}
Invalid Input Type
{
"error": "node_ids must be a list."
}
Node Not Found
{
"node_id": "uuid",
"name": "N/A",
"status": "error",
"error": "Node not found"
}
Connection Error
{
"error": "Failed to connect to GNS3 server. Please check your configuration."
}
Security Considerations
Access Control
- All tools respect GNS3's built-in access control
- Requires valid GNS3 server authentication
- Project-level permissions apply
Audit Logging
All operations are logged:
logger.info("Starting %d nodes in project %s...", len(node_ids), project_id)
logger.info("Creating %d nodes in project %s...", len(nodes), project_id)
logger.info("Creating %d links in project %s...", len(links), project_id)
logger.info("Updating names for %d nodes in project %s...", len(nodes), project_id)
logger.info("Stop command sent for node %s (%s)", node_id, node.name)
logger.info("Suspend command sent for node %s (%s)", node_id, node.name)
Mode-Based Restrictions
-
Teaching Assistant Mode:
- Can create topology (templates, nodes, links, names)
- Can start nodes for diagnostics
- Cannot stop, suspend (prevents disruption of active labs)
-
Lab Automation Assistant Mode:
- Can create and manage full topology
- Can start, stop, and suspend nodes (full lifecycle control)
- Complete lab management including state preservation
Performance Characteristics
| Operation | Typical Duration | Wait Time | Progress | State Preserved |
|---|---|---|---|---|
| Get Templates | < 2s | 0s | No | N/A |
| Create Node | < 1s per node | 0s | No | N/A |
| Create Link | < 1s per link | 0s | No | N/A |
| Update Name | < 1s per node | 0s | No | N/A |
| Start (VPCS/IOU) | 15-37s | Dynamic | Yes | N/A |
| Start (QEMU/etc.) | 120-160s+ | Dynamic | Yes | N/A |
| Start Quick | < 2s | 0s | No | N/A |
| Stop | < 5s | 0s | No | ❌ No |
| Suspend | < 10s | 0s | No | ✅ Yes |
Notes:
- Stop operations are significantly faster than start operations
- Suspend is slightly slower than stop but preserves state
- Stop/Suspend do not require progress tracking (immediate feedback)
- Start duration depends on node type (router, switch, PC, etc.)
- Suspend provides fast resume capability compared to full start
- Create node/link operations are fast and require no waiting
- Template retrieval is instant with no parameters needed
Related Documentation
- Chat API - Session management and SSE
- Command Security - Security framework
- LLM Model Configs - Model configuration
Implementation Date: 2026-03-12
Last Updated: 2026-03-14 (Added dynamic wait time calculation based on device types)
Status: ✅ Implemented - Topology management tools available in both modes. Full lifecycle management (start/stop/suspend) available in Lab Automation Assistant Mode
Changelog:
-
2026-03-14 (Evening): Added dynamic wait time calculation
node_startnow calculates optimal wait times based on device types- Fast devices (VPCS: 15s, IOU: 25s) start much faster than before
- Conservative timing accounts for slower hardware environments
- Slow devices (QEMU, Dynamips, etc.) use conservative 120s base time
- Performance improvements: 79-89% faster for VPCS/IOU labs
- Automatic device type detection via
node.node_type - Logs selected strategy and detected device types
-
2026-03-14 (Morning): Added template filtering
template_listnow filters out built-in utility templates (cloud, nat, ethernet_hub, ethernet_switch, frame_relay_switch, atm_switch)- Focuses on network devices suitable for lab configuration
- Logs filtered count for transparency