Run an agent retrieval dry run
POST/agents/:agent_id/search
Runs the retrieval placeholders of an agent against the pipeline named in the x-pipeline-id header, without calling an LLM, and returns the fragments that each retrieval placeholder retrieves. The body takes the prompt, classification, path and filters fields of an agent execution. Each placeholder searches the default index of its kind in the pipeline, or, for a similarity or mmr placeholder with embedding, the vector index of that embedding model. A request without path covers only the documents without a path. A client application uses the dry run to test the placeholders, filters and classifications of an agent.
Permissions. Execute on the agent and on the pipeline, and a classification allow-list that covers every classification that the request names.
Agents and prompt templates describes retrieval placeholders, and Filter operators describes the filter language.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 500
An object that maps the name of each retrieval placeholder to the fragments that the placeholder retrieved, in the order of the placeholder's search type. query placeholders do not appear.
The x-pipeline-id header is missing (Header of type `x-pipeline-id` was missing) or is not a valid identifier (Invalid pipeline ID), a placeholder cannot run (Invalid parameter), or a filter does not match the pipeline's metadata schema (Schema error). details.error holds the reason, such as Missing parameter '<name>' when prompt lacks the value that a retrieval placeholder targets, a message that the pipeline has no default text index for a full-text or hybrid placeholder, or Missing embedding model ID for placeholder: <name> for a similarity or MMR placeholder without embedding on a pipeline without a default vector index. The same status reports a body that is not valid JSON.
The authentication headers are missing or invalid, or the API key is inactive or expired. Errors lists the messages.
The license is not valid (Invalid license: <reason>), or a named classification that the pipeline defines is outside the classification allow-list of the key, or the key has an empty allow-list (Unauthorized: execute access to Pipeline required, with the classification named in details.error).
The agent does not exist or the key lacks execute permission on the agent (Agent not found), the pipeline does not exist or the key lacks execute permission on the pipeline (Pipeline not found), a placeholder names an embedding model without a ready vector index in the pipeline (Embedding Model not found), or search_type of the classification object is 1 or 3 and a named classification is not defined in the pipeline (Classification not found).
A search index or a distance index that a placeholder searches is still being built, or the search index failed to build (Conflict, with the reason in details.error).
The body does not match the request schema, for example a path that is not a valid path pattern.
Retrieval failed, for example because the embedding model could not convert the query (Internal server error). The API server log records the cause.