API Reference

interface App {
  router: Hono;           // The main application router
  server: Server;         // Server instance with .url property
  logger: Logger;         // Application-level logger
}

// app.ts
import { createApp } from '@agentuity/runtime';
 
// Create the application instance (async)
const { server, logger } = await createApp();
 
// The application will automatically discover and mount agents
// from the agents directory specified in your agentuity.json
 
// Access application properties
logger.info(`Server running at ${server.url}`);

import { createApp } from '@agentuity/runtime';
 
const { server, logger } = await createApp({
  // Custom CORS settings
  cors: {
    origin: ['https://example.com'],
    credentials: true
  },
  // Use local services for development
  services: {
    useLocal: true
  }
});

import { createApp } from '@agentuity/runtime';
 
const { server, logger } = await createApp({
  // Initialize shared resources
  setup: async () => {
    const db = await connectDatabase();
    const redis = await connectRedis();
    return { db, redis };
  },
  // Clean up on shutdown
  shutdown: async (state) => {
    await state.db.close();
    await state.redis.quit();
  },
});
 
// In agents, access via ctx.app:
// ctx.app.db.query('SELECT * FROM users')

// app.ts
import { createApp } from '@agentuity/runtime';
 
if (!process.env.AGENTUITY_SDK_KEY) {
  console.error('Missing AGENTUITY_SDK_KEY environment variable');
  process.exit(1);
}
 
const { server, logger } = await createApp();
 
// Access other environment variables
const apiEndpoint = process.env.API_ENDPOINT || 'https://api.example.com';
const openaiKey = process.env.OPENAI_API_KEY;
// Optional: you can use the AI Gateway to access OpenAI, Anthropic, etc without needing to set various API keys.

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('CachedProcessor', {
  schema: {
    input: z.object({ key: z.string() }),
    output: z.object({ value: z.string() }),
  },
  // Called once when app starts - return value available via ctx.config
  setup: async (app) => {
    const cache = new Map<string, string>();
    const client = await initializeExternalService();
    return { cache, client };
  },
  // Called when app shuts down
  shutdown: async (app, config) => {
    await config.client.disconnect();
    config.cache.clear();
  },
  handler: async (ctx, input) => {
    // ctx.config is fully typed from setup's return value
    const cached = ctx.config.cache.get(input.key);
    if (cached) {
      return { value: cached };
    }
 
    const value = await ctx.config.client.fetch(input.key);
    ctx.config.cache.set(input.key, value);
    return { value };
  },
});
 
export default agent;

agent.validator(): MiddlewareHandler
agent.validator(options: { output: Schema }): MiddlewareHandler
agent.validator(options: { input: Schema; output?: Schema }): MiddlewareHandler

import { createRouter } from '@agentuity/runtime';
import agent from './agent';
 
const router = createRouter();
 
// Use agent's schema
router.post('/', agent.validator(), async (c) => {
  const data = c.req.valid('json'); // Fully typed
  return c.json(data);
});
 
// Custom schema override
router.post('/custom',
  agent.validator({ input: z.object({ custom: z.string() }) }),
  async (c) => {
    const data = c.req.valid('json');
    return c.json(data);
  }
);

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('GreetingAgent', {
  description: 'A simple greeting agent that responds to user messages',
  schema: {
    input: z.object({
      message: z.string().min(1),
      userId: z.string().optional(),
    }),
    output: z.object({
      response: z.string(),
      timestamp: z.number(),
    }),
  },
  handler: async (ctx, input) => {
    // Input is automatically validated and typed
    ctx.logger.info(`Processing message from user: ${input.userId ?? 'anonymous'}`);
 
    return {
      response: `Hello! You said: ${input.message}`,
      timestamp: Date.now(),
    };
  },
});
 
export default agent;

// Using Zod
import { z } from 'zod';
 
const agent = createAgent('Greeter', {
  schema: {
    input: z.object({ name: z.string() }),
    output: z.object({ greeting: z.string() }),
  },
  handler: async (ctx, input) => {
    return { greeting: `Hello, ${input.name}!` };
  },
});

// Using Valibot
import * as v from 'valibot';
 
const agent = createAgent('Greeter', {
  schema: {
    input: v.object({ name: v.string() }),
    output: v.object({ greeting: v.string() }),
  },
  handler: async (ctx, input) => {
    return { greeting: `Hello, ${input.name}!` };
  },
});

