Ship a support agent on your own site: ChatKit and the OpenAI Agents SDK
Agent Builder shuts down on November 30, 2026 — thirteen days from now. If you built your support agent on its visual canvas, you need a new home for it. The replacement is a stack you own outright: ChatKit for the chat UI, the Agents SDK for the brain, and a small Python server in the middle. Here is the whole thing, built and verified end to end.
- Deadline: Agent Builder and the Evals platform shut down November 30, 2026; ChatKit remains available. The deprecation was announced June 3, 2026.
- The surviving stack: ChatKit Python SDK (
openai-chatkit1.6.5) + Agents SDK (openai-agents0.24.0) + FastAPI, with@openai/chatkit-react1.6.1 on the frontend. - Two docs traps: the ChatKit docs' example imports a
MemoryStorethat does not exist in 1.6.5, and callssimple_to_agent_input(thread, item, context)with the wrong signature — both are corrected below. - Cost: no ChatKit platform fee; you pay standard API token rates for the model you choose, plus $0.10/GB-day for ChatKit upload storage (1 GB free).
- Verified: every import, signature, and server behavior in this tutorial was exercised in a sandbox; the one thing that needs your key is the live model reply (see Step 6).

OpenAI's AgentKit launched at DevDay in October 2025 as the friendly way to ship agents: draw the workflow on a canvas in Agent Builder, embed it with ChatKit, measure it with Evals. A year later, two of those three pieces are being switched off. Agent Builder and Evals go read-only, then dark, on November 30, 2026. ChatKit — the embeddable chat UI — survives, and the docs now point new work at "advanced ChatKit integrations": run ChatKit on your own infrastructure, backed by any agent you write with the Agents SDK.
That is a better deal than it sounds. The hosted path rented you a workflow ID and a session endpoint; the self-hosted path gives you the whole server. Your agent runs in your process, your tools hit your database, your guardrails run before the model ever sees the message, and your API key never leaves your backend. The price is about 200 lines of Python, most of it boilerplate. This tutorial writes those lines, runs them, and tests them — including the two places where the official docs are currently wrong.
What you will build: a support agent for a small online store, embedded as a chat widget on the store's site. A customer asks "Where is my order 4821?" and the agent looks the order up with a tool and answers. A customer asks about refunds and the agent answers from a policy tool. A customer pastes a credit-card number and the guardrail stops the message before it reaches the model.
What you'll need#
- An OpenAI API key with billing enabled. The agent calls the API on every reply, so the key needs to be live — the sandbox used to verify this tutorial could not complete a model call without one, and neither can you.
- Python 3.11 or newer. The ChatKit SDK requires 3.10+; the official starter targets 3.11. A virtual environment is strongly recommended.
- Node.js 18+ for the frontend, plus npm.
- About an hour, most of it reading, not typing.
On cost: there is no separate ChatKit price. You pay the underlying model's token rates — this tutorial uses gpt-4.1-mini, the model in OpenAI's own ChatKit starter, which keeps a support conversation to fractions of a cent. ChatKit file and image upload storage is $0.10 per GB-day with 1 GB free, which a text-only support widget will never touch.
Step 1: Install the stack#
Create the project and install the backend dependencies. Pin the versions that were verified for this tutorial — the ChatKit SDK moves fast, and its docs lag behind its releases, as you are about to see.
mkdir support-agent && cd support-agent
python3 -m venv .venv
source .venv/bin/activate
pip install openai-chatkit==1.6.5 openai-agents==0.24.0 fastapi "uvicorn[standard]"
Verify the install before writing any code. The imports below are the exact ones the server needs, and all of them must resolve:
python -c "
from chatkit.server import ChatKitServer
from chatkit.store import Store
from chatkit.agents import AgentContext, stream_agent_response, simple_to_agent_input
from agents import Agent, Runner, function_tool, input_guardrail
print('all imports OK')
"
Note what is not in that list: MemoryStore. The ChatKit docs' example imports it from chatkit.store, but version 1.6.5 ships no such class — the import fails. The Store base class is abstract, and you are expected to implement it. Step 4 does that. This is the first of two docs errors this tutorial corrects; the second is in Step 5.
Step 2: Give the agent tools#
An agent without tools is a chatbot with opinions. This one gets two: an order lookup and a refund policy. The order data is a dict standing in for a database — in production, lookup_order would run a query instead of a dict lookup, and nothing else in the file would change.
Create server.py and add the tools:
from agents import Agent, function_tool
# Demo data: a tiny order book. In production this would be a database query.
ORDERS = {
"4821": {"status": "shipped", "item": "Aurora headphones", "total": 74.99},
"4822": {"status": "processing", "item": "USB-C hub", "total": 39.00},
"4823": {"status": "delivered", "item": "Mechanical keyboard", "total": 129.50},
}
@function_tool
def lookup_order(order_id: str) -> str:
"""Look up an order by its number and return its status."""
order = ORDERS.get(order_id.strip())
if order is None:
return f"No order found with number {order_id}."
return (
f"Order {order_id}: {order['item']}, ${order['total']:.2f}, "
f"status: {order['status']}."
)
@function_tool
def refund_policy() -> str:
"""Return the store's refund policy."""
return (
"Refunds are available within 30 days of delivery for unused items. "
"Refunds are issued to the original payment method within 5 business days."
)
The @function_tool decorator turns each plain function into a tool the model can call, generating the JSON schema from the type hints. The docstring becomes the tool description the model reads when deciding which tool to use, so write it as an instruction, not a comment. Verified behavior: calling lookup_order with "4821" returns "Order 4821: Aurora headphones, $74.99, status: shipped.", and with an unknown number it returns a clean "No order found" instead of inventing an order.
Step 3: Add a guardrail and assemble the agent#
Support chats are where customers paste things they should not paste — most commonly, card numbers. An input guardrail runs before the model sees the message and can halt the run entirely by raising a tripwire. This one is a regex heuristic: demo-grade, not PCI compliance — a production guardrail would add a Luhn check and an allowlist for order numbers. For the tutorial it does the job: it fires on card-shaped digit runs and ignores order numbers and prices.
import re
from agents import (
Agent,
GuardrailFunctionOutput,
RunContextWrapper,
input_guardrail,
)
# Demo-grade heuristic: 13-19 digits with optional spaces or dashes.
# Production systems should add a Luhn check.
CARD_RE = re.compile(r"\b(?:\d[ -]?){13,16}\b")
@input_guardrail
async def no_card_numbers(
ctx: RunContextWrapper[None], agent: Agent, input: str | list
) -> GuardrailFunctionOutput:
text = input if isinstance(input, str) else str(input)
triggered = bool(CARD_RE.search(text))
return GuardrailFunctionOutput(
output_info={"reason": "possible card number" if triggered else "clean"},
tripwire_triggered=triggered,
)
Verified: with the message "my card is 4111 1111 1111 1111 please charge it" the guardrail trips (tripwire_triggered=True); with "Where is my order 4821?" and "What is your refund policy?" it passes. A tripped input guardrail raises InputGuardrailTripwireTriggered and the agent's execution stops before any model call — the card number never reaches OpenAI.
Now assemble the agent itself:
support_agent = Agent(
name="support_agent",
model="gpt-4.1-mini",
instructions=(
"You are a helpful support agent for an online store. "
"Use lookup_order to check order status and refund_policy for refund questions. "
"Never ask for or repeat payment card numbers. Be concise."
),
tools=[lookup_order, refund_policy],
input_guardrails=[no_card_numbers],
)
Two choices worth noting. The model is gpt-4.1-mini because that is the model in OpenAI's official ChatKit starter — cheap, fast, and more than capable of tool calls and short answers. The docs' custom-server example uses gpt-6.2-astra; swap the string if you want the newer model. And the instructions repeat the card-number rule even though the guardrail enforces it — defense in depth costs nothing, and instructions are what the model falls back on when a guardrail's heuristic misses.
Step 4: Implement the store#
Every ChatKit server needs a store: threads, thread items, and attachments have to live somewhere, and ChatKitServer requires one at construction. The SDK ships only the abstract Store class, so you write the concrete one. Twelve methods, all thin wrappers around dicts. This is demo-grade — data vanishes when the process restarts — and the file says so. A production store would implement the same twelve methods against Postgres or Redis.

