Create & Manage Your AI Agents

Overview

Set up AI agents that react to activity in your projects and create tickets, add comments or send emails on their own, based on instructions you write.

An agent is made of four parts, and they do different jobs:

• Instructions tell the agent what to do, in your own words and in as much detail as you like. This is where the real work is described.
• Triggers decide when the agent starts checking. They do not decide whether it acts.
• Actions set the boundary of what the agent is allowed to do. They do not decide what it does.
• Project is the single project the agent watches, and the only data it can read.

Triggers and actions draw the frame; the instructions do the work inside it. For example, to have an agent comment when a ticket is resolved, give it the trigger Ticket updated so that it checks every time a ticket changes, and write in the instructions that it should only act when the status becomes Resolved.

These are the events an agent can use as triggers:

• Ticket created
• Ticket updated
• Comment added to ticket
• File uploaded (in Documents)
• New file version (in Documents)

An agent always reads the tickets and documents of its project to find the information it needs. It runs with the permissions of the user who created and owns it. Keep that in mind in case you have confidential information in tickets or documents and be clear in the instructions about what the agent should do and share and what not.

These are the actions an agent can be allowed to take:

• Create ticket
• Add comment (in a ticket)
• Send email (to project members)

Everything an agent creates carries its name: a ticket or comment it writes shows the agent's name on behalf of the person who created the agent. Read more in Recognise Work Done by AI Agents.

You can also set account-wide global instructions that apply to every agent, and control agent notifications for the whole account. Read more in Configure AI Agents for your Account.

Not supported in the current version:

• Changing or deleting existing tickets, documents or plans. An agent only ever creates.
• Running on a schedule. An agent only reacts to events in its project.
• Working across several projects. Each agent runs in exactly one project — create one agent per project you want covered.
• Emailing people outside the project. Emails can only be sent to project members.

This feature consumes your AI usage limit. Read more in AI Usage Limits and Upgrades.

Read more about Privacy & Security for AI Features.

How to Access AI Agents

1. Click AI Agents

You see the agents of your account:

Create an Agent

An agent needs four things before it can run: instructions, a project, at least one trigger and at least one action. Until they are all in place the agent stays a draft, and a draft never runs.

You can write an agent from scratch, or start from one of the four templates that come with your account.

From Scratch

To create a new agent without a template:

1. Click Create new agent
   
2. Write the instructions, e.g. Create sub-tickets based on comments about incomplete tasks
   Read more below in Write the Instructions.
3. Click Next
   
4. Add a Project, Triggers and Actions
   Read more below in Set the Project, Set the Triggers and Set the Actions.
   
5. Click Review and test
   
6. Click Test run
   Read more below in Test the Agent.
   
7. Click Activate agent
   Read more below in Activate the Agent.
   

From a Template

Four ready-made agents come with your account. Each one arrives fully written, with its instructions, trigger and actions already set, so the only thing missing is the project.

To create an agent with a template:

1. Click Create new agent
   
2. Under Our templates, click the template you want to use
   
3. Click Add under Project
   
4. Select the project
5. Click Save
   
6. Check the Agent name, Description and Instructions, and change them if you want.
7. Click Test run
   
8. Click Activate agent
   

Set Up and Edit an Agent

Everything an agent needs is set on the agent's own screen: name, description, instructions, project, triggers and actions.

To edit a draft agent:

1. Click the agent
   

To edit an active or paused agent:

1. Click the agent
   
2. Click Edit agent
   

Archived agents cannot be edited. You need to restore them first.

The agent screen is the same whether you create a new agent or edit an existing one. Here you can add or edit the following:

1. Agent name (must be unique — if the name is already taken, a number is added)
2. Description
3. Instructions – read more below in Write the Instructions
4. Project – read more below in Set the Project
5. Triggers – read more below in Set the Triggers
6. Actions – read more below in Set the Actions

The agent's screen, with the Testing panel on the right:

Saving changes doesn't change the status of the agent. Agents stay as draft, paused or active.

Write the Instructions

The instructions are the heart of the agent — everything it does follows from them. Write them the way you would explain the job to a colleague.

For example:

• "When a ticket is created without a due date, add a comment asking for one."
• "When a ticket is moved to Resolved, check the photos and comment if the fix is not documented."

To write the instructions:

1. In Instructions, describe what the agent should do.
   
2. Optional: Click Rewrite with AI to get an AI suggestion with clearer phrasing of your instructions.
   
3. Optional: You can keep the suggestion, Undo it, or write your own version instead.
   

Instructions can be up to 4,000 characters.

To expand the instructions input field:

1. Click the Expand icon
   

To collapse the expanded input field:

1. Click the Collapse icon
   

Set the Project

An agent runs in exactly one project, and never reads anything outside it.

To edit the project:

1. Under Project, click Edit
   
2. Select the project the agent runs in
3. Click Save
   

Set the Triggers

A trigger is the event that starts a run. An agent can have several triggers, and it runs when any one of the defined events occurs.

