> Source: https://builder.ema.ai/v2/agent-reference/custom
> Title: Custom Agent

# Custom Agent

The Custom Agent (`custom`) is the fully configurable, general-purpose type. When none of the specialized types fits, you reach for a Custom Agent: you write the Instructions, define the input schema, optionally attach Tools and knowledge bases, optionally declare an output schema, and tune the iteration and budget controls. The platform runs it on the same agentic loop the other LLM-based types use.

A Custom Agent with no extra configuration behaves like a plain responder — it takes the input, follows your Instructions, and returns text. Add an output schema and it returns validated JSON. Add Tools and it can call integrations in a loop, pausing for human input when it needs to. This flexibility is why most one-off and bespoke agents are built as Custom Agents.

The Custom Agent belongs to the **Frequently Used** group in the agent library.

## When to use it

-   The task needs **open-ended reasoning** plus **Tools** — calling integrations, searching a knowledge base, and asking a human, in whatever order the model decides.
-   You want a **structured result** in a shape that isn't classification, extraction, or rule validation.
-   You're prototyping and don't yet know which specialized type fits — start with a Custom Agent and specialize later.

For pure deterministic transformation or programmatic LLM orchestration, prefer the [Code Agent](/builder/v2/agent-reference/code-agent). For dispatching to an external service that implements the logic for you, see [externally dispatched custom agents](#externally-dispatched-custom-agents) below.

## Configuration

You configure the agent through `agent_config.type_config`. Every field is optional — an empty `type_config` is valid.

```json
{
  "instructions": "Summarize the support thread into a one-paragraph status for the account owner.",
  "output_schema": {
    "type": "object",
    "required": ["summary", "needs_followup"],
    "properties": {
      "summary": { "type": "string" },
      "needs_followup": { "type": "boolean" }
    }
  },
  "max_iterations": 15,
  "max_action_calls": 10
}
```

Field

Required

Purpose

`instructions`

No

Additional Instructions appended to the base prompt, wrapped in a clear boundary tag.

`output_schema`

No

When set, the final response must be valid JSON conforming to this schema. When omitted, the agent returns free text.

`retry_on_schema_violation`

No

Whether to retry the model on a schema violation. Defaults to true.

`max_iterations`

No

Per-node override of the agentic-loop iteration budget. Clamped to the platform ceiling.

`max_action_calls`

No

Per-node override of the Tool/action-call budget. Clamped to the platform ceiling.

`max_output_retries`

No

Per-node override of the output-retry budget.

### Iteration controls

The three budget fields above are the Custom Agent's iteration controls. They cap how hard the agentic loop is allowed to work before it must commit to an answer:

-   **`max_iterations`** — how many times the loop may call the model. Default 20, hard ceiling 50.
-   **`max_action_calls`** — how many Tool/integration calls the agent may make across the run. Default 20, hard ceiling 100.
-   **`max_output_retries`** — how many times the agent may self-correct a schema-violating output before failing. Default 2.

Values above the hard ceiling are clamped; negative values are ignored. See the [Agent Reference overview](/builder/v2/agent-reference#loop-and-budget-limits) for the shared defaults and ceilings.

## Inputs and output

Inputs are validated against the node's `input_schema`. `{{input.field}}` placeholders in your Instructions are substituted with input values at run time.

-   **Free text mode** (no `output_schema`): the agent returns the model's text answer as-is. It also receives the common response-formatting guidance (use markdown, embed images inline).
-   **Structured mode** (`output_schema` set): the agent returns validated JSON. The markdown-formatting guidance is suppressed, since the output must be JSON.

## Tools, knowledge bases, and the agentic loop

A Custom Agent can have Tools and knowledge bases attached. They are exposed to the model through the standard agentic loop — the model can call a Tool, get the result, and keep going until it produces a final answer. Knowledge-base search and `ask_human` are themselves exposed as Tools. The built-in `ask_human` Tool lets the agent pause for human input mid-run unless HITL is disabled on the node.

## Validation behavior

-   With no `output_schema`, any text is accepted.
-   With an `output_schema`, the output is unwrapped from any code fence, parsed as JSON, confirmed to be a JSON object, and validated against the schema. On a violation, the agent retries with a corrective prompt (when `retry_on_schema_violation` is on) and otherwise fails the run.
-   If the model emits a text-shaped tool call (a `<tool_call>` block, a `tool_code` fence, or a `tool_calls`/`function_call` envelope in prose) instead of a native tool call, the agent detects it and prompts the model to use the provider's native tool-call mechanism rather than fabricating schema-conforming text.

## Externally dispatched custom agents

A related type, the externally dispatched custom agent (`custom_agent`), **skips the LLM loop entirely** and forwards the node's inputs to an external service that implements the agent's logic. The pre-built agents in the builder's [Custom Agents group](/builder/v2/agent-reference#custom-agents) — the payroll extractors, for example — use this path. Configure it with the agent's ID:

```json
{ "custom_agent_id": "paycom_payroll_extraction" }
```

The platform calls the external service with the tenant, AI Employee, and inputs, and returns whatever output it produces. The set of available custom agents for the current environment is listed via `GET /custom-agents`. Because there is no LLM loop, these runs don't report token usage.

> [INFO]
> **Dispatch-only types.** `custom` and the externally dispatched `custom_agent` are not part of the live/deprecated catalog lifecycle — they are builder-authored or externally dispatched and have no platform-managed versions. See the [Agent Reference overview](/builder/v2/agent-reference#the-agent-type-catalog).

## What's next

-   [Agent Reference overview](/builder/v2/agent-reference) — how agents work, the catalog, the four builder groups, and the shared execution engine.
-   [Code Agent](/builder/v2/agent-reference/code-agent) — run TypeScript that receives typed inputs, calls LLMs, and returns structured output.
-   [Intent Classifier Agent](/builder/v2/agent-reference/intent-classification) — route a workflow by classifying input into labels.