Grounding the Autonomous Agent: Building an Evidence-Driven Diagnostic Layer for LLM Fleet Management

Introduction

In the development of autonomous AI systems, few challenges are as consequential as preventing an agent from making destructive decisions based on speculation rather than evidence. This tension — between granting an agent sufficient autonomy to act decisively and constraining it with safeguards against catastrophic mistakes — lies at the heart of a pivotal message in an opencode coding session: message 4921, where an assistant tests a newly built diagnostic grounding system for an LLM-driven fleet management agent.

The message is deceptively brief — a status report followed by a single bash command that times out — but it represents the culmination of a significant architectural pivot. The assistant had been building an autonomous agent to manage a fleet of GPU proving instances on vast.ai, and the agent had suffered a critical production failure: it misinterpreted active=False and stopped all running instances despite 59 pending tasks, because the demand signal could not distinguish "no demand" from "all workers dead with tasks queued." The fix was not to add more hard-coded rules, but to build a diagnostic sub-agent system that forces the main agent to ground itself in facts before taking destructive actions.

The Message: A Validation Test

The subject message reads in full:

Both work: - 33034145: SSH unreachable but has rich fallback data (state: params_done, registered 19:22, vast status running) - 33034189: SSH reachable, shows processes (entrypoint, benchmark running), entrypoint log showing param download at 99%

>

