Search & Respond Agent

The Search & Respond Agent (search_respond) answers a question by searching your knowledge bases, optionally calling Tools, and synthesizing what it finds into a grounded answer with citations. It runs an agentic loop: it searches, looks at the results, decides whether it has enough to answer, and if not refines its query and searches again — up to a configurable number of iterations.

This is the type to reach for whenever an AI Employee needs to answer from documents you've ingested — policies, product docs, support articles — rather than from the model's general knowledge.

The Search & Respond Agent belongs to the Frequently Used group in the agent library. The Knowledge Search and Search Query Planner agents in the Planning & Resources group are presets of this same base type, tuned for retrieval and single-pass query planning.

How retrieval works

When a node has one or more knowledge bases attached, the agent retrieves from them through the search service (RAG). Retrieved chunks are injected into the Instructions with numbered [N] source labels, and the agent is told to answer using only knowledge-base content — if the knowledge base doesn't cover the question, it says so rather than falling back to general knowledge.

When no knowledge base is attached, the agent falls back to a user-specified source if the question names one, or to general knowledge otherwise.

Each retrieved chunk carries its source document title, and the agent is instructed to use the title for relevance — preferring, say, a chunk from a "Germany" policy document when the question is about Germany, even if another country's chunk looks topically similar.

Knowledge base filtering

By default the agent runs an initial retrieval automatically. You can instead enable knowledge base filtering (kb_filtering_enabled), which skips the automatic initial retrieval and requires the model to choose which knowledge base(s) to search on each search_knowledge_base call by passing the relevant labels. Use this when a node has several distinct knowledge bases and you want the model to route each query to the right one. You supply routing guidance through kb_filtering_instructions (for example, "HR questions go to the HR knowledge base, IT questions go to the ITSM knowledge base"), which is injected into the search Tool's description.

Static filters

Each attached knowledge base can carry static filters — folder_filter, tag_node_ids, file_names — that narrow what retrieval considers. When a knowledge base has filters configured, the available filter values are surfaced to the model so it can pass them verbatim when it wants to narrow a search.

The agentic loop and iteration limit

The number of search/refine iterations is configured through type_config.max_iterations:

{ "max_iterations": 5 }

A value of zero or below falls back to the default of 3. The agent is told it may search up to this many times, then must commit to an answer with the information it has. This bounded loop is what prevents a runaway research session while still letting the agent dig deeper when one search isn't enough.

(This is the conceptual search budget surfaced to the model. The shared execution engine also applies its own hard loop and action-call ceilings — see the Agent Reference overview.)

Tools

A Search & Respond Agent can have Tools attached in addition to knowledge bases. Tools are exposed to the model through the same agentic loop; when the model calls one, the agent executes it through the integrations service and feeds the result back. Knowledge-base search and ask_human are themselves exposed as Tools. Image search (search_images) is available when knowledge bases are attached, so the agent can embed diagrams and charts inline in its answer.

Inputs and output

The agent expects the question on the instructions input key.

Input

{ "instructions": "What is our refund policy for annual plans?" }

Output

{
  "answer": "Annual plans can be refunded within 30 days of purchase...",
  "sources": [
    { "title": "Refund Policy 2026.pdf", "uri": "https://..." }
  ]
}

The output's implicit schema in the catalog is:

{
  "properties": {
    "answer": { "type": "string" },
    "sources": { "type": "array", "items": { "type": "object" } }
  },
  "required": ["answer"]
}

Each entry in sources is an object with a title (the document title from a search result the agent actually used) and an optional uri. The agent is instructed to cite only documents that appeared in its search results — the sources array drives the citation chips shown to the user, so accuracy matters. The response also carries structured cited_sources derived from the numbered search results, which the UI uses to render richer citations.

Validation behavior

• The output must be a JSON object with a non-empty answer. A code-fenced response is unwrapped and re-parsed.
• If the response isn't valid JSON at all, the agent wraps the raw text as the answer with an empty sources array rather than failing — so a model that ignores the JSON instruction still produces a usable result.

Notes and limits

• Because search_respond emits structured JSON, it does not use the trailing SOURCES_USED: text marker that free-text agents use; it carries citations in its own sources array instead.
• If you need the answer in a different shape, use a Custom Agent with an output schema, or post-process the answer in a downstream node.

What's next

• Agent Reference overview — how agents work, the catalog, the four builder groups, and the shared execution engine.
• Data Extractor Agent — turn unstructured text into schema-conforming JSON.