Skip to main content

​
Agent Not Completing Tasks

Problem: Agent status stuck at “running” indefinitely Quick Diagnostic: Check if agent needs input, task is too complex, or website is down.

​
Diagnose the Issue

async function diagnoseStuckAgent(sessionId) {
  const status = await client.getSessionStatus(sessionId);
  console.log(`Status: ${status.status}`);
  
  const messages = await client.getMessages(sessionId);
  
  const questions = messages.messages.filter(m => m.type === 'QUESTION');
  if (questions.length > 0) {
    console.log(`Agent waiting for answer to: ${questions[questions.length - 1].content}`);
    return 'needs_input';
  }
  
  if (messages.messages.length > 0) {
    const lastMsg = messages.messages[messages.messages.length - 1];
    console.log(`Last message: [${lastMsg.type}] ${lastMsg.content}`);
  }
  
  if (!messages.has_agent) {
    console.log('Agent disconnected!');
    return 'disconnected';
  }
  
  return 'unknown';
}

​
Solutions

The agent is waiting for your response to a question:
const messages = await client.getMessages(sessionId);

for (const msg of messages.messages) {
  if (msg.type === 'QUESTION') {
    console.log(`Q: ${msg.content}`);
    const answer = await getUserInput('A: ');
    await client.sendMessage(sessionId, answer);
  }
}
Break down complex tasks into smaller steps:
// ❌ Don't do this:
// await client.sendMessage(sessionId, "Research 10 companies, compare prices, analyze reviews...");

// ✅ Do this instead:
await client.sendMessage(sessionId, "Research Company A");
await client.waitForCompletion(sessionId);

await client.sendMessage(sessionId, "Research Company B");
await client.waitForCompletion(sessionId);
// ... continue with remaining companies
The target website may be down or blocking requests:
await client.sendMessage(sessionId, `
  Check if example.com is accessible.
  If not, try alternative: backup-site.com
`);
Set a timeout and restart with a simpler task if needed:
try {
  const result = await client.waitForCompletion(sessionId, { timeout: 300000 }); // 5 minutes
} catch (e) {
  if (e.name === 'TimeoutError') {
    await client.cancelSession(sessionId);
    // Restart with simpler task
    await client.sendMessage(sessionId, "Simpler version of the task");
  }
}

​
Agent Returns Incomplete Results

Problem: Agent finishes but doesn’t provide all requested data Solution: Be explicit about completeness requirements 
await client.sendMessage(sessionId, `
    Find prices for Product X on these sites:
    - site1.com
    - site2.com
    - site3.com

    IMPORTANT:
    - You must check ALL three sites
    - If a site is inaccessible, note it clearly
    - Return "NOT_FOUND" for unavailable data
    - Do not skip any sites

    Return as JSON:
    {
        "site1.com": {"price": 99.99, "available": true},
        "site2.com": {"price": null, "available": false, "reason": "Out of stock"},
        "site3.com": {"error": "Site inaccessible"}
    }
`);
Always specify what to do with missing or unavailable data in your instructions. Use explicit lists and require confirmation of completeness.

​
Agent Makes Errors

Problem: Agent provides incorrect information Best Practices:
1

1. Add Verification Steps

Request the agent to verify its findings:
await client.sendMessage(sessionId, `
    Find the price of Product X on amazon.com

    Steps:
    1. Search for "Product X exact name"
    2. Verify it's the correct product (check SKU if available)
    3. Get the price from the main product page
    4. Double-check the price in the cart

    Return the verified price.
`);
2

2. Request Sources

Always ask for source URLs and dates:
await client.sendMessage(sessionId, `
    Research Company A's revenue.

    Include:
    - The revenue figure
    - The source URL
    - The date of the information
    - Whether it's confirmed or estimated

    I will verify the sources.
`);
3

3. Validate Results

Add validation logic in your code:
function validateAgentResult(result) {
  // Check for obvious errors
  if (result.price < 0) {
    throw new Error('Invalid negative price');
  }
  
  if (result.price > 100000) {
    console.warn(`Warning: High price detected: ${result.price}`);
  }
  
  // Verify sources exist
  if (result.source_url && !result.source_url.startsWith('http')) {
    throw new Error('Invalid source URL');
  }
  
  return true;
}

Task Design

Learn how to write effective task instructions

Troubleshooting Home

Back to troubleshooting overview