Hosted and self-hosted Ask backend
Production Ask handler for grounded semantic answers — one protocol, host-owned adapters.
Hosted and self-hosted Ask backend
createAskServiceHandler is the production boundary for semantic questions that the deterministic plane cannot answer. One public protocol in every deployment; all authority is derived server-side.
Chat does not reimplement embeddings, vector search, or model transport. Those stay on AgentsKit — RAG, providers/adapters, and memory.
How a question is answered
- Exact / known questions hit the local deterministic artifact (no model).
- Misses escalate to the trusted Ask handler.
- Host injects auth, site policy, retriever, generator, rate limits, and storage.
Shared production factory
import { createAskServiceHandler } from '@agentskit/chat/server'
export const ask = createAskServiceHandler({
authenticate: (request, signal) => auth.verify(request, signal),
resolveSite: (identity, signal) => siteRegistry.resolve(identity.siteId, signal),
resolveSubjectId: identity => identity.subjectId,
retrievers: {
local: { retrieve: input => localRag.retrieve(input) },
federated: { retrieve: input => federatedRag.retrieve(input) },
},
generator: providerGenerator,
sessionStore: durableCasStore,
rateLimit: input => limiter.consume(input.site.siteId, input.subjectId, input.signal),
onMetric: metric => telemetry.record(metric),
})localRag/federatedRagwrap AgentsKit RAG / Retriever.providerGeneratoruses an AgentsKit provider/adapter — Chat never ships model SDKs.
Adapters come from AgentsKit providers: currently 25 native adapters spanning 140+ catalog providers and 5k+ models — Chat does not reimplement them.
Hosted route (Next.js)
// app/api/ask/route.ts
import { createAskServiceHandler } from '@agentskit/chat/server'
const handler = createAskServiceHandler({ /* host adapters above */ })
export const POST = (request: Request) => handler(request)Self-hosted / edge
The same handler works wherever Web Request/Response exist (Hono, Workers, Node 18+). Keep secrets and policy on the server — never in the client shell.
Client shell (docs assistant pattern)
import { defineChat, createAskAdapter, createDeterministicAnswerAdapter } from '@agentskit/chat'
import { AgentChat } from '@agentskit/chat/react'
const ask = createAskAdapter({ endpoint: '/api/ask', corpus: 'public', persona: 'guide' })
const adapter = createDeterministicAnswerAdapter({
artifact: verifiedKnowledge,
fallbackMode: 'backend',
fallback: ask,
})
export const docsChat = defineChat({
id: 'docs',
chat: { adapter },
})
export const DocsAssistant = () => (
<AgentChat definition={docsChat} placeholder="Ask about the product…" />
)Live on this site: the floating Ask the docs button uses this stack.
Security invariants
| Rule | Why |
|---|---|
| Auth before body parse | Untrusted JSON never runs unauthenticated |
| Site policy server-side | Client corpus/persona are equality hints only |
| Citations required | Successful answers include ≥1 safe citation |
| Host owns rate limits | Framework does not ship multi-tenant infra |