Tutorial: run a support bot locally

This is the local Karta-session loop on one machine: an operator runs Karta, an agent builder brings a support bot project, and an end user chats with it through a browser widget - replies streaming token by token. No cloud account. It mirrors the runnable support-bot.

The cast

Operator

Hosts the platform - locally, karta dev plays this part.

Agent builder

Brings the support bot project and exercises it.

End user

Opens a chat widget in the browser and talks to the bot.

browser --HTTP--> web server (:5050) --proxy--> karta dev --turn--> Claude Code

1. The agent

Our bot is Beans, the support agent for a fictional roaster. The whole agent is three files.

app/CLAUDE.md

# Beans - Karta Coffee Co. support agent

You are Beans, the support agent for Karta Coffee Co.

- Warm, concise, a little playful (one coffee pun per reply, max).
- Greet a brand-new conversation with a short hello.
- Help with orders & shipping (2-3 business days; free over $35),
  our roasts (Sunrise, Midnight, Decaf Dusk), returns (30 days, unopened),
  and brewing tips.
- If you do not know something order-specific (like a tracking number), say so
  honestly and offer a human.
- Keep replies to 1-3 sentences unless asked for detail.

app/app.py

from karta import Karta

# Karta imports this `app` (see entry_point in karta.toml).
app = Karta()

app/karta.toml

name = "support-bot"
deploy = true
entry_point = "app:app"
buildpack = "python"

That’s a complete, deployable agent. CLAUDE.md is the instructions; karta.toml gives it a name, opts it into deploys, and tells Karta how to load it. (karta setup writes this file for you.)

2. Run it: one command plays the operator

cd app && karta dev

karta dev serves the folder behind the HTTP session API - the uniform surface every Karta agent speaks - and prints its local URL (Local agent API: http://127.0.0.1:<port>/v1). It also drops you into a chat REPL; for this tutorial the widget is the client, so keep karta dev running and note the URL. A tiny web server hosts the widget and proxies to Karta, so the browser only ever talks to your origin. The two calls it makes:

Open a session

// Create a session for this visitor:
const res = await fetch("/api/spawn", { method: "POST" });
const { session_id } = await res.json();
// server-side: POST <karta dev's URL>/v1/sessions { metadata: {...} }

Send & stream replies

const res = await fetch("/api/message", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ session_id, text: userText }),
});
// server-side: POST /v1/sessions/{id}/messages { text, stream: true }

// Read the SSE stream and append text deltas to the reply bubble:
const reader = res.body.getReader();
const decoder = new TextDecoder();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  // parse `event: text` frames and append data.part.text
  bubble.textContent += extractText(decoder.decode(value));
}

The widget reads the SSE stream and grows the reply bubble token by token - exactly what the Messages endpoint emits with stream: true.

4. Try it

Open the widget in a browser. Beans greets you, and a conversation flows:

You:   Hi! What roasts do you have?
Beans: Welcome! We have Sunrise (light, citrusy), Midnight (dark,
       chocolatey), and Decaf Dusk (smooth, caffeine-free). Anything catch
       your eye?
You:   Do you ship free?
Beans: Orders over $35 ship free, and most arrive in 2-3 business days.

Multi-turn context holds because each message reuses the same session_id - and the history lives in the harness, not the widget.

What this exercised

An agent (CLAUDE.md + karta.toml) with zero Karta-specific agent code.
The operator to developer to end user persona split, locally.
The uniform session API and SSE streaming that a real frontend builds against.

Where to take it next

Add a sub-agent

Hand billing questions to a dedicated harness role.

Add a skill

Give Beans real order-lookup capability.

Deploy it for real

Publish a release behind an agent URL.

Front it with the OpenAI SDK

Point an existing client at your agent.

Get started

Concepts

Agent project

The CLI

Deploy

Platform

Security

Enterprise

Tutorials

Tutorial: run a support bot locally

The cast

Operator

Agent builder

End user

1. The agent

2. Run it: one command plays the operator

3. End user: a streaming chat widget

4. Try it

What this exercised

Where to take it next

Add a sub-agent

Add a skill

Deploy it for real

Front it with the OpenAI SDK

​The cast

Operator

Agent builder

End user

​1. The agent

​2. Run it: one command plays the operator

​3. End user: a streaming chat widget

​4. Try it

​What this exercised

​Where to take it next

Add a sub-agent

Add a skill

Deploy it for real

Front it with the OpenAI SDK

The cast

1. The agent

2. Run it: one command plays the operator

3. End user: a streaming chat widget

4. Try it

What this exercised

Where to take it next