Now let me test the full stop_instance grounding check: ```bash ssh theuser@10.1.2.104 " # Try to stop without diagnosing first — should be rejected echo '=== Stop without diagnosis (should fail) ===' curl -sf -X POST http://127.0.0.1:1236/api/agent/stop -H 'Content-Type: application/json' -d '{\"vast_id\": 33034145, \"reason\": \"test\"}' " 2>&1 === Stop without diagnosis (should fail) ===

> >

<bash_metadata> bash tool terminated command after exceeding timeout 10000 ms </bash_metadata>

The message accomplishes two things. First, it reports successful validation of the diagnostic endpoint itself, confirming that both the SSH-reachable path (direct process inspection, log reading) and the SSH-unreachable fallback path (vast API data, manager database state) produce useful diagnostic information. Second, it attempts to test the critical gating mechanism — the precondition that stop_instance requires a prior diagnose_instance call — and that test times out.

The Architecture of Diagnostic Grounding

To understand why this message matters, we must understand the architecture it validates. The diagnostic grounding system consists of three layers:

Layer 1: The Go Diagnostic Endpoint (GET /api/agent/diagnose/{vast_id}). This endpoint attempts to SSH into a vast.ai instance and collect process lists, entrypoint logs, daemon logs, memory usage, and GPU state. When SSH fails (as it does on many instances due to broken SSH setups), it falls back to data from the vast.ai API and the local manager database, returning instance state, registration time, and status information. Crucially, the fallback includes a note: "SSH failed. Diagnosis based on vast API + manager DB only. Some instances have broken SSH setup — this does NOT mean the instance is unhealthy." This note is a guard against the very speculation the system was designed to prevent — the sub-agent must not conclude an instance is unhealthy simply because SSH is broken.

Layer 2: The Python Sub-Agent (diagnose_instance tool). This tool calls the diagnostic endpoint, then sends the raw data to an LLM sub-agent that interprets it with domain knowledge about normal startup sequences versus actual failures. The sub-agent returns a structured verdict: whether the instance is healthy, what issues exist, and what action (if any) is recommended.

Layer 3: The Precondition Gate on stop_instance. The stop tool returns HTTP 428 (Precondition Required) unless a diagnosis was performed within the last 15 minutes. This shifts the architecture from brittle hard-coded rules (e.g., "don't kill instances younger than X hours") to an evidence-driven, LLM-powered diagnostic layer. The agent is free to make any decision — but only after it has grounded itself in facts.## Why This Approach Was Necessary

The user's directive was clear and came from painful experience: "Noo it is fine that the agent may destroy shorter running instances, it just needs to ground itself in truth first and never speculate whether instance state is bad or not." This instruction (see [msg 4894]) encapsulates a profound insight about autonomous agent design. The problem with the earlier approach — adding hard time-based guards that prevented the agent from killing young instances — was that it treated the symptom rather than the cause. The agent wasn't making bad decisions because it was too aggressive; it was making bad decisions because it was reasoning from incomplete information and filling the gaps with speculation.

The assistant initially attempted a time-based guard, but the user correctly redirected the approach. The resulting architecture is philosophically different: instead of constraining the agent's actions, it constrains the agent's epistemic state. The agent must know, not guess. This is a distinction that has deep parallels in robotics (the "sense-plan-act" paradigm), in safety engineering (the "defense-in-depth" principle), and in epistemology (the difference between knowledge and mere belief).

The SSH Fallback: A Lesson in Real-World Infrastructure

The SSH fallback mechanism tells a story about the gap between idealized infrastructure and production reality. The vast.ai instances had "messed up SSH setup" — some were reachable, some were not, and the reason was not a missing SSH key (the key was properly configured on vast.ai) but something broken in the instance's SSH configuration itself. This is the kind of frustrating, non-deterministic failure mode that plagues distributed systems: SSH works on some instances, fails on others, and the root cause is opaque.

The assistant's response was pragmatic. Rather than trying to fix SSH on every instance (an impossible task when instances are ephemeral and provisioned by a third-party platform), the diagnostic endpoint was designed to degrade gracefully. When SSH fails, it returns fallback data from the vast API and the local database — information that is less rich than direct process inspection but still useful for determining whether an instance is healthy. The sub-agent prompt was updated to handle this case explicitly, instructing the LLM to be conservative when data is incomplete: "If SSH is unreachable, do NOT assume the instance is unhealthy — it may just have a broken SSH setup."

This design choice reflects a mature understanding of production systems. Perfect observability is rarely achievable; the goal is not to have perfect data but to make sound decisions with imperfect data, while being explicit about the limitations of that data.

The Timeout: An Unresolved Thread

The bash command in the message times out after 10 seconds. The stop_instance endpoint, which should have returned immediately with a 428 rejection, instead hung until the tool was killed. This timeout is itself informative: it suggests that the precondition gate may not have been working correctly, or that the endpoint was blocking on some other resource (perhaps a database lock or a network call). The message does not resolve this — the assistant would need to diagnose the timeout in a subsequent round.

This unresolved thread is characteristic of real development work. Not every test passes cleanly; not every validation succeeds on the first attempt. The message captures a moment of verification that is partially successful (the diagnostic endpoint works for both SSH paths) and partially inconclusive (the grounding gate test times out). The reader is left with the understanding that the system is almost working, but a subtle bug remains.

Input Knowledge Required

To fully understand this message, one needs knowledge of several domains:

Output Knowledge Created

This message produces several pieces of knowledge:

  1. Validation of the SSH-reachable diagnostic path: Instance 33034189 is reachable and returns useful process and log data (entrypoint running, benchmark running, param download at 99%).
  2. Validation of the SSH-unreachable fallback path: Instance 33034145 returns fallback data including DB state (params_done), registration time, and vast status (running), with an explicit note that SSH failure does not imply instance unhealthiness.
  3. Evidence of a potential bug: The stop_instance endpoint times out when called without a prior diagnosis, suggesting the precondition gate may have a blocking issue.
  4. Confirmation of the architecture's viability: The diagnostic system can handle both SSH-reachable and SSH-unreachable instances, providing the sub-agent with useful data in either case.

The Thinking Process

The assistant's reasoning in this message is concise but reveals several layers of thought:

First, the assistant reports success on both diagnostic paths, establishing that the foundation is solid. The choice to test two instances — one reachable and one unreachable — shows systematic thinking: both edge cases must be validated.

Second, the assistant proceeds to test the grounding gate. The command is structured as a clear hypothesis: "Try to stop without diagnosing first — should be rejected." The expected outcome is a 428 status code. The fact that the command times out rather than returning a result is itself a result — it tells the assistant (and the reader) that something is wrong with the gate implementation.

The timeout is particularly interesting because it suggests a blocking operation in the stop_instance handler. In a well-designed system, a precondition check should be fast — it's just a database query to check whether a recent diagnosis exists. A 10-second timeout suggests either a database lock, a network call that blocks, or an infinite loop. The assistant does not speculate on the cause in this message, but the timeout is noted for subsequent investigation.

Conclusion

Message 4921 captures a pivotal moment in the development of an autonomous fleet management agent. The diagnostic grounding system — built in response to a catastrophic production failure — is validated for both SSH-reachable and SSH-unreachable instances, but the precondition gate that prevents the agent from acting without evidence shows signs of a blocking bug. The message is a testament to the complexity of building reliable autonomous agents: every layer of the system must be tested, every edge case must be handled, and even well-designed architectures can harbor subtle bugs that only emerge under test conditions.

The deeper lesson is about the relationship between autonomy and safety. The diagnostic grounding system does not constrain the agent's actions — it constrains the agent's knowledge. The agent is free to stop any instance, but only after it has gathered evidence and reasoned about that evidence through a dedicated sub-agent. This is a fundamentally different approach from hard-coded rules, and it represents a more mature understanding of how to build AI systems that can be both autonomous and trustworthy.