hono

The Hono adapter creates HTTP applications from agent runtimes using the Hono framework.

Installation

bun add @regent/hono hono

Basic Usage

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/hono';
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);

Bun.serve({ fetch: app.fetch, port: 3000 });

API Reference

createAgentApp()

Creates a Hono application from an AgentRuntime.

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

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

CreateAgentAppOptions

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

Return Value

type CreateAgentAppReturn = {
  app: Hono;
  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

const { app } = await createAgentApp(agent, {
  beforeMount: (hono) => {
    // Add CORS, logging, auth middleware
    hono.use('*', cors());
    hono.use('*', logger());
  },
  afterMount: (hono) => {
    // Add custom routes
    hono.get('/custom', (c) => c.json({ custom: true }));
  },
});

Dynamic Entrypoints

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

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

Payment Integration

With the payments extension, priced entrypoints are automatically protected:

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',  // $1.00
    handler: async ({ input }) => ({
      output: { result: 'premium content' },
    }),
  })
  .build();

const { app } = await createAgentApp(agent);

withPayments()

Manually apply payment middleware:

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

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

Response Format

Invoke Response

{
  "status": "succeeded",
  "output": { "result": "..." },
  "usage": { "total_tokens": 100 },
  "model": "gpt-4"
}

Stream Response (SSE)

event: run-start
data: {"status":"started","runId":"abc"}

event: delta
data: {"delta":"chunk"}

event: run-end
data: {"status":"succeeded","output":{...}}

Error Responses

{
  "error": {
    "code": "invalid_input",
    "message": "Input validation failed",
    "details": [...]
  }
}

Exports

// Main API
export { createAgentApp } from '@regent/hono';
export { withPayments } from '@regent/hono';

// Types
export type { CreateAgentAppOptions, CreateAgentAppReturn } from '@regent/hono';