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_<id>.output.<field>}} 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 (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".

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.

Frequently Used

The agents you reach for most. Each is documented on its own page.

Generation

Agents that produce written output.

Planning & Resources

Agents that locate information, plan retrieval, and route the workflow.

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 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.

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 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 <user_input> 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:

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.

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.

Error codes

When an agent fails, the agent service returns a structured error code. The workflow engine mirrors each code's retryability onto the streaming error it shows the user — codes marked retryable below surface a "retry" affordance because retrying is confidently safe.

What's next — the Frequently Used agents

• Intent Classifier Agent — route a workflow by classifying input into labels.
• Data Extractor Agent — turn unstructured text into schema-conforming JSON.
• Search & Respond Agent — answer from knowledge bases and Tools with citations.
• Rule Validator Agent — validate documents and data against business rules.
• Code Agent — run TypeScript that receives typed inputs, calls LLMs, and returns structured output.
• Custom Agent — build a general-purpose agentic agent with Tools, an output schema, and iteration controls.