Skip to main content

AI Agent Backend Issues

This document tracks known backend issues with the AI Agent API at ai-dev.aiqlick.com.

1. Document Registration Failure​

Status: ❌ Unresolved (Backend Issue)

Symptom:

  • File uploads to S3 succeed
  • Document registration with AI API fails with generic message: {"success": false, "message": "Failed to create document"}

Impact: Documents cannot be added to agent knowledge base

Frontend Implementation: ✅ Complete and correct

  • Presigned URL upload flow implemented
  • Correct S3 bucket/key parsing
  • Proper mutation input format: s3://bucket/key

Next Steps: Backend team needs to investigate AI API logs

2. Tool Call Validation Error (Conversation History Bug)​

Status: ❌ Unresolved (Backend Issue)

Symptom: AWS Bedrock validation error when agent tries to use tools (especially RAG_SEARCH):

ValidationException: The number of toolResult blocks at messages.4.content
exceeds the number of toolUse blocks of previous turn.

Root Cause: The AI Agent backend is incorrectly formatting conversation history when sending to AWS Bedrock Converse API. The history contains mismatched tool use/tool result blocks.

When It Occurs:

  • Agent attempts to use RAG_SEARCH tool
  • Multi-turn conversations with tool calls
  • Typically appears after the first or second tool execution

Example Error Flow:

{
  "id": "40e26e1b",
  "messageId": "803a9aa4-5ea3-4c13-b1ea-27d7283c0cef",
  "content": "<thinking>To provide information on the latest jobs, I need to search the company knowledge base...</thinking>\n",
  "inputTokens": 0,
  "outputTokens": 0,
  "totalTimeMs": 1323
}

{
  "id": "2f4a5292",
  "status": "INITIALIZING",
  "message": "Initializing chat session..."
}

{
  "id": "2f4a5292",
  "code": "CHAT_ERROR",
  "message": "An error occurred (ValidationException) when calling the ConverseStream operation: The number of toolResult blocks at messages.4.content exceeds the number of toolUse blocks of previous turn.",
  "recoveryHint": "Try sending your message again"
}

AWS Bedrock Requirements:

  • Each toolUse block must have exactly one corresponding toolResult block
  • Tool results cannot exceed tool uses
  • Conversation history must maintain strict message structure:
    • User message
    • Assistant message with toolUse blocks
    • User message with toolResult blocks (system-generated)
    • Assistant message with final response

Frontend Workaround: ✅ Implemented

  1. Error Detection:

    • Frontend detects tool validation errors in chat events
    • Provides user-friendly error message
    • Shows recovery hint

  2. Error Recovery UI:

    • "Start a new conversation" button appears in error banner
    • Allows user to clear conversation history and continue
    • Located in ChatModal.tsx:442-455

  3. Improved Error Messages:

    • Original: Raw AWS validation error
    • Improved: "Conversation history error occurred. This is a known backend issue with tool calls."
    • Recovery hint: "Click 'Start a new conversation' button below to continue chatting."
    • Located in useAIAgentChat.ts:292-304

User Impact:

  • Conversations with tool calls may fail after 1-2 turns
  • Users must start new conversations to continue
  • Each conversation limited to single-turn interactions until fixed

Backend Fix Required:

The backend team needs to:

  1. Review conversation history construction in the agent chat resolver
  2. Ensure tool use/result blocks are properly paired
  3. Validate conversation format before sending to Bedrock
  4. Add logging to track tool block construction
  5. Consider these potential issues:
    • Duplicate tool results being added
    • Tool results from previous conversations being included
    • Incorrect message role assignment for tool results
    • Tool result blocks not being properly associated with tool use blocks

Testing After Backend Fix:

  1. Start a conversation with an active agent
  2. Ask a question that triggers RAG_SEARCH: "What are the latest jobs?"
  3. Verify the agent successfully:
    • Initiates tool call
    • Receives tool results
    • Generates final response with retrieved context
  4. Send multiple follow-up questions requiring RAG
  5. Verify multi-turn conversations work without validation errors

Frontend Implementation Status​

✅ Completed Integrations​

  1. Agent Selection

    • Dropdown in chat modal
    • localStorage persistence
    • Auto-selection of first active agent

  2. Conversation Management

    • Auto-create conversation on modal open
    • Agent status validation (ACTIVE check)
    • New conversation button

  3. Streaming Chat

    • WebSocket subscription
    • Real-time message streaming
    • Event type inference when __typename missing

  4. Error Handling

    • Tool validation error detection
    • User-friendly error messages
    • Recovery UI (new conversation button)

  5. Document Upload

    • Presigned URL flow
    • S3 upload with progress
    • Correct bucket/key extraction
    • Proper mutation input format

❌ Blocked by Backend​

  1. Document Registration

    • Frontend complete
    • Backend returns generic failure

  2. Multi-turn Tool Conversations

    • Frontend complete
    • Backend conversation history formatting broken

🔄 Ready for Testing (After Backend Fixes)​

  • End-to-end chat with RAG
  • Multi-turn conversations with tool calls
  • Document upload to knowledge base
  • Agent responses using uploaded documents

Communication with Backend Team​

Issue #1: Document Registration

Issue #2: Tool Validation

  • Endpoint: WebSocket subscription to agentChat
  • Error source: AWS Bedrock Converse API
  • Needs: Conversation history formatting review
  • Impact: All RAG-based conversations fail

Last Updated: 2026-02-08