Custom AI Agents

Waafir ships with five built-in agents — Summariser, Redactor, Reviewer, Organiser, Translator — and the Agents overview explains how they fit together. The same framework is open to you: you can create your own agents on top of it, each with its own instructions, its own model, and its own trigger. Custom agents follow the same review and audit rules as the built-ins, so the platform's guarantees do not weaken when you extend it.

This page is for the admin or owner setting one up.

What a custom agent is

A custom agent is an agent record you define in your organisation. It carries:

• A name and an optional description so the team knows what it does.
• A system prompt — the instructions the AI follows every time it runs.
• A model chosen from the platform's supported list.
• A trigger that decides when it fires (a click, an upload, a schedule, or an API call).
• An active switch you can flip without deleting the agent.

Custom agents are scoped to your organisation. They are visible only to your data rooms and run only against your data; they do not leak across organisations. You can also narrow an agent to a single data room when you create it, so it is available only inside that room.

When to use one

Reach for a custom agent when:

• You want behaviour that the built-in agents don't cover — for example, an agent that produces a single-paragraph board-style summary in your house format, or one that flags a specific category of clause your team always reviews by hand.
• You want a second variant of an existing capability — for example, a strict redactor for investor-shared documents and a lighter redactor for internal drafts.
• You want a focused single-purpose agent your team can run on demand, rather than threading the work into a built-in's prompt.

If you only want to change how a built-in agent talks (its tone, the format of its output, the model it uses), edit the built-in agent's prompt or model in the same Settings tab — don't create a new agent for that. The built-ins are tunable; you do not lose them, you adjust them.

Creating a custom agent

Custom agents live in Settings → AI Agents. The tab lists every agent in your organisation — the built-ins (marked with a lock icon, indicating they can't be deleted) and any custom agents you have created.

To create one, choose Create Custom Agent and fill in:

• Name. Required. How the agent appears in the agents table and in audit records.
• Description. Optional. A one-line note for your team.
• Type. Pick Custom for a genuinely new agent. The five capability types (summarize, redact, review, organise, translate) exist for variants of a built-in capability.
• LLM Model. Choose from the platform's supported models. Capable generalist models suit broad tasks; smaller, faster models suit narrow, high-volume tasks.
• Trigger Mode. When the agent should fire — see the next section.
• System Prompt. Required. The instructions the AI follows. Be specific about the input the agent will see, the output you want, and the format (plain text, JSON, a bulleted list). Vague prompts produce vague output; precise prompts produce results you can rely on.
• Active. Leave on to enable the agent immediately, or off to stage it while you finish writing the prompt.

Save the agent. It appears in the table and is ready to run under its trigger.

Trigger modes

Every agent record carries a trigger mode that records how the agent is intended to fire. The form in Settings lets you set one of four values when you create or edit an agent. Today, two of these are wired end-to-end and two are configuration-only — the field is stored on the agent so the behaviour can be enabled later, but no dispatcher acts on it yet. The list below is honest about which is which.

• Manual. The agent runs when a user — or an admin — starts it explicitly. This is the default, and the right choice for any custom agent today. It is also the only trigger that fires arbitrary custom agents from end to end. Choose this unless you have a specific reason not to.
• On upload. Set this on the built-in Summariser and it fires automatically each time a file is uploaded — that is how the platform's on-upload summarisation works today, and you can edit the Summariser's prompt and model freely while keeping that behaviour. Setting on_upload on a custom agent stores the value but does not register the agent with the upload pipeline yet; if you want on-upload behaviour for a custom task, run it manually for now and watch the changelog for this trigger becoming general.
• Scheduled. A cron-expression field for a recurring run. The value is stored on the agent record; the scheduler that fires agents on their schedule is not yet wired, so setting this today does not cause the agent to run on its own. Use Manual until then.
• Programmatic. A trigger reserved for runs initiated by an external system or pipeline. Setting it stores the value; the open external trigger surface is not yet wired. Use Manual until then.

The trigger decides when the agent runs; it does not change what happens to the agent's output. The review boundary below applies regardless of trigger.

Where you stay in control

Custom agents inherit the same human-in-the-loop principle the built-ins follow.

• Read-only output (such as a summary) can be configured to apply automatically, exactly as the built-in Summariser does — there is no change to a document or to what investors see, so nothing needs approval.
• Anything that changes a document, or what an investor sees, produces a proposal you review before it takes effect. This is not configurable away. A custom redactor still produces a redaction diff you confirm; a custom organiser still produces a folder preview you accept or reject.

This holds regardless of trigger. When the scheduled and programmatic triggers are wired to dispatch on their own, the review boundary will not move — an agent that fires without a click will still produce a proposal a human approves for any change that is destructive or investor-visible.

Permissions

Creating, editing, deleting, and disabling agents is restricted to organisation owners and administrators. Other roles can see the result of an agent run (a summary, a proposal) but cannot reconfigure the agents themselves, and investors never see the agent configuration surface at all.

Custom agents are a paid-plan feature; the option is gated by your subscription.

Audit trail

Every agent run — whether the agent is built-in or custom, and whatever its trigger — is recorded in the same audit trail described in the Agents overview. The record names the agent, the document or scope it ran against, what it proposed, and who approved or rejected the proposal. Custom agents do not get a parallel, looser audit path; they sit inside the same record so the answer to "what did the AI do, and who signed off on it?" is the same regardless of who configured the agent.

System agents versus custom agents

The five built-in agents and any agents you create coexist in the same table, but they are treated slightly differently.

• The built-ins are always present and cannot be deleted. They define the baseline of platform capability. You can disable a built-in (flip its Active switch off) and you can edit its prompt, model, and trigger — but you cannot remove it. This keeps the baseline intact.
• Custom agents are yours to manage. You can edit any field, disable the agent, or delete it outright.

If you find yourself wanting to "replace" a built-in, the right path is to edit the built-in's prompt or model — not to create a custom agent and disable the original. The built-in keeps the baseline; your edits ride on top of it.

Best practice

• Write the prompt before you pick the model. A precise prompt makes a cheaper model usable for tasks you would otherwise need an expensive model for; a vague prompt wastes a capable model.
• Start manual, stay manual today. Manual is the only trigger that fires arbitrary custom agents end-to-end right now. Build and validate your agent on manual runs; the other triggers are honest configuration fields for behaviour the platform will enable later.
• One agent, one job. Several small agents with focused prompts are easier to review and audit than one agent that tries to do everything.
• Disable, don't delete, while iterating. Flipping Active off keeps the agent's history and configuration; deleting throws away both.

Custom agents extend the AI Agents overview — same framework, same review and audit guarantees, your prompts and your triggers.