Skip to content

[No QA] [Hold for feature] [No QA] Update help docs for Release 3: Custom Agents #92128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MelvinBot wants to merge 11 commits into
base: main
Choose a base branch
from
Open

[No QA] [Hold for feature] [No QA] Update help docs for Release 3: Custom Agents #92128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
5a96fcb
Update help docs for Release 3: Custom Agents
MelvinBot May 30, 2026
1a3dd96
Revise Custom Agents documentation for clarity
stephanieelliott May 30, 2026
b77d0d1
Rename Custom-Agents.md to Create-and-Use-Custom-Agents.md
stephanieelliott May 30, 2026
4c15987
Update _routes.yml
stephanieelliott May 30, 2026
f478e03
Rename Create-and-Use-Custom-Agents.md to Create-and-Use-Custom-Agent…
stephanieelliott May 30, 2026
a34359d
Create index.html
stephanieelliott May 30, 2026
bab633b
Update Add-Approvals.md
stephanieelliott May 30, 2026
f0890d2
Update Custom Agent description in Workspace Rules
stephanieelliott May 30, 2026
09d7ee0
Update Create-and-Use-Custom-Agents.md
stephanieelliott May 30, 2026
2967000
Update Add-Approvals.md
stephanieelliott May 30, 2026
21923f2
Apply suggestions from code review
stephanieelliott May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/_data/_routes.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,11 @@ platforms:
icon: /assets/images/simple-illustration__concierge-bot.svg
description: Learn about Concierge AI and what it can do.

- href: ai-agents
title: AI Agents
icon: /assets/images/simple-illustration__concierge-bot.svg
description: Learn about Custom Agents and what they can do.

- href: workspaces
title: Workspaces
icon: /assets/images/shield.svg
Expand Down
195 changes: 195 additions & 0 deletions docs/articles/new-expensify/ai-agents/Create-and-Use-Custom-Agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
---
title: Create and Use Custom Agents
description: Create, configure, and manage AI-powered agents that act as approvers in your workspace approval workflows.
keywords: [custom agents, AI agent, workflow agent, approval agent, agent approver, automated approval, AI approver, workspace approver, custom approver, agent prompt, agent copilot]
internalScope: Audience is Workspace Admins and account owners. Covers how to create, configure, chat with, and delete custom agents, and how to add an agent as an approver in a workspace approval workflow. Does not cover Concierge AI, billing for agent credits, or personal agent usage in DMs.
---

# Create and Use Custom Agents

Custom Agents are AI-powered virtual members of your Expensify account that can act as approvers in your workspace approval workflows. They follow instructions you write to evaluate reports and approve or reject them according to your company's rules. This allows you to automate approval decisions that may be too complex for standard workflow rules.

Each agent has its own Expensify account with a profile, display name, and instructions you control. You can chat with an agent, copilot into its account to review what it's doing, and add it to a workspace as an approver.

---

## Who can use Custom Agents

Anyone with an Expensify account can create a Custom Agent.

To add a Custom Agent as an approver on a workspace:

- You must be a Workspace Admin.
- **Workflows** must be enabled.
- The Custom Agent must be a member of the workspace.

---

## How to create a Custom Agent

1. In the navigation tabs (on the left on web, on the bottom on mobile), click **Account**.
2. Click **Agents**.
Comment thread
stephanieelliott marked this conversation as resolved.
3. Click **New agent**.
4. Review the auto-generated profile image and display name. If needed, you can edit these later.
5. In the **Write custom instructions** field, enter the prompt, or instructions the agent should follow.
6. Click **Create agent**.

<!-- SCREENSHOT:
Suggestion: Settings > Agents page showing the Create agent button and the agents list with one example agent
Location: After the create agent steps
Purpose: Helps users find the entry point for creating an agent
-->

You can also create a Custom Agent from the **Set Approver** page by clicking **Create an agent**. Expensify automatically adds the new agent to the workspace as a member and assigns it as an approver.

After saving, the new agent appears in your **Agents** list with **Edit**, **Chat**, and **Copilot** buttons.

---

## How to write instructions for a Custom Agent

The prompt you share in the **Write custom instructions** field tells the agent what to do with each incoming report or chat message. Clear instructions help the agent approve or reject reports consistently.

Useful things to include in an agent's instructions:

- The agent's role (for example, "You review marketing team travel reports.").
- The conditions under which the agent should **Approve** a report.
- The conditions under which the agent should **Reject** a report and what feedback to leave.
- Any escalation rules — for example, "Approve reports under $500; for anything higher, leave a comment asking the submitter to confirm the business purpose."

Instructions are stored in Markdown, so you can use headings, bullets, and bold text to organize complex guidance.

**Example approval prompt:**

```
# Role

You review Marketing team travel reports.

# Approve when

- The report includes a business purpose.
- Each expense has a receipt.
- The total report amount is under $500.

# Reject when

- A receipt is missing.
- The business purpose is unclear.

When rejecting a report, leave a comment explaining what information is missing.
```
---

## How to chat with a Custom Agent

To open a direct conversation with a Custom Agent:

1. In the navigation tabs (on the left on web, on the bottom on mobile), click **Account**.
2. Click **Agents**.
3. Find the agent in the list and click **Chat**.

The agent will respond using its current instructions. Use this to test how the agent reacts to different scenarios before adding it to a workflow.

---

## How to Copilot into a Custom Agent account
Comment thread
stephanieelliott marked this conversation as resolved.

Each Custom Agent is its own Expensify account with a profile, inbox, chats, and activity history. When you create a Custom Agent, you become its owner and are automatically added as a full-access Copilot.

Use Copilot to see what the agent has done, review its activity, and inspect any actions it has taken on reports.

