> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpaygent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpaygent.com/_mcp/server.

# Agents

> Create and manage the AI agents Paygent meters and bills.

An agent is one thing you charge for — a support bot, a voice assistant, a summarizer. Usage is reported against an agent, and pricing hangs off it.

## `paygent agent create`

```bash
paygent agent create --name "Support Bot" --external-id support-bot
```

| Flag                   | Description                                 |
| ---------------------- | ------------------------------------------- |
| `--name <name>`        | Display name. Required.                     |
| `--external-id <id>`   | The handle your code reports usage against. |
| `--description <text>` | What this agent does.                       |
| `--type <type>`        | `normal` or `voice`.                        |
| `--status <status>`    | `Live`, `Paused`, or `Inactive`.            |

> **Warning**
>
> Pick `--external-id` once and keep it stable. Changing it orphans every event already sent under the old value.

## `paygent agent list`

```bash
paygent agent list
```

| Flag                | Description                              |
| ------------------- | ---------------------------------------- |
| `--status <status>` | Only agents with this status.            |
| `--type <type>`     | Only `normal` or `voice` agents.         |
| `--search <text>`   | Match name, external ID, or description. |
| `--limit <n>`       | Show at most this many.                  |

## `paygent agent get`

```bash
paygent agent get support-bot
```

An agent can be named by external ID, name, or ID.

## `paygent agent update`

```bash
paygent agent update support-bot --description "Tier-1 support"
```

## `paygent agent enable`

Make an agent accept usage. Also `disable`, `pause`, and `resume`.

```bash
paygent agent enable support-bot
```

| Status     | Meaning                    |
| ---------- | -------------------------- |
| `Live`     | Billable, accepting usage. |
| `Paused`   | Temporarily not billing.   |
| `Inactive` | Not accepting usage.       |

## `paygent agent ensure`

Create an agent only if it does not already exist. Idempotent, so it is safe in a deploy script.

```bash
paygent agent ensure --external-id support-bot --name "Support Bot"
```

Agents created this way start inactive and must be enabled.

## `paygent agent indicator`

Indicators are the units you meter. Add, list, and remove them.

```bash
paygent agent indicator add support-bot --name "Ticket resolved" --type OUTCOME
paygent agent indicator list support-bot
```

| Flag                  | Description                                  |
| --------------------- | -------------------------------------------- |
| `--name <name>`       | What the indicator is called. Required.      |
| `--type <type>`       | `ACTIVITY` for effort, `OUTCOME` for result. |
| `--per-minute`        | Bill by duration rather than by count.       |
| `--pulse-seconds <n>` | Voice agents: bill in pulses of N seconds.   |
| `--human-value <n>`   | What one unit would cost if a person did it. |

```bash
paygent agent indicator add voice-ivr --name "Talk time" --type ACTIVITY \
  --per-minute --pulse-seconds 6
```

## `paygent agent pricing`

Read and write an agent's pricing.

```bash
paygent agent pricing show support-bot
paygent agent pricing set support-bot --platform-fee 99 --price "Ticket resolved=2.50"
```

| Flag                        | Description                                  |
| --------------------------- | -------------------------------------------- |
| `--price "<name>=<amount>"` | Price one indicator. Repeatable.             |
| `--platform-fee <n>`        | Recurring platform fee.                      |
| `--setup-fee <n>`           | One-off setup fee.                           |
| `--billing-type <type>`     | `FLAT`, `VOLUME`, `GRADUATED`, or `CREDITS`. |
| `--included-usage <n>`      | Units included before charging begins.       |
| `--from-file <path>`        | Replace the whole pricing document.          |

`--price` routes to the activity or outcome block automatically, based on the indicator's own type.