const agent = createAgent('DataProcessor', {
  description: 'Processes and transforms user data',
  schema: {
    input: inputSchema,
    output: outputSchema,
  },
  handler: async (ctx, input) => {
    // Agent logic
  },
});

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('UserCreator', {
  schema: {
    input: z.object({
      email: z.string().email(),
      age: z.number().min(0).max(120),
      preferences: z.object({
        newsletter: z.boolean(),
        notifications: z.boolean(),
      }).optional(),
    }),
    output: z.object({
      userId: z.string().uuid(),
      created: z.date(),
    }),
  },
  handler: async (ctx, input) => {
    // Input is validated before handler runs
    // TypeScript knows exact shape of input
 
    ctx.logger.info(`Creating user: ${input.email}`);
 
    return {
      userId: crypto.randomUUID(),
      created: new Date(),
    };
  },
});

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('SearchAgent', {
  schema: {
    input: z.object({
      query: z.string(),
      filters: z.object({
        category: z.enum(['tech', 'business', 'sports']),
        limit: z.number().default(10),
      }),
    }),
    output: z.object({
      results: z.array(z.object({
        id: z.string(),
        title: z.string(),
        score: z.number(),
      })),
      total: z.number(),
    }),
  },
  handler: async (ctx, input) => {
    // TypeScript knows:
    // - input.query is string
    // - input.filters.category is 'tech' | 'business' | 'sports'
    // - input.filters.limit is number
 
    // Return type is also validated
    return {
      results: [
        { id: '1', title: 'Example', score: 0.95 },
      ],
      total: 1,
    };
 
    // This would cause a TypeScript error:
    // return { invalid: 'structure' };
  },
});
 
// When calling the agent from another agent:
import searchAgent from '@agent/search';
 
const result = await searchAgent.run({
  query: 'agentic AI',
  filters: { category: 'tech', limit: 5 },
});
 
// TypeScript knows result has this shape:
// {
//   results: Array<{ id: string; title: string; score: number }>;
//   total: number;
// }

type AgentHandler<TInput, TOutput> = (
  ctx: AgentContext,
  input: TInput
) => Promise<TOutput> | TOutput;

// v0 pattern
export default async (request, response, context) => {
  const { name } = await request.data.json();
  context.logger.info(`Hello ${name}`);
  return response.json({ greeting: `Hello, ${name}!` });
};

// v1 pattern
import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
export default createAgent('Greeter', {
  schema: {
    input: z.object({ name: z.string() }),
    output: z.object({ greeting: z.string() }),
  },
  handler: async (ctx, input) => {
    ctx.logger.info(`Hello ${input.name}`);
    return { greeting: `Hello, ${input.name}!` };
  },
});

const agent = createAgent('UserValidator', {
  schema: {
    input: z.object({
      email: z.string().email(),
      age: z.number().min(18),
    }),
    output: z.object({
      success: z.boolean(),
    }),
  },
  handler: async (ctx, input) => {
    // This code only runs if:
    // - input.email is a valid email format
    // - input.age is a number >= 18
 
    ctx.logger.info(`Valid user: ${input.email}, age ${input.age}`);
 
    return { success: true };
  },
});

// Request with invalid input:
// { email: "not-an-email", age: 15 }
 
// Results in validation error thrown before handler:
// Error: Validation failed
//   - email: Invalid email format
//   - age: Number must be greater than or equal to 18

const agent = createAgent('Adder', {
  schema: {
    input: z.object({ x: z.number(), y: z.number() }),
    output: z.object({ sum: z.number() }),
  },
  handler: async (ctx, input) => {
    return { sum: input.x + input.y };
  },
});

const agent = createAgent('UserFetcher', {
  schema: {
    input: z.object({ userId: z.string() }),
    output: z.object({
      user: z.object({
        id: z.string(),
        name: z.string(),
      }),
    }),
  },
  handler: async (ctx, input) => {
    // Await async operations
    const userData = await fetchUserFromDatabase(input.userId);
 
    // Return the result
    return {
      user: {
        id: userData.id,
        name: userData.name,
      },
    };
  },
});

