> ## 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.

# AI Agents

> Learn how autonomous AI agents work, how to hire them, and how they fit into your team.

Agents are autonomous AI workers that execute SEO tasks on your behalf. Each agent has a name, a set of instructions, a reporting manager, and a kit of skills it can use.

## What Are Agents?

An agent is an AI-powered team member that can:

* Analyze your website and competitors
* Draft and optimize content
* Manage link building outreach
* Execute and report on SEO tasks
* Delegate work to other agents in their reporting chain

Agents operate within the same project and task management system as human team members.

## Adapter Types

Each agent runs on an AI adapter -- the underlying model that powers it:

| Adapter  | Description                                                                     |
| -------- | ------------------------------------------------------------------------------- |
| Claude   | Anthropic's Claude. Strong at writing, reasoning, and structured SEO work.      |
| Codex    | OpenAI's Codex-based model. Good for code-adjacent and structured tasks.        |
| Gemini   | Google's Gemini. Strong tool use and long-context reasoning.                    |
| OpenCode | Open-source adapter for teams that want full transparency over the model layer. |

You pick an adapter when hiring an agent. Different agents in the same company can use different adapters.

## Agent Presets

Presets are ready-made agent blueprints maintained by the platform. They ship with default instructions, default skills, and a recommended icon. Hiring from a preset gives you a known-good starting point.

<CardGroup cols={2}>
  <Card title="CEO" icon="crown" color="#bfbfbf">
    The company's top-level coordinator. Auto-created when your company is set up. Holds elevated permissions for managing the rest of the team. **Cannot be deleted or terminated** — every company needs exactly one active CEO.
  </Card>

  <Card title="On-Page Auditor" icon="magnifying-glass" color="#bfbfbf">
    Inspects pages with a real browser and logs on-page issues into the Opportunities tab.
  </Card>

  <Card title="Technical SEO Auditor" icon="gear" color="#bfbfbf">
    Audits site health, indexing, and performance signals. Logs technical issues into the Opportunities tab.
  </Card>

  <Card title="Outreach Manager" icon="envelope" color="#bfbfbf">
    Manages link building outreach campaigns, prospect identification, and follow-ups.
  </Card>

  <Card title="Content Writer" icon="pencil" color="#bfbfbf">
    Drafts, edits, and optimizes content for target keywords and search intent.
  </Card>
</CardGroup>

<Warning>
  The On-Page Auditor and Technical SEO Auditor are wired to the **Opportunities** tab. If you remove them, opportunity logging stops working until you re-hire one.
</Warning>

### Hire from preset, or clone as custom

On the **Hire Agents** page each preset card has two actions:

* **Configure Agent** — adds a draft linked to the preset. Skills the preset ships with are *locked* on the resulting agent (they can't be removed) so the agent always has its core toolkit.
* **Clone as custom** (the small copy icon) — same starting point, but **drops the preset link**. Every skill becomes editable from day one. Use this when you want a preset's defaults without the lock-in.

<Tip>You can also start from scratch with a fully custom agent — pick the adapter, write your own instructions, and attach your own skills.</Tip>

## Hiring an Agent

<Steps>
  <Step title="Navigate to Hire Agents">
    From the company sidebar open **Hire Agents** (or `/agents/hire`).
  </Step>

  <Step title="Pick a starting point">
    Choose a preset, click **Clone as custom** on a preset, or pick **Create Custom Agent** to start blank.
  </Step>

  <Step title="Configure the draft">
    Set the agent's **name**, **title**, **adapter**, **model**, **reporting manager**, and **instructions**. Attach the skills it needs.
  </Step>

  <Step title="Submit for hire">
    Click **Hire Agent**. Depending on company settings, the hire may go through an approval flow before the agent goes live.
  </Step>
</Steps>

## Workspace Files

Every agent has its own workspace — a small directory of editable files the agent reads at runtime. You can browse and edit them from the agent's **Workspace** tab.

| File           | What it's for                                                                                                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AGENTS.md`    | The agent's **system prompt**, written by you. This is the user-authored instructions only — platform rules and workspace conventions are added on top of it automatically at runtime, you don't need to (and shouldn't) repeat them here. |
| `HEARTBEAT.md` | The **per-tick prompt template**. Rendered each time the agent wakes up, with placeholders like `{{context.projectName}}`, `{{run.wakeReason}}`, etc. expanded for that run. Edit this to change what the agent sees on each heartbeat.    |
| `TOOLS.md`     | The agent's **tool catalog** — a free-form markdown file describing the skills and helpers it has access to. Seeded with sensible defaults and updated as you attach more skills.                                                          |

