agent-file

v1.0.5

Published

7 months ago

Self-contained HTML agent format with built-in security

0High
0Medium
0Low

maceip

ai agent html self-contained portable security langchain langgraph mcp model-context-protocol

agent.html

agent.html is a format for packaging AI agents as single, self-contained HTML files. Share agents as easily as sharing a document—no backend, no installation, no dependencies.

Get started in 10 seconds:

bun install agent-file
agent-html quick
# Open agent.html in your browser - done!

Why agent.html?

Traditional AI agents require complex deployment infrastructure. agent.html packages everything—manifest, code, memory, and UI—into a single HTML file that runs directly in any modern browser.

Key benefits:

Self-contained: One file contains everything
Portable: Share via email, download, or file system
Secure: Built-in integrity checking and permission system
Universal: Works in any modern browser
Framework agnostic: Convert from LangChain, TensorFlow Lite RT, vanilla JS, or WASM (incl wasi)
MCP integration: Built-in Model Context Protocol client for tool calling and resource access

Quick Start

Installation

bun install agent-file

Fastest Way: One Command

Create a working agent instantly:

agent-html quick

This creates agent.html - open it in your browser and you're done! Set your OpenAI API key in the browser console:

await window.agent.setApiKey("sk-...")
await window.agent.run("Hello!")

Customization Path

Create template files to customize:

agent-html init
# Edit manifest.json and agent.js to your needs
agent-html generate --manifest manifest.json --code agent.js

Programmatic Usage

import { AgentFile } from 'agent-file'

const html = await AgentFile.create({
  manifest: {
    id: 'my-agent',
    name: 'My AI Agent',
    version: '1.0.0',
    permissions: {
      network: ['api.openai.com'],
      storage: false,
      code: false
    }
  },
  code: `
    class Agent {
      async run(input) {
        // Your agent logic here
        return result
      }
    }
  `,
  ui: 'full'
})

await Bun.write('my-agent.html', html)

Open my-agent.html in a browser and interact via window.agent.run(input).

How It Works

An agent.html file is a complete HTML document with embedded components:

<!DOCTYPE html>
<html>
  <body>
    <!-- Agent Manifest -->
    <script type="application/json" id="agent-manifest">
      { "id": "my-agent", "permissions": {...}, ... }
    </script>

    <!-- Agent Code -->
    <script type="text/plain" id="agent-code">
      class Agent { ... }
    </script>

    <!-- Integrity Hashes -->
    <script type="application/json" id="agent-integrity">
      { "manifestHash": "sha256-...", "codeHash": "sha256-..." }
    </script>

    <!-- Runtime (loads and executes agent) -->
    <script type="module" id="agent-runtime">
      // Sandboxed execution environment
    </script>
  </body>
</html>

Security Model

agent.html enforces security through three mechanisms:

Integrity Checking: SHA-256 hashes verify the manifest and code haven't been tampered with
Permission System: Explicit whitelisting of network domains, storage, and code execution
Sandboxed Execution: Agent runs in an iframe with restricted permissions

permissions: {
  network: ['api.openai.com'],  // Only these domains
  storage: false,                // No localStorage/sessionStorage
  code: false                    // No eval() or Function()
}

Model Context Protocol (MCP)

Built-in MCP client for connecting to Model Context Protocol servers. Access tools and resources from MCP servers directly in your browser-based agents.

import { MCPClient, MCPManager } from 'agent-file'

// Use in agents via manifest
const manifest = {
  mcp: {
    servers: [{ name: 'filesystem', url: 'http://localhost:3000/mcp' }]
  }
}

// Access in agent code
async run(input) {
  const result = await this.mcp.callTool('read_file', { path: '/etc/hosts' })
  return result
}

// Or use directly
const client = new MCPClient('http://localhost:3000/mcp')
await client.connect()
const result = await client.callTool('read_file', { path: '/etc/hosts' })

See MCP examples for detailed integration guide.

CLI Reference

Quick Start Commands

Create an agent instantly (no files needed):

agent-html quick [--name "Agent Name"] [--output agent.html]

Create template files to customize:

agent-html init

This creates manifest.json and agent.js that you can edit.

Advanced Commands