const agent = createAgent('RiskyOperator', {
  schema: {
    input: z.object({ id: z.string() }),
    output: z.object({ data: z.any() }),
  },
  handler: async (ctx, input) => {
    try {
      const data = await riskyOperation(input.id);
      return { data };
    } catch (error) {
      ctx.logger.error('Operation failed', { error });
      throw new Error('Failed to process request');
    }
  },
});

const agent = createAgent('ValueChecker', {
  schema: {
    input: z.object({ value: z.number() }),
    output: z.object({
      result: z.number(),
      isPositive: z.boolean(),
    }),
  },
  handler: async (ctx, input) => {
    // This would fail output validation:
    // return { result: input.value };
    // Error: Missing required field 'isPositive'
 
    // This passes validation:
    return {
      result: input.value,
      isPositive: input.value > 0,
    };
  },
});

interface AgentContext<TConfig = unknown, TAppState = unknown> {
  // Identifiers
  sessionId: string;                  // Unique ID for this agent execution
 
  // Agent Calling (use imports instead)
  // import otherAgent from '@agent/other-agent';
  // await otherAgent.run(input);
 
  // Configuration
  config: TConfig;                    // Agent-specific config from setup()
  app: TAppState;                     // App-wide state from createApp setup()
 
  // State Management
  session: Session;                   // Session object for cross-request state
  thread: Thread;                     // Thread object for conversation state
  state: Map<string, unknown>;        // Request-scoped state storage
 
  // Storage Services
  kv: KeyValueStorage;                // Key-value storage
  vector: VectorStorage;              // Vector database for embeddings
  stream: StreamStorage;              // Stream storage
 
  // Observability
  logger: Logger;                     // Structured logging
  tracer: Tracer;                     // OpenTelemetry tracing
 
  // Lifecycle
  waitUntil(promise: Promise<void> | (() => void | Promise<void>)): void;
}

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('QueryProcessor', {
  schema: {
    input: z.object({ query: z.string() }),
    output: z.object({ result: z.string() }),
  },
  handler: async (ctx, input) => {
    // Access session ID
    ctx.logger.info(`Session ID: ${ctx.sessionId}`);
 
    // Use storage services
    await ctx.kv.set('cache', 'last-query', input.query);
 
    // Store request-scoped data
    ctx.state.set('startTime', Date.now());
 
    // Call another agent (import at top of file)
    // import enrichmentAgent from '@agent/enrichment';
    const enrichedData = await enrichmentAgent.run({ text: input.query });
 
    // Use session state
    ctx.session.state.set('queryCount',
      (ctx.session.state.get('queryCount') as number || 0) + 1
    );
 
    return { result: enrichedData.output };
  },
});

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('MessageReceiver', {
  schema: {
    input: z.object({ userId: z.string(), message: z.string() }),
    output: z.object({ status: z.string(), timestamp: z.number() }),
  },
  handler: async (ctx, input) => {
    const responseData = {
      status: 'received',
      timestamp: Date.now(),
    };
 
    // Schedule background tasks (async functions)
    ctx.waitUntil(async () => {
      // Log the message asynchronously
      await logMessageToDatabase(input.userId, input.message);
    });
 
    ctx.waitUntil(async () => {
      // Send notification email in the background
      await sendNotificationEmail(input.userId, input.message);
    });
 
    // Can also use synchronous functions
    ctx.waitUntil(() => {
      // Update analytics synchronously
      updateAnalyticsSync(input.userId, 'message_received');
    });
 
    // Return immediately without waiting for background tasks
    return responseData;
  },
});

// Retrieve a value from key-value storage
const result = await ctx.kv.get<{ theme: string }>('user-preferences', 'user-123');
if (result.exists) {
  // data is only accessible when exists is true
  ctx.logger.info('User preferences:', result.data);
} else {
  ctx.logger.info('User preferences not found');
}

// Store a string value
await ctx.kv.set('user-preferences', 'user-123', JSON.stringify({ theme: 'dark' }));
 
// Store a JSON value
await ctx.kv.set('user-preferences', 'user-123', { theme: 'dark' });
 
// Store a binary value
const binaryData = new Uint8Array([1, 2, 3, 4]).buffer;
await ctx.kv.set('user-data', 'user-123', binaryData);
 