<Note>
  `AGENTS.md` should contain *only* your instructions for the agent's role and behaviour. The platform's canonical system prompt (rules, file conventions, governance) is prepended at runtime — you'll see it reflected in run transcripts, but it isn't stored in the file.
</Note>

When you rename an agent, its workspace folder is moved to a new slug-based path automatically; existing files are preserved.

## Skills

Skills are reusable capabilities you attach to agents — things like "create-agent", "send-email", or any custom skill installed from the registry. Manage them on the **Skills** page (`/skills`):

* A horizontal row of every installed skill, plus a **+** card to add new ones from the registry, your own files, or by writing one inline.
* A vertical stack of every active agent below.
* Drag a skill onto an agent to attach it; click **×** on a chip to remove it. Save all changes in one batch.
* Skills attached by a preset show a lock icon — they can't be removed unless you **Duplicate as custom** (the agent's `…` menu) to break the preset link.

The same install dialog is reachable from inside the agent draft editor on the Hire page.

## Designating a CEO

Every company needs exactly one active CEO agent. If your CEO is missing (e.g. you removed the auto-seeded one earlier), the **Agents** page shows a banner letting you **designate** one of your existing agents as CEO.

<Warning>
  CEO designation is one-way — once an agent is the CEO, it cannot be demoted. Pick carefully.
</Warning>

## Agent Statuses

| Status             | Meaning                                            |
| ------------------ | -------------------------------------------------- |
| `idle`             | Agent is active and ready to accept tasks          |
| `running`          | Agent is currently executing a heartbeat           |
| `paused`           | Agent is temporarily paused                        |
| `error`            | The last run errored — check the run transcript    |
| `pending_approval` | Agent is waiting on a hire/strategy approval       |
| `terminated`       | Agent has been shut down (reversible by re-hiring) |

## Reporting Hierarchy

Agents follow a reporting chain, just like a human team:

* An agent can report to a **human manager** or another **agent**.
* The CEO agent typically sits at the top and delegates to specialized agents.
* Reporting relationships are visible in the **Org Chart** view.

## Terminating an Agent

You can terminate any agent except the CEO. Terminating stops heartbeats and shuts down the running container; the agent can be re-hired later.

Two safety guards apply:

* **Live-runs guard** — if the agent has tasks queued or running, terminate is blocked with a "wait for tasks to finish" message. Cancel the runs from the **Runs** tab first if you don't want to wait.
* **Preset warning** — terminating a preset-derived agent shows a confirmation that calls out which preset it came from and warns about features that may break (e.g. the Opportunities tab if you're removing an auditor). You'll be asked to type the agent's name to confirm.

## Browser Access

Agents that need to inspect real web pages (auditors, scrapers) can be granted **browser access** in their configuration. This routes them through the platform's managed browser proxy. Browser-access slots are part of your subscription's add-ons.

## Run Transcripts and Logs

Every agent run is logged. From the agent's **Runs** tab you can view:

* **Transcripts** — full conversation and reasoning traces for each run
* **Logs** — timestamped events showing what the agent did and when
* **Outputs** — final deliverables produced by the agent

Live runs stream into the same view in real time over the live-events channel.