Entrypoints

Entrypoints are typed API endpoints that define your agent's capabilities. Each entrypoint has input/output schemas, a handler, and optional pricing.

Defining an Entrypoint

Use addEntrypoint() from your framework adapter:

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

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

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

addEntrypoint({
  key: 'greet',
  description: 'Greets a user by name',
  input: z.object({
    name: z.string(),
  }),
  output: z.object({
    message: z.string(),
  }),
  async handler({ input }) {
    return {
      output: {
        message: `Hello, ${input.name}!`,
      },
    };
  },
});

EntrypointDef Type

type EntrypointDef<
  TInput extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
  TOutput extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefined,
> = {
  key: string;              // Unique identifier (used in URL path)
  description?: string;     // Human-readable description
  input?: TInput;           // Input validation schema
  output?: TOutput;         // Output validation schema
  streaming?: boolean;      // Whether this entrypoint streams responses
  price?: EntrypointPrice;  // Optional pricing (x402)
  network?: Network;        // Network for payments
  handler?: EntrypointHandler<TInput, TOutput>;  // Non-streaming handler
  stream?: EntrypointStreamHandler<TInput>;      // Streaming handler
  metadata?: Record<string, unknown>;
};

Input and Output Schemas

Schemas are defined with Zod and provide:

• Runtime validation - Invalid inputs return 400 errors

• TypeScript inference - Full type safety in handlers

• JSON Schema generation - Automatic schema in Agent Card

addEntrypoint({
  key: 'analyze',
  input: z.object({
    text: z.string().min(1).max(10000),
    options: z.object({
      language: z.enum(['en', 'es', 'fr']).default('en'),
      includeKeywords: z.boolean().default(true),
    }).optional(),
  }),
  output: z.object({
    sentiment: z.number().min(-1).max(1),
    keywords: z.array(z.string()),
    wordCount: z.number(),
  }),
  async handler({ input }) {
    // input is fully typed:
    // { text: string, options?: { language: 'en' | 'es' | 'fr', includeKeywords: boolean } }

    return {
      output: {
        sentiment: 0.75,
        keywords: ['example', 'analysis'],
        wordCount: input.text.split(' ').length,
      },
    };
  },
});

Handler Function

Handler Signature

type EntrypointHandler<TInput, TOutput> = (
  ctx: AgentContext & { input: TInput }
) => Promise<{
  output: TOutput;
  usage?: Usage;
  model?: string;
}>;

AgentContext

The context object passed to handlers:

type AgentContext = {
  key: string;           // Entrypoint key
  input: unknown;        // Validated input data
  signal: AbortSignal;   // For cancellation
  metadata?: Record<string, unknown>;
  runId?: string;        // Unique run identifier
  runtime?: AgentRuntime; // Access to full runtime
};

Handler Example

async handler({ input, signal, runtime }) {
  // input: Validated and typed input data
  // signal: AbortSignal for cancellation
  // runtime: Access to payments, wallets, etc.

  return {
    output: { result: 'processed' },
    usage: { total_tokens: 150 },  // Optional usage tracking
    model: 'gpt-4',                // Optional model identifier
  };
}

Streaming Entrypoints

For long-running operations or LLM responses, use streaming:

addEntrypoint({
  key: 'chat',
  description: 'Chat with AI assistant',
  input: z.object({
    message: z.string(),
    history: z.array(z.object({
      role: z.enum(['user', 'assistant']),
      content: z.string(),
    })).optional(),
  }),
  streaming: true,
  async stream(ctx, emit) {
    const { input } = ctx;

    // Emit chunks as they become available
    await emit({
      kind: 'delta',
      delta: 'Hello, ',
      mime: 'text/plain',
    });

    await emit({
      kind: 'delta',
      delta: 'how can I help you today?',
      mime: 'text/plain',
    });

    // Return final result
    return {
      output: { completed: true },
      usage: { total_tokens: 25 },
    };
  },
});

Stream Handler Signature

type EntrypointStreamHandler<TInput> = (
  ctx: AgentContext & { input: TInput },
  emit: (chunk: StreamPushEnvelope) => Promise<void> | void
) => Promise<StreamResult>;

type StreamResult = {
  output?: unknown;
  usage?: Usage;
  model?: string;
  status?: 'succeeded' | 'failed' | 'cancelled';
  error?: { code: string; message?: string };
  metadata?: Record<string, unknown>;
};