// Store a value with TTL (expires after 1 hour)
await ctx.kv.set('session', 'user-123', 'active', { ttl: 3600 });

// Delete a value
await ctx.kv.delete('user-preferences', 'user-123');

interface KeyValueItemWithMetadata<T> {
  value: T;              // The stored value
  contentType: string;   // MIME type of the value
  size: number;          // Size in bytes
  created_at: string;    // ISO timestamp
  updated_at: string;    // ISO timestamp
}

// Search for all keys starting with 'user-'
const matches = await ctx.kv.search<{ theme: string }>('preferences', 'user-');
 
for (const [key, item] of Object.entries(matches)) {
  ctx.logger.info('Found key', {
    key,
    value: item.value,
    size: item.size,
    updatedAt: item.updated_at,
  });
}

const keys = await ctx.kv.getKeys('cache');
ctx.logger.info(`Found ${keys.length} keys in cache`);

const namespaces = await ctx.kv.getNamespaces();
// ['cache', 'sessions', 'preferences']

interface KeyValueStats {
  sum: number;          // Total size in bytes
  count: number;        // Number of keys
  createdAt?: number;   // Unix timestamp
  lastUsedAt?: number;  // Unix timestamp
}

const stats = await ctx.kv.getStats('cache');
ctx.logger.info('Cache stats', { keys: stats.count, totalBytes: stats.sum });

const allStats = await ctx.kv.getAllStats();
for (const [namespace, stats] of Object.entries(allStats)) {
  ctx.logger.info(`${namespace}: ${stats.count} keys, ${stats.sum} bytes`);
}

await ctx.kv.createNamespace('tenant-123');

await ctx.kv.deleteNamespace('old-cache');

// Upsert documents with text
const ids = await ctx.vector.upsert(
  'product-descriptions',
  { key: 'chair-001', document: 'Ergonomic office chair with lumbar support', metadata: { category: 'furniture' } },
  { key: 'headphones-001', document: 'Wireless noise-cancelling headphones', metadata: { category: 'electronics' } }
);
 
// Upsert documents with embeddings
const ids2 = await ctx.vector.upsert(
  'product-embeddings',
  { key: 'embed-123', embeddings: [0.1, 0.2, 0.3, 0.4], metadata: { productId: '123' } },
  { key: 'embed-456', embeddings: [0.5, 0.6, 0.7, 0.8], metadata: { productId: '456' } }
);

// Basic search with query only
const results = await ctx.vector.search('product-descriptions', {
  query: 'comfortable office chair'
});
 
// Search with limit and similarity threshold
const results = await ctx.vector.search('product-descriptions', {
  query: 'comfortable office chair',
  limit: 5,
  similarity: 0.7
});
 
// Search with metadata filtering
const results = await ctx.vector.search('product-descriptions', {
  query: 'comfortable office chair',
  limit: 10,
  similarity: 0.6,
  metadata: { category: 'furniture', inStock: true }
});
 
// Process search results
for (const result of results) {
  ctx.logger.info(`Product ID: ${result.id}, Similarity: ${result.similarity}`);
  ctx.logger.info(`Key: ${result.key}`);
  ctx.logger.info('Metadata:', result.metadata);
}

// Retrieve a specific vector by key
const vector = await ctx.vector.get('product-descriptions', 'chair-001');
 
if (vector) {
  ctx.logger.info(`Found vector: ${vector.id}`);
  ctx.logger.info(`Key: ${vector.key}`);
  ctx.logger.info('Metadata:', vector.metadata);
} else {
  ctx.logger.info('Vector not found');
}

// Delete a single vector by key
const deletedCount = await ctx.vector.delete('product-descriptions', 'chair-001');
ctx.logger.info(`Deleted ${deletedCount} vector(s)`);
 
// Delete multiple vectors in bulk
const deletedCount2 = await ctx.vector.delete('product-descriptions', 'chair-001', 'headphones-001', 'desk-002');
ctx.logger.info(`Deleted ${deletedCount2} vector(s)`);
 
// Delete with array spread
const keysToDelete = ['chair-001', 'headphones-001', 'desk-002'];
const deletedCount3 = await ctx.vector.delete('product-descriptions', ...keysToDelete);
 