Generate from custom files:

agent-html generate --manifest manifest.json --code agent.js [options]

Options:
  --output <file>      Output path (default: agent.html)
  --ui <type>          UI type: full, minimal, none (default: full)
  --styles <file>      Custom CSS styles
  --memory <file>      Initial memory/state JSON

Validate an agent file:

agent-html validate agent.html [--verbose]

Modify an existing agent:

agent-html modify agent.html --code new-code.js [--output modified.html]

Publish to registry (coming soon):

agent-html publish agent.html

Examples

Examples for different frameworks and use cases. Each generates a self-contained .html file you can open in a browser.

bun run example:vanilla      # Pure JavaScript
bun run example:langgraph    # LangGraph stateful agents
bun run example:litert       # TensorFlow Lite RT
bun run example:huggingface  # HuggingFace Inference API
bun run example:mcp          # Model Context Protocol
bun run example:wasi         # WebAssembly (WASI)

See detailed examples guide →

Vanilla - Pure JS, no dependencies
LangGraph - Stateful agent conversion
TensorFlow Lite RT - CDN model loading
HuggingFace - Inference API integration
MCP - Tool calling and resource access
WASI - WebAssembly embedding

API Reference

Full TypeScript definitions available in dist/index.d.ts.

Core API

import { AgentFile } from 'agent-file'

// Create agent HTML
const html = await AgentFile.create({
  manifest: { id, name, version, permissions, capabilities },
  code: 'class Agent { ... }',
  ui: 'full' | 'minimal' | 'none'
})

// Extract components
const { manifest, code, memory, integrity } = AgentFile.extract(html)

MCP Client

import { MCPClient, MCPManager } from 'agent-file'

// Single server
const client = new MCPClient(url, authToken?)
await client.connect()
await client.callTool(name, args)

// Multiple servers
const manager = new MCPManager()
await manager.addServer(name, url, authToken?)
await manager.callTool(toolName, args)

Security

import { generateHashes, verifyHashes, checkPermission } from 'agent-file'

const hashes = await generateHashes(manifest, code)
const valid = await verifyHashes(manifest, code, hashes)
const allowed = checkPermission(permissions, 'fetch', url)

Agent Class Interface

Your agent code must export a class named Agent:

class Agent {
  constructor(manifest) {
    this.manifest = manifest
    // Your initialization
  }

  // Required: Main entry point
  async run(input) {
    // Your logic
    return result
  }

  // Optional: Additional methods
  async setApiKey(key) { }
  async getState() { }
  async clearState() { }
}

Development

bun install
bun run build         # Compile TypeScript
bun test              # Run tests
bun run mcp:server    # Start MCP test server

See examples/ for running example agents.

Project Structure

agent.html/
├── src/
│   ├── agent-file.ts         # Main AgentFile class
│   ├── security.ts           # Security utilities
│   ├── mcp-client.ts         # MCP client for browser
│   ├── mcp-client-inline.ts  # Inline MCP client for agents
│   └── index.ts              # Public exports
├── examples/
│   ├── vanilla/              # Pure JavaScript examples
│   ├── langchain/            # LangGraph examples
│   ├── litert/               # LiterT examples
│   ├── huggingface/          # HuggingFace examples
│   ├── mcp/                  # MCP integration examples
│   └── advanced/
│       └── wasi/             # WebAssembly examples
└── dist/                     # Built files

Browser Support

Requires a modern browser with:

ES2020+ JavaScript
Fetch API
Web Crypto API (SHA-256)
iframe sandboxing
ES Modules

Tested on Chrome/Edge 90+, Firefox 88+, Safari 14+

Philosophy

agent.html is built on five principles:

Simplicity: One file, standard technologies, minimal API
Security: Explicit permissions, integrity verification, sandboxing
Portability: Works anywhere, no dependencies, no backend
Transparency: Source code is visible and verifiable
Extensibility: Platform-agnostic format, easy integration

Contributing

Contributions welcome. Please:

Read existing code and follow patterns
Add tests for new features
Update documentation
Submit PR with clear description

License

MIT License - see LICENSE file

Learn More

Examples Guide - Comprehensive examples and patterns
Model Context Protocol - MCP specification