> Source: https://builder.ema.ai/v2/agent-reference/search-query-planner
> Title: Search Query Planner Agent

# 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](/builder/v2/agent-reference/knowledge-search) or [Search and Respond](/builder/v2/agent-reference/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](/builder/v2/agent-reference/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:

Setting

Purpose

Instructions

The system prompt. Ships pre-filled with query-planning guidance; edit it to shape how the agent forms its query. Supports `{{input.<field>}}` placeholders.

LLM configuration

The model and generation settings, served through EmaFusion™.

Knowledge bases

Optional. Attach the knowledge bases the planned query searches.

HITL

Optional human-in-the-loop, letting the agent pause to ask a clarifying question via `ask_human`.

The defining setting is the locked iteration budget:

Field

Value

Editable

`type_config.max_iterations`

1

No — locked by the preset.

The default Instructions are:

```text
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**

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

**Output**

```json
{
  "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](/builder/v2/agent-reference/respond) node rewrites the result into a user-friendly reply.
3.  A publish node delivers it.

## What's next

-   [Knowledge Search Agent](/builder/v2/agent-reference/knowledge-search) — multi-iteration retrieval from your knowledge base.
-   [Search and Respond Agent](/builder/v2/agent-reference/search-and-respond) — the general research agent that shares this loop, with the full iteration budget and Tools.
-   [Agent Reference overview](/builder/v2/agent-reference) — the type model, catalog, and shared execution engine.