Build with coding agents

Vectara is a headless platform. Your application is yours — whether your team builds it or Vectara Managed Agents delivers it. If your team is building, you're in the right place: because every piece of the platform is REST-driven and well-typed, a coding agent like Claude Code, Cursor, or Codex can scaffold working applications on top of Vectara in the time it takes to drink a coffee.

This page covers both halves of that flow:

1. Install Vectara Skills — packaged patterns that teach your coding agent the platform.
2. Use the recipes below — four ready-to-paste prompts that scaffold real applications in 30 minutes each.

The platform does the AI heavy lifting. You and your coding agent do the UI, the workflow, and the integration.

Why this works

Three things make Vectara unusually friendly to coding-agent scaffolding:

1. Declarative everything. An agent is JSON. A pipeline is JSON. A tool is JSON. There is no SDK to learn, no class hierarchy to internalize. Coding agents are excellent at JSON.
2. REST + typed events. The streaming event protocol is plain Server-Sent Events with typed payloads. A coding agent can write the parser in under 50 lines of vanilla JavaScript.
3. Vectara Skills. The vectara/agent-skills repository is a packaged set of patterns the coding agent reads directly. It already knows the right shape for tool_configurations, $ref, argument_override, next_steps, and the event types — no stale training data, no "are you sure that field exists?".

Install the skills once and the coding agent is fluent in Vectara.

Install Vectara Skills

Agent skills are instruction files that you install into your coding agent's project. They teach the agent how to use the Vectara API correctly, including creating agents, configuring tools, managing sessions, and avoiding common mistakes.

Available skills

Skill	Description
agents	Build AI agents with tools, sessions, and instructions

One command (all platforms)

npx skills add vectara/agent-skills

This detects your coding agent and installs the skill files to the correct location automatically.

Manual install

If the one-command path doesn't work for your setup:

Claude Code

mkdir -p .claude/skills/vectara-agents
curl -o .claude/skills/vectara-agents/SKILL.md \
  https://raw.githubusercontent.com/vectara/agent-skills/main/skills/agents/SKILL.md

Cursor

mkdir -p .cursor/rules/vectara-agents
curl -o .cursor/rules/vectara-agents/SKILL.md \
  https://raw.githubusercontent.com/vectara/agent-skills/main/skills/agents/SKILL.md

OpenAI Codex

mkdir -p .agents/skills/vectara-agents
curl -o .agents/skills/vectara-agents/SKILL.md \
  https://raw.githubusercontent.com/vectara/agent-skills/main/skills/agents/SKILL.md

Get an API key

Console → API Keys → Create. Give it agent read+write permissions. Set it as VECTARA_API_KEY in your shell or a .env file:

export VECTARA_API_KEY=zut_...

That's the entire setup. Now open your coding agent in a fresh directory and paste one of the recipes below.

Recipe 1 — Connector wrapper UI for an agent

Scenario. You have a Vectara agent that reads Google Docs and opens GitHub issues. You need a small web app where end users can connect their Google and GitHub accounts before chatting with the agent — a "Connect your account" page.

What's hard about this normally: OAuth dances, session storage, token refresh, wiring it into the agent at session-create time. A backend engineer who has never wired OAuth before would budget two days.

Paste this into your coding agent:

Build a Node.js Express app that wraps a Vectara agent and acts as a
connector hub for its users.

Stack:
- Node 20+, Express, no frontend framework (vanilla HTML/JS)
- Vectara Skills installed; use them

Two pages:
1. /connect — three cards: "Connect Google Drive", "Connect GitHub",
   "Open agent". Each connect card kicks off an OAuth dance against
   the respective provider, stores the resulting refresh_token /
   bearer in a server-side session keyed by cookie, and shows a
   "✓ connected" state once done.
2. /agent — chat UI that talks to the Vectara agent. When the user
   sends a message, my app creates a Vectara session, passing the
   user's tokens via session.metadata (GOOGLE_REFRESH_TOKEN,
   GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET for Drive;
   GITHUB_BEARER_HEADER and GITHUB_ISSUES_URL for GitHub). Then it
   streams the response back to the UI.

The Vectara agent already exists. Its key is in
VECTARA_AGENT_KEY env var. Its tools use $ref session.metadata.*
for credentials (so I just have to set those fields at session create
— the platform handles the actual API calls).

