> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage, Budgets, and Activity

> Manage secrets, publishing, spend limits, and result notifications for custom agents.

Budgets and Notifications give teams operational control over custom agents. Use them to manage credentials, test changes, limit tool usage, control spend, and stay informed when work succeeds or fails.

<Frame caption="Operational controls help teams manage secrets, staging, tool limits, budgets, and publishing behavior for custom agents.">
  <img src="https://mintcdn.com/xpanderai-099931d1/ZExbmT2Yknjn6o_V/images/image-53.png?fit=max&auto=format&n=ZExbmT2Yknjn6o_V&q=85&s=36cfb92fb4bab17a69aacc8327136fe2" alt="Operational controls for custom agents" width="3014" height="1510" data-path="images/image-53.png" />
</Frame>

## Workspace secrets

Workspace secrets store credentials and environment variables securely. Use secrets for API keys, tokens, and private configuration. Do not place sensitive values directly in prompts.

<Frame caption="Store credentials and environment variables as workspace secrets.">
  <img src="https://mintcdn.com/xpanderai-099931d1/ZExbmT2Yknjn6o_V/images/image-69.png?fit=max&auto=format&n=ZExbmT2Yknjn6o_V&q=85&s=37ae8ddcc5e286117f85efadaa5eebf6" alt="Workspace secrets" width="1428" height="1434" data-path="images/image-69.png" />
</Frame>

## Stage before publishing, then promote to live

Staging lets teams test changes before they affect the live agent. Stage before publishing whenever you change prompts, tools, models, permissions, or runtime behavior, so you can verify the update in isolation without disrupting the version users are on. When the staged changes are ready, promote to live to publish them. Together, staging and promoting give teams a clean, deliberate way to update important agents.

<Frame caption="Stage changes, verify them, then promote to live.">
  <img src="https://mintcdn.com/xpanderai-099931d1/ZExbmT2Yknjn6o_V/images/image-68.png?fit=max&auto=format&n=ZExbmT2Yknjn6o_V&q=85&s=d5e127b5ebec002d26c0e8952bb44583" alt="Staging changes and promoting an agent to live" width="706" height="1442" data-path="images/image-68.png" />
</Frame>

## Max tool calls

Max tool calls limits how many tools an agent can call in one task. Use it to keep work bounded and avoid unnecessary tool usage.

## Per-task vs. per-agent budgets and alerts

Budgets cap spend at two levels: a per-task budget bounds a single run (good for research- or tool-heavy and recurring workflows), while a per-agent budget bounds spend across the agent’s activity over time (good for agents that run often or on schedules). Budget alerts sit alongside both, flagging unusual usage early without blocking work. Use the two limits together to bound cost, and turn on alerts for a heads-up before a limit is reached.

<Frame caption="Set per-task and per-agent budgets, and configure budget alerts.">
  <img src="https://mintcdn.com/xpanderai-099931d1/ZExbmT2Yknjn6o_V/images/image-67.png?fit=max&auto=format&n=ZExbmT2Yknjn6o_V&q=85&s=7ad2f2d84bc789a34ea11fe9257dc29f" alt="Per-task and per-agent budgets with budget alerts" width="662" height="912" data-path="images/image-67.png" />
</Frame>

## Notifications

Notifications keep agent work visible even when no one is watching the task run. They are useful for scheduled agents, background workflows, long-running jobs, and agents that send work to other systems.

<Frame caption="Notification settings let teams choose when to be alerted about successful runs, failed tasks, or workflows that need attention.">
  <img src="https://mintcdn.com/xpanderai-099931d1/ZExbmT2Yknjn6o_V/images/image-54.png?fit=max&auto=format&n=ZExbmT2Yknjn6o_V&q=85&s=a9ea97a6e8c52454e498b77f04cd3007" alt="Notification controls for custom agents" width="686" height="790" data-path="images/image-54.png" />
</Frame>

### On success

Success notifications tell users when a task completes. Use them when the result matters, but the user does not need to monitor every step.

> The daily market digest was generated and sent.

### On error

Error notifications tell users when a task fails, stops, or needs attention. Use them for workflows where failures should be noticed quickly, such as email delivery, approvals, data access, scheduled reports, or external API actions.

### Recommended pattern

Turn on notifications for agents that run in the background or complete work outside the main conversation. For interactive agents, users may only need error notifications. For scheduled or business-critical agents, success and error notifications can both be useful.