Core

Complete example of building a full-featured agent.

Basic Agent

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/hono';
import { z } from 'zod';

// Define input/output schemas
const EchoInput = z.object({
  text: z.string().min(1).max(1000),
});

const EchoOutput = z.object({
  echoed: z.string(),
  timestamp: z.string(),
});

// Create agent
const agent = await createAgent({
  name: 'example-agent',
  version: '1.0.0',
  description: 'A full-featured example agent',
})
  .use(http())
  .addEntrypoint({
    key: 'echo',
    description: 'Echo input text with timestamp',
    input: EchoInput,
    output: EchoOutput,
    handler: async ({ input }) => ({
      output: {
        echoed: input.text,
        timestamp: new Date().toISOString(),
      },
    }),
  })
  .build();

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

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

console.log('Agent running at http://localhost:3000');

Streaming Handler

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/hono';
import { z } from 'zod';

const agent = await createAgent({
  name: 'streaming-agent',
  version: '1.0.0',
})
  .use(http())
  .addEntrypoint({
    key: 'generate',
    description: 'Generate text with streaming',
    input: z.object({ prompt: z.string() }),
    streaming: true,
    stream: async ({ input }, emit) => {
      const words = ['Hello', 'from', 'the', 'streaming', 'agent!'];

      for (const word of words) {
        await emit({
          kind: 'delta',
          delta: word + ' ',
        });
        await new Promise(r => setTimeout(r, 100));
      }

      return {
        output: { completed: true },
        usage: { total_tokens: words.length },
      };
    },
  })
  .build();

const { app } = await createAgentApp(agent);

Multiple Entrypoints

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/hono';
import { z } from 'zod';

const agent = await createAgent({
  name: 'multi-endpoint-agent',
  version: '1.0.0',
})
  .use(http())
  .addEntrypoint({
    key: 'add',
    input: z.object({ a: z.number(), b: z.number() }),
    handler: async ({ input }) => ({
      output: { result: input.a + input.b },
    }),
  })
  .addEntrypoint({
    key: 'multiply',
    input: z.object({ a: z.number(), b: z.number() }),
    handler: async ({ input }) => ({
      output: { result: input.a * input.b },
    }),
  })
  .addEntrypoint({
    key: 'divide',
    input: z.object({ a: z.number(), b: z.number() }),
    handler: async ({ input }) => {
      if (input.b === 0) {
        throw new Error('Division by zero');
      }
      return { output: { result: input.a / input.b } };
    },
  })
  .build();

const { app } = await createAgentApp(agent);

Dynamic Entrypoints

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/hono';
import { z } from 'zod';

const agent = await createAgent({
  name: 'dynamic-agent',
  version: '1.0.0',
})
  .use(http())
  .build();

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

// Add entrypoints dynamically
addEntrypoint({
  key: 'greet',
  input: z.object({ name: z.string() }),
  handler: async ({ input }) => ({
    output: { greeting: `Hello, ${input.name}!` },
  }),
});

// Add more entrypoints based on config
const features = ['feature1', 'feature2'];
for (const feature of features) {
  addEntrypoint({
    key: feature,
    handler: async () => ({
      output: { feature, enabled: true },
    }),
  });
}

Custom Middleware

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';

const agent = await createAgent({
  name: 'middleware-agent',
  version: '1.0.0',
})
  .use(http())
  .build();

const { app } = await createAgentApp(agent, {
  beforeMount: (hono) => {
    // Add CORS
    hono.use('*', cors());

    // Add logging
    hono.use('*', logger());

    // Add custom auth
    hono.use('*', async (c, next) => {
      const auth = c.req.header('Authorization');
      if (!auth && c.req.path !== '/health') {
        return c.json({ error: 'Unauthorized' }, 401);
      }
      await next();
    });
  },
  afterMount: (hono) => {
    // Add custom routes
    hono.get('/version', (c) => c.json({ version: '1.0.0' }));

    // Add error handler
    hono.onError((err, c) => {
      console.error(err);
      return c.json({ error: err.message }, 500);
    });
  },
});

Usage Tracking

import { createAgent } from '@regent/core';
import { http } from '@regent/http';
import { createAgentApp } from '@regent/hono';
import { z } from 'zod';

const agent = await createAgent({
  name: 'usage-agent',
  version: '1.0.0',
})
  .use(http())
  .addEntrypoint({
    key: 'analyze',
    input: z.object({ text: z.string() }),
    handler: async ({ input }) => {
      const words = input.text.split(' ').length;

      return {
        output: { wordCount: words },
        usage: {
          prompt_tokens: words,
          completion_tokens: 1,
          total_tokens: words + 1,
        },
        model: 'word-counter-v1',
      };
    },
  })
  .build();

const { app } = await createAgentApp(agent);

Testing the Agent

# Health check
curl http://localhost:3000/health

# List entrypoints
curl http://localhost:3000/entrypoints

# Get manifest
curl http://localhost:3000/.well-known/agent.json

# Invoke entrypoint
curl -X POST http://localhost:3000/entrypoints/echo/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Hello"}}'

# Stream entrypoint
curl -X POST http://localhost:3000/entrypoints/generate/stream \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Hello"}}'