> Source: https://builder.ema.ai/v2/agent-reference > Title: Agent Reference # Agent Reference Agents are the building blocks of every workflow your AI Employee (AIE) runs. An agent is a single node on a workflow — it takes typed inputs from upstream nodes, does one job (routing, answering from a knowledge base, pulling structured data out of text, validating against rules, running code, and so on), and produces a typed output the next node can read. Rather than a fixed catalog of pre-named agents, an agent in ema-next is built from a small set of **configurable base types**. You pick a type, give it Instructions and a JSON Schema for its inputs, attach a Knowledge base or Tools if it needs them, and the platform runs it on a shared execution engine. Some agents are fully configurable (you write the Instructions, schema, and Tools), some are configurable agentic agents (`custom`), and some are custom — dispatched to an external service or a code sandbox. The same handful of types covers the full range of jobs. ## How agents work Every agent runs as a node inside a workflow's directed graph. The workflow engine resolves the node's inputs from the outputs of the nodes wired into it, hands the agent its inline configuration plus those inputs, and reads back the agent's output to pass downstream. - **Typed inputs.** Each node declares an `input_schema` (JSON Schema). Upstream node outputs are wired into the node's inputs through `input_mapping`, referenced with the `{{node_.output.}}` micro-DSL. Input keys are free-form — map upstream outputs to whatever key the agent's Instructions reference; the built-in builder presets default to an `instructions` key. - **A base type.** The node's `agent_config.agent_type` is a stable identifier — `intent_classification`, `search_respond`, `extraction`, `rule_validation`, `respond`, `custom`, `code_execution`, and a few specialized types. The type decides which execution path runs and what output contract applies. - **Per-instance configuration.** `agent_config.system_prompt_template` holds your Instructions; `agent_config.type_config` holds the type-specific configuration (the intents to classify into, the output schema to extract, the rules to validate against, the script to run, and so on). - **A typed output.** Each type produces a documented output shape. Downstream nodes reference its fields by name. Most types run on one shared, stateless execution engine: the workflow service calls the agent service's internal `POST /internal/execute` endpoint with the node's full inline config plus its inputs, and the engine validates inputs, resolves the Instructions, retrieves from any attached knowledge bases, runs the agentic loop against EmaFusion™ and any Tools, validates the output, and returns it. Two types short-circuit this loop: an externally dispatched custom agent (`custom_agent`) is forwarded to an external service, and a [Code Agent](/builder/v2/agent-reference/code-agent) (`code_execution`) is dispatched to the script-executor sandbox. Both skip the LLM loop. ### The agent-type catalog The platform keeps a global catalog of which `(type, version)` pairs exist and what their lifecycle status is. Today every type runs version **`v0`**, and the catalog seeds one live `v0` row per lifecycle-eligible type: `search_respond`, `intent_classification`, `extraction`, `rule_validation`, and `respond`. You can browse the catalog through the read-only `GET /agent-types` endpoint; `GET /agent-types/{type}/{version}` returns the input schema, output schema, and type-config schema a builder needs to construct a valid node. A node may pin a version via `agent_config.base_type_version` — empty, missing, or the legacy integer forms (`0` or `1`) all normalize to `"v0"`. > [INFO] > **Custom types are dispatch-only.** `custom`, the externally dispatched `custom_agent`, `code_execution`, and `document_agent` can run but are not part of the live/deprecated catalog lifecycle — they are builder-authored or externally dispatched, so they have no platform-managed versions. ## The four builder groups In the AI Employee builder, the **Add an Agent** library organizes every agent into four groups. Drop one into the AI Employee builder and it copies the agent's preset configuration inline into the workflow node, where you tailor it. Group What it holds [Frequently Used](#frequently-used) The everyday building blocks — classification, extraction, search, validation, code, and the general-purpose Custom Agent. [Generation](#generation) Agents that produce written output — documents and conversational responses. [Planning & Resources](#planning--resources) Agents that locate, plan, and route — knowledge retrieval, query planning, and feedback routing. [Custom Agents](#custom-agents) Specialized, pre-built agents that dispatch to an external service for deterministic processing. ### Frequently Used The agents you reach for most. Each is documented on its own page. Agent Base type What it does [Intent Classifier Agent](/builder/v2/agent-reference/intent-classification) `intent_classification` Classifies user input into one of the configured intent labels. [Data Extractor Agent](/builder/v2/agent-reference/extraction) `extraction` Extracts structured data from unstructured input using a defined output schema. [Search & Respond Agent](/builder/v2/agent-reference/search-and-respond) `search_respond` Searches knowledge bases and generates a response with sources. [Rule Validator Agent](/builder/v2/agent-reference/rule-validation) `rule_validation` Evaluates input against configured rules and returns a pass/fail verdict with reasoning. [Code Agent](/builder/v2/agent-reference/code-agent) `code_execution` Runs TypeScript in a sandbox: receives typed inputs, can `call_llm` and `log`, and returns structured output. [Custom Agent](/builder/v2/agent-reference/custom) `custom` Fully configurable agentic agent with Tools, output schema, and iteration controls. ### Generation Agents that produce written output. Agent Base type What it does [Document Writer Agent](/builder/v2/agent-reference/document-writer) `document_agent` Generates well-structured documents from provided instructions, with version history and knowledge base research. [Respond Agent](/builder/v2/agent-reference/respond) `respond` Generates a natural-language response using the system prompt and LLM configuration. ### Planning & Resources Agents that locate information, plan retrieval, and route the workflow. Agent Base type What it does Knowledge Search Agent `search_respond` Retrieves relevant sections from your knowledge base, including documents and scraped websites. Search Query Planner Agent `search_respond` Formulates an optimal search query for single-pass information retrieval (search loop locked to one iteration). Feedback Router Agent `feedback_router` Routes the workflow based on user feedback sentiment — positive or negative. Makes no LLM call. The Knowledge Search and Search Query Planner agents are presets of the same `search_respond` base type as the Search & Respond Agent above — they ship with different default Instructions and locked settings tuned to retrieval and planning. See [Search & Respond Agent](/builder/v2/agent-reference/search-and-respond) for the shared mechanics. ### Custom Agents Pre-built, specialized agents that dispatch to an external service rather than running an LLM loop. They are configured for a specific source and produce a deterministic result. Agent Base type What it does [Criteria Expression Builder](/builder/v2/agent-reference/criteria-expression-builder) `custom_agent` Builds structured expression JSON from extraction columns with location data. [Fixed Response Agent](/builder/v2/agent-reference/fixed-response) `custom_agent` Returns a statically configured template string verbatim — no LLM call. [Multilingual Translation Agent](/builder/v2/agent-reference/multilingual-translation) `custom_agent` Translates extraction columns into multiple target languages, appending one new row per target language. [QA Merge Agent](/builder/v2/agent-reference/qa-merge) `custom_agent` Deduplicates and merges question-and-answer pairs using semantic similarity and an LLM. These specialized agents dispatch to the custom-action service rather than running an LLM loop. They share the externally dispatched `custom_agent` path described on the [Custom Agent](/builder/v2/agent-reference/custom#externally-dispatched-custom-agents) page. ## The shared execution model All LLM-based types run on one stateless execution engine. The execute endpoint does **zero database writes** on this hot path, so it scales horizontally with workflow volume. For every LLM-based type the engine does the same sequence: 1. **Validate inputs** against the node's `input_schema`. A misconfigured node fails fast with `422`. 2. **Resolve the Instructions.** `{{input.field}}` placeholders in the system prompt are substituted with input values (wrapped in `` tags as a prompt-injection guard), and the type-specific instruction block is appended. 3. **Retrieve from knowledge bases** (RAG) when any are attached — search results are injected with numbered `[N]` source labels. 4. **Run the agentic loop** — call EmaFusion™ for the LLM completion; if the model calls a Tool (an attached integration, knowledge-base search, or `ask_human`), execute it and feed the result back; repeat until the model produces a final answer or a budget is hit. 5. **Validate the output** against the type's contract. 6. **Return** the output, the token breakdown, and any cited sources. ### Loop and budget limits The loop is bounded so a misconfigured agent can never run away: Limit Default Hard ceiling Notes Loop iterations 20 50 Override per node via `type_config.max_iterations`; clamped to the ceiling. Tool / action calls 20 100 Override via `type_config.max_action_calls`; clamped to the ceiling. Output retries 2 — Override via `type_config.max_output_retries`. For the Search & Respond Agent specifically, the conceptual search-iteration count is configured separately via `type_config.max_iterations` with a default of 3 and a maximum of 10. See [Search & Respond Agent](/builder/v2/agent-reference/search-and-respond). ### Mid-execution human input (HITL) Any LLM-based agent can pause mid-run to ask a clarifying question. The LLM calls the built-in `ask_human` Tool; the agent service calls back to the workflow service, which creates a human-in-the-loop request and pauses the run. When the person responds, the workflow service calls the agent's resume endpoint (`POST /internal/resume-execute`) and execution continues with full context. A node with HITL disabled has `ask_human` removed from its Tool list. ### Long-running async execution Read-only, long-running types (Extraction, Rule Validation, and opt-in custom agents) can run asynchronously via `POST /internal/execute-async`. The agent returns a job envelope (`job_id`, signed continuation token, `expires_at`, `cancel_url`) immediately and runs the work in the background on the same execution engine, posting the terminal result back to the workflow service. Intra-agent HITL is not allowed on the async path. ## Output validation Each type validates the model's final response against its own contract before returning it. When the model makes a recoverable mistake (malformed JSON, a missing field, a score outside the allowed set), the engine feeds a corrective prompt back to the model and retries within the output-retry budget rather than failing the run. Type Output shape Validation `intent_classification` `{"intent": "