Custom agent configuration reference

This is the companion reference to Custom agents — start there for the concepts and a walk-through of setting one up. This page lists every setting you can configure on a custom agent, grouped by area, with what each one does, its options, its default, and who can change it. A reminder on the two layers of behavior (covered in depth on the Custom agents page): instructions are the free-text brief the agent does its best to follow, while configuration — everything on this page — is enforced by Nash on every run. When you need a guarantee, put it in configuration.

Who can set these

Almost every setting here is changed through the same managed permission tier that lets you create, edit, schedule, and run custom agents — typically operations managers and admins, not every user. Throughout this page that tier is referred to as agent management. Members with read-only access can view an agent’s configuration but can’t change it. A few settings have an extra requirement on top of agent management; those are called out in the Who can set it column.

Nash ships a set of ready-made global agents that appear in every organization’s list. They’re read-only templates — to change any setting below, duplicate the agent first and edit your own copy.

Identity

How the agent shows up in your list.

Field	What it does	Options / values	Default	Who can set it
Name	The agent’s display name.	Free text, 1–256 characters. Required.	— (required)	Agent management
Description	A short description of the agent, shared with the rest of Nash so it’s recognizable elsewhere. Nash generates it automatically from the agent’s name and instructions.	Generated automatically — not entered by hand.	Generated	Automatic
Icon	A UI icon to make the agent easy to spot.	An icon name token.	`Bot`	Agent management
Color	A UI color for the agent.	A color token.	`violet`	Agent management

Instructions

The free-text brief the agent follows on every run.

Field	What it does	Options / values	Default	Who can set it
Instructions	The agent’s behavioral brief — what to do and how to think about the job. Guidance, not a hard rule.	Free text, up to 10,000 characters.	Empty	Agent management

Before you save, you can have Nash review a draft’s instructions and flag anything that would be more reliable as a structured setting — for example, a list of providers typed into the prompt that belongs in the scope filter. It only suggests; it never blocks you from saving.

Scope

Narrows what slice of your operation the agent focuses on. Leave a dimension empty for no constraint on that dimension. Setting any of providers, zones, or contracts pins the agent to that slice on every run.

Field	What it does	Options / values	Default	Who can set it
Providers	Restrict the agent to specific delivery providers.	A list of provider IDs.	Empty (no constraint)	Agent management
Zones	Restrict the agent to specific zones.	A list of zone IDs.	Empty (no constraint)	Agent management
Contracts	Restrict the agent to specific contracts.	A list of contract IDs.	Empty (no constraint)	Agent management
Date range	Records a time window for the agent’s work.	Either a preset (`last_7_days`, `last_30_days`, `last_90_days`, `ytd`) or an explicit start and end date — one or the other, not both. Start must be on or before end.	None	Agent management

The provider, zone, and contract filters take effect today and constrain every run. The date range is stored but not yet applied — it’s saved on the agent so the setting survives, but it does not currently restrict what the agent looks at. Until that changes, the agent chooses the time window for each question itself. Don’t rely on the date range to limit the agent’s view yet.

Behavior and execution mode

Controls whether the agent can act on its own and which high-stakes actions always pause for your approval.

Field	What it does	Options / values	Default	Who can set it
Execution mode	Whether the agent can take action or only report.	`report_only` (investigate and write up findings and proposed actions; never acts destructively on its own) or `auto_execute` (may carry out actions itself).	`report_only`	Agent management
Confirm-first actions	Specific destructive actions that always pause for your sign-off, even in auto-execute mode.	A list of action keys (see the table below). Each must be a recognized key, or the save is rejected.	Empty (only Nash’s standard defaults apply)	Agent management
Disabled actions	Specific actions this agent can’t take at all.	Any of the same action keys. A disabled action never runs and never raises a confirmation card.	Empty	Agent management

Each action key you set is an override on one action; anything you leave alone keeps the organization’s setting. Setting an action to disabled is the strongest of the three — use it for actions this agent should never have, and confirm-first for the ones you want to review case by case.

When you duplicate an agent, the copy’s execution mode is always reset to report only, regardless of what the original was set to. This is a deliberate safety default — a copy never inherits the ability to take action until you grant it.

Confirm-first action keys

Any action key you list here is forced to require your confirmation before the agent runs it, even when the agent is in auto-execute mode. The recognized keys are:

Action key	Covers
`cancel_delivery`	Canceling a delivery
`request_refund`	Requesting a refund
`initiate_return`	Starting a return
`reassign_provider`	Reassigning a provider
`reschedule_delivery`	Rescheduling a delivery
`mark_attempted`	Marking a delivery as attempted
`checkout`	Checkout
`create_resource` / `update_resource` / `delete_resource` / `archive_resource`	Creating, updating, deleting, or archiving a record
`create_user` / `invite_user` / `add_user_roles` / `replace_user_roles` / `remove_user_roles`	User and role management
`send_message`	Sending a message
`place_voice_call` / `send_sms`	Reaching a contact by voice call or text (see Skills and tools below)
`other_write`	Any other write action

