Diagnosing and Fixing Unresponsive AI Agents

When an AI agent suddenly goes quiet, development stops with it. As an indie developer, I lean on Antigravity's agents to handle the routine work across the Dolice Labs sites, and the hardest failure has never been "it crashed" — it's "it threw no error and simply never answered." A crash leaves a trace in the logs; silence leaves you guessing where to even look.

What I want to share here is the order I actually follow to isolate that silence: a five-stage diagnosis — startup, authentication, network, prompt, resources — paired with cause-specific fixes. Once that sequence becomes muscle memory, the next time an agent stalls you can work down the list calmly instead of poking at random.

Problem Classification and Initial Diagnosis

Agent unresponsiveness falls into four main categories:

1. Timeout Issues: The agent takes excessively long to respond or doesn't respond at all
2. Error Logs: Error messages appear but the agent stops functioning
3. Unexpected Behavior: The agent runs but produces unexpected output
4. Partial Failure: In multi-agent setups, only some agents fail to respond

In my experience the real distribution is skewed toward "startup and auth" and "resource exhaustion." A dramatic network outage is far rarer than a .env that didn't load, or a heap that quietly swelled over a long run. That's exactly why working top-down beats trying to guess the cause.

Diagnostic Flowchart for Unresponsiveness

Follow this sequence to isolate the root cause:

1. Is the agent process actually running?
   → Yes: Go to Step 2
   → No: Check startup script errors (see below)

2. Is the API key properly configured?
   → Yes: Go to Step 3
   → No: Reconfigure API key (see below)

3. Is network connectivity normal?
   → Yes: Go to Step 4
   → No: Review network settings (see below)

4. Are there issues with the prompt or context?
   → Yes: Go to Step 5
   → No: Fix the prompt (see below)

5. Is the timeout period sufficient?
   → Yes: Suspect memory leaks or resource exhaustion
   → No: Increase timeout duration

Cause-Specific Solutions

Cause 1: Agent Startup Script Errors

When an agent doesn't launch at all:

Diagnosis:

# Check if agent process is running
ps aux | grep agent
 
# If no output, the agent isn't running
# Check the log file
tail -50 logs/agent.log
 
# Look for patterns like:
# - Node.js version mismatch
# - Missing dependencies
# - Port already in use

Solution:

Verify package installation:

# List installed packages
npm list | grep -E "agent|gemini|langchain"
 
# Reinstall if missing
npm install
 
# Clear cache if needed
npm cache clean --force
npm install

Check for port conflicts:

# See if port 3000 is in use (example)
lsof -i :3000
 
# If it is, change the port in agent.js or .env
# PORT=3001
 
# Or kill the existing process (use with caution)
kill -9 <PID>

Verify Node.js version:

node --version
# Should be v18.0.0 or higher
 
# Use nvm to switch versions if needed
nvm use 20

Cause 2: API Key or Authentication Issues

When the agent can't authenticate to the API:

Diagnosis:

# Check logs for auth-related errors
tail -100 logs/agent.log | grep -i "auth\|401\|invalid"
 
# Verify environment variables load correctly
echo $GEMINI_API_KEY
# Should print your key; if empty, .env isn't loading

Solution:

Reset the API key:

# Confirm .env exists
ls -la .env
 
# Create it if missing
cat > .env << EOF
GEMINI_API_KEY=YOUR_API_KEY_HERE
GEMINI_MODEL=gemini-2-flash
AGENT_TIMEOUT=30000
EOF
 
# Get your key from https://console.cloud.google.com/

Verify key validity:

# In Google Cloud Console, check:
# Console > APIs & Services > Credentials > API Key
# - API restrictions: "Gemini API" selected?
# - Application restrictions: Properly configured?

Test environment variable loading:

// Test in Node.js
require('dotenv').config();
console.log('API Key:', process.env.GEMINI_API_KEY ? 'Set' : 'Not set');
// Should print: API Key: Set

This step is unglamorous, but it's the pitfall I've hit most often. An environment variable that's perfectly visible in your terminal is frequently not inherited by a process you launched in the background, or by a job started from a different shell. When an agent goes silent, the fastest move is to confirm — with the three lines above — that the key is actually visible from that process.

Cause 3: Network and Timeout Issues

When the agent times out waiting for responses:

Diagnosis:

# Test network connectivity
ping google.com
# Success: "64 bytes from..."
# Failure: "ping: cannot resolve"
 
# Test direct API access
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://generativelanguage.googleapis.com/v1beta/models/gemini-2-flash:generateContent
 
# Success: JSON response
# Error: "401" or "403"

Solution:

Increase timeout duration:

// In agent.js configuration
const agent = new Agent({
  model: 'gemini-2-flash',
  timeout: 60000,  // Increase from 30s to 60s
  maxRetries: 3,   // Add retry logic
});

Implement exponential backoff retry:

async function callAgentWithRetry(prompt, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await agent.run(prompt);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
 
      // Wait 2^i seconds before retrying
      const delayMs = Math.pow(2, i) * 1000;
      console.log(`Retry ${i + 1} after ${delayMs}ms`);
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }
}

Configure proxy for corporate networks:

# Add to .env
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1

Cause 4: Prompt or Context Problems

When the agent behaves unexpectedly or responds slowly:

Diagnosis:

# Review past execution logs
tail -200 logs/agent.log | grep -A 5 "Prompt:"
 