// Handle cases where some vectors might not exist
const deletedCount4 = await ctx.vector.delete('product-descriptions', 'existing-key', 'non-existent-key');
ctx.logger.info(`Deleted ${deletedCount4} vector(s)`); // May be less than number of keys provided

import { sql } from 'bun';

// Query with automatic parameter escaping
const users = await sql`SELECT * FROM users WHERE active = ${true}`;
 
// Insert data
await sql`INSERT INTO users (name, email) VALUES (${"Alice"}, ${"alice@example.com"})`;
 
// Update data
await sql`UPDATE users SET active = ${false} WHERE id = ${userId}`;
 
// Delete data
await sql`DELETE FROM users WHERE id = ${userId}`;

await sql.begin(async (tx) => {
  await tx`UPDATE accounts SET balance = balance - ${amount} WHERE id = ${fromId}`;
  await tx`UPDATE accounts SET balance = balance + ${amount} WHERE id = ${toId}`;
  await tx`INSERT INTO transfers (from_id, to_id, amount) VALUES (${fromId}, ${toId}, ${amount})`;
});
// Automatically rolls back on error

const users = await sql`
  SELECT * FROM users
  WHERE 1=1
  ${minAge ? sql`AND age >= ${minAge}` : sql``}
  ${active !== undefined ? sql`AND active = ${active}` : sql``}
`;

const newUsers = [
  { name: "Alice", email: "alice@example.com" },
  { name: "Bob", email: "bob@example.com" },
];
await sql`INSERT INTO users ${sql(newUsers)}`;

import { SQL } from "bun";
 
// PostgreSQL
const postgres = new SQL({
  url: process.env.POSTGRES_URL,
  max: 20,
  idleTimeout: 30,
});
 
// MySQL
const mysql = new SQL("mysql://user:pass@localhost:3306/mydb");
 
// SQLite
const sqlite = new SQL("sqlite://data/app.db");

import { s3 } from 'bun';

const file = s3.file('uploads/profile-123.jpg');
 
if (await file.exists()) {
  const text = await file.text();       // For text files
  const json = await file.json();       // For JSON files
  const bytes = await file.bytes();     // For binary data
  const blob = await file.blob();       // As Blob
}

const file = s3.file('documents/readme.txt');
 
// Write text
await file.write('Hello, world!', { type: 'text/plain' });
 
// Write JSON
await file.write(JSON.stringify({ name: 'John' }), { type: 'application/json' });
 
// Write binary data
await file.write(pdfBuffer, { type: 'application/pdf' });

const file = s3.file('uploads/old-file.pdf');
await file.delete();

// Download URL (1 hour)
const downloadUrl = s3.presign('uploads/document.pdf', {
  expiresIn: 3600,
  method: 'GET',
});
 
// Upload URL
const uploadUrl = s3.presign('uploads/new-file.pdf', {
  expiresIn: 3600,
  method: 'PUT',
});

const file = s3.file('uploads/document.pdf');
const stat = await file.stat();
// { etag, lastModified, size, type }

import { S3Client } from 'bun';
 
const objects = await S3Client.list({
  prefix: 'uploads/',
  maxKeys: 100,
});

const file = s3.file('large-file.zip');
const writer = file.writer({ partSize: 5 * 1024 * 1024 }); // 5MB parts
 
writer.write(chunk1);
writer.write(chunk2);
await writer.end();

interface Stream {
  id: string;                     // Unique stream identifier
  url: string;                    // Public URL to access the stream
  bytesWritten: number;           // Total bytes written (readonly)
  compressed: boolean;            // Whether compression is enabled (readonly)
 
  write(chunk: string | Uint8Array | ArrayBuffer | object): Promise<void>;
  close(): Promise<void>;
  getReader(): ReadableStream<Uint8Array>;  // Get readable stream from URL
}

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
 
const agent = createAgent('UserExporter', {
  schema: {
    input: z.object({ userId: z.string() }),
    output: z.object({ streamId: z.string(), streamUrl: z.string() }),
  },
  handler: async (ctx, input) => {
    // Create a stream with metadata
    const stream = await ctx.stream.create('user-export', {
      contentType: 'text/csv',
      metadata: {
        userId: input.userId,
        timestamp: Date.now(),
      },
    });
 
    // Write data in the background
    ctx.waitUntil(async () => {
      try {
        await stream.write('Name,Email\n');
        await stream.write('John,john@example.com\n');
      } finally {
        await stream.close();
      }
    });
 
    return {
      streamId: stream.id,
      streamUrl: stream.url,
    };
  },
});

