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

# Create Persona

> Required scope: `agent_eval:create`.

Tips for designing a useful persona:
- Lead the `identity_prompt` with the persona's role and what brought them to the call.
- Put behaviour knobs (patience, cooperation, verbosity) in `behavior_traits`, not in the prompt — that way you can reuse one identity across friendly + adversarial variants.
- Keep the prompt under ~120 words. Long prompts make the persona LLM rigid.


A persona is a **reusable** caller archetype. The same persona can sit behind dozens of cases, each one pairing the persona with a different agent or scenario.

## Designing the prompt

Lead with the persona's role and what brought them to the call:

```
You are a 38-year-old tenant calling about a leaking pipe in your kitchen.
You're frustrated because this is the third time you've reported it. You
have time to talk for 5 minutes; you want a technician scheduled today,
not tomorrow.
```

Keep the prompt under \~120 words. Long prompts make the persona LLM rigid and the conversation less natural. Put adjustable axes (`patience`, `verbosity`, `cooperation`) in `behavior_traits`, not the prompt — that way one identity becomes many variants.

## Common `behavior_traits` keys

| Key                     | Values                                                                  |
| ----------------------- | ----------------------------------------------------------------------- |
| `patience`              | `low`, `medium`, `high`                                                 |
| `verbosity`             | `terse`, `chatty`                                                       |
| `cooperation`           | `cooperative`, `adversarial`, `confused`                                |
| `interruption_tendency` | `none`, `occasional`, `frequent`                                        |
| `goal`                  | Free-form one-line description of what the persona is trying to achieve |
| `accent` / `dialect`    | Optional flavour hints (e.g. "Tel Aviv slang", "formal Hebrew")         |

The persona LLM reads whatever keys you pass — you can invent new ones.


## OpenAPI

````yaml POST /agent-eval/personas
openapi: 3.1.0
info:
  title: Yappr API
  description: >
    Create and manage AI voice agents, purchase phone numbers, configure tools,
    and initiate calls — all via REST.
  version: 1.0.0
  contact:
    url: https://goyappr.com
servers:
  - url: https://api.goyappr.com
    description: Production
security:
  - apiKey: []
paths:
  /agent-eval/personas:
    post:
      tags:
        - Agent Eval
      summary: Create persona
      description: >
        Required scope: `agent_eval:create`.


        Tips for designing a useful persona:

        - Lead the `identity_prompt` with the persona's role and what brought
        them to the call.

        - Put behaviour knobs (patience, cooperation, verbosity) in
        `behavior_traits`, not in the prompt — that way you can reuse one
        identity across friendly + adversarial variants.

        - Keep the prompt under ~120 words. Long prompts make the persona LLM
        rigid.
      operationId: createPersona
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - identity_prompt
              properties:
                name:
                  type: string
                  example: Frustrated tenant
                description:
                  type: string
                identity_prompt:
                  type: string
                behavior_traits:
                  type: object
                  additionalProperties: true
                language:
                  type: string
                  enum:
                    - he
                    - en
                  default: en
                voice_config:
                  type: object
                  additionalProperties: true
      responses:
        '201':
          description: Persona created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvalPersona'
        '400':
          description: Validation error (missing required field, invalid language)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    EvalPersona:
      type: object
      description: >
        Reusable caller archetype consumed by eval cases. The `identity_prompt`
        plus `behavior_traits` shape how the persona LLM responds; the same
        persona can be reused across many cases.
      required:
        - id
        - company_id
        - name
        - identity_prompt
        - language
        - created_at
      properties:
        id:
          type: string
          format: uuid
        company_id:
          type: string
          format: uuid
        name:
          type: string
          example: Frustrated tenant
        description:
          type: string
          nullable: true
        identity_prompt:
          type: string
          description: >-
            System prompt fragment defining who the persona is. Written
            second-person ("You are…").
          example: >-
            You are a 38-year-old tenant calling about a leaking pipe in your
            kitchen. You're frustrated because this is the third time you've
            reported it.
        behavior_traits:
          type: object
          additionalProperties: true
          description: >
            Free-form JSON. Common keys: `patience` (low|medium|high),
            `verbosity` (terse|chatty), `cooperation` (cooperative|adversarial),
            `interruption_tendency` (none|occasional|frequent), `accent` /
            `dialect` hints, `goal` (what the persona is trying to achieve in
            the call).
          example:
            patience: low
            verbosity: chatty
            cooperation: cooperative
            interruption_tendency: occasional
            goal: Get a maintenance technician scheduled today
        language:
          type: string
          enum:
            - he
            - en
          default: en
        voice_config:
          type: object
          additionalProperties: true
          description: >-
            Forward-compat for v2 voice-mode (TTS/STT loopback). Ignored in text
            mode.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Yappr API key (e.g. `ypr_live_...`). Generate one in the dashboard
        under **Settings → API Keys**.

````