1. In the navigation tabs (on the left on web, on the bottom on mobile), click **Account**.
2. Click **Agents**.
3. Find the agent in the list and click **Copilot**.

[Learn more about Copilot](/articles/new-expensify/settings/Copilot-Access.md).

---

## How to edit a Custom Agent's instructions

You can edit an agent's profile image, display name, and instructions at any time.

1. In the navigation tabs (on the left on web, on the bottom on mobile), click **Account**.
2. Click **Agents**.
3. Click **Edit** on the agent you want to update.
4. Update the profile image, display name, or instructions.
5. Click **Save**.

Updated instructions apply to all future reports and chat messages the agent receives.

---

## How to delete a Custom Agent

Deleting a Custom Agent closes its Expensify account.

1. In the navigation tabs (on the left on web, and at the bottom on mobile), click **Account**.
2. Click **Agents**.
3. On the agent you want to remove, click **Delete**.
4. Confirm the deletion.

If the agent is currently set as an approver on any workflow, remove it from those workflows first. [Learn how to edit or delete a workflow](/articles/new-expensify/workspaces/Add-Approvals#edit-or-delete-approval-workflows).

---

## How to use a Custom Agent as an approver

Before you can select a Custom Agent as an approver, the agent must be a member of the workspace.

If the agent was created from a workflow setup flow, Expensify automatically adds it to the workspace. Otherwise, add the agent as a workspace member first.

[Learn how to add a Custom Agent to a Workspace](/articles/new-expensify/workspaces/Managing-Workspace-Members#invite-members-to-a-workspace).

Once an agent is added to a workspace as a member, you can select it as an approver anywhere you'd choose a person:

1. In the navigation tabs (on the left on web, on the bottom on mobile), click **Workspaces**.
2. Click your workspace name.
3. Click **Workflows**.
4. Click the workflow you want to edit, or click **Add approval workflow** to create a new one.
5. Click **Approver**.
6. Choose the agent from the list of workspace members.
7. Click **Save**.

The agent will receive each report submitted into the workflow and decide whether to **Approve** or **Reject** it based on its instructions.

For details on configuring approval workflows generally, [learn how to add approvals to a workspace](/articles/new-expensify/workspaces/Add-Approvals).

## What happens after a Custom Agent reviews a report

- The agent receives reports assigned to its approval step and evaluates them using its current instructions.
- When the agent approves a report, the workflow continues to the next approval step.
- When the agent rejects a report, the submitter receives the agent's feedback and can update and resubmit the report.

Changes you make to the agent's instructions apply to future reports and conversations. You can chat with the agent to test updated instructions before using them in a workflow.
Comment thread
stephanieelliott marked this conversation as resolved.

---

# FAQ

## Who can edit or delete a Custom Agent?

Only the agent's owner can edit its instructions or delete it. The owner is the account that created the agent.

## Are Custom Agents billed?

An agent is a member of any workspace it's added to and is billed as a workspace member like any other member. Usage-based billing for agent activity is not yet in effect at this release.

## Can I remove myself as a Copilot from a Custom Agent I created?
Comment thread
stephanieelliott marked this conversation as resolved.

No. The owner is permanently added as a full-access Copilot on the agent's account so you always retain access to review and update the agent.

## What happens if my agent approves or rejects a report unexpectedly?

Copilot into the agent's account, open the **AI Prompt** page, and review the current instructions. Adjust the instructions so the agent handles that scenario the way you want, then click **Save**.

## Can a Custom Agent be added to multiple workspaces?

Yes. An agent is a member like any other and can be added to as many workspaces as you'd like, and selected as an approver in each of their workflows.

## Can I use a Custom Agent in multi-step approval workflows?

Yes. On Control plans, Custom Agents can be used anywhere an approver can be selected, including multi-step approval workflows.

On Collect plans, workspaces support a single approver. A Custom Agent can be used as that approver.
8 changes: 8 additions & 0 deletions docs/articles/new-expensify/workspaces/Add-Approvals.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,14 @@ Set up default or custom approval workflows to route expenses through one or mor

**Note:** Custom workflows are only available on the Control plan. To enable custom workflows, upgrade to the Control plan in Settings > Billing & Subscriptions.

## How to Set a Custom Agent as Approver

You can select a Custom Agent as an approver in any workflow. Custom Agents are AI-powered virtual members that review reports and approve or reject them based on instructions you define.

Custom Agents are added to workspaces and assigned as approvers the same way as other workspace members. Once a Custom Agent is a member of the workspace, you can select it anywhere you would normally choose an approver.

[Learn how to create and use Custom Agents](/articles/new-expensify/ai-agents/Create-and-Use-Custom-Agents).

Comment thread
stephanieelliott marked this conversation as resolved.
---

## Edit or Delete Approval Workflows
Expand Down
2 changes: 2 additions & 0 deletions docs/articles/new-expensify/workspaces/Workspace-Rules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ Workspace Rules let Admins enforce expense policies by setting custom requiremen

You can also [add text or a PDF expense policy document](/articles/new-expensify/workspaces/Add-an-Expense-Policy-to-a-Workspace) to your workspace overview page so members can reference your company's expense guidelines.

If your approval requirements can't be handled using workspace rules alone, you can use a Custom Agent as an approver in your workflow. Custom Agents are AI-powered virtual members that review reports and approve or reject them based on instructions you define. [Learn how to create and use Custom Agents](/articles/new-expensify/ai-agents/Create-and-Use-Custom-Agents).

---

## How to enable Workspace Rules
Expand Down
6 changes: 6 additions & 0 deletions docs/new-expensify/hubs/ai-agents/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
layout: default
title: AI Agents
---

{% include hub.html %}
Loading