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

# Personas

> The identity object: name, description, the endpoints it owns, and how it attaches to agents.

> [!NOTE]
>
> **Available now.** The identity object and its provisioning tooling are live. The [policy](https://vetta.sh/docs/concepts/policies.md) layer governs which identities an agent may use, and what each may do.

A **persona** is the identity object itself — the small, durable record that every endpoint and secret hangs off of. It answers one question for the agent: *who am I being right now?*

## Attaching to agents

Agents reference identities; identities reference no agents. The relationship is **many-to-many**.

**1. Create the persona**

```bash CLI theme={"system"}
vetta identity create --name "Acme Billing" \
  --description "Handles invoices and refunds for Acme"
```

**2. Give it endpoints**

Provision domains, inboxes, numbers, and connections on the identity.

**3. Attach to one or more agents**

```bash CLI theme={"system"}
vetta identity attach --agent agt_01j8rf6tq2m4vz9xkp3n7c5hwd --identity "Acme Billing"
vetta identity attach --agent agt_01j8rg3xk5m9pq2vz7n4c6hwte --identity "Acme Billing"   # shared by two agents
```

### One agent, several identities

An agent can hold more than one identity and choose which to act as per task — a support persona for inbound tickets, an outbound sales persona for prospecting.

```bash CLI theme={"system"}
vetta agent create --name Concierge \
  --model z-ai/glm-5.3-flash --harness pi \
  --identity acme-billing,ava-sales
```

```typescript TypeScript theme={"system"}
const agent = await vetta.agents.create({
  name: "Concierge",
  model: "z-ai/glm-5.3-flash",
  harness: "pi",
  identities: ["acme-billing", "ava-sales"],
});
```

### Choosing which to act as

When an agent holds multiple identities, the acting identity is named on the run. Whichever one it is, the persona's name, description and the addresses it owns are put in front of the model for that run only — the agent's stored configuration is never rewritten, so selecting a persona mints no new agent version.

**Per session**, for an interactive run:

```bash CLI theme={"system"}
vetta session create --agent agt_01j8rj7zn4m2xq6vk9p3c5hwgb --identity ava-sales
```

**On the deployment**, for unattended [scheduled](https://vetta.sh/docs/capabilities/deployments.md) runs — the mode a persona that owns an inbox actually operates in. The persona is resolved and grant-checked when the schedule is written, so a bad reference fails while you are watching rather than at 03:00:

```bash CLI theme={"system"}
vetta deploy create --agent agt_01j8rj7zn4m2xq6vk9p3c5hwgb --identity ava-sales \
  --cron "0 9 * * *" --budget-usd 5 --prompt "Answer anything waiting in the inbox."
```

> [!NOTE]
>
> **Inbound selects the persona by itself.** Mail or a text that arrives at one of a persona's endpoints wakes that endpoint's owning agent as that persona, so the owner must hold it. See [Inbound events](https://vetta.sh/docs/identity/inbound.md) for what wakes and what it costs.

## Endpoints are specific, not boolean

An identity does not "have email" — it owns `ava@acme-mail.com`. It does not "have a phone" — it owns `+1 415 555 0142`. This is what makes personas concrete and safely shareable:

* `billing@acme.com` and `support@acme.com` are **two different identities**, even on the same domain.
* Routing, [policy](https://vetta.sh/docs/identity/policies.md) scoping, and inbound matching all key off the specific address or number.

## How personas relate to policies

Every persona is governed by a [policy](https://vetta.sh/docs/identity/policies.md). The policy decides:

* Which **primitives** the identity may use (`email`, `phone`, `connections`, `vault`, `domains`).
* Which **connections** it may authorize and which **tools** it may call, at toolkit and tool granularity.
* Which actions require **human approval** (e.g. spend over a threshold, provisioning a number, purchasing a domain).

Enforcement is at the tool-call boundary and **fails closed** — an identity can never reach a system or spend money the policy did not grant.

## The identity object

**id** `string`

Stable identifier for the identity (e.g. `idn_ava`). Referenced by agents and per session.

**name** `string` *required*

Human-facing name of the persona, e.g. `"Ava Sales"` or `"Acme Billing"`. Surfaced to the model so it acts in character.

**description** `string`

What this persona is for. The model reads it to decide tone, scope, and which endpoints are appropriate — e.g. `"Handles invoices and refunds for Acme."`

**domains** `array`

The verified web domains this identity sends and receives on.

**emails** `array`

The email inboxes the identity owns (`localpart@domain`). Each is tied to an owning agent for routing.

**phones** `array`

The phone numbers the identity owns, with their messaging capabilities and campaign state.

**connections** `array`

The third-party connections the identity has authorized over OAuth.

**vault** `object`

The write-only [credential vault](https://vetta.sh/docs/identity/vault.md) scoped to this identity.

> [card] Next: web domains
>
> The dual-track domain system that email sits on top of.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.