Building a Composable AI Agent Frontend Library with VAPD AgentKit

Background and Goal

To support three business scenarios—notes, knowledge base, and project management—the team built a unified, composable AI Agent capability that can be incrementally enhanced with multi‑turn dialogue, tool calls, context injection, and traceability.

Design Principles

Message as Protocol: Backend events are decoded into a front‑end message model, allowing the UI to consume messages without caring about the source protocol.

Plug‑in Runtime: Any backend that can emit a stream (SSE, GraphQL, WebSocket, Fetch ReadableStream, etc.) can be adapted to the same AgentStreamEvent format.

Front‑end Orchestration: Hooks and context manage agents, tools, retries, callbacks, forming a stable glue layer.

Progressive Enhancement: The first phase implements Chat mode while reserving threadId / runId for future history, checkpoint, replay, and evaluation features.

Architecture Overview

The core modules for Chat mode are:

Unified Message Model covering UserMessage, AssistantMessage, ThinkingMessage, ActionExecutionMessage, ResultMessage, with status, optional parentMessageId, and extensibility for images or status messages.

Runtime Adapter Interface exposing generateResponse(params) / retry(params) that return ReadableStream<AgentStreamEvent>, and sendFeedback for positive/negative feedback. It can connect to VAPD, GraphQL, WebSocket, or custom fetch streams, normalising everything to AgentStreamEvent.

Front‑end Orchestration where AgentKit provides a provider that injects runtime, actions, context tree, messages, loading state, and callbacks. useAgentChat composes useChat to offer appendMessage, reloadMessages, stopGeneration, threadId, runId, etc.

Vue UI Components encapsulate the chat container, input area, actions, and suggestions, synchronising with the core via useCopilotChatLogic.

Event Flow and Message Model

Backend emits events; the Adapter aggregates token fragments into ThinkingMessage / AssistantMessage, maps tool calls to ActionExecutionMessage and tool results to ResultMessage, and maintains threadId (session) and runId (loop) for future history and checkpoint support. The UI only renders the standardised AgentStreamEvent:

export type AgentStreamEvent = {
  threadId?: string | null;
  runId?: string | null;
  messages?: Message[];
  guardrailsFailureReason?: string;
};

This decouples UI rendering from transport details.

Agent Loop and Tool Calls

Stream events are appended in order.

When an ActionExecutionMessage appears, the front‑end tool handler is invoked and its result is wrapped as a ResultMessage.

At the end of a loop, the final AssistantMessage is returned and the next round can start.

In “reload/variant” scenarios, existing candidates are kept and new ones are added, forming a multi‑variant set.

Tool calls are declared via useAgentAction, which defines name, description, parameters, a handler returning a result packaged as ResultMessage, optional rendering as an embedded card, idempotent execution, and delegation to the Adapter for protocol‑agnostic handling.

UI Interaction and Suggestions

Chat container renders Thinking, Assistant, User, and Error messages.

Supports copy, stop, regenerate, and suggestion clicks. useCopilotChatLogic links core capabilities with UI events and provides throttled suggestion refresh.

Minimal Integration: Three Steps

// 1) Wrap the root component with AgentKit and select a Runtime
<template>
  <AgentKit :runtime="'runtime'">
    <MyChat />
  </AgentKit>
</template>

<script lang="ts">
import { AgentKit, VapdRuntimeAdapter } from '@vapd-agentkit/vue-core';
export default {
  components: { AgentKit },
  setup() {
    const runtime = new VapdRuntimeAdapter({/* optional custom url/headers/... */});
    return { runtime };
  }
};
</script>

// 2) Use the Chat component in a page
<template>
  <AgentChat :labels="{ placeholder: 'Ask something' }" />
</template>
<script setup lang="ts">
import { AgentChat } from '@vapd-agentkit/vue-ui';
</script>

// 3) (Optional) Register a tool for the model to call
import { useAgentContext } from '@vapd-agentkit/vue-core';
const ctx = useAgentContext();
ctx.setAction('searchDocs', {
  name: 'searchDocs',
  description: 'Search knowledge base',
  parameters: [{ name: 'q', type: 'string' }],
  handler: async ({ q }) => {
    const result = await fetch(`/api/search?q=${encodeURIComponent(q)}`).then(r => r.json());
    return { hits: result.items };
  }
});

Business Alignment

For notes, knowledge base, and project management, the front‑end can merge the selected text, tags, or page structure into agentArgs via addContext without changing the runtime. Future plans include a knowledge‑base RAG agent that supports internet and internal retrieval, semantic vector search, and eventually editing or adding documents directly.

For integration‑process automation, the system will allow non‑technical users to describe workflows in natural language, automatically generate nodes, provide form‑based configuration with intelligent validation, step‑by‑step verification, simulation runs, and log output.

Next Steps

History: Persist chat logs for replay using the pre‑embedded threadId.

Checkpoints: Use runId to mark loops and enable continue/undo/rollback capabilities.

Tool Events: Implement Human‑In‑The‑Loop confirmation and form filling for tool interactions.

Conclusion

By combining a unified message model, a protocol‑agnostic runtime adapter, and front‑end orchestration, the Chat mode becomes a modular foundation where the UI only cares about messages, the runtime can be swapped freely, and interactions such as tools, context, and retries live in the orchestration layer. The threadId / runId groundwork prepares for history and checkpoint features, allowing the three business scenarios to evolve on the same infrastructure.