http

The HTTP extension adds HTTP protocol support to agents, including request handling, Server-Sent Events (SSE) streaming, and landing page rendering.

Installation

bun add @regent/http

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .build();

API Reference

http(options?)

Creates the HTTP extension.

function http(options?: HttpExtensionOptions): Extension<{ handlers: AgentHttpHandlers }>

HttpExtensionOptions

type HttpExtensionOptions = {
  landingPage?: boolean;  // Enable landing page at "/" (default: true)
  favicon?: boolean;      // Enable favicon endpoint (default: true)
};

Example:

const agent = await createAgent(meta)
  .use(http({ landingPage: false, favicon: true }))
  .build();

HTTP Handlers

When the HTTP extension is used, agent.handlers provides:

type AgentHttpHandlers = {
  health: (req: Request) => Promise<Response>;
  entrypoints: (req: Request) => Promise<Response>;
  manifest: (req: Request) => Promise<Response>;
  landing?: (req: Request) => Promise<Response>;
  favicon: (req: Request) => Promise<Response>;
  invoke: (req: Request, params: { key: string }) => Promise<Response>;
  stream: (req: Request, params: { key: string }) => Promise<Response>;
  tasks: (req: Request) => Promise<Response>;
  getTask: (req: Request, params: { taskId: string }) => Promise<Response>;
  listTasks: (req: Request) => Promise<Response>;
  cancelTask: (req: Request, params: { taskId: string }) => Promise<Response>;
  subscribeTask: (req: Request, params: { taskId: string }) => Promise<Response>;
};

Framework adapters use these handlers to create routes.

Endpoints

Endpoint	Method	Description
/	GET	Landing page (if enabled)
/.well-known/agent.json	GET	Agent Card manifest
/health	GET	Health check
/entrypoints	GET	List available entrypoints
/entrypoints/:key/invoke	POST	Invoke an entrypoint
/entrypoints/:key/stream	POST	Stream from an entrypoint
/tasks	POST	Create a new task
/tasks	GET	List tasks
/tasks/:id	GET	Get task by ID
/tasks/:id/cancel	POST	Cancel a task
/tasks/:id/subscribe	GET	Subscribe to task updates (SSE)
/favicon.ico	GET	Favicon (if enabled)

Request/Response Format

Invoke Request

POST /entrypoints/greet/invoke
Content-Type: application/json

{
  "input": {
    "name": "Alice"
  }
}

Invoke Response

{
  "run_id": "abc123",
  "status": "succeeded",
  "output": {
    "message": "Hello, Alice!"
  },
  "usage": {
    "total_tokens": 10
  }
}

Stream Request

POST /entrypoints/chat/stream
Content-Type: application/json

{
  "input": {
    "message": "Hello"
  }
}

Stream Response (SSE)

event: run-start
data: {"kind":"run-start","runId":"abc123"}

event: delta
data: {"kind":"delta","delta":"Hello, ","mime":"text/plain","runId":"abc123","sequence":1}

event: delta
data: {"kind":"delta","delta":"how can I help?","mime":"text/plain","runId":"abc123","sequence":2}

event: run-end
data: {"kind":"run-end","runId":"abc123","status":"succeeded","output":{"completed":true}}

SSE Streaming

createSSEStream

Create a Server-Sent Events stream:

import { createSSEStream, writeSSE } from '@regent/http';

const response = createSSEStream(async ({ write, close }) => {
  write({ event: 'message', data: '{"text":"Hello"}' });
  write({ event: 'message', data: '{"text":"World"}' });
  close();
});

SSE Types

type SSEWriteOptions = {
  event: string;
  data: string;
  id?: string;
};

type SSEStreamRunnerContext = {
  write: (options: SSEWriteOptions) => void;
  close: () => void;
  controller: ReadableStreamDefaultController<Uint8Array>;
};

type SSEStreamRunner = (ctx: SSEStreamRunnerContext) => Promise<void> | void;

Stream Envelope Types

StreamRunStartEnvelope

type StreamRunStartEnvelope = {
  kind: 'run-start';
  runId: string;
  sequence?: number;
  createdAt?: string;
};

StreamDeltaEnvelope

type StreamDeltaEnvelope = {
  kind: 'delta';
  delta: string;
  mime?: string;
  final?: boolean;
  role?: string;
  runId?: string;
  sequence?: number;
  createdAt?: string;
};

StreamTextEnvelope

type StreamTextEnvelope = {
  kind: 'text';
  text: string;
  mime?: string;
  role?: string;
  runId?: string;
  sequence?: number;
  createdAt?: string;
};

StreamAssetEnvelope

type StreamAssetEnvelope = {
  kind: 'asset';
  assetId: string;
  mime: string;
  name?: string;
  sizeBytes?: number;
  runId?: string;
  sequence?: number;
} & (
  | { transfer: 'inline'; data: string }
  | { transfer: 'external'; href: string; expiresAt?: string }
);

StreamControlEnvelope

type StreamControlEnvelope = {
  kind: 'control';
  control: string;
  payload?: unknown;
  runId?: string;
  sequence?: number;
};

StreamErrorEnvelope

type StreamErrorEnvelope = {
  kind: 'error';
  code: string;
  message: string;
  retryable?: boolean;
  runId?: string;
  sequence?: number;
};

StreamRunEndEnvelope

type StreamRunEndEnvelope = {
  kind: 'run-end';
  runId: string;
  status: 'succeeded' | 'failed' | 'cancelled';
  output?: unknown;
  usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
  model?: string;
  error?: { code: string; message?: string };
  sequence?: number;
};

StreamPushEnvelope

Envelopes used with emit() callback (excludes run-start and run-end):

type StreamPushEnvelope =
  | StreamTextEnvelope
  | StreamDeltaEnvelope
  | StreamAssetEnvelope
  | StreamControlEnvelope
  | StreamErrorEnvelope;

Invoke Handler

import { invokeHandler } from '@regent/http';

const result = await invokeHandler(entrypoint, rawInput, {
  signal: req.signal,
  headers: req.headers,
  runId: crypto.randomUUID(),
  runtime: agent,
});

InvokeResult

type InvokeResult = {
  output: unknown;
  usage?: {
    prompt_tokens?: number;
    completion_tokens?: number;
    total_tokens?: number;
  };
  model?: string;
};

Utility Functions

normalizeOrigin

Normalizes the origin from a request, handling reverse proxy headers:

import { normalizeOrigin } from '@regent/http';

const origin = normalizeOrigin(request);
// Checks X-Forwarded-Proto and X-Forwarded-Host

Exports

// Extension
export { http } from '@regent/http';

// SSE utilities
export { createSSEStream, writeSSE } from '@regent/http';
export type { SSEStreamRunner, SSEStreamRunnerContext, SSEWriteOptions } from '@regent/http';

// Handler utilities
export { invokeHandler } from '@regent/http';
export type { InvokeResult } from '@regent/http';

// Types
export type {
  HttpExtensionOptions,
  AgentHttpHandlers,
  StreamEnvelope,
  StreamPushEnvelope,
  StreamDeltaEnvelope,
  StreamTextEnvelope,
  StreamAssetEnvelope,
  StreamControlEnvelope,
  StreamErrorEnvelope,
  StreamRunStartEnvelope,
  StreamRunEndEnvelope,
} from '@regent/http';