Inkeep tutorial - Autoplay SDK

Without context, your customer support chat has to ask what the user was doing and what went wrong. With Autoplay wired in, Inkeep already knows — and can explain the real blocker, point to the right next step, and link directly to the relevant workflow instead of giving a generic answer. This tutorial shows you how to build that flow using the Inkeep agents framework and InkeepEmbeddedChat from @inkeep/agents-ui. Your events, conversation history, and LLM keys never leave your infrastructure. Who this is for: Teams using or evaluating Inkeep who want chat to react to what users actually do — not just answer generic questions. Assumes comfort with Python, TypeScript/React, and a small FastAPI service. Stack: Inkeep agents framework (Docker), @inkeep/agents-ui, Next.js 14, Python 3.10+, FastAPI, uv, and Anthropic or OpenAI. https://developers.autoplay.ai/recipes/inkeep

✨ Final result

Without real-time context
With real-time context

Admin: why can't I unblock this vendor?

Bot: Vendors may be blocked for several reasons, including policy
violations, expired approvals, or missing compliance information.
Check the vendor details page for more information.

(Generic reply — the bot doesn't know which vendor the admin is viewing
or that the unblock attempt just failed.)

Admin: why can't I unblock this vendor?

Bot: It looks like you just tried to [complete action] on [item],
but it's blocked because [specific reason]. To move forward,
[next concrete step]. Here's where to do that: [link].

(Same question — but the bot already knows what the user was
on, what they attempted, and exactly what's in the way.)

Video walkthrough — Open on Loom if the player does not load.

📋 Prerequisites

Before you start, you need:

Node.js 18+ and Python 3.10+ on the host.
uv — the Python package manager used in this tutorial.
curl -LsSf https://astral.sh/uv/install.sh | sh
pnpm — the Inkeep agents monorepo uses pnpm workspaces.
npm i -g pnpm
Docker Desktop — for running Inkeep’s backing services (PostgreSQL, Doltgres, SpiceDB).
An Anthropic or OpenAI API key — the Inkeep agents framework calls your LLM directly; no Inkeep cloud key required.

That’s it. The tutorial covers every code file step by step — copy-paste runnable.

The Inkeep CDN widget (@inkeep/cxkit-js) requires a paid Inkeep cloud API key. This tutorial uses the open-source Inkeep agents framework (@inkeep/agents-ui) which you self-host with your own LLM key — no per-seat or per-call fee to Inkeep for the chat itself.

Architecture

┌─────────────────────────────────────────────────────┐
│  VendorOps  (Next.js, :3000)                        │
│                                                     │
│  ┌────────────────────────────────────────────────┐ │
│  │  Vendor profile                                │ │
│  │  Status: blocked                               │ │
│  │  Missing docs: W-9, certificate of insurance   │ │
│  └────────────────────────────────────────────────┘ │
│       │ sendVendorUnblockAttempt()                  │
│       │ POST /demo/actions                          │
│       ▼                                             │
│  ┌───────────────────────────────────────────────┐  │
│  │  Context fetch                                 │  │
│  │  GET /context/{user_id}                        │  │
│  └───────────────────────────────────────────────┘  │
│       │                                             │
│       ▼                                             │
│  ┌───────────────────────────────────────────────┐  │
│  │  InkeepEmbeddedChat                           │  │
│  │  → explains missing compliance documents      │  │
│  │  → points admin to request-documents flow     │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
               │ POST /demo/actions
               │ GET  /context/{user_id}
               ▼
┌─────────────────────────────────────────────────────┐
│  Bridge  (FastAPI, :8787)                           │
│                                                     │
│  httpx GET → Autoplay connector REST endpoint       │
│    (stateless pull by product_id + user_id;         │
│     no stream, no session store)                    │
│                                                     │
│  Context: vendor_unblock_attempt + blocked status   │
│    + missing compliance documents                   │
│                                                     │
│  GET  /context/{user_id}  → pulled + assembled      │
│                              context, on demand      │
└─────────────────────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────┐
│  Inkeep agents framework  (:3002)                   │
│  (self-hosted, your LLM key)                        │
│                                                     │
│  project: vendor-ops                                │
│  agent:   vendor-support                            │
│  sub-agent: compliance-support-worker               │
│                                                     │
│  InkeepEmbeddedChat ↔ AI sub-agent                  │
│  introMessage ← context from /context/{user_id}    │
└─────────────────────────────────────────────────────┘

Two inputs feed the context layer: the vendor profile reports the admin’s action directly to the bridge (POST /demo/actions), and the bridge pulls the vendor’s blocked status plus missing compliance-document state from the Autoplay connector the moment it’s needed. The bridge owns all context logic; Inkeep stays a clean conversational surface. The GET /context/{user_id} endpoint calls the Autoplay connector’s REST live-activity endpoint synchronously — a stateless, on-demand pull keyed by the admin’s stable user_id, not a session — and assembles a human-readable summary of their recent activity and the vendor’s compliance state. When the admin opens chat, this summary becomes the introMessage passed to InkeepEmbeddedChat — so the AI’s first message references the blocked vendor and missing documents, not a generic greeting. There’s no persistent connection to manage: the bridge asks the connector for “what has this user been doing” exactly once, right when the frontend needs it.

The tutorial

Step 1 — Connect real-time events — Build the vendor-management frontend, wire unblock attempts and vendor context into a FastAPI bridge, run the Inkeep agents framework in Docker, and embed InkeepEmbeddedChat. At the end of this step you have a working AI chat widget on the vendor profile. ~45 minutes.
Step 2 — Define proactive triggers — Add blocked-vendor detection to the bridge, wire the guidance channel to the frontend, and build the proactive handoff that opens Inkeep chat with the vendor’s missing compliance documents pre-loaded. ~45 minutes.

​✨ Final result

​📋 Prerequisites

​Architecture

​The tutorial

✨ Final result

📋 Prerequisites

Architecture

The tutorial