Use https://api.vectara.io as the base URL. API key from
VECTARA_API_KEY env var. Read the connector-authentication doc in
Vectara Skills for the exact session.metadata field names.

Print a startup banner showing the connect URL. No tests — this is a
demo. Be concise: one server.js, one connect.html, one agent.html.

What you get in ~20 minutes. A working Express app. Three OAuth flows. A chat UI that streams the agent's response with citations. The coding agent will pull the connector-authentication patterns straight from the Vectara Skills.

The 30-minute version of this has been built as an internal reference implementation ("OAuth tools demo") — one Express server, two HTML pages, three OAuth flows. Ask your Vectara contact for access, or have your coding agent scaffold the same shape from the connector authentication patterns directly.

Recipe 2 — Fancy agent UI / debug dashboard

Scenario. You have a multi-step agent in production. The product team keeps asking "why did it pick that branch?" and "what did it search for?". You want a one-page dashboard that shows what the agent does for any session.

What's hard about this normally: parsing the streaming event protocol, modeling tool input/output pairs, rendering step transitions without a timeline library.

Paste this into your coding agent:

Build a single-page web app (one .html file, vanilla JS) that calls a
Vectara agent and renders its activity in two columns:

LEFT — conversation:
- User messages (right-aligned bubble)
- Agent responses (streamed token-by-token)
- A small header showing the current step name

RIGHT — agent activity timeline:
- session.metadata block when the session is created
- step_transition events as "from → to" pills
- tool_input/tool_output pairs as collapsible cards, with a spinner
  while pending and a green tick when done
- structured_output events as key-value tables
- Errors in red

Stream POST /v2/agents/{key}/sessions/{ses}/events with
{ type: "input_message", stream_response: true, messages: [...] }.
Parse Server-Sent Events: lines start with "data:" and events are
separated by "\n\n". Read the request-lifecycle doc in Vectara Skills
for the full event-type list.

Show a config gate at first load asking for API base URL, API key, and
agent key. Persist to localStorage. No backend.

Make it look clean. Tailwind via CDN is fine, or hand-roll CSS — your
call. Show me what's possible.

What you get in ~25 minutes. A working debugger you can drop into any project. The coding agent will know about every event type (tool_input, tool_output, step_transition, structured_output, streaming_agent_output, compaction, skill_load, and the terminal/error events) because they are all documented in the Vectara Skills.

This already exists as the Agent Playground shipped with these docs. The coding agent can produce a variant with your own branding, your own events, or a richer trade-off visualization (HHEM score over time, tool-call latency histogram, step path frequency).

Variants to ask for

The playground is the baseline. Ask the coding agent for:

• A trade-off panel. Plot HHEM score vs. response latency for the last 50 sessions. Coding agent reads hallucination evaluation for the score model.
• A step-frequency Sankey. Show which step paths your agent takes most often. Highlight the long-tail branches that fire rarely.
• A live secrets indicator. Show which $ref fields resolved this turn and which scope (agent.secrets masked, session.metadata visible).

Recipe 3 — A stepped business agent from a whiteboard sketch

Scenario. Your product manager has a workflow on a Confluence page: "When a customer requests a refund, classify intent, look up the order, compute the eligible amount, and if over $500 escalate to a manager." You want it running as an actual agent before standup tomorrow.

What's hard about this normally: deciding what's a step vs. a prompt, designing the next_steps conditions, writing the JSON-schema output parsers, wiring the sub-agent for manager approval.

Paste this into your coding agent:

Create a Vectara agent that handles refund requests. Here's the
workflow on our Confluence page:

