Search Query Planner Agent

The Search Query Planner agent formulates an optimal search query and retrieves in a single pass — it analyzes the request, decides the best query, searches once, and answers. It is the focused, low-latency variant of retrieval: no iterative refine loop, just one well-planned search.

In the AI Employee (AIE) builder, the Search Query Planner Agent appears in the Planning & Resources group of the agent library. It is a preset built on the search_respond base type with the search-iteration budget locked to 1.

When to use it

Use the Search Query Planner when one good search is enough and you want a fast, predictable result:

• Retrieve the most relevant information in a single hop, without the cost of a multi-iteration refine loop.
• Plan a precise query as one step of a larger workflow that handles synthesis or routing downstream.
• Keep latency and token use bounded when the question is well-scoped.

If a single search often won't be enough and the agent should refine and search again, use Knowledge Search or Search and Respond instead — those allow up to 10 iterations.

How it works

The Search Query Planner runs the shared search_respond agentic loop (see Search and Respond for the full retrieval mechanics), but its iteration budget is fixed. The preset sets type_config.max_iterations to 1 and locks it, so the agent plans its query, performs one search, and commits to an answer — it cannot refine and search again.

Its instructions are written around query formulation: it is told to analyze the user request and formulate the single best query to retrieve the most relevant information in one pass. Retrieval, source labeling, and citation work exactly as they do for the other retrieval agents.

Configuration

The Search Query Planner ships with its instructions pre-filled and exposes these advanced settings in the builder:

The defining setting is the locked iteration budget:

The default Instructions are:

You are a search query planner. Analyze the user request and formulate an
optimal search query to retrieve the most relevant information in a single
pass.

User instructions: {{input.instructions}}

Inputs and output

The preset declares one input field, instructions — the information need to plan a search for. You wire it on the node through input_mapping.

Input

{ "instructions": "Find the section of the security policy that covers password rotation requirements." }

Output

{
  "answer": "Passwords must be rotated every 90 days and cannot reuse the last 5...",
  "sources": [
    { "title": "Security Policy 2026.pdf", "uri": "https://..." }
  ]
}

The output is the standard search_respond shape: a synthesized answer plus a sources array of the documents the agent actually used. The response also carries structured cited_sources for richer citation rendering, and the builder node exposes answer and citations output ports.

Example

A retrieval step inside a larger workflow:

1. A Search Query Planner node takes a well-scoped question, plans the single best query, and retrieves the most relevant section from the knowledge base in one pass.
2. A Respond node rewrites the result into a user-friendly reply.
3. A publish node delivers it.

What's next

• Knowledge Search Agent — multi-iteration retrieval from your knowledge base.
• Search and Respond Agent — the general research agent that shares this loop, with the full iteration budget and Tools.
• Agent Reference overview — the type model, catalog, and shared execution engine.