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

# Agents

> Programmatic control of specialist agent engines via the v1 API and MCP.

Requires the site to be on a plan that includes automations (**Pro or Advanced**) and to have sufficient AI credits.

## UI vs. API

The **Automations page** (`app.trysight.ai/automations`) is the primary way to create, schedule, and monitor automations — including custom tool-based workflows. See the [Automations documentation](/automations/overview) for setup guides.

The v1 API endpoints below operate on the **agent configuration store** (template agent keys). Custom automations created in the UI (`custom_actions`) are **not yet exposed** on the v1 REST or MCP API.

## REST endpoints

| Method | Path                                           | Scope          |
| ------ | ---------------------------------------------- | -------------- |
| GET    | `/api/v1/sites/{siteId}/agents`                | `agents:read`  |
| GET    | `/api/v1/sites/{siteId}/agents/runs`           | `agents:read`  |
| PUT    | `/api/v1/sites/{siteId}/agents/{agentKey}`     | `agents:write` |
| POST   | `/api/v1/sites/{siteId}/agents/{agentKey}/run` | `agents:write` |

### Agent keys

| Key                | Template                         |
| ------------------ | -------------------------------- |
| `article_creation` | Search Opportunity Agent         |
| `ai_prompt`        | AI Opportunity Agent             |
| `article_boost`    | Article Boost Agent              |
| `interlinking`     | Interlinking Agent               |
| `site_performance` | Site Performance Agent           |
| `outreach`         | Outreach Agent *(Advanced only)* |

## MCP tools

With `agents:read` / `agents:write` scopes:

* `list_agents` / `list_agent_runs`
* `update_agent` — toggle or tune an agent
* `run_agent` — on-demand run (rate-limited; agent must be active)

See [MCP Setup](/developers/mcp-setup) for OAuth and end-to-end workflow examples.

## Typical workflow

```
list_agents → update_agent (enable + schedule) → run_agent → list_agent_runs
```

Or starting from opportunities:

```
list_opportunities → run_agent (article_creation) → list_agent_runs → sync_article
```

<Note>
  Rate limits: agent runs are capped at **5/hour per site**. AI credit affordability is enforced when credits enforcement is active.
</Note>

## Outreach Agent: outbound vs. inbound

The Outreach Agent has two distinct API surfaces:

| Endpoint                                              | Purpose                                                                                                                                                             | Scope          |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `POST /api/v1/sites/{siteId}/agents/outreach/run`     | **Outbound discovery** — the agent finds new prospects, looks up their emails, and sends cold pitches. This is the `agents:write` endpoint above.                   | `agents:write` |
| `POST /api/v1/sites/{siteId}/outreach/inbox/messages` | **Inbound ingestion** — push a forwarded collab pitch into the agent's inbox so it triages and replies. Same behavior as forwarding an email to `forward+<token>@`. | `inbox:write`  |

See [Outreach Inbox](/developers/api-reference/outreach-inbox) for the inbound ingestion endpoint, and [Webhooks](/developers/webhooks) for receiving outbound event notifications when the agent acts.

Plan, license, and seat purchases are not available via API.