Try it live — the playground

The fastest way to feel what a Vectara agent does is to drive one yourself and watch what it streams back. The Agent Playground is a live debugger we ship with the docs: paste your API key, paste an agent key, send a message — and watch session metadata, step transitions, tool calls, tool outputs, and structured outputs land in real time.

Open the Agent Playground →

The playground is a single static HTML page. It calls Vectara's streaming API directly from your browser. Your API key never leaves this machine — it sits in localStorage. There is no backend.

What you'll see

Two panels, side by side:

Panel	What it shows
Conversation	Your messages and the agent's streamed responses. The current step is in the header — when the state machine transitions, you watch it update.
Agent activity	Every typed event the agent emits: session.metadata at session create, step_transition, tool_input, tool_output, structured_output, errors. Tool cards collapse a one-line summary; click to expand the full JSON.

This is the same data the Admin Center shows in production. The playground is just one place to see it interactively while you build.

Setup in five minutes

1. Create a Vectara account. Go to console.vectara.com/signup and sign up. The free trial includes the agent runtime — no credit card.
2. Get an API key. In the Console, open API Keys → Create API Key. Give it agent read+write permissions. Copy the key (it starts with zut_).
3. Create an agent. Either:
   • Build one in the Console — follow the Agents quickstart for the wizard, or
   • Paste the JSON. The Agent anatomy example is a runnable starting point.
4. Copy the agent key. In the Console, open your agent. The key field is at the top — it's a lowercase slug like my-support-agent.
5. Open the playground. Click here. The config gate appears. Paste the API base URL (use the default https://api.vectara.io unless you're on a private cloud), API key, and agent key. Optionally paste session.metadata as JSON — anything your agent reads via $session.metadata.*.
6. Send a message. Watch the events stream into the right panel.

That's it. Configuration sticks in localStorage. Hit "change config" in the topbar to swap agents.

Reading the activity panel

The activity panel is a typed event timeline. Each event maps to a concept in Agent anatomy and Request lifecycle.

session.metadata block

The first card shown after a session is created. Confirms exactly what your app passed in. Tools that $ref session metadata will read these values at call time.

{
  "user_id": "alice.chen",
  "tier": "enterprise",
  "corpus_key": "company-kb"
}

If a tool fails with an "auth" error, check this block first — a missing or mis-spelled key in session.metadata is the most common cause.

step_transition events

Render as from_step → to_step with the condition that matched. The current step shows in the conversation header.

classify → manager_approval        (intent=refund, amount > 500)

Every transition is a next_steps condition firing. This is the agent's logic — not prose in a prompt.

tool_input / tool_output cards

Paired by tool_call_id. A calling… spinner shows while the tool runs. Click show details to expand the full JSON. Errors land in red.

Field on the card	Source event
Tool name	tool_configuration_name
Arguments	tool_input
Result or error	tool_output

Secrets passed via $ref agent.secrets.* or $ref session.secrets.* appear masked as **** — they are encrypted at rest and never enter the LLM's prompt. The playground proves this to you. If a value looks suspicious in a tool input, check whether it should have been a secret.

structured_output events

When a step has a json output parser, the parsed object renders as a key-value table. Downstream conditions read it via get('$.path').

intent       refund
order_id     A-12345
reason       damaged
amount       347.50

Streaming agent output

The agent's final text streams chunk-by-chunk into the conversation. The blinking cursor marks an active stream.

What to test

A focused set of prompts reveals what every part of the agent does.

1. A simple question. Tests the happy path. You should see one step_transition, no tool calls (or one search call), and a streamed answer.
2. A query that triggers a tool. Phrase it so the LLM picks a specific tool (e.g. for a corpus search agent: "find docs about ..."). Watch tool_input → tool_output pair up.
3. A query that triggers a step transition. If your agent has conditional routing, phrase it to trigger the non-default branch. Watch the step header update.
4. A query that crosses a sub-agent. Watch the parent pause while the sub-agent runs.
5. A follow-up message. Watch reentry_step route the second turn to the right state, not back to intake.

Each of these maps to a feature in the architecture pages. The playground is where the abstractions become concrete.

Reference implementations

For agents that show off a richer flow:

• The connector authentication patterns — see Connector authentication for ready-to-paste configs covering per-user OAuth, per-user bearer, and service-account OAuth. An internal reference implementation ("OAuth tools demo") wires all three onto a single agent — ask your Vectara contact for access.
• The refund-handling agent — a multi-step agent that classifies, looks up the order, computes the refund, routes through a manager approval sub-agent, and resolves with HHEM-graded citations. Full JSON in the Agent anatomy example.

Paste their agent keys into the playground and drive them yourself.

Build your own playground

The playground is ~700 lines of vanilla HTML/JS. No framework, no build step, no backend. The whole thing is one file in public-docs/static/playground/index.html.

If you want to embed a similar debug view in your own app:

const url = `${base}/v2/agents/${agentKey}/sessions/${sessionKey}/events`;
const res = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "text/event-stream",
    "x-api-key": apiKey
  },
  body: JSON.stringify({
    type: "input_message",
    stream_response: true,
    messages: [{ type: "text", content: userMessage }]
  })
});

// Parse Server-Sent Events
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  // Each event is separated by "\n\n"; the data line starts with "data: "
  let sep;
  while ((sep = buffer.indexOf("\n\n")) >= 0) {
    const chunk = buffer.slice(0, sep);
    buffer = buffer.slice(sep + 2);
    const dataLine = chunk.split("\n").find(l => l.startsWith("data:"));
    if (!dataLine) continue;
    const event = JSON.parse(dataLine.slice(5).trim());
    handleEvent(event);
  }
}

handleEvent(event) routes by event.type — streaming_agent_output, streaming_agent_output_end, tool_input, tool_output, structured_output, step_transition, skill_load, compaction, plus the terminal events. See the Request lifecycle for the full list.

Privacy and safety

• Your API key is stored in browser localStorage on your machine only. Nothing is sent to Vectara's docs site or any third party.
• All API calls go directly from your browser to your Vectara endpoint. Open DevTools → Network to verify.
• Rotate your API key after testing if you want belt-and-braces.

Related

• Agents quickstart — create your first agent in the Console.
• Developer quickstart — get an API key and make your first API call.
• Agent anatomy — the parts of one agent.
• Request lifecycle — the full event stream end-to-end.
• Connector authentication — the three credential patterns the OAuth demo proves.