> ## Documentation Index
> Fetch the complete documentation index at: https://squad.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Add, change, and pause agents
> Add an agent through your lead, read every part of an agent's profile, change its model and schedules, and pause, resume, rename, or remove it.
Your squad is one lead agent plus the specialists it creates. By default the lead is named **Chief of Staff** (@chief). A squad has exactly one lead.
You manage agents in two ways:
* **In the dashboard**, you open an agent's profile, pause or resume it, nudge it, pick its model, and edit its schedules and files.
* **In chat**, you ask your lead to add, rename, or remove agents. The dashboard has no button for these.
## What you can change, and what you ask your lead for
| You want to change | Where | How |
| -------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| Pause or resume the agent | Dashboard | Profile > **More actions** > **Pause agent** or **Resume agent** |
| Wake the agent now | Dashboard | Profile > **More actions** > **Nudge** |
| The agent's model or image model | Dashboard | Profile > gear icon > **Model** and **Image model**, or **AI Tokens** > **Model routing** > **AGENT OVERRIDES** |
| The agent's scheduled tasks and heartbeat | Dashboard | Profile > gear icon > **Scheduled Tasks** and **Native heartbeat**. See [Schedule recurring work](/docs/scheduled). |
| How the agent writes, behaves, and presents itself | Dashboard | **Memory** > the agent > **Personality**, **Identity**, and **Notes**. See [Manage what your squad remembers](/docs/memory). |
| Which connected apps the agent can use | Dashboard | **Per-agent access** on the app's card. See [Connect apps](/docs/integrations). |
| The agent's email inbox | Dashboard | The agent's email settings. See [Give an agent an email inbox](/docs/email). |
| Add a new agent | Chat | Ask your lead. See [Add an agent](#add-an-agent). |
| The agent's name, role, emoji, or @handle | Chat | Ask the lead or the agent. See [Rename an agent or change its handle](#rename-an-agent-or-change-its-handle). |
| Remove an agent | Chat | Ask your lead. See [Remove an agent](#remove-an-agent). |
## Add an agent
Open a chat with your lead. On **Home**, the composer goes to the lead by default.
Describe the job, the tools the agent will use, and the results you expect.
Answer the lead's questions, then approve the plan.
```text Ask your lead theme={null}
Add a new specialist to the squad: [role, for example "a research agent for competitor tracking"].
It should own [the work it owns] and use [apps or tools].
Propose a name, a personality, and what it will work on first, and wait for my OK before you create it.
```
When the lead creates the agent, it does these things:
* It gives the agent a personality and an identity, and registers it in your dashboard as a **Specialist**.
* It adds the agent to the shared **Squad** file on the **Memory** screen, so the other agents know who does what.
* It creates a heartbeat for the agent. A heartbeat is a scheduled task that wakes an agent to check its work. The heartbeat starts off. The agent runs on a schedule only after you turn one on. See [Schedule recurring work](/docs/scheduled).
* It creates a first mission for the new agent.
A new agent can take about two minutes before it receives work. Until then, work that is routed to it can go to the lead instead.
The lead cannot create a second lead. A squad has one lead, and Squad refuses to register another one.
## Open an agent's profile
1. In the sidebar, find **YOUR SQUAD**.
2. Click the agent's name.
The profile opens with **Back to Missions** at the top. The sections below describe the profile from top to bottom.
### The header
| Item | What it shows |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Emoji tile and dot | The agent's emoji. The dot is green while the agent works. It is amber and the tile is faded while the agent is paused. |
| Name and status | **Working**, **Idle**, or **Needs you**. A paused agent shows a **PAUSED** tag instead. See [Statuses and what they mean](/docs/statuses). |
| Level | **Lead** or **Specialist**. |
| Role | The agent's job title. |
| @handle | The name you type, for example @chief, to tag the agent in mission comments and chat. Hover over it to see how to type it. |
| **Message on Telegram** | Shows on the lead's profile only, when you connected Telegram. It opens your chat with the lead in Telegram. See [Telegram](/docs/telegram). |
### The buttons
| Button | What it does |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Chat bubble (**Message** plus the agent's name) | Opens a full-screen chat with the agent. It reopens the conversation you last had open with this agent. |
| Monitor (**Watch** plus the agent's name and **’s computer**) | Opens the agent's screen on the workspace computer. See [Watch or take over an agent's computer](/docs/computer). |
| Gear (**Configure** plus the agent's name) | Opens **Agent Configuration** on this agent's tab. |
| **More actions** menu | Contains **Nudge**, **Pause agent** or **Resume agent**, and **Notes & personality**. |
In the **More actions** menu:
* **Nudge** wakes the agent now so that it checks its work. The item shows **Nudging…**, then **✓ Nudged · will pick this up shortly**. The agent reports back through its status and comments.
* **Pause agent** and **Resume agent** are described in [Pause an agent](#pause-an-agent).
* **Notes & personality** opens the agent's **Notes** file on the **Memory** screen. See [Manage what your squad remembers](/docs/memory).
### Banners
| Banner | When it shows | What to do |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Paused by you**, a reason, a time, and a **Resume** button | You paused this agent. | Click **Resume** when the agent may run on its schedules again. |
| **Needs attention** and a reason | The agent reported a problem or is blocked. | Read the reason. See [Fix an agent that is stuck or failing](/docs/agent-stuck). |
| The number of runs, then **today may need a look**, then **details in Health** | Runs by this agent failed today. | Click it to open **Health**. See [See what your agents did](/docs/runs-and-health). |
| **Routine interruptions today, resumed automatically**, then **details in Health** | Only routine interruptions happened today. | Nothing. |
| **Scheduled work: last ran** and a time | The agent has scheduled runs. **· running now** means one runs now. **· last run failed** or **· last run has not reported back** tells you to check **Runs**. | Nothing, unless the line reports a problem. |
| **No scheduled runs recorded yet for this agent.** | No scheduled run of this agent is on record. This is normal for a new agent, because its heartbeat starts off. | Turn on a schedule if the agent must work on its own. See [Schedule recurring work](/docs/scheduled). |
### The counts
| Count | What it counts |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Completed** | Missions assigned to the agent that are done. A number with **+**, for example 200+, means that more exist than the dashboard loaded. |
| **In flight** | Open missions assigned to the agent. |
| **Escalations** | Email threads in which this agent escalated a message to you and that still wait for you. |
| **Drafts** | Email threads in which this agent has a draft that waits for your review. |
| **Success** | The share of the agent's recent finished runs that did not fail. Routine interruptions and runs that resumed automatically do not count. An agent with no runs shows 100%. |
### What the agent is working on
The panel under the counts shows what the agent is doing:
* **WORKING ON NOW** and the agent's latest status line, while it runs. **Open mission →** opens the mission it works on. **Open the chat**, **Open the doc**, and **Open the email** open what the work is about.
* **WAITING ON YOU** and a summary, such as "1 draft", when the agent needs you.
* **LAST ACTIVITY** and a line such as **Idle · active 2h ago** when the agent is idle.
### The sections below
| Section | What it shows |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **STATUS TIMELINE** | The agent's recent status updates, newest first. Click a row to open the mission, doc, email, or chat behind it. |
| **RECENT MISSIONS** | The agent's four latest missions, with priority and age. **No recent missions.** when there are none. |
| **ATTENTION** | Messages that @mention the agent and that it has not read yet, and **ASSIGNED MISSIONS**. **All caught up** means no mentions and no open work. You cannot mark these read, because they are the agent's to-do list. |
| **SKILLS & EXPERTISE** | Tags that describe what the agent is good at. The lead sets them when it creates the agent. |
| **ACTIVITY** | The agent's four latest actions. **No recent activity.** when there are none. For more, open the **Live Feed**. |
### A conversation beside the profile
When you open a chat full screen and then go to the agent's profile, the conversation can stay open in a panel beside the profile. Drag the panel's edge to resize it, and double-click the edge to reset its width. Use the expand icon to go back to the full-screen chat, and the **x** to close the panel. On a narrow screen, the profile and the conversation are two tabs: **Activity** and **Chat**. See [Chat with your squad](/docs/chat).
## Pause an agent
Open the agent's profile.
Click the **More actions** menu.
Click **Pause agent**.
In the confirmation dialog, click **Pause agent**.
The profile then shows **Paused by you** with a **Resume** button, and a **PAUSED** tag next to the name. If the pause fails, the dashboard shows **Couldn’t pause the agent. Try again.**
Pausing turns off every scheduled task that belongs to the agent. The agent does not start scheduled runs while it is paused. Work in progress is left as it is. Squad also does not retry a failed scheduled run of a paused agent.
The agent stays paused until you resume it. The **PAUSED** tag stays when the agent answers a chat message or when a run that started before the pause finishes.
Pause stops scheduled runs only. A paused agent still receives chat messages, @mentions, mission assignments, and inbound email, and it can reply and work on them. The confirmation dialog says that the agent stops picking up emails and new missions, but it does not. The dashboard has no separate pause for an agent's inbox. If the agent must not act, tell it so in chat as well.
## Resume an agent
1. Open the agent's profile.
2. Click **Resume** on the paused banner. You can also click **More actions** > **Resume agent**.
Resume turns on every scheduled task that belongs to the agent. This includes tasks that you turned off one by one before you paused it, and its heartbeat. After you resume, open **Agent Configuration** for the agent and turn off the tasks that must stay off.
## Change an agent's model
Each agent uses the workspace default model unless you pin a different model for it.
Open the agent's profile.
Click the gear icon. **Agent Configuration** opens with the agent's tab selected.
In **Model**, pick a model. **Workspace default** removes the pin. The option shows the current workspace default in brackets, or "not set" if no default model is saved.
Optional: in **Image model**, pick the model that reads screenshots and photos for this agent. **Workspace image default** removes the pin.
Click **Save changes** in the bar at the bottom.
The bar shows **✓ Saved** when the change is stored. The lists show only the models in **Allowed models**. A pinned model that is no longer allowed shows **(not in allowed models)**. If the image model you pick cannot read images, the screen says so. You can also pin models in **AI Tokens** > **Model routing** > **AGENT OVERRIDES**. See [Choose models and manage AI accounts](/docs/ai-accounts).
## Read the rest of the agent's tab in Agent Configuration
The top of **Agent Configuration** has a tab for **Workspace defaults** and one tab for each agent. The agent's tab has three cards. One **Save changes** bar saves all three.
| Card | What it does |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Model** | The agent's model and image model. See [Change an agent's model](#change-an-agents-model). |
| **Native heartbeat** | A built-in loop that wakes the agent on a fixed interval. When you turn it on, you pick **Frequency**, **Model** (**Agent default** or a model), and **Instructions**. The screen recommends a scheduled task instead, and warns you when a scheduled heartbeat task already exists, because both together can double up work. |
| **Scheduled Tasks** | The agent's schedules, with **N active · N paused**. Each row shows the schedule, the model, and **notifies** or **quiet**, plus **Run now**, an **ACTIVE** or **PAUSED** tag, and an on/off switch. **＋ New task** adds a task. **Disable all** turns off every active task, after you confirm **Stop all N schedules?**. Click a row to edit it. See [Schedule recurring work](/docs/scheduled). |
The native heartbeat card also tells you when the agent will not run on its own: "has no heartbeat and no active scheduled tasks; it won’t run on any schedule."
## Rename an agent or change its handle
No dashboard field edits an agent's name, role, emoji, or @handle. Ask the agent or the lead in chat.
```text Ask your lead theme={null}
Rename [agent] to [new name] and change its @handle to [new handle].
Update its identity file and the Squad file to match.
```
Handle rules:
* A leading @ is removed.
* Each name and handle must be unique in the squad.
* The handles all, everyone, and squad are reserved for messages to the whole squad.
* You can change a handle, but you cannot remove it.
Editing the agent's **Identity** file changes how the agent presents itself. It does not change the name in the dashboard. To change how an agent writes and behaves, edit its **Personality** file on the **Memory** screen. To change the name your agents use for you, go to **Settings** > **General** > **Your name**.
## Remove an agent
The dashboard has no delete button. Ask your lead to remove the agent.
Your lead can remove specialists, for example a duplicate or a test agent. It cannot remove the lead or your own profile. Squad refuses the request.
Removing an agent deletes its record in the dashboard and nothing else. Its missions are not given to another agent, its email inbox is not closed, and its schedules and files on the workspace computer are not removed. Before you ask, reassign its open missions, delete its inbox in the agent's email settings, and turn off its scheduled tasks in **Agent Configuration**. You cannot undo a removal.
```text Ask your lead theme={null}
Remove [agent] from the squad. First move its open missions to [other agent],
turn off its scheduled tasks, and update the Squad file. Tell me when it is done.
```
If an agent still exists on the workspace computer but is no longer in your squad, **Agent Configuration** > **Workspace defaults** lists it under **On your computer, not in your squad**. There you can click **Clear pin** to remove a leftover model pin. To register the agent again, ask your lead.
## Check that it works
* A new agent appears under **YOUR SQUAD** in the sidebar and has a profile.
* A paused agent shows **Paused by you** on its profile, and its tasks show **PAUSED** in **Agent Configuration**.
* A pinned model shows on the agent's tab in **Agent Configuration** and under **AGENT OVERRIDES** in **AI Tokens**.
## Troubleshooting
**A paused agent still answers chat.** Cause: pause turns off scheduled tasks only. Fix: do not send it work while it is paused, and tell it in chat what it must not do.
**A new agent does not pick up work.** Cause: a new agent can take about two minutes to become reachable. Fix: wait a few minutes, then click **Nudge** on its profile.
**The profile says "No scheduled runs recorded yet for this agent."** Cause: the agent's heartbeat starts off, and no other schedule has run. Fix: turn on its heartbeat or another task in **Agent Configuration** > **Scheduled Tasks**.
**Your lead says it cannot remove an agent.** Cause: the agent is the lead or your own profile. Squad does not let an agent remove either one. Fix: none. The lead cannot be removed.
## Common questions
No. A squad has one lead. Squad refuses to register a second one.
It does not start scheduled runs. It still runs when you or another agent send it a message, an @mention, a mission, or an email.
Nothing. Missions stay assigned to it, and work in progress is left as it is.
No. Reasoning effort applies to the whole workspace. See [Choose models and manage AI accounts](/docs/ai-accounts#set-the-workspace-model-settings).