Agent configuration

Agents are the configurable AI runtime surface in TOW. Admins define what an Agent is allowed to know, when it runs, which tools it can use, what shape its output must have, and where it is available.

Use Agents when you need a global AI baseline, an organisation restriction, a project-specific cadence, a custom prompt, or a personal availability preference.

Agents control LLM behavior and tool access. Deterministic platform services such as indexing, embeddings, search infrastructure, and permission checks remain platform capabilities.

Mental model

An Agent has three layers:

Layer	What it contains	Why it matters
Definition	Stable key, name, owner scope, category, built-in flag, archived flag.	Identifies the Agent and who owns its configuration.
Version	Prompt, model settings, tools, write policy, context, output contract, and default triggers.	Runtime behavior changes only when a draft is published.
Binding	Scope availability, enabled state, selected version, and schedule override.	Makes an Agent available to server, organisation, project, or user scope.

Each run is stored as an Agent Run. Runs include the Agent/version IDs, trigger source, target, input payload, status, output, tool calls, errors, and timestamps.

Built-in Agents

TOW seeds these pre-built Agents during migration and startup. Server admins can edit and publish their definitions, but the stable keys should stay unchanged because product actions call those keys.

Agent key	Pre-built Agent	Default triggers	Output contract	Context	What it controls
chat_assistant	Chat assistant	Manual, chat message event	text	Chat context	Interactive workspace chat responses and configured chat tools.
chat_memory_reviewer	Chat memory reviewer	Chat turn completed event	memory_diff	Related memory	Reviews completed chat turns and creates reviewable memory diffs.
today_checkin_processor	Check-in processor	Check-in completed event	proposal_list	Operating context	Processes project Check-Ins into coaching, memory review, and work proposals.
proactive_daily_review	Proactive daily review	Daily schedule at 00:00 UTC	proactive_review	Proactive operating context	Produces daily proactive review and follow-up questions.
operating_pulse	Operating pulse	Interval schedule every 60 minutes	operating_pulse	Operating context	Refreshes focus, drift, and operating context for Today.
roadmap_proposal_generator	Roadmap proposal generator	Manual, roadmap generation requested event	proposal_list	Roadmap context	Generates roadmap and epic proposals.
docs_memory_reviewer	Docs memory reviewer	Doc changed event	memory_diff	Related memory	Reviews doc changes for memory diffs. Indexing and embeddings remain platform work.
snapshot_generator	Snapshot generator	Manual, snapshot requested event	snapshot	Snapshot context	Generates source-grounded memory snapshots for review.
ticket_conflict_scanner	Ticket conflict scanner	Manual, ticket conflict scan requested event, daily schedule at 02:00 UTC	proposal_list	Ticket context	Runs manual and recurring duplicate/conflict proposal scans for tickets.

Do not rename built-in keys

Built-in keys are integration contracts. You can change prompts, tools, triggers, schedules, and availability, but product code expects keys such as snapshot_generator and chat_assistant.

Scopes and inheritance

Agent availability resolves across four scopes:

Scope	Purpose
Server	Global baseline for the deployment. Server admins can create Agents and edit built-in Agent definitions.
Organisation	Workspace-wide availability and schedule policy.
Project	Project-specific availability and cadence for project-scoped work.
User	Personal availability where higher scopes allow it.

Any scope can disable an Agent. Lower scopes cannot re-enable an Agent disabled above them.

Schedule resolution uses the most specific available value:

1. User binding.
2. Project binding.
3. Organisation binding.
4. Server binding.
5. Published Agent version trigger defaults.

In the UI:

• Inherited means this scope has no local binding and is using a higher-scope or default configuration.
• Customized means this scope has a local binding that changes availability or schedule from the inherited base.
• No customization badge is shown when the current scope owns the Agent, because that scope is the base.

Drafts, publishing, and rollback

Definition edits happen on the draft version. Runtime uses published versions.

Recommended workflow:

1. Edit the draft.
2. Save the draft.
3. Run a manual test where possible.
4. Publish with a short note.
5. Watch Agent Runs and Inbox for the first few runs.
6. Roll back by publishing or binding a known-good version if the new behavior is wrong.

Keep publish notes operational: "Tightened ticket creation criteria" is more useful than "updates".

Configuration fields

Basics

Field	Guidance
Name	Human-readable name shown in settings and run history.
Stable key	API and trigger key. Use lowercase letters, numbers, and underscores. Do not change built-in keys.
Description	Explain what the Agent does and what output to expect.
Category	Metadata for filtering and scanning. It does not change runtime behavior.
Owner scope	The scope that owns the Agent definition. In v1, regular users cannot create or edit definitions.

System prompt

The system prompt is the standing instruction sent to the model for every run of that version.

Good prompts:

• State the Agent's job.
• State what not to do.
• Name the output style.
• Require evidence from provided context.
• Say when to produce no proposal.
• Prefer small, reviewable outputs over broad rewrites.

Avoid prompts that ask the Agent to ignore permissions, invent missing facts, or "always create" records.

Model and reasoning

The model field can be blank to use the server default. Use a specific model only when the Agent has a real need for it.

Reasoning effort is an optional budget hint. Higher effort can improve difficult synthesis, but it can increase latency and cost. Use higher effort for roadmap synthesis, conflict scanning, and operating reviews. Use default or low effort for narrow formatting or notification-style Agents.

