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. For dispatching to an external service that implements the logic for you, see 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.

{
  "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
}

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 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 — the payroll extractors, for example — use this path. Configure it with the agent's ID:

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

What's next

• Agent Reference overview — how agents work, the catalog, the four builder groups, and the shared execution engine.
• Code Agent — run TypeScript that receives typed inputs, calls LLMs, and returns structured output.
• Intent Classifier Agent — route a workflow by classifying input into labels.