Agentuity Docs

All routes live in src/api/. You have two options for handling requests:

Simple routes - Handle HTTP directly in the route (health checks, CRUD, webhooks)
Call an agent - Import an agent for structured processing with validation

Quick Decision Guide

Handle directly in route	Create an agent
Health checks, status endpoints	LLM-powered processing
Simple CRUD operations	Schema-validated input/output
Webhook signature verification	Evaluations or lifecycle events
Static responses	Multi-step workflows

Simple Route Example

A health endpoint doesn't need an agent:

// src/api/index.ts
import { createRouter } from '@agentuity/runtime';
 
const router = createRouter();
 
router.get('/health', async (c) => {
  const dbHealthy = await checkDatabase();
  return c.json({ status: dbHealthy ? 'healthy' : 'degraded' });
});
 
export default router;

Calling an Agent

For complex logic, create an agent and call it from your route:

// src/api/index.ts
import { createRouter } from '@agentuity/runtime';
import chat from '@agent/chat';
 
const router = createRouter();
 
router.post('/chat', chat.validator(), async (c) => {
  const data = c.req.valid('json');
  const result = await chat.run(data);
  return c.json(result);
});
 
export default router;

The agent lives in src/agent/chat/agent.ts with its schema, handler, and optional evals.

When Agents Add Value

Agents provide:

Schema validation with agent.validator() middleware
Evaluations to measure quality
Lifecycle events for monitoring
Type safety for agent-to-agent calls

Webhook Pattern

Webhooks verify signatures in the route, then hand off to an agent:

import paymentProcessor from '@agent/payment-processor';
 
router.post('/webhooks/stripe', async (c) => {
  const signature = c.req.header('stripe-signature');
  const rawBody = await c.req.text();
 
  if (!verifyStripeSignature(rawBody, signature)) {
    return c.json({ error: 'Invalid signature' }, 401);
  }
 
  // Respond fast, process in background
  c.waitUntil(async () => {
    await paymentProcessor.run(JSON.parse(rawBody));
  });
 
  return c.json({ received: true });
});

Next Steps

HTTP Routes: Complete routing guide
Adding Middleware: Authentication patterns
Creating Agents: When you need schemas and evals

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!

Routes vs Agents