Agentuity Docs

Routes define how requests reach your application, whether HTTP calls, scheduled jobs, incoming emails, or SMS messages. Built on Hono, the router provides a familiar API with full TypeScript support.

Infrastructure as Code

Routes are defined in your codebase and automatically discovered. Changes are tracked in Git, reviewed in PRs, and deployed with your code. No UI configuration required.

Where Routes Live

All routes live in src/api/. Agents and routes are separate concerns:

Directory	Purpose
`src/agent/*/`	Agent logic (no routes here)
`src/api/`	All routes: HTTP, cron, email, SMS, etc.

Routes import and call agents directly:

// src/api/index.ts
import { createRouter } from '@agentuity/runtime';
import slackHandler from '@agent/slack-handler';
 
const router = createRouter();
 
router.post('/slack', async (c) => {
  const payload = await c.req.json();
  const result = await slackHandler.run(payload);
  return c.json(result);
});
 
export default router;

Routes in src/api/ are automatically mounted at /api. For the full project layout, see Project Structure.

Route Types

Type	Method	Use case
HTTP	`router.get()`, `router.post()`, `router.stream()`	REST APIs, webhooks, LLM streaming
Middleware	Hono middleware	Auth, logging, validation
Cron	`router.cron()`	Scheduled tasks
Email	`router.email()`	Process incoming emails
SMS	`router.sms()`	Process incoming SMS
WebSocket	`router.websocket()`	Real-time bidirectional
SSE	`router.sse()`	Server-sent events

Quick Examples

HTTP

import { createRouter } from '@agentuity/runtime';
import assistant from '@agent/assistant';
 
const router = createRouter();
 
router.get('/health', (c) => {
  return c.json({ status: 'ok', timestamp: Date.now() });
});
 
router.post('/chat', assistant.validator(), async (c) => {
  const data = c.req.valid('json');
  const result = await assistant.run(data);
  return c.json(result);
});
 
export default router;

Cron

import reportGenerator from '@agent/report-generator';
 
router.cron('0 9 * * *', async (c) => {
  await reportGenerator.run({ type: 'daily' });
  return c.text('OK');
});

Email

import emailHandler from '@agent/email-handler';
 
router.email('support@myapp.com', async (email, c) => {
  const result = await emailHandler.run({
    from: email.fromEmail(),
    subject: email.subject(),
    body: email.text(),
  });
  return c.text('Processed');
});

SMS

import smsResponder from '@agent/sms-responder';
 
router.sms({ number: '+15551234567' }, async (c) => {
  const formData = await c.req.parseBody();
  const reply = await smsResponder.run({
    message: formData.Body as string,
    from: formData.From as string
  });
  return c.text(reply); // Sent as SMS reply
});

WebSocket

import assistant from '@agent/assistant';
 
router.websocket('/chat', (c) => (ws) => {
  ws.onMessage(async (event) => {
    const response = await assistant.run(event.data);
    ws.send(response);
  });
});

SSE

router.sse('/stream', (c) => async (stream) => {
  for (let i = 0; i < 5; i++) {
    await stream.writeSSE({ data: `Message ${i}` });
  }
  stream.close();
});

Context Access

All route handlers have access to the same context:

import myAgent from '@agent/my-agent';
import analytics from '@agent/analytics';
 
router.post('/', async (c) => {
  // Request data
  const body = await c.req.json();
  const header = c.req.header('Authorization');
 
  // Logging and session
  c.var.logger.info('Processing request');
  const sessionId = c.var.sessionId;
 
  // Thread and session state
  c.var.thread.state.set('topic', body.topic);
  const userId = c.var.session.state.get('userId');
 
  // Storage
  await c.var.kv.set('cache', 'key', data);
  const results = await c.var.vector.search('docs', { query: 'search term' });
 
  // Durable streams
  const stream = await c.var.stream.create('export', { contentType: 'text/csv' });
 
  // Call agents (import them at the top of your file)
  const result = await myAgent.run(body);
 
  // Background tasks
  c.waitUntil(async () => {
    await analytics.run({ event: 'request' });
  });
 
  return c.json(result);
});

Next Steps

HTTP Routes - REST endpoints, parameters, validation
Middleware - Authentication, logging, CORS
When to Use APIs - Choosing between agents and lightweight routes

Need Help?

Join our Community for assistance or just to hang with other humans building agents.

Send us an email at hi@agentuity.com if you'd like to get in touch.

Please Follow us on

If you haven't already, please Signup for your free account now and start building your first agent!

Routing Overview