Build and configure Agents

Use this guide when you want to create a custom Agent or tune a built-in Agent for a team, project, or operating rhythm.

For field-by-field reference and the built-in Agent catalog, see Agent configuration.

Before you build

1. Decide the job in one sentence.
2. Decide whether the Agent should read, propose, or write.
3. Pick the narrowest useful context.
4. Pick the output contract before writing the prompt.
5. Start with manual trigger enabled so you can test.
6. Publish only after the draft produces reviewable output.

Start review-first

Default to Review first for any Agent that can affect workspace state. Move to direct writes only after the Agent is narrow, observable, and easy to reverse.

Example 1: Create a customer handoff reviewer

Goal: Review customer handoff notes and propose follow-up tickets.

Use this when support, customer success, or sales writes notes that should turn into project work, but a person still needs to approve the work.

Recommended configuration:

Setting	Value
Owner scope	Organisation or project
Output	proposal_list
Context	Ticket context
Tools	Search tickets, read tickets, create tickets
Write policy	Review first
Trigger	Manual at first, then event if a matching product event exists

Prompt pattern:

Review the handoff notes and related ticket context.

Create a proposal only when the note contains a concrete follow-up, owner need, risk, or customer commitment.
Do not create generic "follow up" work.
Prefer one small ticket per action.
Include the source note or ticket reference in each proposal.
If the notes are informational only, return no proposals.

Steps:

1. Open the appropriate Agents tab.
2. Select New Agent.
3. Name it Customer handoff reviewer.
4. Set Output to Proposal list.
5. Set Context to Ticket context.
6. Enable read ticket tools.
7. Enable Create tickets as Propose changes.
8. Keep Write policy as Review first.
9. Keep Manual runs enabled.
10. Save the draft.
11. Run a manual test with realistic handoff notes.
12. Publish after the output is specific and low-noise.

What to watch:

• Too many proposals means the prompt criteria are too broad.
• Missing proposals usually means the context is too narrow or the prompt asks for too much certainty.
• If duplicate tickets appear, add instructions to search for existing matching tickets before proposing new work.

Example 2: Tune the built-in operating pulse for a project

Goal: Run the operating pulse less often for a quiet project, without changing the server-wide default.

Use this when one project needs a different cadence from the rest of the workspace.

Recommended configuration:

Setting	Value
Agent	operating_pulse
Scope	Project
Schedule override	Interval
Every minutes	180 or 240
Quiet hours	Optional UTC off-hours

Steps:

1. Open the project.
2. Open Project Settings, then Agents.
3. Open Operating pulse.
4. Leave the definition unchanged.
5. In Availability, set Schedule override to Interval.
6. Set the interval, for example 240.
7. Save availability.
8. Confirm the card shows the project schedule source.

What to watch:

• This changes only the binding for the project scope.
• A server or organisation disable still blocks the Agent.
• Interval quiet hours are UTC, not the user's local time.

Example 3: Add a daily ticket hygiene review

Goal: Propose duplicate, stale, or contradictory ticket cleanup once per day.

You can tune the built-in ticket_conflict_scanner or create a custom Agent if the criteria are different enough.

Recommended configuration:

Setting	Value
Output	proposal_list
Context	Ticket context
Tools	Search tickets, read tickets, archive/update tickets as proposals
Write policy	Review first
Trigger	Daily UTC hour

Prompt pattern:

Scan active tickets for duplicate work, contradictory status, stale blockers, and work that should be archived.

Only propose cleanup when the evidence is clear from ticket title, description, status, comments, or links.
Do not propose cleanup for tickets that merely share keywords.
Each proposal must name the records compared and the reason a human should review it.

Steps:

1. Open Organisation Settings, then Agents.
2. Open Ticket conflict scanner or create a new Agent.
3. Use Ticket context.
4. Use Proposal list output.
5. Keep Write policy as Review first.
6. Set Daily schedule to the desired UTC hour.
7. Publish the draft if you changed the definition.
8. Save the organisation schedule override if you only changed timing.

What to watch:

• Daily schedules run in UTC.
• Review proposals in Inbox before archiving anything.
• If noisy, narrow the prompt to fewer conflict types.

Example 4: Create a docs memory reviewer for a specific knowledge area