interface StreamInfo {
  id: string;                        // Unique stream identifier
  name: string;                      // Stream name
  metadata: Record<string, string>;  // User-defined metadata
  url: string;                       // Public URL to access the stream
  sizeBytes: number;                 // Size of stream content in bytes
}

const info = await ctx.stream.get('stream_0199a52b06e3767dbe2f10afabb5e5e4');
ctx.logger.info('Stream details', {
  name: info.name,
  sizeBytes: info.sizeBytes,
  url: info.url,
});

const readable = await ctx.stream.download('stream_0199a52b06e3767dbe2f10afabb5e5e4');
 
// Process the stream
const reader = readable.getReader();
const chunks: Uint8Array[] = [];
 
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}
 
const content = Buffer.concat(chunks).toString('utf-8');

interface ListStreamsResponse {
  success: boolean;
  message?: string;           // Error message if not successful
  streams: StreamInfo[];      // Array of stream metadata
  total: number;              // Total count for pagination
}

// List all streams
const result = await ctx.stream.list();
ctx.logger.info(`Found ${result.total} streams`);
 
// Filter by metadata
const userStreams = await ctx.stream.list({
  metadata: { userId: 'user-123' }
});

await ctx.stream.delete(streamId);
ctx.logger.info('Stream deleted successfully');

interface Logger {
  trace(message: unknown, ...args: unknown[]): void;
  debug(message: unknown, ...args: unknown[]): void;
  info(message: unknown, ...args: unknown[]): void;
  warn(message: unknown, ...args: unknown[]): void;
  error(message: unknown, ...args: unknown[]): void;
  fatal(message: unknown, ...args: unknown[]): never;
  child(opts: Record<string, unknown>): Logger;
}

ctx.logger.trace('Detailed diagnostic info', { data: complexObject });

ctx.logger.debug('Processing request', { requestId: '123' });

ctx.logger.info('Request processed successfully', { requestId: '123' });

ctx.logger.warn('Resource not found', { resourceId: '456' });

ctx.logger.error('Failed to process request', error);

// Log fatal error and exit
ctx.logger.fatal('Critical system failure', { error, context });
// Code after this line will never execute

const requestLogger = ctx.logger.child({ requestId: '123', userId: '456' });
requestLogger.info('Processing request');

// Create a span
ctx.tracer.startActiveSpan('process-data', async (span) => {
  try {
    // Add attributes to the span
    span.setAttribute('userId', '123');
 
    // Perform some work
    const result = await processData();
 
    // Add events to the span
    span.addEvent('data-processed', { itemCount: result.length });
 
    return result;
  } catch (error) {
    // Record the error
    span.recordException(error);
    span.setStatus({ code: SpanStatusCode.ERROR });
    throw error;
  } finally {
    span.end();
  }
});

import otherAgent from '@agent/other';
 
// Call another agent
const result = await otherAgent.run(input);

// src/agent/processor/agent.ts
import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
import enrichmentAgent from '@agent/enrichment';
 
const processor = createAgent('Processor', {
  schema: {
    input: z.object({ userInput: z.string() }),
    output: z.object({
      processed: z.boolean(),
      analysis: z.object({
        sentiment: z.string(),
        keywords: z.array(z.string()),
      }),
    }),
  },
  handler: async (ctx, input) => {
    // Call the enrichment agent
    const enriched = await enrichmentAgent.run({
      text: input.userInput,
    });
 
    // TypeScript knows enriched has the shape from the agent's schema
 
    return {
      processed: true,
      analysis: {
        sentiment: enriched.sentiment,
        keywords: enriched.keywords,
      },
    };
  },
});
 
export default processor;

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
import webSearchAgent from '@agent/web-search';
import databaseAgent from '@agent/database';
import cacheAgent from '@agent/cache';
 