Stream Envelope Types

The emit() function accepts these envelope types:

// Text delta (most common for LLM responses)
await emit({
  kind: 'delta',
  delta: 'chunk of text',
  mime: 'text/plain',
});

// Complete text block
await emit({
  kind: 'text',
  text: 'Complete paragraph',
  mime: 'text/plain',
});

// Asset (file, image, etc.)
await emit({
  kind: 'asset',
  assetId: 'file-123',
  mime: 'image/png',
  transfer: 'external',
  href: 'https://example.com/image.png',
});

// Control message
await emit({
  kind: 'control',
  control: 'typing',
  payload: { active: true },
});

// Error (non-fatal)
await emit({
  kind: 'error',
  code: 'rate_limit',
  message: 'Rate limit exceeded',
  retryable: true,
});

Full StreamEnvelope Union

type StreamEnvelope =
  | StreamRunStartEnvelope    // Sent automatically at start
  | StreamTextEnvelope        // Complete text block
  | StreamDeltaEnvelope       // Incremental text
  | StreamAssetEnvelope       // File or media
  | StreamControlEnvelope     // Control signal
  | StreamErrorEnvelope       // Error message
  | StreamRunEndEnvelope;     // Sent automatically at end

// StreamPushEnvelope excludes run-start and run-end (used with emit)
type StreamPushEnvelope = Exclude<
  StreamEnvelope,
  StreamRunStartEnvelope | StreamRunEndEnvelope
>;

Invoking Entrypoints

Non-Streaming (invoke)

curl -X POST http://localhost:3000/entrypoints/greet/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {"name": "Alice"}}'

Response:

{
  "run_id": "abc123",
  "status": "succeeded",
  "output": {
    "message": "Hello, Alice!"
  },
  "usage": {
    "total_tokens": 10
  }
}

Streaming (stream)

curl -X POST http://localhost:3000/entrypoints/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Hello"}}'

Response (SSE):

event: run-start
data: {"kind":"run-start","runId":"abc123"}

event: delta
data: {"kind":"delta","delta":"Hello, ","mime":"text/plain","runId":"abc123","sequence":1}

event: delta
data: {"kind":"delta","delta":"how can I help?","mime":"text/plain","runId":"abc123","sequence":2}

event: run-end
data: {"kind":"run-end","runId":"abc123","status":"succeeded","output":{"completed":true}}

Adding Pricing

Entrypoints can require payment via the x402 protocol:

addEntrypoint({
  key: 'premium-analysis',
  description: 'Advanced AI analysis',
  input: z.object({ text: z.string() }),
  output: z.object({ analysis: z.string() }),
  price: '$0.01',  // Price per invocation
  async handler({ input }) {
    return {
      output: { analysis: 'detailed analysis...' },
    };
  },
});

Or with separate invoke/stream pricing:

addEntrypoint({
  key: 'chat',
  streaming: true,
  price: {
    invoke: '$0.01',
    stream: '$0.005',
  },
  async stream(ctx, emit) {
    // ...
  },
});

With payments configured, requests without valid payment headers return 402 Payment Required.

Usage Tracking

Return usage from handlers to track resource consumption:

return {
  output: { text: input.text },
  usage: {
    prompt_tokens: 100,
    completion_tokens: 50,
    total_tokens: 150,
  },
  model: 'gpt-4',
};

Listing Entrypoints

curl http://localhost:3000/entrypoints

Response:

[
  {
    "key": "greet",
    "description": "Greets a user by name",
    "streaming": false
  },
  {
    "key": "chat",
    "description": "Chat with AI assistant",
    "streaming": true
  }
]

Validation Errors

Invalid input returns a 400 error with details:

{
  "error": {
    "code": "invalid_input",
    "issues": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "number",
        "path": ["name"],
        "message": "Expected string, received number"
      }
    ]
  }
}

Best Practices

1. Use descriptive keys - The key appears in URLs and the Agent Card

2. Always add descriptions - They help with discovery and documentation

3. Validate thoroughly - Use Zod's built-in validators (.min(), .max(), .email(), etc.)

4. Stream when appropriate - Use streaming for LLM responses or long operations

5. Track usage - Return usage for billing and analytics

6. Handle errors gracefully - Throw errors with clear messages; they're returned as JSON

Next Steps

• Packages: @regent/core - Core package reference

• Packages: @regent/x402 - Monetize your entrypoints