# Agent Kit

> Vue components for agent products: conversations, streaming answers, thinking and tool process, questions and artifacts. Connect one transport and it runs as a full page or a floating widget. Package: `@cognitiolabs/agent-vue` (Vue 3).

Survives disconnects: Streaming answers resume from a cursor. Reload, go offline, or switch away and back, and reading continues where it left off, with nothing rerun or lost. Visible process: Thinking, parallel tools, subtasks, plans and questions are drawn as a timeline that collapses to one line when done and opens on demand. Themeable: Components read only `--ak-*` variables. Override a few colours and fonts and the whole interface takes on your product’s look.

**Install.** Packages are published to GitHub Packages under the CognitioLabs organization and are available to its members only. Point the `@cognitiolabs` scope at it in your project’s `.npmrc`, reading the token from an environment variable rather than the file. Set `GITHUB_TOKEN` to a classic GitHub token with the `read:packages` scope. In GitHub Actions use the workflow’s own `secrets.GITHUB_TOKEN`, and give your repository read access on the package’s settings page. `@cognitiolabs/agent-vue` brings `agent-client` and `agent-protocol` with it; if you import their types (for example `ConfirmPayload` from `@cognitiolabs/agent-protocol`), add them to your own dependencies too.

```ini
# .npmrc
@cognitiolabs:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```

```bash
npm install @cognitiolabs/agent-vue vue
```

**Smallest complete app.** Two files on top of a Vite + Vue 3 project (`npm create vite@latest my-app -- --template vue`):

```js
// main.js
import { createApp } from 'vue'
import '@cognitiolabs/agent-vue/style.css'
import App from './App.vue'

createApp(App).mount('#app')
```

```vue
<!-- App.vue -->
<script setup>
import { AgentChat, createAgentI18n, createHttpTransport, provideAgentI18n } from '@cognitiolabs/agent-vue'

// UI language: zh (the default) or en; every child component reads it from here
provideAgentI18n(createAgentI18n({ locale: 'en' }))

// Requests go to /api by default
const transport = createHttpTransport({ baseUrl: '/api' })
</script>

<template>
  <div style="height: 100vh">
    <AgentChat :transport="transport" title="Agent" layout="workspace" sync-url />
  </div>
</template>
```

**Know before you write code.**

- `<AgentChat :transport="...">` is the whole UI. `createHttpTransport({ baseUrl: '/api' })` talks to a backend that implements the agent-kit HTTP binding ([endpoints](guides/get-started.md#http-endpoints-used-by-createhttptransport)). Any object implementing `AgentTransport` works too.
- Build the backend from the [Server guide](guides/server.md): a complete Express server, keyless provider, atomic user input, conversation CRUD, optional endpoints and protocol v1. `createRunHandlers` alone does not supply the host routes.
- `baseUrl` is a same-origin path. In development, proxy it to your backend in `vite.config.js`, e.g. `server: { proxy: { '/api': 'http://127.0.0.1:8787' } }` (use your backend's address).
- Interface text defaults to Chinese: call `provideAgentI18n(createAgentI18n({ locale: 'en' }))` in `App.vue` for English.
- Import `@cognitiolabs/agent-vue/style.css` once. Components used on their own (without `<AgentChat>`) must sit inside an element with class `ak-root`.
- Restyle by overriding `--ak-*` CSS variables ([Theming](guides/theming.md)).

## Guides

- [Get started](guides/get-started.md): Four steps to a complete agent interface in a Vue 3 project: install the package, import the styles, drop in an AgentChat, connect your backend.
- [Server](guides/server.md): Build the backend for AgentChat: a runnable Express host, atomic input, providers, tools and resumable events.
- [Theming](guides/theming.md): Components read only `--ak-*` CSS variables. Override them on `:root` or any `.ak-root` container to restyle; defaults are declared with `:where`, so any selector in your product wins.

## Components

- [AgentChat](components/agent-chat.md): Full page. A complete agent UI that runs from a single transport.
- [ConversationSidebar](components/conversation-sidebar.md): Sidebar. Conversation list: grouped by day, pin, rename.
- [Welcome](components/welcome.md): Welcome. Title, composer and example prompts for a new chat.
- [MessageUser](components/message-user.md): User message. User bubble: attachments, copy and edit.
- [MessageAssistant](components/message-assistant.md): Assistant message. Streaming answers, thinking and tool process, artifacts.
- [CodeBlock](components/code-block.md): Code blocks. Syntax highlighting, copy, folding, two styles.
- [MessageActions](components/message-actions.md): Reply toolbar. Copy, regenerate, rate, switch versions.
- [SourceList](components/sources.md): Sources and citations. Inline [n] citations with previews, and the source list.
- [TraceTimeline](components/trace-timeline.md): Process timeline. One segment of thinking and tool calls, collapsed to one line.
- [PlanBlock](components/plan-block.md): Plan. The agent’s own to-do list, updated as it works.
- [ProcessPanel](components/process-panel.md): Right panel. Plan, steps, artifacts and usage for the workspace layout.
- [SearchStep](components/search-step.md): Search step. Queries and results inside the process timeline.
- [RunNotice](components/run-notice.md): Connection and error notice. Reconnecting, waiting to retry, or a failed run.
- [Nono](components/nono.md): Nono. A small character that shows what the agent is doing.
- [Composer](components/composer.md): Composer. Multi-line input, attachments, modes, queueing and stop.
- [SlashMenu](components/slash-menu.md): Slash menu. Type / for skills and commands.
- [MentionMenu](components/mention-menu.md): Mention menu. Type @ to mention a file or person.
- [AskPrompt](components/ask-prompt.md): Question card. The agent asks mid-turn; replaces the composer.
- [ToolApproval](components/tool-approval.md): Approval card. Ask before a sensitive tool runs; replaces the composer.
- [ContextUsage](components/context-usage.md): Usage ring. How much of the context window is used.
- [ArtifactCard](components/artifact-card.md): Artifact card. A web page or file produced in this turn.
- [ArtifactPanel](components/artifact-panel.md): Artifact panel. Preview web artifacts in a sandbox.

## Optional

- [llms-full.txt](llms-full.txt): this file followed by every page above, in one file