Agents

Overview

An Agent is a saved configuration that combines an LLM provider, a model, a system prompt, and a set of tools (MCP server tools plus built-in platform tools). Once saved, an agent has a stable ID that the Custom Agent Node in a workflow references.

Think of an agent as a role: "Recon Agent", "Vulnerability Triager", "Phishing Analyst". Each role has a fixed personality (system prompt) and a fixed toolbelt, but accepts a different task (per-run prompt) every time the workflow runs.

Agents live under Automation → Custom Agents → Agents.

Prerequisites

Before you create an agent, make sure you have:

1. At least one Provider registered — see Providers.
2. (Optional) MCP Servers connected if you want the agent to use external tools — see MCP Servers.

If you skip MCP servers, your agent still has access to the five built-in Internal Tools (covered below).

Creating an agent

1. Open Automation → Custom Agents → Agents.
2. Click New agent in the top-right of the list.
3. Walk through the six configuration cards (described below).
4. Click Save agent.

1. Identity

Field	Required	Description
Name	Yes	3–255 characters, must be unique inside your organisation. Shown in the workflow node's agent dropdown.
Description	No	Free-form. Used as context in the workflow builder when picking agents.

2. Intelligence

The provider and model are set per agent and apply to every run — you can't override them inside a workflow.

Field	Required	Description
LLM Provider	Yes	One of the providers registered in your organisation.
Model	Yes	A model from the selected provider's catalogue. The list loads automatically when you pick a provider.

If the model list shows the hint "Models loaded from cache — provider API may be unavailable", the platform couldn't reach the provider's catalogue endpoint and is falling back to a cached list. You can still save the agent; check the provider's dashboard if this persists.

3. System Instructions

Field	Required	Description
System prompt	Yes	The persistent instructions prepended to every run. Defines the agent's role, tone, constraints, and output expectations.

A character counter is shown at the bottom-right of the textarea. There's no hard limit set in the UI — practical limits come from the chosen model's context window.

System instructions are global to this agent. Per-run task instructions are set separately in the Custom Agent Node panel inside the workflow.

4. Execution Parameters

Three sliders/inputs that fine-tune how the model generates responses.

Field	Range	Default	Description
Temperature	0 – 2 (step 0.1)	0.7	0 = deterministic. 2 = highly creative.
Max output tokens	≥ 1	63 000	The hard cap on tokens the model may produce in a single turn.
Max steps	≥ 1	50	The maximum number of reasoning/tool-call steps the agent may take in a single run before stopping.

About max steps. Custom Agents run as a tool-calling loop. The agent thinks, calls a tool, observes the result, thinks again, calls another tool, and so on, until it either finishes the task or hits this cap. Bumping it up gives the agent more room for complex tasks; lowering it limits the worst-case cost per run.

5. MCP Servers

This card is where you give the agent access to external tools.

1. Click Connect MCP Servers. A dialog opens listing every MCP server registered in your organisation.
2. Tick the servers this agent should have access to. Click Confirm.
3. Each selected server shows up as a card with the list of tools discovered on that server.
4. Pick the subset of tools the agent is allowed to call:
   • Tick individual tools, or
   • Use Select all / Clear all at the server card level.
5. To remove a server entirely, click the remove button on the server's card — its tool selections are cleared at the same time.

Best practice — minimum tools. Don't tick every tool from every server. Each tool is described to the model in its system context; giving an agent 40 unrelated tools both inflates token cost and confuses tool selection. Tick only what the agent's role actually needs.

6. Internal Tools

The platform provides five built-in tools that are automatically available to every agent. They are listed for reference in this card and cannot be deselected.

Tool	Purpose
write_output_file	Writes the agent's final structured output. The agent is expected to call this exactly once at the end of its task — it's the primary output mechanism. Output is enforced to be valid JSON.
file_write	Writes arbitrary content (text, markdown, HTML, JSON) to the agent's working directory. Use it for intermediate artefacts or extra reports alongside the main output.
think	Internal reasoning tool. The agent records a thought; it is logged but not visible in the final output. Useful for chain-of-thought without leaking it.
http_request	Makes outbound HTTP requests (GET/POST/PUT/DELETE). Dual-layer SSRF protection blocks private ranges, loopback, link-local, and cloud-metadata endpoints. Response size is capped.
generate_pdf	Renders a themed PDF (themes: blue, red, green, dark) from a structured set of sections (text, bullets, tables, badges). Useful for executive-style report nodes.

7. Output Schema (optional)

You can optionally lock the agent's output to a JSON schema. When set, the agent's write_output_file call must produce JSON that conforms to the schema; the runtime validates it before completing the run.

