# Session inputs (draft)

Source: https://docs.scenaro.io/voice-agent/session-inputs/

# Session inputs (draft — not shipped)

Phase 1 already supports opaque `metadata` → LiveKit `session_context` → voice-agent
injection (`## Session context` block + `<session_context:path>` placeholders).

This page describes the **optional Cockpit layer** to declare expected keys on a
scenario version.

## Goals

- Authors see which bootstrap keys a scenario expects
- Prompt editor can insert `<session_context:dog.name>` from a picker
- Live / test runs can fill a form instead of raw JSON
- Soft validation (warn when required keys are missing) without breaking clients

## Proposed schema (scenario version content)

```json
{
  "session_inputs": [
    {
      "key": "dog.name",
      "type": "string",
      "required": true,
      "description": { "en": "Dog display name", "fr": "Nom du chien" }
    },
    {
      "key": "dog.age_years",
      "type": "number",
      "required": false,
      "description": { "en": "Age in years" }
    }
  ]
}
```

`key` is a dotted path into the client `metadata` object (same resolution as
placeholders today).

## Platform work (when prioritized)

1. **platform-api** — persist `session_inputs` on scenario versions; optional soft
   check on `POST /v1/public/session`
2. **platform-spa** — editor UI + Live form for test values
3. **voice-agent** — already injects placeholders; no change required for lookup
4. **docs / SDK** — point authors at declared inputs when present

Until this ships, any JSON `metadata` map remains valid. Clients (e.g. Lupi)
document their contract in scenario prompts.