1. Classify the user's request. Extract intent, order_id, reason.
2. Look up the order via our internal Orders API
   (https://orders.internal/v1/orders, bearer auth from agent.secrets).
3. Compute the eligible refund amount using a Python Lambda with our
   business rules (full refund if damaged; otherwise 10% restocking
   fee within 14 days, 25% after, nothing after 30 days).
4. If the eligible amount is > $500, route to a manager-approval
   sub-agent. Otherwise, generate the user-facing response with policy
   citations from the support-kb corpus.

Constraints:
- Each step uses its own scoped allowed_tools (least privilege).
- The classify step has an output_parser with json_schema requiring
  intent, order_id, reason.
- The lookup step's next_steps condition routes on $.amount > 500.
- HHEM grades every generated answer; below 0.6 we decline.

Output:
1. agent.json — the agent config, ready to PUT to /v2/agents
2. lambda.py — the refund-amount Lambda's process() function
3. setup.mjs — a Node script that creates/updates the agent and
   registers the Lambda via POST /v2/tools

Use Vectara Skills for the exact JSON shape. Use my $VECTARA_API_KEY
env var. Make it production-shaped, not demo-shaped.

What you get in ~30 minutes. A real agent.json that runs. A working Lambda. A node setup.mjs invocation that deploys both. The coding agent reads Agent anatomy and Steps from the skills, so the JSON is shaped correctly the first time.

Open the Agent Playground and paste in the agent key. Drive it. Iterate.

Recipe 4 — A chat UI with citations and HHEM badges

Scenario. You have a knowledge-base agent. You want to ship a chat widget your team can embed in any internal tool. The widget needs to show citations inline and a confidence badge per answer.

Paste this into your coding agent:

Build a React component <VectaraChat /> that:

Props: { apiBase, apiKey, agentKey, sessionMetadata }.

Renders:
- A scrollable message list.
- A textarea + send button at the bottom (⌘+Enter to send).
- For each agent response:
  - The streamed text from streaming_agent_output events.
  - A footnotes section below listing the citation docs from any
    corpora_search tool_output that fired during the turn.
  - A small confidence badge (green / amber / red). For agents that
    use Vectara generation, the factual-consistency score lands in
    the generation tool_output. Optionally, your app can also call
    /v2/evaluate-factual-consistency directly to grade the answer
    against the cited sources.

Behavior:
- Creates a session on first message, passes sessionMetadata.
- POSTs to /v2/agents/{key}/sessions/{ses}/events with
  stream_response: true.
- Parses Server-Sent Events. Routes on event.type. Reads citations
  from tool_output payloads — see the request-lifecycle doc in
  Vectara Skills.

Style: minimal, embeddable, no external CSS dependencies. Single .tsx
file. Include a small README.md with a copy-paste integration snippet.

What you get in ~20 minutes. A drop-in React component. Citations hooked up correctly. HHEM-driven badges. The coding agent reads citations from the skills.

The 30-minute mindset

You are not writing AI code. You are writing UI code, integration code, and workflow JSON — exactly what a coding agent is best at.

The platform handles:

• The LLM gateway (Anthropic, OpenAI, Gemini, on-prem, BYO).
• Retrieval (hybrid BM25 + dense, Slingshot reranking).
• Hallucination grading (HHEM, < 50ms per answer).
• The agent runtime (state machine, step gating, structured outputs).
• Tools (35+ built-in, Lambdas, MCP, web_get with OAuth).
• Pipelines, RBAC, audit, multi-tenancy.

You handle:

• Where the agent lives in your product.
• What the UI looks like.
• What metadata your app passes per session.
• Which connectors your users actually need.

That split is why a backend engineer with no AI background can ship a real agent + UI in 30 minutes with a coding agent. The platform is the AI engineer. Your coding agent is the application engineer. You are the product.

Tips for working with the coding agent

A few patterns we've seen work across all four recipes:

• Ask it to read the Vectara Skills first. "Before writing any code, read the agents skill and tell me which patterns apply." This catches stale-training drift in the first turn.
• Be explicit about Vectara primitives. Say "use argument_override for credentials" or "use next_steps conditions for routing" — the coding agent will pick the right shape.
• Show, don't paraphrase. When the agent suggests a JSON shape, ask it to test against the API ("curl the create-agent endpoint with this payload and show me the response"). Catches schema mistakes immediately.
• Iterate in the playground. The Agent Playground is your debug surface. Tell the coding agent to paste the agent key there after every change.

Worked examples

• Agent Playground — the debug dashboard from Recipe 2. One HTML file. Open it in DevTools to see the SSE parser.
• vectara/agent-skills — the skills your coding agent reads. Open SKILL.md to see exactly what the agent sees.

Related

• Agent anatomy — the parts a coding agent will scaffold.
• Connector authentication — the three auth patterns Recipe 1 uses.
• Request lifecycle — the event protocol Recipes 2 and 4 parse.
• Try the playground — drive any agent you scaffold.