# The voice AI agent workspace

> The agent rail, the reachability pip, in-engine and external agent creation, the eight workspace tabs, and the ?agent= / ?view= deep links.

The voice AI console in TeleQuick is agent-object-centric. There is no
global tab bar: a left rail lists your AI agents, and selecting one opens a
single workspace whose tabs all operate on that agent. Org-level screens
(trunks, numbers, call records, webhooks, and the rest) render in the same
frame, and the agent rail stays visible while they do, so switching agents
never costs a round trip through the menu.

This page documents the workspace shell — the rail, the create flow, the tab
set, and the URL. It does not document the contents of every tab.

## The agent rail and what the status pip means

The rail lists the org's AI agents. Each row carries a small pip that answers
one question: **can a call reach this agent right now?** It is a reachability
readout, not a health metric — nothing in it reflects audio quality, latency or
error rate.

| Pip | Reading |
| --- | --- |
| `draft` | The agent row exists but nothing has been published for it yet. Creating an agent — either kind — inserts a draft. |
| `not published` | The agent has saved configuration, but no published version stands behind it, so traffic has nothing to land on. Publish from the **Versions** tab. |
| `active` | The agent is enabled as a configuration object. |
| `live` | The agent is reachable and taking traffic. |

For quality and outcome signals, use the agent's **Activity** tab, the org-level
call records and transcripts screens, and [Telemetry](/platform/telemetry).

## Creating an in-engine agent from a template

**New voice agent** opens a modal with a kind toggle. With **In-engine agent**
selected, you supply a name and pick a template. The template list is fixed;
each entry shows a label and a one-line blurb, and `blank` is the default.

Creating calls `adminAgents.createConfig` with the org id, the trimmed name, and
the template's `systemPrompt` and `welcomeMessage`. The new agent is inserted as
a draft and is selected in the rail as soon as the modal closes. Everything the
template seeded is editable afterwards on the **Config** tab — the template only
decides what the first version of the prompt says.

## Creating an external agent and the one-time credential reveal

An **external agent** is one you run yourself — a LiveKit Agents worker or
equivalent — outside the TeleQuick engine. Media still rides the
TeleQuick QUIC transport: no WebRTC, no LiveKit cloud.

The modal asks for a name and an **agent handle**, which is the name your worker
registers as. The handle is derived from the display name unless you edit it:
lower-cased, any run of characters outside `a-z 0-9 . _ -` collapsed to `-`,
leading and trailing `-` stripped, and truncated to 64 characters. Creating runs
two steps:

1. `adminAgents.createConfig` inserts the agent row as a draft with **no
   in-engine pipeline**.
2. `mediaApps.provision({ orgId, agentConfigId, handle })` mints a `/media/`
   key for that agent. The same call marks the agent external and hydrates the
   `VENDOR_BRIDGE` pipeline.

The modal then switches to a reveal panel with four copyable fields:

| Field | Value |
| --- | --- |
| Connect URL | `wss://<engine-host>/media/<key>`. The host comes from the per-brand `QUIC_URL` in `/config.js`; the scheme is forced to `wss` and the original port and path are dropped. |
| Agent handle | The handle the provision call actually stored, which may differ from what you typed if it was normalised. |
| App key | The `/media/` app key. |
| Secret (shown once) | The app secret. If the agent was already provisioned, this field reads `(already provisioned — rotate to get a new secret)` instead. |

Point your unmodified worker — via the `livekit-plugins-telequick`
transport — at these values.

> **WARNING:**
> The secret is sealed at rest and is **never shown again**. Copy it before you
> close the panel. While the reveal is on screen the backdrop is inert: clicking
> outside will not dismiss it, so you cannot lose the secret by mis-clicking. Only
> **Done** closes it, and that selects the new agent in the rail.

If you lose a secret, rotate it. Rotate and revoke for a `/media/` credential
are reachable from the org-level **External agents** screen, which also holds the
fleet list and the bulk importer.

## The eight workspace tabs and which ones an external agent hides

Selecting an agent opens its workspace. Every tab is scoped to that one agent.

| Tab | What it is for |
| --- | --- |
| Config | The agent object itself — name, system prompt, welcome message. |
| Build | Assembling the agent's in-engine behaviour beyond the prompt. |
| Flow | The flow view of the same agent. |
| Versions | The agent's versions. Publishing here is what moves the rail pip off `not published`. |
| Keys | Per-agent provider key overrides. Org-wide defaults live on the org-level **Credentials** screen. |
| Evals | Evaluations for this agent. |
| Test | Test-drive the agent from the console. |
| Activity | What this agent has actually done. |

An **external agent shows only Test and Activity.** The other six describe an
in-engine ASR/LLM/TTS pipeline, and an external agent has none — its pipeline is
`VENDOR_BRIDGE`, and the prompt, model, flow, versioning and provider keys all
live in your own worker. Test and Activity remain because they are the two
surfaces that observe the call rather than define it.

## Deep-linking an agent and a section

The selected agent and the current section are both carried in the query string,
so any console state here is a linkable URL:

| Parameter | Meaning |
| --- | --- |
| `?agent=<agentConfigId>` | Selects that agent in the rail. |
| `?view=` | The section. Absent or empty selects the agent workspace, which is the default. Any other value is the key of an org-level screen. |

```text
# the workspace for one agent
/?agent=<agentConfigId>

# an org-level screen, agent rail still selected behind it
/?agent=<agentConfigId>&view=cdr
```

A `view` key that this console does not render is not reachable — see the next
section for the set that is.

## Org-level screens that sit alongside the workspace

These are not scoped to the selected agent. The console renders a fixed set of
surfaces; a screen the product manifest grants but that is not in this set does
not appear in the nav.

| Group | Keys |
| --- | --- |
| Start | `overview`, `get-started` |
| Telephony | `trunks`, `numbers`, `dispatch`, `campaigns`, `telephony-tools` |
| SIP | `sip-domains`, `sip-acl`, `sip-security`, `sip-capture` |
| Operations | `monitoring`, `recordings`, `cdr`, `transcripts`, `supervisor-inbox`, `alerts`, `audit`, `billing` |
| Agents | `external-agents`, `orchestrator`, `modules` |
| Channels | `chat-widgets`, `sms`, `branding` |
| Developers | `credentials`, `api-keys`, `webhooks` |

Two of these are easy to confuse because both hold keys, and they point in
opposite directions:

- **Credentials** holds the org-wide default provider keys — where TeleQuick
  authenticates *into* someone else's provider. The per-agent overrides of the
  same thing live on an agent's **Keys** tab.
- **API keys** holds the keys your own integrations authenticate *into*
  TeleQuick with.

The per-agent surfaces are deliberately absent from this list. You do not reach
an agent's config, evals or test drive from the nav — you pick the agent in the
rail and work through its tabs. Listing them in the nav as well would navigate
to the same screens a second way, and an "agent pools" entry would duplicate the
rail itself.

## Related

- [Authentication](/concepts/authentication) — API keys, relay tokens, and rotation
- [Telemetry](/platform/telemetry) — metrics, CDRs, and SIP capture behind the operations screens