Field	Description
JSON schema	Standard JSON Schema. Empty = no schema (free-form output). Invalid JSON shows an inline error and prevents save.

Example — for a triage agent:

{
  "type": "object",
  "properties": {
    "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
    "summary": { "type": "string" },
    "remediation_steps": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["severity", "summary"]
}

Use an output schema when the agent's output feeds a downstream integration node or report — it gives you a guarantee on shape.

Editing an agent

Click an agent's row to open its detail page. Every field on the create form is editable. Saved changes apply to the next workflow run; in-flight runs keep using the configuration they started with.

Deleting an agent

From the agent's detail page, click Delete. Workflows that reference the deleted agent will fail at the Custom Agent Node with a clear error until the node is updated to point at a different agent.

What happens at runtime

When a workflow execution reaches a Custom Agent Node, the platform:

1. Loads the agent configuration by ID — provider, model, system prompt, MCP servers, selected tools, output schema, execution parameters.
2. Authenticates to the provider with the encrypted API key.
3. Connects to each associated MCP server (using the server's stored credentials, or the calling user's OAuth token for OAuth MCP servers) and binds the selected tools.
4. Adds the five internal tools.
5. Sends the system prompt + the per-run task prompt to the model and runs a tool-calling loop, capped at max steps.
6. The agent calls write_output_file to write its structured result. The runtime validates the JSON (and the optional output schema) and emits a completion event back to the workflow.

If the agent finishes the loop without calling write_output_file, the runtime nudges it once or twice with a reminder before giving up. This usually means the system prompt didn't tell the model clearly enough to write its final output — add an explicit instruction.

Best practices

• Be explicit in the system prompt about output. Always include something like "When you've completed the task, call write_output_file with the final result as JSON." The nudge loop will catch most omissions, but an explicit instruction avoids the retry cost.
• Match temperature to the role. Triage and structured-extraction agents want low temperature (0.0 – 0.3). Brainstorming or copy-writing agents tolerate higher (0.7 – 1.0). Above 1.0 is rarely useful.
• Keep max_steps snug. Set it 30–50% above your expected worst-case to leave headroom, but don't leave it wide open — a runaway agent can burn through tokens fast.
• Use an output schema for any agent feeding an integration. It makes the downstream step deterministic.
• Iterate on prompts in development workflows. Build a throwaway workflow with the agent and a sample input, run it, inspect the output, refine the system prompt, repeat.

Troubleshooting

Issue	Resolution
Cannot save — name validation fails	Names must be 3–255 characters and unique within your organisation.
Model dropdown is empty	Pick the provider first; if it stays empty, the provider's API key may be invalid.
Cannot save — "Invalid JSON" on output schema	The schema textarea isn't valid JSON. Validate it externally and paste it back.
Agent run finishes but produces no output file	The system prompt didn't tell the agent to call write_output_file. Add an explicit closing instruction.
Agent stops early with "max steps reached"	Bump Max steps — the agent needed more reasoning iterations than allowed.
Tools the agent should have access to aren't appearing in the run	Ensure the MCP server is Connected (for OAuth MCP, the calling user must have authorised) and the relevant tools are ticked in the agent's MCP server card.
Tool calls fail with "permission denied" inside the agent	The MCP server itself rejected the call — check the server's auth or the user's OAuth scope.

Example agents

Recon Agent

• Provider/Model: Anthropic / claude-sonnet-…
• System prompt: "You are a reconnaissance specialist. Given a domain, enumerate subdomains and key infrastructure using the available tools. End by calling write_output_file with a JSON object containing subdomains[] and notes."
• MCP servers: Internal recon MCP server (subset: subfinder, dnsx, httpx)
• Temperature: 0.2
• Max steps: 30
• Output schema: { subdomains: string[], notes: string }

Vulnerability Triager

• Provider/Model: OpenAI / gpt-…
• System prompt: "You are a vulnerability triage analyst. Receive a list of findings, group them by severity, and produce a prioritised remediation plan. End by calling write_output_file with the structured plan."
• MCP servers: Threat-intel MCP (subset: cve_lookup, mitre_lookup)
• Temperature: 0.1
• Max steps: 50
• Output schema: critical/high/medium/low groups with remediation_steps.

Report Writer

• Provider/Model: Anthropic / claude-… (high-context model)
• System prompt: "You are a security report writer. Produce a professional executive-style PDF using generate_pdf (theme: blue). Then call write_output_file with a short JSON summary."
• MCP servers: none
• Temperature: 0.4
• Max steps: 25

Updated: 2026-05-04