Test Retrieval

Test knowledge retrieval with a query to see what the agent would find.

POST/knowledge/test-retrieval

Run a similarity search against an agent's knowledge base. Returns the most relevant chunks.

No parameters for this endpoint.


Request Body

FieldTypeRequiredDefaultDescription
agent_idstringYesThe agent's public ID (ag_*)
querystringYesThe search query (natural language question)
top_kintegerNo5Number of most relevant chunks to return (1–20)

Response 200

{
  "results": [
    {
      "content": "Our return policy allows returns within 30 days of purchase. Items must be unused and in original packaging.",
      "source_name": "Return Policy",
      "source_type": "text",
      "similarity_score": 0.94,
      "chunk_index": 0
    },
    {
      "content": "Refunds are processed within 5-7 business days after we receive the returned item.",
      "source_name": "Return Policy",
      "source_type": "text",
      "similarity_score": 0.87,
      "chunk_index": 1
    },
    {
      "content": "Exchanges can be made for items of equal or lesser value. Price differences are refunded to the original payment method.",
      "source_name": "FAQ Document",
      "source_type": "text",
      "similarity_score": 0.72,
      "chunk_index": 3
    }
  ],
  "query": "What is your return policy?",
  "total_results": 3
}

Response Fields

FieldTypeDescription
resultsarrayRanked list of matching chunks
results[].contentstringThe text content of the chunk
results[].source_namestringName of the knowledge source
results[].source_typestringSource type (text, url, file, etc.)
results[].similarity_scorefloatCosine similarity (0.0–1.0). Higher = more relevant
results[].chunk_indexintegerPosition of this chunk within its source
querystringThe original search query
total_resultsintegerNumber of results returned

Use Cases

  • Debug retrieval quality: Verify that the right content is being found for specific questions
  • Tune chunk size: Check if chunks are too large (low relevance) or too small (missing context)
  • Validate knowledge: Confirm that newly added sources are indexed and retrievable

Errors

CodeDescription
401Missing or invalid authentication
404Agent not found or no knowledge sources attached

On this page