const coordinator = createAgent('Coordinator', {
  schema: {
    input: z.object({ query: z.string() }),
    output: z.object({
      results: z.array(z.any()),
      metadata: z.object({
        sources: z.number(),
        processingTime: z.number(),
      }),
    }),
  },
  handler: async (ctx, input) => {
    const startTime = Date.now();
 
    // Call multiple agents in parallel
    const [webResults, dbResults, cacheResults] = await Promise.all([
      webSearchAgent.run({ query: input.query }),
      databaseAgent.run({ query: input.query }),
      cacheAgent.run({ key: input.query }),
    ]);
 
    // Combine results
    const allResults = [
      ...webResults.items,
      ...dbResults.records,
      ...(cacheResults.found ? [cacheResults.data] : []),
    ];
 
    return {
      results: allResults,
      metadata: {
        sources: 3,
        processingTime: Date.now() - startTime,
      },
    };
  },
});
 
export default coordinator;

import { createAgent } from '@agentuity/runtime';
import { z } from 'zod';
import externalService from '@agent/external-service';
 
const robustAgent = createAgent('Robust', {
  schema: {
    input: z.object({ userId: z.string() }),
    output: z.object({ success: z.boolean(), data: z.any() }),
  },
  handler: async (ctx, input) => {
    try {
      // Try calling external agent
      const result = await externalService.run({
        userId: input.userId,
      });
 
      return { success: true, data: result };
    } catch (error) {
      ctx.logger.error('External service failed', { error });
 
      // Fallback to cached data
      const cached = await ctx.kv.get('user-cache', input.userId);
 
      if (cached.exists) {
        return { success: true, data: cached.data };
      }
 
      return { success: false, data: null };
    }
  },
});
 
export default robustAgent;

// src/api/index.ts
import { createRouter } from '@agentuity/runtime';
 
const router = createRouter();
 
// Define routes
router.get('/', (c) => {
  return c.json({ message: 'Hello from route' });
});
 
export default router;

interface RouterContext {
  // Request
  req: Request;                       // Hono request object with .param(), .query(), .header(), .json()
 
  // Agentuity Services (via c.var)
  var: {
    kv: KeyValueStorage;              // Key-value storage
    vector: VectorStorage;            // Vector storage
    stream: StreamStorage;            // Stream storage
    logger: Logger;                   // Structured logging
    tracer: Tracer;                   // OpenTelemetry tracing
  };
 
  // Response Helpers
  json(data: any, status?: number): Response;
  text(text: string, status?: number): Response;
  html(html: string, status?: number): Response;
  redirect(url: string, status?: number): Response;
  // ... other Hono response methods
}

import processor from '@agent/processor';
 
router.post('/process', processor.validator(), async (c) => {
  // Access request
  const body = c.req.valid('json');
  const authHeader = c.req.header('Authorization');
 
  // Use Agentuity services
  c.var.logger.info('Processing request', { body });
 
  // Call an agent
  const result = await processor.run({ data: body.data });
 
  // Store result
  await c.var.kv.set('results', body.id, result);
 
  // Return response
  return c.json({ success: true, result });
});

router.get('/users', (c) => {
  return c.json({ users: [] });
});
 
router.get('/users/:id', (c) => {
  const id = c.req.param('id');
  return c.json({ userId: id });
});

router.post('/users', async (c) => {
  const body = await c.req.json();
  return c.json({ created: true, user: body });
});

router.put('/users/:id', async (c) => {
  const id = c.req.param('id');
  const body = await c.req.json();
  return c.json({ updated: true, id, data: body });
});
 
router.patch('/users/:id', async (c) => {
  const id = c.req.param('id');
  const updates = await c.req.json();
  return c.json({ patched: true, id, updates });
});
 
router.delete('/users/:id', (c) => {
  const id = c.req.param('id');
  return c.json({ deleted: true, id });
});

import processorAgent from '@agent/processor';
 
router.post('/process', processorAgent.validator(), async (c) => {
  const input = c.req.valid('json');
 
  // Call the agent
  const result = await processorAgent.run({
    data: input.data,
  });
 
  return c.json(result);
});

type EmailHandler = (email: Email, c: Context) => any | Promise<any>;
 
interface Email {
  // Sender information
  fromEmail(): string | null;
  fromName(): string | null;
 
  // Recipient information
  to(): string | null;              // All recipients (comma-separated)
  toEmail(): string | null;         // First recipient email
  toName(): string | null;          // First recipient name
 
  // Message content
  subject(): string | null;
  text(): string | null;
  html(): string | null;
 