Tools

Tools define what the Agent can inspect or change. Tools are grouped by capability, such as Web, Memory, Knowledge, Docs, and Tickets.

Access types:

Access	Meaning
Read	The Agent can inspect data but cannot write workspace changes through that tool.
Proposal write	The Agent can propose a change for human review, usually through Inbox or a pending action.
Direct write	The Agent can apply the change directly. This requires explicit admin opt-in.

Default to read tools plus proposal writes. Direct writes are for low-risk, narrow, observable actions where a failed write is easy to detect and reverse.

Write policy

Policy	Use when
Read only	The Agent should summarize, classify, or diagnose without changing workspace state.
Review first	The Agent can propose changes, but people approve them before they become workspace state. This is the default.
Allow direct writes	The Agent may directly use selected write tools that are individually configured for direct writes.

Direct write policy alone is not enough. Each write tool still needs its behavior set to Write directly.

Context

Context controls server-built retrieval added to each run before the model is called.

Context option	Typical use
No extra retrieval	Manual Agents where the input payload is enough.
Chat context	Chat assistant behavior.
Related memory	Memory extraction and review.
Operating context	Check-In, Today, and pulse Agents.
Proactive operating context	Daily proactive review.
Roadmap context	Roadmap and epic proposal generation.
Snapshot context	Snapshot generation.
Ticket context	Ticket conflict scans or ticket-focused review.

Choose the narrowest useful context. More context is not always safer; it can make an Agent slower, noisier, and more likely to mix scopes.

Output contracts

Agent outputs are validated against server-defined templates. Admins choose a template; they do not paste arbitrary JSON Schema in v1.

Contract	Use for
text	Plain assistant text.
run_summary	Durable summary of what the run did.
proposal_list	One or more reviewable proposals.
memory_diff	Proposed memory additions or edits.
snapshot	Generated memory snapshot content.
operating_pulse	Focus, drift, and operating pulse output.
proactive_review	Daily proactive operating review output.
json_object_template	Server-defined schemas only.

If output validation fails, the run can fail even when the model produced text. Match the prompt to the selected output contract.

Triggers

Agents can have multiple trigger types:

Trigger	Meaning	Notes
Manual	Users or API calls can explicitly run the Agent.	Best for testing and on-demand work.
Event	Product events enqueue the Agent automatically.	Examples include chat turns, doc changes, check-ins, snapshots, roadmaps, and ticket scans.
Interval	Runs every N minutes.	Supports optional UTC quiet hours. Minimum interval is enforced by the server.
Daily	Runs once per day at a UTC hour.	There is no cron syntax in v1.

Event triggers available in v1 include:

• Chat message.
• Chat turn completed.
• Check-in completed.
• Doc changed.
• Snapshot requested.
• Roadmap generation requested.
• Ticket conflict scan requested.

Availability and schedule overrides

Bindings let each scope enable or disable an Agent and override its schedule.

Use binding overrides when:

• A whole organisation should disable a risky Agent.
• A project needs a slower or faster cadence.
• A user wants to opt out of a personal Agent where allowed.
• A scheduled Agent should run at a different UTC hour for an organisation.

Do not use bindings to change the prompt. Prompt, tools, context, output, and trigger defaults belong to versions.

Gotchas

Gotcha	How to avoid it
Draft edits do nothing at runtime	Publish the draft after review.
A lower scope says enabled but the action is disabled	Check higher-scope disables. Server, organisation, and project disables win over user settings.
Schedule seems wrong	Check the effective schedule source. A user, project, organisation, or server binding can override the Agent version default.
Daily schedule fires at an unexpected local time	Daily hours are UTC. Convert local operating hours before saving.
Interval runs continue during off-hours	Add UTC quiet hours to the interval schedule.
Direct write tool does not write directly	Confirm the Agent write policy is Allow direct writes and the specific tool behavior is Write directly.
Output is rejected	Confirm the prompt asks for the selected output contract shape.
Too many low-value proposals	Narrow the trigger, context, prompt criteria, or output contract.
Agent sees too much context	Use a narrower context option and fewer read tools.
Built-in product action stopped working	Check whether the built-in Agent key was archived, disabled, or renamed.

Settings UI

Agent settings are available in:

• Admin, Server Settings, Agents.
• Organisation Settings, Agents.
• Project Settings, Agents.
• User Settings, Agents.

Each card shows effective availability, schedule or trigger summary, inherited/customized state, category, and disabled reason. The gear button opens the editor for availability, draft configuration, tools, triggers, and publishing.

Troubleshooting

Symptom	What to check
A button is disabled	Open the relevant Agents tab and check the disabled reason.
A run never starts	Confirm the Agent is enabled, has a published version, and has the expected trigger.
A schedule is not being used	Check the effective schedule source and whether a more specific binding overrides it.
A prompt edit did not affect runs	Confirm the draft was published and the binding points at the expected version.
Output is missing	Check Agent Runs, Inbox, Memory Diffs, and the target record for errors or reviewable proposals.
A run failed	Check Agent Runs, backend logs, output contract validation, and tool permission errors.

Related guides: Build and configure Agents, Agent runs, Inbox, and Background AI system.