HTML Agent

This repository is an experiment in using HTML as a first-class output format for AI agents.

Instead of treating the agent as something that only returns plain text or JSON, this project tests a different model:

• the agent can answer directly in HTML
• the UI renders that HTML live while the model is still streaming
• tool calls and agent loop activity appear inline in the same conversation timeline
• the same agent core can be exercised from a CLI or from a browser-based chat UI

Purpose

The current goal is to explore questions like:

• What becomes easier when an agent can return structured HTML instead of plain text?
• How usable is a chat interface where the assistant can emit rich layouts, SVG diagrams, and formatted explanations directly?
• What does the agent loop feel like when tool activity is shown as part of the conversation rather than in a separate debugger view?
• How much frontend structure is needed to make agent-generated HTML practical and understandable?

This is not intended to be a general-purpose agent framework. It is a focused sandbox for testing HTML-native agent output.

Workspace

• evaluator/simple-agent: reusable Rust agent library
• evaluator/simple-agent-cli: CLI for running the agent from a terminal
• evaluator/simple-agent-server: HTTP server with the web chat frontend
• evaluator/simple-agent-server/frontend: React + TypeScript source for the frontend
• site: old static archive from an earlier version of the project

Current Behavior

• The agent uses a built-in system prompt from evaluator/simple-agent/src/prompts/system.md.
• Assistant replies are rendered as trusted HTML in the web UI.
• The conversation panel is a single timeline containing:
  • user and assistant messages
  • streamed assistant output
  • inline agent-loop/tool activity
• The server uses SSE to stream run updates to the browser.
• The agent can call built-in tools such as bash, create_file, readfile, and multiedit.

Running the CLI

The CLI reads config.json from the directory it is launched in. If config.json does not exist, it writes a starter file and exits.

Example:

cargo run --manifest-path /path/to/repo/evaluator/Cargo.toml -p simple-agent-cli

Then type or pipe the prompt into stdin. For interactive use, finish input with Ctrl-D.

Running the Server

The server reads the same config.json from the directory it is launched in.

Example:

cargo run --manifest-path /path/to/repo/evaluator/Cargo.toml -p simple-agent-server

By default it listens on http://127.0.0.1:3000.

The main frontend source lives in:

• evaluator/simple-agent-server/frontend/src/App.tsx
• evaluator/simple-agent-server/frontend/src/lib/timeline.ts

The Rust server currently serves the built frontend assets from evaluator/simple-agent-server/static/.

Config

The shared config.json supports:

• base_url: OpenAI-compatible API base URL
• model: model name
• token_env_var: optional bearer token environment variable
• messages_file: optional initial message history
• workdir: working directory for tool execution
• max_iterations: iteration cap, default 100
• output_json: optional path for full run output
• server_host: server bind host, default 127.0.0.1
• server_port: server bind port, default 3000

Library Entry Point

simple-agent exposes run_agent_with_events(...), which both the CLI and server use.

That shared path is where:

• the system prompt is injected
• tool-enabled agent execution happens
• structured agent events are emitted for the server UI