  // Attachments
  attachments(): Array<{
    filename: string;
    contentType: string;
  }>;
 
  // Metadata
  date(): Date | null;
  messageId(): string | null;
  headers(): Headers;
}

router.email('support@example.com', async (email, c) => {
  c.logger.info('Email received', {
    from: email.fromEmail(),
    fromName: email.fromName(),
    to: email.to(),                    // All recipients
    toEmail: email.toEmail(),          // First recipient
    subject: email.subject(),
    date: email.date(),
    messageId: email.messageId(),
    hasAttachments: email.attachments().length > 0
  });
 
  // Process attachments if present
  const attachments = email.attachments();
  if (attachments.length > 0) {
    c.logger.info('Attachments found', {
      count: attachments.length,
      files: attachments.map(att => ({
        filename: att.filename,
        contentType: att.contentType
      }))
    });
  }
 
  // Process email and trigger agent
  // import emailProcessor from '@agent/email-processor';
  const result = await emailProcessor.run({
    sender: email.fromEmail(),
    content: email.text() || email.html() || '',
  });
 
  return c.json({ processed: true });
});

type WebSocketHandler = (c: Context) => (ws: WebSocketConnection) => void | Promise<void>;
 
interface WebSocketConnection {
  onOpen(handler: (event: any) => void | Promise<void>): void;
  onMessage(handler: (event: any) => void | Promise<void>): void;
  onClose(handler: (event: any) => void | Promise<void>): void;
  send(data: string | ArrayBuffer | Uint8Array): void;
}

import chatAgent from '@agent/chat';
 
router.websocket('/chat', (c) => (ws) => {
  ws.onOpen((event) => {
    c.var.logger.info('WebSocket connected');
    ws.send(JSON.stringify({ type: 'connected' }));
  });
 
  ws.onMessage(async (event) => {
    const message = JSON.parse(event.data);
 
    // Process message with agent
    const response = await chatAgent.run({
      message: message.text,
    });
 
    ws.send(JSON.stringify({ type: 'response', data: response }));
  });
 
  ws.onClose((event) => {
    c.var.logger.info('WebSocket disconnected');
  });
});

type SSEHandler = (c: Context) => (stream: SSEStream) => void | Promise<void>;
 
interface SSEStream {
  write(data: string | number | boolean | object): Promise<void>;
  writeSSE(message: { data?: string; event?: string; id?: string }): Promise<void>;
  onAbort(handler: () => void): void;
  close?(): void;
}

import longRunningAgent from '@agent/long-running';
 
router.sse('/updates', (c) => async (stream) => {
  // Send initial connection message
  await stream.write({ type: 'connected' });
 
  // Stream agent progress updates
  const updates = await longRunningAgent.run({ task: 'process' });
 
  for (const update of updates) {
    await stream.write({
      type: 'progress',
      data: update,
    });
  }
 
  // Clean up on client disconnect
  stream.onAbort(() => {
    c.var.logger.info('Client disconnected');
  });
});

type StreamHandler = (c: Context) => ReadableStream<any> | Promise<ReadableStream<any>>;

import dataGenerator from '@agent/data-generator';
 
router.stream('/data', async (c) => {
  // Create a readable stream
  const stream = new ReadableStream({
    async start(controller) {
      // Stream data chunks
      const data = await dataGenerator.run({ query: 'all' });
 
      for (const chunk of data) {
        controller.enqueue(new TextEncoder().encode(JSON.stringify(chunk) + '\n'));
      }
 
      controller.close();
    },
  });
 
  return stream;
});

type CronHandler = (c: Context) => any | Promise<any>;

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday = 0)
│ │ │ │ │
* * * * *

import reportGenerator from '@agent/report-generator';
import healthCheck from '@agent/health-check';
 
// Run daily at 9am
router.cron('0 9 * * *', async (c) => {
  c.var.logger.info('Running daily report');
 
  const report = await reportGenerator.run({
    type: 'daily',
    date: new Date().toISOString(),
  });
 
  // Send report via email or store
  await c.var.kv.set('reports', `daily-${Date.now()}`, report);
 
  return c.json({ success: true });
});
 
// Run every 5 minutes
router.cron('*/5 * * * *', async (c) => {
  await healthCheck.run({});
  return c.json({ checked: true });
});