To edit triggers:

1. Under Triggers, click Edit
   
2. Under Source, choose whether the agent reacts to Tickets or to Documents.
   
3. Under Event, choose the event that starts the run.
   
4. Click Save
   

Each trigger is one source and one event:

To add more triggers:

1. Click + Add trigger
2. Select a Source and Event as described above
   

You can narrow a trigger with Scope, so the agent only reacts to part of the project:

• Ticket triggers can be limited to a Layer, a Form, or both.
• Document triggers can be limited to a Folder.

To limit the scope of a ticket trigger:

1. Click Advanced settings
2. Select a Layer and/or Form
   

To limit the scope of a document trigger:

1. Click Advanced settings
2. Select a Folder
   

A document trigger watches a folder, not a single file. To have an agent react to one specific document, move it into its own folder and scope the trigger to that folder.

A trigger decides when the agent looks, not whether it acts. Ticket updated fires on any change to a ticket, so if the agent should only act on some of them, say so in the instructions — for example "only act when the status becomes Resolved". The agent reads the event, checks it against your instructions, and does nothing if it does not apply.

Ticket events count wherever they happen — a ticket created in the mobile app starts the agent just as one created in the Webapp does.

Document triggers are available for accounts with Document Management.

Set the Actions

Actions are what the agent is allowed to write. Add the ones it needs; the agent decides for itself when to use each of them, based on your instructions. Each action can be added once.

To edit actions:

1. Under Actions, click Edit
   
2. Click Add action
3. Click Create ticket, or Add comment, or Send email.
   
4. Optional: Fill in the settings you want the agent to always use.
   For Create ticket you can define: Layer, Form. And under Set specific field values: Title, Assignee, Priority, Status
   For Send email you can define: To, CC, Subject
5. Click Save
   

Test the Agent

The Testing panel lists the four things the agent needs and marks each one off as you complete it. Once all four are in place you can run a test.

A test run reads real data from your project but writes nothing. The result shows you what the agent would have created, commented or sent. Nothing is created or changed in your project. You can test changes before you save them.

To test an agent:

1. In the Testing panel, click Test run.
   
2. Read what the agent would have done.

A test that ends without the agent doing anything is a normal result. It means the agent judged that no action was needed.

A test consumes your AI usage limit, the same as a real run.

Activate the Agent

An agent only starts working once you activate it.

To activate an agent:

1. Click Activate agent
   

The agent shows as Active in the list and runs from then on, every time one of the events defined in the triggers occurs.

To keep the agent without switching it on, click Save as draft instead. A draft never runs, and you can come back and activate it at any time.

Save the agent as a draft instead of activating it:

Every run the agent makes is recorded. Open Activity log to see what it did and why. Read more in Monitor AI Agents in the Activity Log.

Manage Your Agents

• Everyone with the user permission AI Agents sees the agents that run in the projects they have access to, including agents a colleague created. The same applies to Archived agents and the Activity log.
• The person who creates an agent owns it, and only they can edit, test, activate, pause, archive, restore or delete it.

Duplicate

Duplicating makes your own copy of an agent, which you own and can change. You can duplicate any agent you can see, including one a colleague created — this is how you reuse someone else's agent, or run the same behaviour in a second project.

To duplicate an agent:

1. Open the More menu of the agent
2. Click Duplicate agent
   

The copy is named after the original with (copy) added, and it starts as a draft. Change the project or anything else you need, then test and activate it.

Pause

Pausing stops the agent running and keeps all its settings, so you can switch it back on whenever you want.

To pause an agent:

1. Open it from the agents list
   
2. Open the More menu
3. Click Pause agent
   

Archive and Restore

Archiving moves the agent to Archived agents and stops it running, without deleting anything.

To archive an agent:

1. Open the More menu of the agent
2. Click Archive agent
   

To restore an agent:

1. Click Archived agents
2. Open the More menu of the agent
3. Click Restore agent
   

Restored agents are always paused. Activate them when ready.

Delete

Delete an agent only if you are sure you never want to restore it. If you are not sure, archive it instead. Its runs stay in the Activity log so you can still see what it did.

To delete an agent:

1. Open the More menu of the agent
2. Click Delete agent
   
3. Click Delete to confirm
   

When an Agent Pauses Itself

An agent pauses itself in these cases:

• Your account has reached its AI usage limit.
• Runs kept failing because the content sent to the AI model was too large. Shorten the instructions, or point the agent at smaller forms or fewer documents.
• The agent reached its limit of actions in a single run.
• The agent's project was archived or deleted.
• Too many runs started in a short time.
• The owner of the agent was set to inactive, lost the AI Agents permission, or lost access to the project.

You get a notification, and the agent stays paused until you activate it again.

It is possible to deactivate the notifications for a failed agent run or an automatic pause for the whole account. Read more in Configure AI Agents for your Account.

An agent never starts itself again. Hover over the Paused status to see why it stopped.