Listing an action key here is an override: it forces confirmation for that action on top of whatever your organization already requires confirmation for. It’s how you ratchet a single agent stricter than the org default.

Skills and tools

What capability the agent can reach beyond its base toolkit.

Field	What it does	Options / values	Default	Who can set it
Skills	Named bundles of capability available to the agent.	Leave unset for a sensible default set; provide an explicit list of skill names to use exactly those; provide an empty list to load none.	Unset (default set)	Agent management
Tools	Additional toolkits to wire in.	A list of toolkit IDs. The analytics connector is the recognized value today; other IDs are accepted but have no effect.	Empty	Agent management
Native contact tools	Lets the agent reach a contact directly by text message or outbound voice call.	A list that may include `send_sms` and `place_voice_call`. Unrecognized values are rejected.	Empty	Agent management plus the contact-tools permission

The text-message and voice-call tools always pause for your confirmation before they send or dial, and they must be turned on for the agent (listed above) before it can use them at all. They also require your account to hold the permission for these tools — without it, they won’t appear as options. They may not be available to every account. Text messaging in particular is opt-in and may not be available on every account yet; voice calling is the more established of the two. See Skills for more on skills.

Knowledge

Reference material that grounds the agent in your operation’s context. See Knowledge for the full picture.

Field	What it does	Options / values	Default	Who can set it
Reference text	A free-text block of notes, policies, and context the agent reads as background.	Free text.	Empty	Agent management
Reference URLs	Links the agent can fetch on demand when a question makes one relevant.	Up to 50 links, each a standard `http`/`https` web address.	Empty	Agent management
Inherit org knowledge	Whether the agent also reads your organization’s shared knowledge.	On (combine org knowledge with the agent’s own) or off (use only the agent’s own).	On	Agent management

Output and writeback

How the agent reports its results, and whether it records them onto a job. By default an agent reports its findings as a written summary. You can instead define a structured output format so every run fills in the same named fields, and you can optionally have the agent write those results back onto a job’s record.

Field	What it does	Options / values	Default	Who can set it
Output format	A set of named fields each run fills in, instead of a free-form write-up.	A list of one or more field definitions (see below).	None (free-form summary)	Agent management
Writeback target	Where the agent records its structured results.	`job` is the only supported target today; any other value is rejected.	None (results aren’t written back)	Agent management
Writeback namespace	A short label that scopes which record fields the agent is allowed to write, so it can’t disturb anything else.	A short text prefix, up to 32 characters. Required when writeback is turned on (and an output format is also required).	None	Agent management
Writeback field map	Maps your output fields to the destination fields on the record.	A mapping where every key starts with your writeback namespace. The reserved key `agent_meta` is not allowed.	None (a sensible default mapping is used)	Agent management

Output format fields

Each field in an output format has these properties:

Property	What it does	Options / values	Default
Name	The field’s identifier.	Required. 1–64 characters, lowercase `snake_case` (start with a letter; letters, numbers, and underscores only). Must be unique within the format.	— (required)
Label	A human-friendly display name.	Up to 128 characters.	Auto-derived as Title Case from the name if left blank
Type	The kind of value the field holds.	One of `bool`, `number`, `string`, `text`, `enum`, or `list_string`. Required.	— (required)
Description	What the field means — guides the agent on what to fill in.	Required, 1–500 characters.	— (required)
Required	Whether the agent must fill the field on every run.	On or off.	Off
Allowed values	The permitted choices for an enum field.	A list of strings. Required when the type is `enum`; not allowed otherwise.	None
Display role	How the field is surfaced in the UI.	`status`, `summary`, `headline`, or `detail`. `status` requires an `enum` type; `summary` requires `string` or `text`; `headline` requires `string`. At most one field each may be `status`, `summary`, or `headline`.	`detail`

Limits

A token cap is a safety limit on how much a single run may consume. It does not determine how the run is priced. The cap works alongside your organization’s default: a tighter agent-level cap takes precedence, and you can only lower the org cap, never raise it. Leave it unset to fall back to the organization default.

Field	What it does	Options / values	Default	Who can set it
Token cap	A per-run safety ceiling.	A non-negative whole number. `0` means no cap from the agent (the org default still applies).	None (use org default)	Agent management

A cap of 0 does not mean “block everything” — it means “no cap from this agent.” If you want to limit a run, set a positive number. To pause an agent entirely, use pause/resume instead.

This per-agent safety cap is an override of your organization’s per-session token default. The org-wide default it falls back to is set in your organization’s Nash Agent settings, not here.

Notifications

Who gets told when a run finishes or fails.

Field	What it does	Options / values	Default	Who can set it
Notify groups	Recipient groups to notify on run completion or failure.	A list of recipient group IDs.	Empty	Agent management
Notify on	When to send a notification.	`on_completion`, `on_success_only`, or `on_failure_only`.	`on_completion`	Agent management
Notification title	Overrides the notification’s title line.	Free text up to 500 characters, with `{{variable}}` placeholders. Leaving it unset uses `{{agent_name}} — {{status}}`.	None (default title)	Agent management
Notification template	Overrides the auto-generated notification body.	Free text up to 10,000 characters. Leaving it unset uses the auto-rendered body; you can still reference the auto body inside a custom template.	None (auto-rendered)	Agent management

