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

<Info>**Available now.** The identity object and its provisioning tooling are live. The [policy](/docs/concepts/policies) layer governs which identities an agent may use, and what each may do.</Info>

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

<Steps>
  <Step title="Create the persona">
    ```bash CLI theme={"system"}
    vetta identity create --name "Acme Billing" \
      --description "Handles invoices and refunds for Acme"
    ```
  </Step>

  <Step title="Give it endpoints">
    Provision domains, inboxes, numbers, and connections on the identity.
  </Step>

  <Step title="Attach to one or more agents">
    ```bash CLI theme={"system"}
    vetta identity attach --agent Refunder --identity "Acme Billing"
    vetta identity attach --agent Triage   --identity "Acme Billing"   # shared by two agents
    ```
  </Step>
</Steps>

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

<CodeGroup>
  ```bash CLI theme={"system"}
  vetta agent create --name Concierge \
    --model zai-org/GLM-5.2-FP8 --harness pi \
    --identity acme-billing,ava-sales
  ```

  ```typescript TypeScript theme={"system"}
  const agent = await vetta.agents.create({
    name: "Concierge",
    model: "zai-org/GLM-5.2-FP8",
    harness: "pi",
    identities: ["acme-billing", "ava-sales"],
  });
  ```
</CodeGroup>

### 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 Concierge --identity ava-sales
```

**On the deployment**, for unattended [scheduled](/docs/capabilities/deployments) 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 Concierge --identity ava-sales \
  --cron "0 9 * * *" --budget-usd 5 --prompt "Answer anything waiting in the inbox."
```

<Warning>
  **Inbound does not yet select a persona, because inbound does not yet wake an agent.** Mail and SMS that arrive for an identity's endpoints are authenticated, matched and stored — readable through `vetta identity email messages` — but no session is started for them, so the routing-selects-the-persona path described in [Inbound events](/docs/identity/inbound) is not live. Until it is, a persona answers on a schedule or when you start a session, not on arrival.
</Warning>

## 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](/docs/identity/policies) scoping, and inbound matching all key off the specific address or number.

## How personas relate to policies

Every persona is governed by a [policy](/docs/identity/policies). 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

<ParamField path="id" type="string">
  Stable identifier for the identity (e.g. `idn_ava`). Referenced by agents and per session.
</ParamField>

<ParamField path="name" type="string" required>
  Human-facing name of the persona, e.g. `"Ava Sales"` or `"Acme Billing"`. Surfaced to the model so it acts in character.
</ParamField>

<ParamField path="description" type="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."`
</ParamField>

<ParamField path="domains" type="array">
  The verified web domains this identity sends and receives on.
</ParamField>

<ParamField path="emails" type="array">
  The email inboxes the identity owns (`localpart@domain`). Each is tied to an owning agent for routing.
</ParamField>

<ParamField path="phones" type="array">
  The phone numbers the identity owns, with their messaging capabilities and campaign state.
</ParamField>

<ParamField path="connections" type="array">
  The third-party connections the identity has authorized over OAuth.
</ParamField>

<ParamField path="vault" type="object">
  The write-only [credential vault](/docs/identity/vault) scoped to this identity.
</ParamField>

<Card title="Next: web domains" icon="globe">
  The dual-track domain system that email sits on top of.
</Card>