# Count tokens (more tokens = slower)
# Generally, 50,000+ tokens causes delays

Solution:

Optimize your prompt:

// ❌ Bad: Too verbose
const prompt = `
You are the world's greatest programmer.
Execute this task perfectly.
Task: Answer the user's question.
Details: The user is a beginner.
...(long explanation continues)
`;
 
// ✅ Good: Concise and specific
const prompt = `
Role: Programming instructor for beginners
Task: Answer the user's JavaScript question
User question: ${userQuestion}
`;

Limit context size:

// Restrict previous conversation history
const agent = new Agent({
  model: 'gemini-2-flash',
  maxContextTokens: 8000,  // Cap history at 8,000 tokens
  contextWindow: 5,         // Keep only last 5 messages
});

Clarify system prompt:

const systemPrompt = `
You are a code review agent. Your responsibilities:
1. Analyze the provided code
2. Identify potential bugs
3. Suggest improvements
4. Provide corrected code
 
Keep responses concise. Use JSON format for structured output.
`;
 
agent.setSystemPrompt(systemPrompt);

Cause 5: Partial Failure in Multi-Agent Setups

When some agents respond while others don't:

Diagnosis:

# Health check each agent
curl http://localhost:3000/health/manager
curl http://localhost:3001/health/worker1
curl http://localhost:3002/health/worker2
 
# Timeouts or 500 errors indicate problems

Solution:

Check inter-agent communication:

// Manager checks worker health
const workerStatus = await manager.checkWorkerHealth();
console.log(workerStatus);
// Output: { worker1: 'healthy', worker2: 'timeout', worker3: 'healthy' }
 
// Auto-restart timed-out workers
if (workerStatus.worker2 === 'timeout') {
  await manager.restartWorker('worker2');
}

Prevent deadlocks:

// Avoid circular dependencies between workers
// ❌ Bad: Worker A waits for B while B waits for A
// ✅ Good: Manager coordinates execution order
 
const result = await manager.executeSequential([
  { task: 'worker-a-task', input: data },
  { task: 'worker-b-task', input: 'result-from-worker-a' }
]);

A Silence Pattern Specific to Antigravity

Beyond the generic diagnosis, once you run Antigravity's Background Agents or Sub-agents you'll meet a kind of silence that fits none of the five categories above. The one I hit repeatedly in real use was an agent running a command that quietly waited for interactive input — a y/n confirmation or an auth prompt — on a terminal I couldn't see. The process was alive and barely touching the CPU, yet the response simply never came, so at first I had no idea what was wrong.

This pattern won't show up in a health check or an error log. The way to spot it is simple: ask whether the command the agent just ran assumes a human at the keyboard. git push (waiting on auth), npm init (an interactive wizard), and package-manager confirmation prompts are the usual suspects. The fix is to attach non-interactive flags (--yes, --no-input, CI=true) to anything you hand the agent from the start. I've written up the durable prevention in "Fixing Antigravity Agents That Hang on Interactive Commands".

Memory Leaks and Resource Exhaustion

When agents work fine initially but become unresponsive after hours:

Diagnosis:

# Launch with inspector
node --inspect agent.js
 
# Visit chrome://inspect in your browser
# Select agent.js from the device list
# Check heap size in Memory tab
 
# Or periodically log memory usage
setInterval(() => {
  const memUsage = process.memoryUsage();
  console.log(`Heap: ${Math.round(memUsage.heapUsed / 1024 / 1024)}MB`);
}, 5000);

Solution:

// Explicitly free resources after each task
async function runAgentTask(input) {
  try {
    const result = await agent.run(input);
    return result;
  } finally {
    // Cleanup
    agent.clearCache();
    gc(); // Force garbage collection (requires --expose-gc flag)
  }
}
 
// Or periodically restart
setInterval(() => {
  if (process.memoryUsage().heapUsed > 500 * 1024 * 1024) {
    console.log('Memory threshold reached. Restarting...');
    process.exit(0); // PM2 or Docker auto-restarts
  }
}, 60000);

When you let agents run for hours as overnight batch jobs, this "swell slowly, then go quiet" failure is the hardest one to catch. In my own setup, the pragmatic choice that proved most stable was the one above: when the heap crosses a threshold, end the process and let the process manager bring it back. For a one-person operation, periodically resetting to a clean state turned out to be far more reliable than chasing every last leak.

Two Cases People Trip Over

Q: The same prompt returns different outputs each time

→ Check the temperature setting. Set it to 0.0 for deterministic output:

const agent = new Agent({
  model: 'gemini-2-flash',
  temperature: 0.0,  // 0 = deterministic, 1.0 = random
});

Q: Agent responses are incomplete or cut off

→ The max_output_tokens might be too small. Try increasing it:

const agent = new Agent({
  maxOutputTokens: 4096,  // Increase from default 1024
});

What to Try Next

When an agent goes quiet, work down the list in order: startup → authentication → network → prompt → resources. More often than not, the cause is somewhere in the first three.

For myself, I keep this sequence as a short checklist in AGENTS.md and open it the moment an agent stalls. The speed at which you find the cause depends less on how much you know and more on whether you've decided, in advance, what order to suspect things in — that's the lesson that has stuck with me from years of building solo. For deeper design work, see "Multi-Agent Production Patterns" and "Agent Memory Patterns".