Galvanized Pukeko

(Only for ADK)

Galvanized Pukeko is a framework that enables LLM-powered agents to dynamically render forms, charts, and tables when interacting with users. It eliminates the need for static HTML pages while maintaining consistent formatting and branded interfaces.

Status: This is a proof-of-concept; expect frequent changes and occasional breakage while we iterate.

A quick demo on YouTube: https://youtu.be/rfiUhsaDtrU

Features

• Dynamic UI Rendering - AI agents can render forms, charts, and tables on-the-fly
• Real-time Communication - WebSocket integration for instant form updates
• Chat Interface - Built-in conversational UI powered by SSE streaming
• Extensible Architecture - Support for MCP (Model Context Protocol) and A2A (Agent-to-Agent) integrations
• Embedded Deployment - Web client can be served directly from the agent server

Monorepo Structure

This project is organized as a monorepo containing the following packages:

Package	Description	Documentation
galvanized-pukeko-agent-adk	Spring Boot application extending Google ADK with UI rendering capabilities. Available on Maven Central.	README
galvanized-pukeko-vue-ui	Vue.js UI component library and chat interface source (compiled into web-client)	—
galvanized-pukeko-web-client	Web client host: serves the Vue UI build, owns config.json and Playwright tests	README
gaunt-sloth-assistant	TypeScript CLI tool for agent workflows; provides an AG-UI-compatible HTTP server as an alternative backend	—

System Architecture

The system consists of a Web UI (Vue.js) and a UI Server ADK (Spring Boot) hosting the AI Agent.

graph LR
    subgraph Browser
        UI["Web UI (Vue.js)<br/>Port: 5555"]
    end

    subgraph Server["UI Server ADK (Spring Boot)<br/>Port: 8080"]
        UIAgent["UI Agent<br/>(io.github.galvanized_pukeko.UiAgent)"]
    end

    subgraph Agents["External AI Agents<br/>(Business Logic)"]
        direction TB
        Agent1["Agent 1"]
        Agent2["Agent 2"]
    end

    UI -->|AG-UI| UIAgent
    UI <-->|WebSocket /ws| UIAgent
    UIAgent <-.->|A2A| Agent1
    UIAgent <-.->|MCP| Agent2

Loading

Components Overview

1. Web Client (packages/galvanized-pukeko-web-client):

   • Vue.js application providing chat interface and dynamic form renderer
   • Runs standalone on port 5555 for development, or served from the ADK agent
   • Communicates via AG-UI for chat and WebSockets for UI rendering

2. Agent ADK (packages/galvanized-pukeko-agent-adk):

   • Spring Boot application running on port 8080
   • Extends Google ADK to host UiAgent with dynamic UI rendering tools
   • Serves the built web client and exposes API endpoints
   • Supports MCP and A2A integrations for external tools and agents

Getting Started

Prerequisites

• Java 17+ (recommended: Temurin 21)
• Node.js 24+
• Maven (included via Maven wrapper ./mvnw)

Quick Start

Option 1: ADK Agent + Web Client (Development)

Start both the ADK agent and the web client dev server together:

npm run start-adk

This builds and starts:

1. Agent ADK on port 8080 (logs to start-adk-java.log)
2. Web Client dev server on port 5555

Navigate to http://localhost:5555 for development. Press Ctrl+C to stop both.

Option 2: Gaunt Sloth AG-UI backend

To use the TypeScript Gaunt Sloth backend instead of the Java ADK agent:

npm run start-gth-ag-ui

This starts:

1. Gaunt Sloth AG-UI server on port 3000
2. Web Client dev server on port 5555 (pointing at the Gaunt Sloth backend)

Manual Startup

Start the Agent ADK only:

cd packages/galvanized-pukeko-agent-adk
./mvnw clean compile exec:java -Dexec.classpathScope=compile \
  -Dexec.args="--server.port=8080 --adk.agents.source-dir=target"

Start the Web Client dev server only:

npm run web

Deploying Web Client to Agent

After making changes to the web client, rebuild and deploy to the ADK agent:

npm run sink

This builds the Vue UI (galvanized-pukeko-vue-ui) and copies the artifacts into the ADK agent's resources directory.

Usage

1. Open http://localhost:8080 (or http://localhost:5555 in development mode)
2. Type "Hello" in the chat to verify connectivity
3. Try these commands to see dynamic UI rendering:
   • "Show me a contact form" - Renders a dynamic form
   • "Show me a chart of month lengths" - Displays a chart
   • "Show me a table of suppliers" - Renders a data table

Testing

We use Playwright for End-to-End (E2E) testing.

Running Integration Tests

The integration test scripts start all required services automatically:

# ADK agent integration tests
npm run it-adk

# ADK agent integration tests (headed browser)
npm run it-adk-headed

# Gaunt Sloth AG-UI integration tests
npm run it-gth-ag-ui

If Playwright reports the browser is not found, run npx playwright install.

Manual Test Run (services already running)

# Run all e2e tests
npx playwright test

# Interactive UI mode
npx playwright test --ui

# Headed mode (visible browser, sequential execution)
npx playwright test --headed --workers=1

# Debug mode
npx playwright test --debug

Configuration

Environment Variables

ADK Agent (Google Gemini):

Variable	Description	Default
GOOGLE_API_KEY or GEMINI_API_KEY	API key for Google AI / Gemini models	Required
GOOGLE_GENAI_USE_VERTEXAI	Set to "true" to use Vertex AI instead of Google AI	false

Gaunt Sloth backend (multi-provider):

The Gaunt Sloth backend supports many AI providers (Anthropic, OpenAI, Groq, Google AI, Ollama, xAI, etc.). Configure via .gsloth.config.json in the working directory. See examples/pukeko-gaunt-sloth-ag-ui/ for a sample configuration.

Application Properties

See Agent ADK README for detailed configuration options including:

• UI customization (logo, header, footer)
• CORS settings
• MCP server integration
• A2A agent configuration

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Related Resources

• Google ADK (Agent Development Kit)
• Model Context Protocol (MCP)
• Vue.js Documentation