Docs MDX components

Embeddable components available inside every .mdx file — Stackblitz, CodeSandbox, GIFs, Mermaid.

Every MDX page under /docs has access to these components. No import required.

#`<Playground />`

Inline runnable playground. Runs in-browser via Sandpack — no remote cold-start.

<Playground preset="basic-chat" />

Custom files:

<Playground
  title="Custom demo"
  entry="/App.tsx"
  files={{
    '/App.tsx': `export default function App() { return <h1>hi</h1> }`,
  }}
/>

Prop	Type	Default
`preset`	`'basic-chat' \| 'tool-call'`	—
`files`	`Record<string, string>`	overrides preset
`entry`	`string`	`/App.tsx`
`dependencies`	`Record<string, string>`	—
`eager`	`boolean`	`false` (click-to-load)
`title`	`string`	—

Presets live in components/mdx/playground-presets.ts. Add new ones by exporting another entry.

Live playground · runs in your browser

Basic chat

Streaming chat with a mock adapter.

#`<FrameworkTabs />`

Framework picker with global persistence. Pick React once; every tab on every page switches automatically.

<FrameworkTabs defaultValue="react">
  <Framework name="react">
    ```tsx
    import { useChat } from '@agentskit/react'
    ```
  </Framework>
  <Framework name="vue">
    ```ts
    import { useChat } from '@agentskit/vue'
    ```
  </Framework>
  <Framework name="svelte">
    ```ts
    import { useChat } from '@agentskit/svelte'
    ```
  </Framework>
</FrameworkTabs>

Known name values: react, vue, svelte, solid, angular, react-native, ink, node, cli. Unknown names accepted — label falls back to the raw name. Override the label per framework with <Framework label="…" />.

Preference persists in localStorage under ak:framework and syncs across every mounted tab group via a custom event.

#Callouts

Pick the right one and the reader's eye will land on it.

<Tip>Caching the adapter result is usually safe.</Tip>
<Warning>The runtime aborts on the first unhandled tool error.</Warning>
<Pitfall>Do not mutate the `messages` prop. Clone it first.</Pitfall>
<Performance>Stream chunks on `requestAnimationFrame` for 60fps.</Performance>
<Security>Never render tool output as raw HTML.</Security>
<Info>Accepted in all runtimes since v0.3.</Info>
<Success>Shipped in v0.6.</Success>

Tip

Caching the adapter result is usually safe.

Warning

The runtime aborts on the first unhandled tool error.

Pitfall

Do not mutate the messages prop. Clone it first.

⚡ Performance

Stream chunks on requestAnimationFrame for 60fps.

🔒 Security

Never render tool output as raw HTML.

#`<Compare />`

Side-by-side do-vs-don't.

<Compare
  good={<pre>{`useChat({ adapter, memory })`}</pre>}
  bad={<pre>{`useChat({ adapter, memory: new Memory() }) // new ref each render`}</pre>}
/>

#`<Since />`

Version badge for APIs.

### useChat <Since v="0.4.0" pkg="react" />

#`<ArchDiagram />`

Interactive package dependency graph. Click any node to pin it; hover to explore neighbors.

<ArchDiagram />

Package graph · click to lock · hover to explore

#`<RunCode />`

Wrap any fenced code block to get a "Run ▶" button in its top-right corner. Clicking swaps the snippet for a live Sandpack playground using a preset or inline files.

<RunCode preset="basic-chat">
```tsx
import { useChat } from '@agentskit/react'

export function App() {
  const { messages } = useChat()
  return messages.map((m) => <p key={m.id}>{m.content}</p>)
}
```
</RunCode>

Prop	Type	Default
`preset`	`'basic-chat' \| 'tool-call'`	—
`files`	`Record<string, string>`	overrides preset
`entry`	`string`	`/App.tsx`
`dependencies`	`Record<string, string>`	—

#`<StackblitzEmbed />`

Live editable sandbox for any GitHub path.

<StackblitzEmbed
  project="AgentsKit-io/agentskit/tree/main/apps/example-react"
  file="src/App.tsx"
  height={520}
/>

Prop	Type	Default
`project`	`string`	required — `owner/repo/tree/branch/path` or Stackblitz id
`file`	`string`	—
`height`	`number`	520
`title`	`string`	auto
`lazy`	`boolean`	`true` (click-to-load, keeps LCP fast)