from chatkit.store import (
Attachment,
NotFoundError,
Page,
Store,
ThreadItem,
ThreadMetadata,
)
class MemoryStore(Store[dict]):
def __init__(self) -> None:
self.threads: dict[str, ThreadMetadata] = {}
self.items: dict[str, list[ThreadItem]] = {}
self.attachments: dict[str, Attachment] = {}
async def load_thread(self, thread_id: str, context: dict) -> ThreadMetadata:
thread = self.threads.get(thread_id)
if thread is None:
raise NotFoundError(f"thread {thread_id} not found")
return thread
async def save_thread(self, thread: ThreadMetadata, context: dict) -> None:
self.threads[thread.id] = thread
async def load_thread_items(
self, thread_id: str, after: str | None, limit: int, order: str, context: dict
) -> Page[ThreadItem]:
items = list(self.items.get(thread_id, []))
if order == "desc":
items = list(reversed(items))
return Page[ThreadItem](data=items[:limit], has_more=False, after=None)
async def load_threads(
self, limit: int, after: str | None, order: str, context: dict
) -> Page[ThreadMetadata]:
threads = list(self.threads.values())
if order == "desc":
threads = list(reversed(threads))
return Page[ThreadMetadata](data=threads[:limit], has_more=False, after=None)
async def add_thread_item(
self, thread_id: str, item: ThreadItem, context: dict
) -> None:
self.items.setdefault(thread_id, []).append(item)
async def save_item(
self, thread_id: str, item: ThreadItem, context: dict
) -> None:
items = self.items.setdefault(thread_id, [])
for i, existing in enumerate(items):
if existing.id == item.id:
items[i] = item
return
items.append(item)
async def load_item(
self, thread_id: str, item_id: str, context: dict
) -> ThreadItem:
for item in self.items.get(thread_id, []):
if item.id == item_id:
return item
raise NotFoundError(f"item {item_id} not found")
async def delete_thread(self, thread_id: str, context: dict) -> None:
self.threads.pop(thread_id, None)
self.items.pop(thread_id, None)
async def delete_thread_item(
self, thread_id: str, item_id: str, context: dict
) -> None:
self.items[thread_id] = [
item for item in self.items.get(thread_id, []) if item.id != item_id
]
async def save_attachment(self, attachment: Attachment, context: dict) -> None:
self.attachments[attachment.id] = attachment
async def load_attachment(
self, attachment_id: str, context: dict
) -> Attachment:
attachment = self.attachments.get(attachment_id)
if attachment is None:
raise NotFoundError(f"attachment {attachment_id} not found")
return attachment
async def delete_attachment(self, attachment_id: str, context: dict) -> None:
self.attachments.pop(attachment_id, None)
One detail to get right: the context argument on every method is whatever your route passes to server.process() — here a dict holding the request. The store ignores it, but the signature must accept it. And NotFoundError is the SDK's own exception for missing threads and items; raising anything else turns a missing thread into a 500.
Step 5: Wire up the ChatKit server#
This is the heart of the tutorial: a ChatKitServer subclass whose respond() hands the conversation to the Agents SDK, and a single FastAPI route that feeds it requests. Append this to server.py:
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse, Response, StreamingResponse
from chatkit.agents import AgentContext, simple_to_agent_input, stream_agent_response
from chatkit.server import ChatKitServer, StreamingResult
from agents import Runner
class SupportChatKitServer(ChatKitServer[dict]):
def __init__(self) -> None:
self.store = MemoryStore()
super().__init__(store=self.store)
async def respond(self, thread, item, context):
items = list(
reversed(
(
await self.store.load_thread_items(
thread.id, after=None, limit=30, order="desc", context=context
)
).data
)
)
agent_input = await simple_to_agent_input(items)
agent_context = AgentContext(
thread=thread, store=self.store, request_context=context
)
result = Runner.run_streamed(support_agent, agent_input, context=agent_context)
async for event in stream_agent_response(agent_context, result):
yield event
chatkit_server = SupportChatKitServer()
app = FastAPI()
@app.post("/chatkit")
async def chatkit_endpoint(request: Request) -> Response:
payload = await request.body()
result = await chatkit_server.process(payload, {"request": request})
if isinstance(result, StreamingResult):
return StreamingResponse(result, media_type="text/event-stream")
if hasattr(result, "json"):
return Response(content=result.json, media_type="application/json")
return JSONResponse(result)
Read respond() carefully, because it contains the second docs error. The official docs' example calls simple_to_agent_input(thread, item, context) — three arguments. In the installed 1.6.5 SDK, that function takes exactly one: a sequence of thread items. The correct pattern is the one in OpenAI's own starter: load the thread's recent items from the store (newest first, so reverse them back into order), convert them with simple_to_agent_input(items), run the agent with Runner.run_streamed, and yield the converted stream events with stream_agent_response. Pass the three-argument form and you get a TypeError on the first message.
The route itself is deliberately boring: read the raw body, hand it to server.process(), and return whatever comes back — a streaming result for chat turns, a JSON result for thread management. There is no workflow ID, no client secret, and no call to POST /v1/chatkit/sessions anywhere in this path. Those belong to the hosted Agent Builder integration, and they die with it. Here, the ChatKit client connects directly to your server, and your app's own authentication — a login cookie, a header, whatever you already use — is what protects the endpoint.
Step 6: Run it and test it with curl#
Start the backend with your key in the environment — never in the code:
OPENAI_API_KEY=sk-proj-... uvicorn server:app --port 8000
Before opening a browser, prove the server speaks the ChatKit protocol. List threads — the store starts empty:
curl -s -X POST http://127.0.0.1:8000/chatkit \
-H 'Content-Type: application/json' \
-d '{"type":"threads.list","params":{}}'
{"data":[],"has_more":false}
That empty page is the whole wiring check in miniature: the route parsed the request, the server routed it, the store answered. Next, create a thread with a real user message. The payload shape matters — the SDK validates it strictly, and three fields are required even when empty:
curl -s -X POST http://127.0.0.1:8000/chatkit \
-H 'Content-Type: application/json' \
-d '{"type":"threads.create","params":{"input":{
"content":[{"type":"input_text","text":"Where is my order 4821?"}],
"attachments":[],
"inference_options":{}
}}}'
Two things to note. First, input is an object, not a string — send a bare string and validation fails with params.input: Field required. Second, attachments and inference_options are required fields on the message input even though they are empty here; omit either and the request is rejected. Both facts were confirmed against the installed SDK's models, not guessed.
One honest caveat: the sandbox used to verify this tutorial could exercise everything above — the imports, the protocol validation, the store, the guardrail, the tools — but not the live model reply, because the SDK's network path to the API stalls in that sandbox (a plain curl to the same endpoint answers in under a second). With a real key, the same threads.create streams the agent's reply back as server-sent events: the agent calls lookup_order with "4821" and answers that the Aurora headphones, $74.99, have shipped. If your reply instead says the order was not found, check the order number, not the code — the tool only knows the three orders in the dict.
Step 7: Put the widget on your site#
The backend is done; the widget is a React component. Scaffold a Vite app and install the ChatKit React bindings (version 1.6.1, verified):
npm create vite@latest store-chat -- --template react-ts
cd store-chat
npm install
npm install @openai/chatkit-react@1.6.1
Replace src/App.tsx with the widget. The api option points at your server, and domainKey is the development key the SDK uses to verify the integration's domain:

import { ChatKit, useChatKit } from "@openai/chatkit-react";
export default function App() {
const { control } = useChatKit({
api: {
url: "/chatkit",
domainKey: "domain_pk_localhost_dev",
},
});
return <ChatKit control={control} />;
}
The url is relative on purpose. The ChatKit client calls it with fetch, so a cross-origin URL would need CORS headers on your FastAPI app. A relative URL plus a Vite proxy keeps everything same-origin in development — add this to vite.config.ts:
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
server: {
proxy: {
"/chatkit": "http://localhost:8000",
},
},
});
Then run both halves — backend on port 8000 from Step 6, frontend with npm run dev — and open the Vite URL. Type "Where is my order 4821?" and watch the agent look it up. A small naming warning: the docs and the starter's README both give the development domain key as domain_pk_localhost_dev, but the starter's .env.example uses domain_pk_local_dev. If the widget refuses to connect, check the key first — it is the most likely culprit, and it is also the most confusingly documented value in the whole stack.
Which approach should you use?#
ChatKit currently offers two paths, and the choice is now made for you by a calendar date — but the trade-offs are worth stating plainly:
| Approach | Best for | Watch out for |
|---|---|---|
| Custom server (this tutorial) | Anything going to production; you need your own auth, your own data, your own tools | You own the store, the deployment, and the scaling |
| Hosted via Agent Builder | Prototypes built before the shutdown | Shuts down November 30, 2026 — do not start new work here |
| ChatGPT Workspace Agents | Internal agents for Business, Enterprise, or Edu workspaces | Workspace-only; not a public website widget |
If you already have an Agent Builder workflow in production, the migration the docs prescribe is exactly what this tutorial builds: export the workflow with Code → Agents SDK, then serve it behind ChatKit yourself. The agent logic survives; only the hosting changes. Budget a day for the export and a second day for the store — the in-memory version here is the one thing you must replace before real traffic, since a restart wipes every conversation.
The takeaway#
The Agent Builder shutdown looks like a rug-pull until you build the replacement: the pieces that survive — ChatKit and the Agents SDK — were always the load-bearing ones, and the self-hosted stack is strictly more capable than the canvas was. You get your own tools against your own data, guardrails that run before the model sees anything, and a server you can deploy anywhere. The cost is a store implementation and one route, and the docs' two stale examples — the phantom MemoryStore and the wrong simple_to_agent_input signature — are the only real traps. Build it once, and the widget on your site is yours: no workflow ID to expire, no hosted canvas to be deprecated out from under you.
Where to go next: replace the dict with a real order lookup, swap the in-memory store for a database-backed one, and add a second agent — an escalation agent that takes over when the support agent's confidence drops — using handoffs. The Agents SDK's handoff primitive is the same one this blog's multi-agent tutorial covers, and it plugs into this server without changing a line of the ChatKit wiring.