The title is what recipients scan first: it becomes the subject line in email and the opening line in Slack, text, and the other supported channels. It takes the same {{variable}} placeholders as the body, so a title like Late deliveries — {{status}} reads usefully in an inbox without opening the message. You can preview how a notification will read — title and body — before you save it.

Notify only when the result is worth reading

An agent that runs every fifteen minutes and notifies every time trains its recipients to ignore it. If the agent has an output format, you can attach a condition to its notification so a successful run only notifies when the result is actually actionable: is_fraud came back true, status landed on bad, confidence reached 0.8. A condition names one output field, an operator, and a value. What you can compare depends on the field’s type:

Field type	Operators	Example
`enum`	`in`; the value is one of the ones you list	`status in ["bad", "at_risk"]`
`bool`	`in`; the value is one of the ones you list	`is_fraud in [true]`
`number`	`equal_to`, `greater_than`, `greater_than_or_equal`, `less_than`, `less_than_or_equal`	`confidence greater_than_or_equal 0.8`

Conditions are checked against the field’s declared type without coercion, so a condition that doesn’t fit the field it names is rejected when you save it rather than quietly never matching. Fields of other types can’t carry a condition; the control explains why when it’s unavailable.

A condition gates notifications for runs that succeeded. A failed run still notifies according to your Notify on setting. A condition can’t silence an agent that broke.

Organizing

How the agent is filed and surfaced in your list.

Field	What it does	Options / values	Default	Who can set it
Folder	The shared folder the agent lives in.	A folder in your organization. Globals can’t be foldered.	None (Ungrouped)	Agent management
Tags	Org-shared tags for grouping and filtering.	A list of tag IDs, each belonging to your organization.	None (unchanged)	Agent management

You can only choose a folder when you first create an agent. To move an existing agent into a different folder (or back to Ungrouped), use the dedicated move action rather than the edit form — folder changes made through a plain edit are ignored. Star, pause, and resume are also their own actions rather than fields on the edit form; see Custom agents for managing an agent over its lifecycle.

Model selection

Nash selects the model for each agent based on its configured behavior. The selection is tuned to maximize effectiveness while controlling cost, and can change as the available models improve. You don’t need to choose or maintain a model name, and existing agents keep working when Nash updates the models behind them.

Scheduling and runs

A custom agent’s recurring runs — their cadence, timezone, and trigger — are configured as separate run definitions attached to the agent, not as fields on the agent itself. Those run settings, including how the agent can work iteratively over time, are covered on the Scheduling and execution page.

FAQ

Why did my duplicated agent lose its auto-execute setting?

That’s intentional. Every duplicate is forced into report-only mode as a safety default, no matter what the original was set to. Re-enable auto-execute on the copy once you’re sure it’s scoped the way you want.

I set a date range on an agent — why doesn't it seem to limit anything?

The date range is saved but not yet applied to the agent’s work. The provider, zone, and contract scope filters do take effect, but the date range setting doesn’t currently restrict the time window the agent looks at — the agent still picks a window per question. Use the scope filters for hard boundaries today.

Is there a per-agent setting to turn code execution on or off?

No. That capability is controlled at the organization level in your Nash Agent settings, not per agent, so there’s no field for it on the agent.

What's the difference between the agent's token cap and my organization's token cap?

The agent’s token cap is a per-agent override that can only tighten, never loosen, your organization’s per-run default. If you set a tighter cap on the agent, it wins; if you leave it unset, the agent falls back to the org default. The org-wide default is set in your organization’s Nash Agent settings. Token caps constrain runs; they are not pricing units.

Can I write results back to anything other than a job?

Not today. The only supported writeback target is a job’s record. When you turn writeback on, you also have to define an output format and a writeback namespace so the agent’s writes are confined to clearly-labeled fields.

Custom agents

The conceptual overview — what a custom agent is, when to use one, and how to set it up.

Scheduling & execution

Configure when and how often an agent runs, and how it works iteratively over time.

Knowledge

Ground an agent with SOPs, policies, and reference links.

Skills

Reusable, named procedures you can hand an agent.

​Who can set these

​Identity

​Instructions

​Scope

​Behavior and execution mode

​Confirm-first action keys

​Skills and tools

​Knowledge

​Output and writeback

​Output format fields

​Limits

​Notifications

​Notify only when the result is worth reading

​Organizing

​Model selection

​Scheduling and runs

​FAQ

​Related

Custom agents

Scheduling & execution

Knowledge

Skills

Who can set these

Identity

Instructions

Scope

Behavior and execution mode

Confirm-first action keys

Skills and tools

Knowledge

Output and writeback

Output format fields

Limits

Notifications

Notify only when the result is worth reading

Organizing

Model selection

Scheduling and runs

FAQ

Related