🤖

kandi-agentic-forms

v0.1.0 · MIT · KandiForge

AI-powered conversational system where an agent uses MCP tools and chat to guide users toward a predefined end state. XML spec in, structured output files out.

Architecture

React Client (FormProvider + KandiAgenticFormContainer)
    │ SSE Stream + REST API
    ▼
Node.js Server SDK (kandi-agentic-forms/server)
    │ createFormServer({ adapterConfig, sessionStore, verifyToken })
    ▼
Agent Adapter (Vercel AI SDK / Forge)
    │ streamText + tool calling + MCP servers
    ▼
LLM Provider (OpenAI / Anthropic)

Features

📋

XML Form Specs

Declarative <agentic-form> format defines fields, agent behavior, validation, conditions, and output files.

🤖

Agent Adapter

Abstract interface for AI providers. Ships with Vercel AI SDK adapter — swap in your own.

🔧

MCP Servers

Each form spec declares which MCP servers the agent can use — per-form capability boundaries.

📡

SSE Streaming

Real-time agent responses via Server-Sent Events with Bearer token auth.

🎨

MUI Container

Glassmorphism chat drawer + artifact timeline. Stop button, progress bar, file preview.

📦

Output Files

Produces manifest.json, form-data.json, session-log.json, and rendered files from templates.

Getting Started

Install

terminal

npm install kandi-agentic-forms

# Server (pick your LLM provider)
npm install ai @ai-sdk/anthropic

# MUI components (optional)
npm install @mui/material @emotion/react @emotion/styled

Define a Form Spec (XML)

Create an XML file that defines what data to collect, agent behavior, validation rules, and output files.

project-setup.xml

<agentic-form name="project-setup" version="1.0">
  <agent>
    <tone>professional-friendly</tone>
    <greeting>Let's set up your project!</greeting>
    <error-recovery strategy="retry-with-hint" max-retries="3" />
  </agent>

  <sections>
    <section id="basics" label="Project Basics" order="1">
      <field id="name" type="text" required="true">
        <label>Project Name</label>
        <validation>
          <pattern regex="^[a-z][a-z0-9-]*$" message="Lowercase with hyphens" />
        </validation>
      </field>
      <field id="framework" type="select" required="true">
        <label>Framework</label>
        <options>
          <option value="nextjs">Next.js</option>
          <option value="remix">Remix</option>
          <option value="astro">Astro</option>
        </options>
      </field>
    </section>
  </sections>

  <output>
    <manifest filename="manifest.json" />
    <raw-data filename="project-config.json" />
    <session-log filename="setup-log.json" />
  </output>
</agentic-form>

Create the Server

lib/form-server.ts

import { createFormServer } from 'kandi-agentic-forms/server';

const forms = createFormServer({
  adapterConfig: {
    provider: 'anthropic',
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: 'claude-sonnet-4-20250514',
  },
  sessionStore: mySessionStore,
  verifyToken: async (token) => auth.verifyToken(token),
});

// Mount on Express, Next.js, Vercel, Fastify, etc.
app.post('/forms/sessions', forms.handleCreateSession);
app.get('/forms/sessions/stream', forms.handleStream);
app.post('/forms/sessions/message', forms.handleSendMessage);

Add the Client

app.tsx

import { FormProvider } from 'kandi-agentic-forms/react';
import { KandiAgenticFormContainer } from 'kandi-agentic-forms/react/mui';

function App() {
  return (
    <FormProvider config={{ formServerUrl: '/api/forms', getToken }}>
      <KandiAgenticFormContainer height="600px" />
    </FormProvider>
  );
}

Entry Points

Import Path	Purpose
kandi-agentic-forms	Core + React exports
kandi-agentic-forms/core	Types, spec parser, validator, FormSession
kandi-agentic-forms/react	FormProvider, useAgenticForm, useFormStream
kandi-agentic-forms/react/headless	HeadlessFormChat (render-prop)
kandi-agentic-forms/react/mui	KandiAgenticFormContainer + styled components
kandi-agentic-forms/server	createFormServer, VercelAdapter, SessionManager

Server Handlers

Method	Path	Description
POST	/sessions	Create session from XML spec
GET	/sessions/:id/stream	SSE stream for session events
POST	/sessions/:id/message	Send user message to agent
GET	/sessions/:id	Get session state
POST	/sessions/:id/complete	Trigger output generation
DELETE	/sessions/:id	Cancel/delete session
POST	/specs/validate	Validate XML spec

GitHub npm

← Back to packages