@agentuity/runtime

@agentuity/runtime

Server runtime for building Agentuity applications with Bun and Hono.

Installation

bun add @agentuity/runtime

Overview

@agentuity/runtime provides the server-side runtime for Agentuity applications. Built on Hono and optimized for Bun, it enables you to create type-safe agents with automatic routing, validation, and observability.

Quick Start

Creating an Application

import { createApp } from '@agentuity/runtime';

const { server, logger } = await createApp();

logger.info('Server running on %s', server.url);

Defining an Agent

import { createAgent } from '@agentuity/runtime';
import { s } from '@agentuity/schema';

const agent = createAgent('greeting', {
	description: 'A simple greeting agent',
	schema: {
		input: s.object({
			message: s.string(),
		}),
		output: s.object({
			response: s.string(),
		}),
	},
	handler: async (ctx, input) => {
		ctx.logger.info('Processing message:', input.message);
		return { response: `You said: ${input.message}` };
	},
});

export default agent;

Creating Custom Routes

import { createRouter } from '@agentuity/runtime';
import greetingAgent from './agent/greeting';

const router = createRouter();

router.get('/hello', (c) => {
	return c.json({ message: 'Hello, world!' });
});

// Route with agent validation
router.post('/greeting', greetingAgent.validator(), async (c) => {
	const data = c.req.valid('json'); // Fully typed from agent schema!
	const result = await greetingAgent.run(data);
	return c.json(result);
});

export default router;

Using Plain Hono with Agentuity Types

If you prefer using new Hono() directly instead of createRouter(), import the Env type to type Agentuity context variables (c.var.logger, c.var.thread, c.var.session, c.var.kv, etc.). These values are populated at runtime when the router is mounted through the Agentuity runtime (via createApp()):

import { type Env } from '@agentuity/runtime';
import { Hono } from 'hono';

const router = new Hono<Env>();

router.get('/hello', (c) => {
	// All Agentuity context variables are fully typed
	c.var.logger.info('Request from thread %s', c.var.thread.id);
	return c.json({ sessionId: c.var.sessionId });
});

export default router;

With custom application state:

import { type Env } from '@agentuity/runtime';
import { Hono } from 'hono';

interface MyAppState {
	db: Database;
}

const router = new Hono<Env<MyAppState>>();

router.get('/data', (c) => {
	const db = c.var.app.db; // typed as Database
	return c.json({ connected: true });
});

Streaming Responses

import { createRouter, stream } from '@agentuity/runtime';

const router = createRouter();

router.post(
	'/events',
	stream((c) => {
		return new ReadableStream({
			start(controller) {
				controller.enqueue('Event 1\n');
				controller.enqueue('Event 2\n');
				controller.close();
			},
		});
	})
);

WebSocket Support

import { createRouter, websocket } from '@agentuity/runtime';

const router = createRouter();

router.get(
	'/chat',
	websocket((c, ws) => {
		ws.onOpen(() => {
			console.log('Client connected');
		});

		ws.onMessage((event) => {
			const data = JSON.parse(event.data);
			ws.send(JSON.stringify({ echo: data }));
		});

		ws.onClose(() => {
			console.log('Client disconnected');
		});
	})
);

Server-Sent Events (SSE)

import { createRouter, sse } from '@agentuity/runtime';

const router = createRouter();

router.get(
	'/updates',
	sse((c, stream) => {
		for (let i = 0; i < 10; i++) {
			stream.writeSSE({
				data: JSON.stringify({ count: i }),
				event: 'update',
			});
		}
	})
);

API Reference

createApp(config?)

Creates a new Agentuity application instance.

Returns:

• router - Hono application instance
• server - Server instance with listen() method
• logger - Structured logger

createAgent(config)

Creates a type-safe agent with input/output validation.

Config:

• schema.input? - Schema for input validation (Zod, Valibot, etc.)
• schema.output? - Schema for output validation
• handler - Agent handler function (ctx, input) => output

createRouter()

Creates a new Hono router pre-typed with Env for Agentuity context variables. This is equivalent to new Hono<Env>() but is the recommended approach.

Methods:

• get/post/put/delete/patch - HTTP method handlers

Middleware Functions:

Use these middleware functions with standard HTTP methods:

• websocket((c, ws) => { ... }) - WebSocket connections (use with router.get())
• sse((c, stream) => { ... }) - Server-Sent Events (use with router.get())
• stream((c) => ReadableStream) - Streaming responses (use with router.post())
• cron(schedule, (c) => { ... }) - Scheduled tasks (use with router.post())

Env<TAppState>

The Hono environment type that provides typed access to Agentuity context variables in route handlers. Use this when creating a plain new Hono() instance instead of createRouter().

import { type Env } from '@agentuity/runtime';
import { Hono } from 'hono';

const router = new Hono<Env>();
// c.var.logger, c.var.thread, c.var.session, c.var.kv, etc. are typed

Variables provided by Env:

Variable	Type	Description
logger	Logger	Structured logger
tracer	Tracer	OpenTelemetry tracer
meter	Meter	OpenTelemetry meter
sessionId	string	Current session ID
thread	Thread	Thread information and state
session	Session	Session information and state
kv	KeyValueStorage	Key-value storage
stream	StreamStorage	Stream storage
vector	VectorStorage	Vector storage
sandbox	SandboxService	Sandbox service
queue	QueueService	Queue service
email	EmailService	Email service
schedule	ScheduleService	Schedule service
task	TaskStorage	Task storage
app	TAppState	Custom application state

AgentContext

Context object available in agent handlers:

interface AgentContext {
	logger: Logger; // Structured logger
	tracer: Tracer; // OpenTelemetry tracer
	sessionId: string; // Unique session ID
	kv: KeyValueStorage; // Key-value storage
	stream: StreamStorage; // Stream storage
	vector: VectorStorage; // Vector storage
	state: Map<string, unknown>; // Request-scoped state
	thread: Thread; // Thread information
	session: Session; // Session information
	config: TConfig; // Agent-specific config from setup
	app: TAppState; // Application state from createApp
	waitUntil: (promise) => void; // Defer cleanup tasks
}

Storage Services

Agentuity provides built-in storage abstractions:

• KeyValueStorage - Simple key-value storage
• StreamStorage - Streaming data storage
• VectorStorage - Vector embeddings storage

Access these via the agent context:

const agent = createAgent('storage-example', {
	schema: {
		output: s.object({ value: s.string().optional() }),
	},
	handler: async (ctx, input) => {
		await ctx.kv.set('key', 'value');
		const value = await ctx.kv.get('key');
		return { value };
	},
});

Observability

Built-in OpenTelemetry support for logging, tracing, and metrics:

const agent = createAgent('observability-example', {
	schema: {
		output: s.object({ success: s.boolean() }),
	},
	handler: async (ctx, input) => {
		ctx.logger.info('Processing request');

		const span = ctx.tracer.startSpan('custom-operation');
		// ... do work ...
		span.end();

		return { success: true };
	},
});

TypeScript

Fully typed with TypeScript. Input and output types are automatically inferred from your schemas.

License

Apache 2.0