Background Agents are part of Caruso’s AI features. AI can make mistakes, so review what an agent has done before relying on it, especially where it has changed data. Every action an agent takes is recorded in the Audit Log.
Background Agents watch for events across your investors and funds, or run on a schedule, and carry out work on your behalf without anyone opening the Manager Console. You write the instructions in plain English, choose what should trigger the agent, and decide which actions it is allowed to take. Caruso runs the agent each time the trigger fires and keeps a record of every run.
Typical uses include triaging new investment applications, chasing missing AML/KYC information, emailing a weekly operations digest to a team lead, or working through a checklist when a batch is created.
How Background Agents Work
Trigger event – what starts a run. Either something that happens in Caruso (for example, an application is received or a checklist is submitted for review) or a recurring schedule
Instructions – what the agent should do when it runs, written in plain language
Allowed GraphQL mutations – the changes the agent is permitted to make in Caruso. Anything not on the list, the agent can read but not change
Runs – each time the trigger fires, Caruso records a run with its status, a summary of what the agent did, and any records it touched
Background Agents operate under their own role, so they can only see and do what that role permits, regardless of who created them.
Step 1: Create a Background Agent
In the top right of the screen, select the Settings (cog) icon, then select Background Agents
Click Add background agent
Enter a Name that describes what the agent does, for example “Application triage” or “Weekly operations digest”
Choose the trigger event
The Trigger event is what starts a run. Every time the event happens in Caruso, the agent runs once with the details of that event, for example the application that was just received. Select how the agent should start:
On an event – select the event from the list. Events are grouped by area, for example Orders, Investing Entities, Tasks, and Checklists. Where the event supports it, a filter field appears so you can narrow the trigger, for example to a single fund or one checklist template. Leave the filter empty to run on every occurrence
On a schedule – set how often the agent runs: daily, weekly, or monthly; the interval; the weekdays or day of month; the time of day; and the timezone. Optionally set an end date. A Schedule summary shows the recurrence in plain English, for example “Every 2 weeks on Monday at 9:00 AM (Pacific/Auckland)”
Note: Scheduled agents follow the wall clock in the timezone you choose, so a 9:00 AM schedule stays at 9:00 AM across daylight saving changes. If a scheduled run is missed, for example during maintenance, it runs once as soon as possible afterwards; it is never skipped or run twice.
Write the instructions
In Instructions, describe what the agent should do each time it runs. Be specific about what to check, what decisions to make, and what to do with the result
Instructions can be up to 50,000 characters, so you can include detailed procedures, examples, and edge cases
Set the allowed GraphQL mutations
A mutation is any action that changes data in Caruso, such as creating a task or updating a record. By default an agent can look things up but cannot change anything. The Allowed GraphQL mutations list is where you grant the specific changes this agent may make.
Under Allowed GraphQL mutations, select each action the agent is permitted to take. Common choices include:
createManualTask – create a task for a team member
setDepositSuggestedMatch – suggest which application a bank deposit belongs to
sendAdminEmailMessage – email an admin user in your organisation
Leave the list empty for a read-only agent that only reports
Click Confirm to save
Important: Grant only the mutations the agent needs. An agent cannot take an action that is not on its list, even if the instructions ask it to. Removing a mutation later takes effect from the agent’s next run.
Emailing Your Team from an Agent
An agent allowed the sendAdminEmailMessage mutation can email any admin user in your organisation, which turns a scheduled agent into a report that lands in someone’s inbox. Emails can only be sent to admin users, not to investors or external addresses. Every email carries a footer stating that it was sent automatically by the named background agent, and each send is recorded in the Audit Log.
Step 2: Review What Your Agents Have Done
Automations page
In the navigation pane, under Home, select Automations
The page shows everything your agents have done, grouped by day. Repeated runs of the same agent are collapsed into a single row; expand it to see each individual run
Use the date range at the top to change the period shown. The default is the last 30 days
Click a run to open its details: the trigger, the agent’s summary of what it did, and a link to the record it worked on
Run history for one agent
Go to Settings → Background Agents and click the agent
The Runs tab lists every run for that agent with its status, start and completion time, and summary
Audit Log
Any change an agent makes to a record appears in the Audit Log with a via Agent badge, in the same way as changes made through the Fund Admin Agent. See Audit Log.
Managing Background Agents
From Settings → Background Agents, click the ellipsis (...) next to an agent to:
Edit – change the name, trigger event, filter, schedule, instructions, or allowed mutations. Changes apply from the next run
Disable or Enable – pause an agent without deleting it. A disabled agent keeps its run history
Delete – remove the agent
Tips
Start read-only. Create the agent with no allowed actions, watch a few runs on the Automations page, then add actions once you trust the summaries
Use a trigger filter rather than instructions to limit scope. “Only for Growth Fund” in the instructions still fires the agent on every event; a filter does not
Have reporting agents email findings only when something needs attention, so the inbox stays useful
Give agents descriptive names. The name appears on every run, in the Audit Log, and in any email the agent sends
Related Articles
If you have any questions or need help at any stage, please contact our Caruso Support team either by email or live chat.