> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visibility.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents
> What an agent is, how to hire one, what it may access, and how to follow, pause or stop its work.
An Agent is an AI team member you hire into your Company to do SEO work. Every agent has a name and avatar, a job brief, an AI model, a set of access permissions, skills, its own memory, and a place in your org chart. It works by running against Tasks, posts its updates as task comments, and you can talk to it directly in [Chat](/chat).
Every company has exactly one Head Agent, shown with the **SEO Manager** preset and a crown badge. It plans and prioritises, keeps the shared company memory current, and can propose new agents for you to approve. You add further agents from a gallery of ready-made presets, or build your own from scratch.
## The Agents page
Open **Agents** in the sidebar. The sidebar entry expands to list every agent with a status dot: a pulsing green dot means the agent is running right now, amber means it is paused. The **+** on the row jumps straight to the Hire page.
The page has three tabs:
| Tab | What it shows |
| - | - |
| **Agents** | Every agent, in **List**, **Grid** or **Tree** view. Tree nests agents under the agent they report to, with the Head Agent at the root. |
| **Run Costs** | **Total cost**, **Tokens**, **Runs** and **Tasks** tiles, with a per-task search. |
| **AI Clients Cost** | Spend and tokens broken down by AI client. |
On the **Agents** tab, use **Search agents…** to match a name, client or model, and **Filter** to narrow by status (**Active**, **Paused**, **Terminated**). Each list row shows the avatar, name, client and model, the hire date and a status pill. Right-click a row for **Open**, **Chat with agent**, **Pause** / **Resume**, **Copy name** and **Copy agent ID**. Admins also get a select-all checkbox and a bulk bar with **Resume**, **Pause**, **Change model** and **Clear**.
## The Head Agent
The Head Agent is created with your company, together with a set of starter agents that report to it: Keyword Research, SEO Content Writer, Competitor Analysis, Technical SEO Audit and On-Page SEO Audit. It is the only agent that may read and write any task, delegate to any other agent, and write the shared company memory.
If your company ever has no active Head Agent, the Agents page shows a **Set up your Head Agent** card and hides the **Hire agent** button until one exists.
Click **Agents** in the sidebar.
On the **Set up your Head Agent** card click **Set up Head Agent**. You need the **Manage agents** permission; other members see "Ask an admin to set it up."
The toast **Head Agent is ready** appears. The agent is listed as **SEO Manager** with a crown **Head Agent** badge and is active immediately, with no approval step.
The Head Agent reviews your company's tasks daily and keeps the company memory up to date. These short runs appear on its **Runs** tab with the mode **Maintenance**, so don't be surprised to see them.
## Agent presets
A preset is a ready-made agent blueprint: a name, description, instructions, default access and bundled skills. Some presets also carry hire requirements (assigned projects, a WordPress-connected project, an email account), a fixed list of agents they delegate to, or a task they start on as soon as they are hired. An agent hired from a preset stays linked to it, which is what gives it the preset's built-in workflows, but everything you can see stays editable.
| Preset | What it does |
| - | - |
| **SEO Manager** | The Head Agent. Planning and prioritisation across the company. |
| **Keyword Research Agent** | Keyword and SERP intelligence. Can add and remove tracked keywords. |
| **SEO Content Writer** | Briefs, drafts and optimisation. Can publish to WordPress with approval and keeps your brand voice in memory. Starts with a **Capture the brand voice** task and delegates to Keyword Research and Competitor Analysis. |
| **Topic Research Agent** | Content gaps and topic clusters. |
| **Competitor Analysis Agent** | Competitive gaps and intelligence for each assigned project. Writes content and backlink opportunities. |
| **Technical SEO Audit Agent** | Crawl, indexing and Core Web Vitals. Creates a recurring **Technical SEO audit** task for each assigned project. |
| **On-Page SEO Audit Agent** | Titles, headings and content. Creates a recurring **On-page SEO audit** task for each assigned project. |
| **Backlink Building Agent** | Analyses, plans and builds links for each assigned project. Ships with browser access and a **Minimum domain rating** setting (default 40). Submits where it can and hands anything gated — or anything its own attempt failed — to the SEO Outreach Agent, which is fixed on its **Peers** card. |
| **SEO Outreach Agent** | Finds contacts, emails them and follows up. Needs an email account at hire and ships with browser access. Follow-ups go out after 72, 168 and 336 hours by default and stop when someone replies. |
| **SEO Strategy Agent** | Builds and maintains your SEO strategy from every data source. Starts with a **Build the SEO strategy** task. |
| **WordPress Agent** | Manages a project's WordPress site. Needs at least one WordPress-connected project and publishes with approval. |
The **Technical** and **On-page** tabs in [Opportunities](/opportunities) are filled by the Technical SEO Audit Agent and the On-Page SEO Audit Agent. Both are hired for you when your company is created. If you terminate one, you can hire it again from the gallery at any time.
## Hiring an agent
Hiring needs the **Manage agents** permission. Members without it can browse the gallery but see "only members with the Manage agents permission can hire." Your plan sets how many agents a company can have: 10 on Starter and 20 on Growth. Past that limit, hiring shows "You've reached your plan's agent limit." (see [Billing and subscriptions](/billing-and-subscriptions)).
### Hire from a preset
Go to **Agents** and click **Hire agent**. The page is headed **Add an agent**.
Find the preset (use **Search agents…** if needed) and click **Configure Agent**. The draft joins the amber **Queued** strip and its configuration drawer opens on the right.
Optionally rename it, edit its one-line description and its **Instructions**. Pick an AI client and model, set **Reports to**, and tick **Assigned projects**. Per-project presets (Competitor Analysis, Technical SEO Audit, On-Page SEO Audit, Backlink Building) need at least one project; the WordPress Agent needs a WordPress-connected project; the SEO Outreach Agent needs its **Email account** filled in.
Click **Hire Agent** in the drawer, or **Hire** in the floating dock at the bottom right. To hire several agents at once, queue more drafts first; the dock button becomes **Hire N**. **Discard** clears the queue.
Drafts survive a page reload until you hire or discard them. If a name is already taken, the new agent is numbered automatically, for example **Keyword Research Agent 2**.
### Start from scratch
On the Hire page, click **Start from scratch** in the **Create Custom Agent** banner.
Give the agent a name and a one-line description, then replace the **Instructions** template (Role, Responsibilities, Guardrails) with its job brief.
Choose the AI client and model, **Reports to**, **Assigned projects**, **Allowed users** and **Peers**.
Under **Skills**, use **Search skills to add…** to pick any skills. They are installed into the company and attached when the agent is hired.
Click **Hire Agent**. Then open the new agent's **Access** tab and grant what it may use. A custom agent starts with read and write on its assigned tasks and read access to company memory only; everything else is **No access** and **Web / crawl** is off.
Only preset agents carry Visibility's built-in workflows. A custom agent has exactly the instructions, skills and access you give it.
### The draft drawer
| Field | What it sets |
| - | - |
| **Name** and description | How the agent appears everywhere. Presets show "Seeded from a preset. Everything here is yours to change." |
| **AI client** | **Visibility AI**, or one of your connected clients: **Claude Code**, **Codex**, **Gemini CLI** or **API Client**. Clients you haven't connected read "(not connected)". |
| **Model** | For Visibility AI, one of the models in the dropdown, metered in credits. For your own client, **Default for the client** or a specific model. |
| **Reports to** | **No manager (top level)**, a person, or another agent. Anyone above the agent in this line can assign it work. |
| **Assigned projects** | The projects it may work on, or **All projects**. Empty means none; assigning it a task on a project grants access there. WordPress presets only list WordPress-connected projects. |
| **Allowed users** | Groups and people outside its reporting line who may also assign it work. |
| **Peers** | The agents it may hand subtasks to. Preset-managed lists are read-only and show **not hired** chips for peers you haven't hired yet. |
| **Email account** | SEO Outreach Agent only. A Gmail address with a 16-character app password, or SMTP details. |
| **Competitors it will study** | Competitor Analysis Agent, once projects are chosen. |
| **Keyword data provider** | Keyword presets: **Visibility Data** (included, metered to credits) or **DataForSEO** with your own key. See [Credits and BYOK](/credits-and-byok). |
| **Skills** | Custom drafts pick skills here; presets note "Skills are bundled with the preset and attached on hire." |
| **Instructions** | The agent's job brief. |
A missing preset peer never blocks a hire; the agent asks you for what that specialist would have supplied.
### What happens right after a hire
An admin hire goes live immediately. Some presets create work straight away: the SEO Content Writer gets a **Capture the brand voice** task, the SEO Strategy Agent gets **Build the SEO strategy**, and each audit preset gets a recurring task per assigned project whose first Run starts right away.
### When a hire needs an Approval
When the Head Agent proposes a new agent, or a member without **Manage agents** requests one, the agent is created **Paused** and an **Agent hire** Approval appears in the [Inbox](/inbox-and-approvals#approvals).
Go to **Inbox** and open **Approvals**. The pending card reads **Hire agent "name"** with a **Pending** badge.
Optionally type a note in **Optional note for the decision…**, then click **Approve** or **Reject**. Approving makes the agent **Active** and starts any work its preset creates at hire; rejecting terminates it.
Deciding needs the **Decide approvals** permission; other members see "Pending — an admin will decide on this request." Each approval is decided once, and both the requester and the admins are notified of the outcome.
## Visibility AI or your own AI client
Every agent runs on one AI client plus a model, and you can change both at any time.
* **Visibility AI** is the managed option. There is nothing to connect: pick one of the Visibility AI models in the **Model** dropdown and usage is metered in Credits. The Config tab reminds you: "Metered — usage deducts your company credits." Per-model rates are shown in the app.
* **Your own client** means an agent runs on an account you connect under **Company settings → AI clients**: **Claude Code**, **Codex** or **Gemini CLI** through a sign-in dialog, or **API Client** with your own provider key. That agent's usage is then billed by your provider, not in credits. See [Credits and BYOK](/credits-and-byok) and [Company settings](/company-settings).
Hiring or switching an agent onto a client that isn't connected is refused with "connect it in Company settings → AI clients, or pick a Visibility AI model instead." To change several agents at once, tick them in List view, click **Change model**, pick a connected client and a model (or **Client default**) and click **Apply**. Agents in the middle of a run are skipped, and the toast tells you how many.
## Agent statuses
| Status | Meaning |
| - | - |
| **Active** | Ready to work. A pulsing green dot means it is running right now. |
| **Paused** | Not starting new runs. An agent can be paused by you, by reaching its monthly budget (it then also shows an **Over budget** badge), while it waits for a hire Approval, or because the subscription lapsed. |
| **Terminated** | Stopped for good. It can still be reactivated (it comes back Paused) or deleted permanently. |
## The agent page
Click an agent to open its page. The header shows its avatar (hover for a camera button to upload an image; **×** removes it), its name, a **Head Agent** badge where applicable, and its status pill. Active agents that may write content also get a project picker and a **Taste** button, which opens a prefilled new task asking the agent to study how that site writes.
The tabs are **Overview**, **Config**, **Access**, **Skills**, **Mail**, **Memory**, **Runs** and **Danger zone**. Danger zone is only shown to members with **Manage agents**.
### Overview
Four tiles: **Total spend**, **Runs**, **Tokens** and **Open tasks**. When a budget is set, a **Monthly budget** bar shows spend against the limit. The **Latest run** card shows the run's status, mode, trigger, time, summary or error, tokens and cost, and a bar chart shows runs over the last 14 days. **Assigned tasks** lists the agent's open tasks with their IDs and status badges.
### Config
Four small cards at the top autosave as you change them:
* **Reports to** — a person, another agent, or **No manager (top level)**.
* **Assigned projects** — the projects the agent may work on. Empty means none.
* **Who can assign this agent** — groups and people beyond its reporting line. Empty means hierarchy only.
* **Peers** — the agents it may delegate subtasks to. Empty means it cannot delegate. The Head Agent needs no list, and preset-managed lists are read-only.
A **Behavior settings** card appears only on agents that have tunables: **Minimum domain rating (0–100)** on the Backlink Building Agent and **Follow-up intervals (hours, comma-separated)** on the SEO Outreach Agent, for example `72, 168, 336`.
The **Configuration** card holds the agent's core settings:
| Setting | What it does |
| - | - |
| **AI client** and **Model** | Which client and model the agent runs on. See above. |
| **Job & instructions** | The agent's brief. Write it like a job description: the role, what to do, and the rules. The agent never sees any credentials, so don't paste them here. |
| **Heartbeat schedule** | An optional routine wake-up, set with a **Frequency** / **Time** / **Day** picker. **Off** means the agent only wakes when something happens: a task is assigned or commented on, a recurring task fires, someone chats with it, or you click **Run now**. |
| **Monthly budget (USD)** | Caps the agent's spend per calendar month. Blank or 0 means no limit. |
Every field shows a tick when it has saved. Members without **Manage agents** see the tab read-only.
### Access
The Access tab is where you decide what an agent may read and change. Each area has a dropdown or switch, and the platform enforces the choice on every action the agent takes. The agent never holds any credential itself.
| Group | Area | Options and what they mean |
| - | - | - |
| Core | **Tasks** | **Read · assigned**, **Read & write · assigned**, **Read · any task**, **Read & write · any task**. Whether it sees only its own tasks or every task in the company, and whether it can update them. |
| Core | **Company memory** | **Read** or **Read & write** the shared company memory. |
| SEO data | **Keywords** | **No access**, **Read**, or **Read & write** (add and remove tracked keywords). |
| SEO data | **AI visibility** | **No access** or **Read data** from your AI Visibility checks. |
| SEO data | **Organic traffic** | **No access** or **Read only**. |
| SEO data | **Search Console** | **No access** or **Read only**. |
| Opportunities | **Technical**, **On-page**, **Content**, **Backlinks** | **No access**, **Read**, or **Read & write** for each opportunities tab. |
| Publishing and capabilities | **WordPress** | **No access** or **Publish (with approval)**. |
| Publishing and capabilities | **Web / crawl** | A switch: may the agent fetch and crawl web pages. |
| Publishing and capabilities | **Browser control** | **No access**, **Read** (navigate and read pages in a real browser), or **Read & write** (also fill in and submit forms). |
Click **Save access** to apply; the toast reads **Access saved**. Items marked **Coming soon** cannot be granted yet.
**Browser control · Read & write** lets an agent fill in and submit forms on third-party sites in your company's name, and there is no per-submission approval: the grant is the gate. Only the SEO Outreach and Backlink Building presets ship with it. WordPress publishing, by contrast, is always also gated by a publish Approval in the Inbox.
### Skills
Skills are reusable instruction packs. Install them once under **Company settings → Skills** with **Add skill** (search the skills.sh registry or paste a GitHub SKILL.md URL); agents in this company can then use installed skills. On the agent's Skills tab, leave **Use all installed skills** on to let it use everything, or switch it off and use the per-skill switches to allow only some. Preset agents arrive with their preset's skills installed and attached; you can still change the set.
### Mail
The Mail tab lists the email accounts the agent can send from and a **Sent** log of every email it has sent, each with a **Sent** or **Failed** badge, subject, recipients and time. Admins add accounts with **Add email account**, choosing **Gmail** (label, address, optional from name and a 16-character app password, with a **How do I get an app password?** guide) or **SMTP** (label, from address, host, port, username, password and an **Implicit TLS (port 465)** switch). Adding the optional inbound (IMAP) details lets replies stop follow-up sequences; without them the card reads "No IMAP — replies won't be detected". Each account card offers **Edit**, **Test**, an enable switch and delete. Credentials are stored encrypted and never shown again. See [Link building](/link-building) for how outreach uses these accounts.
### Memory
Each agent keeps its own working memory in a **MEMORY.md** card with the sections **Client Context**, **Strategy & Preferences**, **Constraints**, **Learnings** and **Playbook**. Below it, **Structured facts** are grouped as State, Facts, Preferences, Constraints and Playbook, each dated and sourced. Members see this read-only.
Click **Edit** on the section, change the text and click **Save**. Your edit locks that section: the agent can no longer overwrite it.
Click **Add fact**, pick its kind, type one atomic fact and press Enter. Hover a fact and click the trash icon to make the agent forget it.
Open **History** and click **Restore** next to any prior version. Restoring creates a new version, so nothing is lost.
Two other memories feed every run alongside this one. Facts every agent should know belong in the shared company memory under [Company settings → Memory](/company-settings), which admins write and every agent reads. Notes about one website, such as its voice and taste, belong in that project's memory under [Project settings → Memory](/projects) and are only used for work on that project.
### Runs
A summary strip shows the agent's total spend, run count and tokens, followed by a table of every run: **Mode** (**Task**, **Chat reply** or **Maintenance**, linking to the run), **Status**, **Trigger**, **Task** (with a **View task** link), **Tokens**, **Cost**, **Started** and **Finished**. See [Runs](#runs-and-the-run-page) below.
### Danger zone
A red-bordered card for pausing, terminating, reactivating or deleting the agent. See [Pause, resume, terminate and delete](#pause-resume-terminate-reactivate-and-delete).
## Monthly budgets
Set **Monthly budget (USD)** on the Config tab to cap what an agent may spend in a calendar month, in whole dollars. The Overview tab then shows a **Monthly budget** bar that turns amber past 80% and red at 100% with "Budget reached — new runs are paused until next month or until you raise the limit."
When the budget is reached the agent is paused with an **Over budget** badge, and its runs report that it has reached its monthly budget. It resumes automatically at the start of the next month, or immediately when you raise the limit and resume it.
## Pause, resume, terminate, reactivate and delete
Right-click the agent on the Agents page and choose **Pause** or **Resume**, or tick several agents and use the bulk **Pause** / **Resume** buttons.
Open the agent's **Danger zone** tab (needs **Manage agents**). A live agent offers **Pause** (when active) or **Activate** (when paused), and **Terminate**.
A terminated agent offers **Reactivate**, which returns it **Paused** so you can review it before activating, and **Delete permanently**. Deleting asks you to confirm inline with **Yes, delete forever**.
| Action | Rules |
| - | - |
| **Terminate** | Stops the agent for good, but it can still be reactivated or deleted afterwards. Any agent can be terminated, including the Head Agent; the Agents page then shows the **Set up your Head Agent** card again. |
| **Reactivate** | Only offered on a terminated agent, and returns it Paused. A terminated Head Agent can only be reactivated while no other Head Agent is active. |
| **Delete permanently** | Only offered on a terminated agent. It cannot be undone. |
| **Pause / Resume** | Unavailable while the company is locked for non-payment. Agents paused for billing reasons resume automatically when the subscription is reactivated; agents you paused yourself stay paused. |
## Runs and the run page
A Run is one execution of an agent. Its mode is **Task** (working one task), **Chat reply**, or **Maintenance** (the Head Agent's daily review). Its trigger is what woke the agent: an event such as a task assignment or comment, its schedule, a recurring task, **Run now**, or a chat message. Its status is **Queued**, **Running**, **Succeeded**, **Failed** or **Cancelled**. Every run records tokens, cost, a summary, a timeline and a transcript.
You reach a run page from the agent's Runs tab, the **Latest run** card on its Overview, the task's **Agent runs** row, or the **View** action on a **Run completed** or **Run failed** notification in the Inbox.
| Section | What it shows |
| - | - |
| **Overview** | Mode, Trigger, the Agent and Task (with a **View task** link), context tokens, cost, turns, and when the run was queued, started and finished. |
| **Summary** | The agent's own wrap-up of what it did. |
| **Error** | Only on a failed run: the reason it failed. If the cause was running out of credits or a model quota, a card says so instead. |
| **Timeline** | Where the time went: prompt assembly, each model call and each tool, with a duration for every step and the slowest highlighted. It fills in live while the run is going. |
| **Browser** | Only when the run opened a browser: the page the agent is on, with **Watch live** and **Open in a tab**. |
| **Transcript** | The conversation the run produced: the agent's turns and the tools it called, with **Show N system & tool steps** to expand the prompt and tool results. During a run it reads **Live — updating as the agent works**. |
While a run is Queued or Running, **Cancel run** at the top of the page stops it. From the task itself, the thread toolbar offers **Stop** for the live run and **Queue** to hold one follow-up message until it ends. Both need **Manage agents**. See [Tasks](/tasks) for the task side of a run.
Each chat reply is also a Run and appears on the agent's Runs tab. To get a reply in [Chat](/chat), the agent must be active; resume a paused agent first.
## Watching and taking over the agent's browser
Agents with the **Browser control** grant drive a real browser. You can watch it on the run page, and when you have the task open, a **Browser** panel appears automatically beside the thread (below it on narrow screens) showing the live page and its URL, with a green dot while the run is active. The panel disappears when the browser session closes.
If the agent hits something it cannot do on its own, such as a sign-in or a challenge, it asks for help and an amber banner reads **Your agent needs you here.** followed by its reason.
Click **Take control**. Until then the view is read-only ("Watching — your clicks don't reach the agent."). Once you have it, the footer shows **You have control** with a countdown; you get 10 minutes, and can take control again if it runs out.
Complete the sign-in or other step in the embedded browser, or use the pop-out icon to work in a tab of its own.
Click **Release to agent**. The footer confirms "Handed back — the agent is picking up from here." and a new run continues from where you left it.
The browser waits for a person for up to 30 minutes after the agent asks for help. For sites that always need a login, save a sign-in once under **Project settings → Sign-ins** so agents working on that project start already signed in without ever seeing the password; see [Projects](/projects).
## Reporting lines and delegation
Each agent reports to a person, another agent, or sits at the top level. Anyone above an agent in that line may assign it work, and **Allowed users** widens that to named groups and people. **Peers** are the agents it may hand subtasks to; an empty list means it cannot delegate at all. The Head Agent can delegate to any agent without a list.
The **Tree** view on the Agents page shows the agent-only hierarchy, and the **Org chart** tab under [Team](/team-management) draws the full tree of people and agents together.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.