express

The Express adapter creates HTTP applications from agent runtimes using Express.js.

Installation

bun add @regent/express express
npm install @regent/express express

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/express';
import { z } from 'zod';

const agent = await createAgent({
  name: 'my-agent',
  version: '1.0.0',
})
  .use(http())
  .addEntrypoint({
    key: 'echo',
    input: z.object({ text: z.string() }),
    handler: async ({ input }) => ({
      output: { echoed: input.text },
    }),
  })
  .build();

const { app, addEntrypoint } = await createAgentApp(agent);

app.listen(3000, () => {
  console.log('Agent running on port 3000');
});

API Reference

createAgentApp()

Creates an Express application from an AgentRuntime.

async function createAgentApp(
  runtime: AgentRuntime,
  opts?: CreateAgentAppOptions
): Promise<CreateAgentAppReturn<Express, AgentRuntime, AgentRuntime['agent']>>

Requirements: Runtime must have HTTP extension enabled via .use(http())

CreateAgentAppOptions

type CreateAgentAppOptions = {
  beforeMount?: (app: Express) => void;  // Add middleware before agent routes
  afterMount?: (app: Express) => void;   // Add routes/error handlers after
};

Return Value

type CreateAgentAppReturn = {
  app: Express;
  runtime: AgentRuntime;
  agent: AgentRuntime['agent'];
  addEntrypoint: (def: EntrypointDef) => void;
};

Routes

Method	Path	Description
GET	/health	Health check
GET	/entrypoints	List entrypoints
GET	/.well-known/agent.json	Agent manifest
GET	/.well-known/agent-card.json	Agent card
GET	/favicon.svg	Favicon
GET	/	Landing page (if enabled)
POST	/entrypoints/{key}/invoke	Invoke entrypoint
POST	/entrypoints/{key}/stream	Stream entrypoint
POST	/tasks	Create task
GET	/tasks	List tasks
GET	/tasks/{taskId}	Get task
POST	/tasks/{taskId}/cancel	Cancel task
GET	/tasks/{taskId}/subscribe	Subscribe to task (SSE)

Middleware Hooks

import cors from 'cors';
import express from 'express';

const { app } = await createAgentApp(agent, {
  beforeMount: (expressApp) => {
    expressApp.use(cors());
    expressApp.use(express.json());
  },
  afterMount: (expressApp) => {
    // Error handler
    expressApp.use((err, req, res, next) => {
      console.error(err);
      res.status(500).json({ error: 'Internal server error' });
    });
  },
});

Dynamic Entrypoints

const { app, addEntrypoint } = await createAgentApp(agent);

addEntrypoint({
  key: 'process',
  input: z.object({ data: z.string() }),
  handler: async ({ input }) => ({
    output: { processed: true },
  }),
});

Payment Integration

import { payments, paymentsFromEnv } from '@regent/x402';

const agent = await createAgent({ name: 'my-agent', version: '1.0.0' })
  .use(http())
  .use(payments({ config: paymentsFromEnv() }))
  .addEntrypoint({
    key: 'premium',
    price: '1.00',
    handler: async ({ input }) => ({
      output: { result: 'premium content' },
    }),
  })
  .build();

const { app } = await createAgentApp(agent);

withPayments()

import { withPayments } from '@regent/express';

withPayments({
  app,
  path: '/entrypoints/premium/invoke',
  entrypoint,
  kind: 'invoke',
  payments: paymentsConfig,
  runtime,
});

Request/Response Conversion

The adapter converts between Express and Fetch API formats:

// Express Request → Fetch Request
const webRequest = toWebRequest(expressReq);

// Fetch Response → Express Response
await sendResponse(expressRes, fetchResponse);

Exports

export { createAgentApp } from '@regent/express';
export { withPayments } from '@regent/express';
export type { CreateAgentAppOptions, CreateAgentAppReturn } from '@regent/express';