Goal: Review changed docs and propose durable memory facts only for a specific domain, such as security posture or customer commitments.

Recommended configuration:

Setting	Value
Output	memory_diff
Context	Related memory
Tools	Usually no write tools
Write policy	Read only or Review first
Trigger	Doc changed event

Prompt pattern:

Review the changed doc for durable facts about security posture.

Propose memory only for facts that are stable, specific, and useful outside this document.
Do not extract meeting notes, opinions, tentative plans, or implementation details that may change soon.
Prefer fewer high-confidence memory diffs.
Quote or identify the source passage for every proposed memory item.

Steps:

1. Create the Agent at the organisation or project scope.
2. Set Output to Memory diff.
3. Set Context to Related memory.
4. Enable the Doc changed event.
5. Avoid write tools unless you have a narrow need.
6. Save and publish.
7. Edit a test doc and wait for Agent Runs to finish.
8. Review the memory diffs before accepting them.

What to watch:

• Memory should be a fact layer, not a summary of every doc edit.
• A memory reviewer should produce no output for weak or transient content.
• The built-in docs memory reviewer already exists; create a custom one only when the extraction rules are meaningfully different.

Example 5: Build a direct-write Agent for low-risk ticket comments

Goal: Add a standard comment to tickets after a very specific event.

Direct write Agents should be rare. This example is appropriate only when the action is narrow and reversible.

Recommended configuration:

Setting	Value
Output	run_summary
Context	Ticket context
Tools	Read tickets, comment on tickets
Write policy	Allow direct writes
Tool behavior	Comment on tickets: Write directly
Trigger	Manual first, then a narrow event

Prompt pattern:

Add a short standard comment only when the input explicitly says the ticket has completed external QA.

Do not change status, assignee, priority, dates, title, or description.
Do not comment if the ticket already has an external QA completion comment.
The comment must include the source event date and say that external QA was completed.
Return a run summary of what was changed or why no change was made.

Steps:

1. Create the Agent in a test project first.
2. Select Ticket context.
3. Enable read ticket tools.
4. Enable Comment on tickets.
5. Set Write policy to Allow direct writes.
6. Set Comment on tickets behavior to Write directly.
7. Keep every other write tool disabled.
8. Save the draft.
9. Test manually on a non-critical ticket.
10. Publish only after the Agent safely does nothing for ambiguous input.

What to watch:

• Direct write policy and direct tool behavior are both required.
• Keep direct-write Agents narrow enough that the prompt can describe exactly when not to act.
• Prefer comments over status or field changes for early direct-write rollouts.

Example 6: Restrict a built-in Agent for one organisation

Goal: Disable snapshots for one organisation without affecting the whole server.

Steps:

1. Open Organisation Settings.
2. Open Agents.
3. Open Snapshot generator.
4. Set State to Disabled here.
5. Save availability.
6. Confirm snapshot generation buttons show the disabled reason.

What to watch:

• Users and projects inside that organisation cannot re-enable it.
• Server admins can still see and edit the built-in definition.
• Other organisations on the same server are not affected.

Testing checklist

Before broad rollout:

1. Confirm the effective scope and schedule source.
2. Run manually with representative input.
3. Test a case where the Agent should produce no output.
4. Test a case with missing or ambiguous context.
5. Confirm the output contract validates.
6. Confirm write tools create proposals unless direct writes are intentionally enabled.
7. Check Agent Runs for failures.
8. Check Inbox, Memory Diffs, tickets, docs, snapshots, or Today for expected output.
9. Publish with a clear note.
10. Watch the first scheduled or event-triggered run after publishing.

Common fixes

Problem	Fix
Agent creates too much work	Tighten the prompt, narrow context, remove write tools, or switch output from proposals to summary.
Agent misses obvious work	Add the right context, enable needed read tools, and include examples of valid output in the prompt.
Scheduled Agent runs at the wrong time	Convert the desired local time to UTC and check schedule overrides.
Event Agent runs unexpectedly	Remove the event trigger or add stricter prompt criteria.
Direct write is not happening	Confirm both Allow direct writes and the specific tool's Write directly setting.
Runs fail after publishing	Check output contract mismatch, missing tools, disabled bindings, and backend logs.

Related concepts: Agent configuration, Agent runs, Inbox, and Review AI proposals.