#`<CodeSandboxEmbed />`

Mirror shape for CodeSandbox-hosted examples.

<CodeSandboxEmbed sandbox="abcd123" file="/src/App.tsx" height={520} />

#`<GifEmbed />`

A11y-aware GIF with reduced-motion fallback.

<GifEmbed
  src="/demos/streaming-chat.gif"
  poster="/demos/streaming-chat.png"
  alt="Streaming chat response with tool calls"
  caption="RAG chat responding with sources"
/>

Respects prefers-reduced-motion — shows the PNG poster + a link to the animation for users with motion sensitivity.

#`<Artifact />`

Claude.ai-style typed inline artifact. Five kinds: code, json, markdown, html, chart.

<Artifact
  kind="code"
  language="ts"
  title="agent.ts"
  content={`import { openai } from '@agentskit/adapters'\n\nexport const adapter = openai({ apiKey: '...', model: 'gpt-4o' })`}
/>

<Artifact kind="chart" title="Latency by adapter" content='[
  { "label": "groq", "value": 80 },
  { "label": "openai", "value": 320 },
  { "label": "anthropic", "value": 410 }
]' />

html artifacts run in an iframe with sandbox="" (no scripts, no same-origin) — safe to render LLM-generated HTML.

#`<LivePlayground />`

JS/TS editor + Web Worker sandbox runner. Each edit spawns a fresh worker that evaluates the snippet in isolation. No DOM, 3-second timeout.

<LivePlayground
  title="Reduce demo"
  code={`const sum = [1,2,3,4,5].reduce((a, b) => a + b, 0)\nconsole.log(sum)`}
/>

Pair with <Artifact /> to render the resulting structure inline.

#`<G />` — inline glossary

Inline glossary lookup with hover / focus popover. Terms are registered once in apps/docs-next/components/mdx/glossary.tsx; pages reference them by key.

The <G term="adapter">adapter</G> is the only thing that changes when
swapping providers. Behind the scenes, an <G term="observer">observer</G>
streams events to your trace pipeline.

<G term="..."> is case-insensitive. Adding a term: append one entry to the GLOSSARY map — one definition + one canonical link.

#`<VoiceMode />`

Push-to-listen mic + energy-threshold VAD + barge-in. Bring your own ASR / LLM / TTS via transcribe, respond, speak props — the component is vendor-free.

<VoiceMode
  transcribe={async (blob) => fetch('/api/transcribe', { method: 'POST', body: blob }).then(r => r.text())}
  respond={async function* (text) {
    const response = await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ text }) })
    const reader = response.body!.getReader()
    const decoder = new TextDecoder()
    while (true) {
      const { done, value } = await reader.read()
      if (done) return
      yield decoder.decode(value)
    }
  }}
  speak={async (text) => fetch('/api/tts', { method: 'POST', body: text }).then(r => r.blob())}
/>

VAD is a 2048-bin RMS threshold (default 0.02); barge-in cuts assistant audio the moment user energy crosses it. No external models / wasm bundles.

#`<Mermaid />`

Inline diagrams. See components/mermaid.tsx.

#Using all together

A typical recipe page mixes code blocks, a GIF showing the outcome, and a live Stackblitz:

## What you'll build

<GifEmbed src="/demos/rag-chat.gif" alt="RAG chat UI streaming" />

## Live sandbox

<StackblitzEmbed project="AgentsKit-io/agentskit/tree/main/apps/example-react" file="src/App.tsx" />

## Copy-paste

\`\`\`ts
// ...
\`\`\`

Contribute → package docs
Issue #481/#482/#483/#484 — future MDX components (LivePlayground, better GIF helpers).

Explore nearby

✎ Edit this page on GitHub·Found a problem? Open an issue →·How to contribute →

Docs MDX components

#<Playground />

#<FrameworkTabs />

#Callouts

#<Compare />

#<Since />

#<ArchDiagram />

#<RunCode />

#<StackblitzEmbed />

#<CodeSandboxEmbed />

#<GifEmbed />

#<Artifact />

#<LivePlayground />

#<G /> — inline glossary

#<VoiceMode />

#<Mermaid />