> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom agent configuration reference
> A field-by-field reference for everything you can set on a custom agent — identity, scope, behavior, skills, knowledge, output, and limits.
This is the companion reference to [Custom agents](/nash-agent/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](/nash-agent/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 |
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](#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](/nash-agent/skills) for more on skills.
## Knowledge
Reference material that grounds the agent in your operation's context. See [Knowledge](/nash-agent/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
Caps on how much a single run may spend or consume. These work alongside your organization's defaults — a tighter agent-level cap takes precedence, and you can only ever lower the org cap, never raise it. Leave both unset to fall back to the organization default.
| Field | What it does | Options / values | Default | Who can set it |
| --------- | ------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------- | ---------------- |
| Spend cap | A per-run dollar ceiling. | A non-negative dollar amount. `0` means no cap from the agent (the org default still applies). | None (use org default) | Agent management |
| Token cap | A per-run token 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.
These per-agent caps are the agent-level overrides of your organization's per-session defaults. The org-wide defaults they fall back to are set on your organization's Nash Agent settings, not here. See [Usage and cost](/nash-agent/usage) for the org-wide spend limits these caps sit alongside.
## 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 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 |
You can preview how a notification will read before you save it.
## 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](/nash-agent/custom-agents) for managing an agent over its lifecycle.
## Model
Which model the agent runs on.
| Field | What it does | Options / values | Default | Who can set it |
| ----- | ------------------------- | ----------------------------------------- | ----------------- | ---------------- |
| Model | The model the agent uses. | A model identifier, up to 128 characters. | `claude-opus-4-8` | Agent management |
There's no validation of the model identifier when you save — any text up to 128 characters is accepted and only checked when the agent actually runs. Stick to a model ID you know is supported (the default, `claude-opus-4-8`, is a safe choice); a typo or an unsupported value won't be caught at save time and would only fail at run time.
## 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](/nash-agent/scheduling-and-execution) page.
## FAQ
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.
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.
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.
The agent's spend and token caps are per-agent overrides that can only tighten — never loosen — your organization's per-run defaults. If you set a tighter cap on the agent, it wins; if you leave them unset, the agent falls back to the org default. The org-wide defaults are set on your organization's Nash Agent settings. See [Usage and cost](/nash-agent/usage).
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.
## Related
The conceptual overview — what a custom agent is, when to use one, and how to set it up.
Configure when and how often an agent runs, and how it works iteratively over time.
Ground an agent with SOPs, policies, and reference links.
Reusable, named procedures you can hand an agent.