Skip to main content

​
Installation Guide

Standard Agents is a Vite plugin that runs as a standalone application or mounts at a subpath of an existing Vite application. It can run locally for development and must be deployed to Cloudflare Workers for production. The easiest way to get started is using our CLI to create a new project: 
npx @standardagents/cli init my-agent-project
This command will:
  1. Create a new Vite project using create vite
  2. Install the required dependencies (@cloudflare/vite-plugin, @standardagents/builder, wrangler)
  3. Configure your vite.config.ts with the necessary plugins
  4. Create wrangler.jsonc with Durable Object bindings
  5. Set up the worker entry point and Durable Object classes
  6. Create the agents/ directory structure with documentation
Once complete, start the development server: 
cd my-agent-project
npm run dev

​
Adding to an Existing Project

If you already have a Vite project and want to add Standard Agents: 
npx @standardagents/cli scaffold
The scaffold command intelligently modifies your existing project:
  • Adds cloudflare() and agentbuilder() plugins to your vite.config.ts
  • Creates or updates wrangler.jsonc with required bindings
  • Sets up the worker entry point with the Standard Agents router
  • Creates the agents/ directory structure
Use --force flag to overwrite existing configuration if needed.

​
Manual Installation

If you prefer to set things up manually, follow these steps:

​
Step 1: Install Dependencies

npm install -D vite @cloudflare/vite-plugin @standardagents/builder wrangler
AgentBuilder’s UI is pre-compiled, so there is no need to use a front end framework. However if you plan to use the Vite application to host more than just AgentBuilder, you can also install those frameworks.

​
Step 2: Configure the Vite Plugins

Open your vite.config.ts file and add the following plugins: 
import { defineConfig } from 'vite'
import { cloudflare } from '@cloudflare/vite-plugin'
import { agentbuilder } from '@standardagents/builder'

export default defineConfig({
  plugins: [cloudflare(), agentbuilder({ mountPoint: '/' })],
})

​
Step 3: Configure Cloudflare Bindings

Create a wrangler.jsonc file in the root of your project: 
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "your-project-name",
  "main": "worker/index.ts",
  "compatibility_date": "2025-01-01",
  "compatibility_flags": ["nodejs_compat"],
  "observability": {
    "enabled": true
  },
  "assets": {
    "directory": "dist",
    "not_found_handling": "single-page-application",
    "binding": "ASSETS",
    "run_worker_first": ["/**"]
  },
  "durable_objects": {
    "bindings": [
      {
        "name": "AGENT_BUILDER_THREAD",
        "class_name": "DurableThread"
      },
      {
        "name": "AGENT_BUILDER",
        "class_name": "DurableAgentBuilder"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["DurableThread"]
    },
    {
      "tag": "v2",
      "new_sqlite_classes": ["DurableAgentBuilder"]
    }
  ]
}

​
Step 4: Create the Durable Objects

Create an agents directory in the root of your project with two files: 
// agents/Thread.ts
import { DurableThread } from 'virtual:@standardagents/builder'

export default class Thread extends DurableThread {}

// agents/AgentBuilder.ts
import { DurableAgentBuilder } from 'virtual:@standardagents/builder'

export default class AgentBuilder extends DurableAgentBuilder {}
Also create the following directories for your agent configuration: 
mkdir -p agents/agents agents/prompts agents/models agents/tools agents/hooks agents/api

​
Step 5: Worker Entry Point

Create a worker directory with an index.ts file: 
// worker/index.ts
import { router } from "virtual:@standardagents/builder"
import DurableThread from '../agents/Thread';
import DurableAgentBuilder from '../agents/AgentBuilder';

export default {
  async fetch(request, env) {
    const res = await router(request, env)
    return res ?? new Response(null, { status: 404 })
  },
} satisfies ExportedHandler<Env>

export { DurableThread, DurableAgentBuilder }

​
Step 6: TypeScript Configuration

Add the following to your tsconfig.json to enable type checking: 
{
  "compilerOptions": {
    "types": [
      "vite/client",
      "./worker-configuration.d.ts",
      "./.agents/types.d.ts",
      "./.agents/virtual-module.d.ts"
    ]
  },
  "include": ["worker", "agents"]
}
Generate the Cloudflare types: 
npx wrangler types
This creates a worker-configuration.d.ts file. AgentBuilder types are generated when running the dev command.

​
Step 7: Start Development

npm run dev
The development server will automatically generate types for your agents, prompts, tools, and API routes, and spin up “miniflare” which is a local simulation of the Cloudflare Worker environment.

​
Project Structure

After installation, your project will have this structure: 
your-project/
├── agents/
│   ├── Thread.ts           # Durable Object for conversation threads
│   ├── AgentBuilder.ts     # Durable Object for agent state
│   ├── agents/             # Agent definitions
│   ├── prompts/            # Prompt/system message definitions
│   ├── models/             # AI model configurations
│   ├── tools/              # Custom tools agents can call
│   ├── hooks/              # Lifecycle hooks
│   └── api/                # Thread-specific API endpoints
├── worker/
│   └── index.ts            # Cloudflare Worker entry point
├── vite.config.ts          # Vite configuration
├── wrangler.jsonc          # Cloudflare Workers configuration
└── tsconfig.json           # TypeScript configuration

​
Next Steps

Architecture

Learn how Standard Agents works

API Reference

Explore the complete API