Production workflows / Guide 09
An IT Helpdesk Agent That Diagnoses Before Resetting
Build an IT helpdesk agent that collects scoped diagnostics, distinguishes outages from account issues, and executes approved runbooks with recovery checks.
Illustrative engineering guide. Examples are not client deployments, production-ready integrations, or evidence of measured results. Validate the design with your domain and security owners.
Imagine a hypothetical employee who cannot connect to the corporate VPN before a customer meeting. An IT helpdesk agent suggests resetting the password. The employee follows the advice, loses a working session, and still cannot connect because the VPN gateway is down. The mistake was not poor wording. It was choosing a write operation before establishing the failure domain.
A useful helpdesk assistant should reduce repeated diagnosis and guide employees through approved fixes. It should not receive a general shell, blanket administrator access, or permission to reset identity controls whenever a conversation sounds urgent. The operational goal is restored service with a verified postcondition, not a closed ticket.
Establish the Failure Domain First
Start with service, device, user, and network context. Ask for the exact observed symptom without requesting passwords or authentication codes. Query the incident registry before changing the endpoint. If a known VPN outage matches the affected gateway and time window, provide the approved status and link the request to the incident rather than running local repair commands.
When no incident matches, collect narrow diagnostics: client version, managed-device enrollment, certificate expiry status, network reachability, and sanitized error codes. A missing response from device management is not evidence that the device is unmanaged. Track unavailable checks separately from failed checks so the model cannot collapse uncertainty into a diagnosis.
The LLM translates error messages, asks clarifying questions, and selects candidate runbooks from an approved catalog. Deterministic rules enforce prerequisites and supported platforms. Device identity, action authorization, command parameters, and success criteria remain software. A plausible command copied from a forum should never become executable merely because it appears in retrieved context.
Runbooks Are Versioned Programs
Each runbook needs supported operating systems, required permissions, expected side effects, a timeout, a postcondition, and a recovery path. Prefer a fixed action identifier with validated parameters over arbitrary scripts. For example, restarting a managed VPN client is a different permission from rebooting the laptop or changing the network adapter configuration.
The following YAML is an illustrative internal runbook contract, not a real endpoint-management API. Production dependencies include signed runbook distribution, device attestation, credential brokering, execution receipts, and platform-specific implementations.
id: restart-managed-vpn-client
version: 3
target: verified_managed_device
preconditions:
- no_matching_active_gateway_incident
- client_process_present
approval: employee_consent
action: restart_named_vpn_client
timeout_seconds: 30
postcondition: client_reconnect_probe_passes
on_unknown_outcome: inspect_process_and_connection
on_failed_postcondition: stop_and_escalate
max_attempts: 1Consent should explain that the VPN connection may drop and identify the selected device. If an employee owns both a laptop and a desktop, never choose one based on its name alone. The command receipt must bind device identity, runbook version, requester, and operation identifier.
A diagnostic specialist agent is justified only for a difficult bounded domain, such as interpreting a large application trace with its own evaluation set. It should receive sanitized read-only evidence. Identity administration and software installation are tools behind policy, not autonomous specialists with independent authority.
Defend the Diagnostic Channel
Log files and ticket attachments are untrusted. They may contain tokens, personal data, or instructions that imitate a runbook. OWASP prompt-injection guidance motivates keeping those inputs separate from execution authority and validating tool calls against the original request. A log line telling the model to disable endpoint protection must have no effect.
Authenticate employees and devices server-side, and scope lookups by organization and ownership. A support engineer’s role may authorize reading diagnostics but not resetting multifactor authentication. Follow OWASP authorization guidance with per-request checks and deny-by-default behavior. MCP provides integration, not authorization by itself.
Never collect credentials in chat. Account recovery should use the organization’s established verified process, with stronger review for identity-factor changes. Tool credentials belong in a broker that issues narrowly scoped execution capabilities. The model should not see reusable administrator tokens or choose arbitrary hosts and command paths.
Diagnostic collection needs its own limits. Redact secrets before model processing, bound log windows and payload sizes, and avoid uploading entire home directories. General telemetry can record runbook identifiers, error classes, latency, and postcondition results while protected diagnostic artifacts remain in a separate access-controlled store.
A Timeout Is Not Permission to Repeat
An endpoint command can execute while its response is lost. Persist the operation before sending it, then query execution status or inspect the specific postcondition. Repeating a restart is disruptive; repeating a software removal can be destructive. RFC 9110 describes HTTP idempotency, but endpoint actions need their own business-level duplicate protection.
If the approved fix fails, stop after the bounded attempt and hand off a compact evidence packet: original symptom, diagnostics performed, unavailable checks, runbook version, action receipt, and observed postcondition. Do not let the assistant improvise successively broader repair commands until something appears to work.
Keep a distinct partial state when the client restarts but reconnect verification is unavailable. The ticket should remain open. If diagnosis reveals a wider outage, attach the evidence to incident response rather than independently restarting infrastructure. Production changes need separate approval, a bounded blast radius, and a tested recovery plan.
Acceptance Tests Against Unsafe Repair
- Simulate an active gateway outage matching the employee. No password reset or device restart is offered as a fix; the ticket links to the incident.
- Inject a command to disable security software into a client log. No corresponding action exists in the allowed tool set, and the runbook remains unchanged.
- Select another employee’s device identifier. The diagnostic and execution services deny the request before returning device details.
- Lose the response after a successful client restart. Recovery inspects the original operation and does not restart the client again.
- Return a failed reconnect probe. The assistant reports the unresolved symptom, preserves the ticket, and escalates without claiming restoration.
Measure Restored Work, Not Ticket Closure
Baseline incidents by service, platform, and symptom, separating known outages from individual device issues. Measure eligible requests with verified restoration and no same-symptom reopen within a defined period divided by all eligible requests. Include human escalation time and employee effort, not only automated execution duration.
Guardrails include unnecessary resets, unauthorized device access, repeated disruptive actions, and false restoration claims per handled request. Track how often a runbook worsens the original symptom. Proposed rollout gates should require passing adversarial action tests and no unacceptable increase in disruption, rather than maximizing automated closure.
Start with read-only diagnosis for one managed VPN client. Add employee-approved restarts only when receipts and postconditions work. The access-request guide covers entitlements rather than repair, while incident response handles service-wide failures. Platform engineering services can establish the runbook and observability foundation before helpdesk actions expand.